[TUTORIAL] Beginners guide to weapons modding

The place to discuss scripting and game modifications for X4: Foundations.

Moderators: Moderators for English X Forum, Scripting / Modding Moderators

vedder1993
Posts: 5
Joined: Sat, 8. Dec 18, 00:02
x4

[TUTORIAL] Beginners guide to weapons modding

Post by vedder1993 » Sat, 8. Dec 18, 15:06

Hey.

With some help, I spend today making sense of the file structure used by X4. Some of you might have seen the X4 tracer world mod (thanks for that awesome mod rjtwins!) and wonder how to edit and or add weapons in X4. To get you started I have set up this basic guide to file structure. I hope this help people in understanding what files are related to gun damage, gun FX etc.
Note that this guide does not include how to make XML Patch files if there is enough demand I might make this.

First, you need to extract the needed files, for this, I refer you to this guide: viewtopic.php?f=181&t=402452

Next, we need to make sense of the file structure that is used in X4, this will help us find the right files in the right folders. Disclaimer I'm not an expert on file types.
We will be looking into files from the following folders:
Spoiler
Show
Image
We will start in libraries/wares.xml
This file contains all wares in the game including weapon systems. I like to use this file as a guide directing me to all the files I need to edit or add.
We will take a look at the medium laser turret from the Argon:
Spoiler
Show

Code: Select all

<!-- Example of a weapon ware -->
<ware id="turret_arg_m_beam_01_mk1" name="{20105,4164}" description="{20105,4161}" group="turrets" transport="equipment" volume="1" tags="equipment noplayerblueprint turret">
    <!-- The number in name and discriptoin refer to page and id number found in t/001-L044(for eng). These names are shown in the shopping list and only there-->
	<price min="45385" average="50428" max="55471" />
    <production time="10" amount="1" method="default" name="{20206,101}">
      <primary>
        <ware ware="advancedelectronics" amount="6" />
        <ware ware="energycells" amount="10" />
        <ware ware="turretcomponents" amount="10" />
      </primary>
    </production>
    <component ref="turret_arg_m_beam_01_mk1_macro" amount="1" />
	[b]<!-- this refers a macro, the linked macro in:
	Assets/props/weaponsystems/energy/macros-->[/b]
    <restriction licence="militaryequipment" />
    <use threshold="0.65" />
    <owner faction="argon" />
  </ware>
You can now already edit the price, needed components for construction etc in here, but more interested are the properties of the weapon itself.
For this, we have to go to the linked macro file: Assets/props/weaponsystems/energy/macros/turret_arg_m_beam_01_mk1_macro.xml
We will find the following file in there:
Spoiler
Show

Code: Select all

<macros>
  <macro name="turret_arg_m_beam_01_mk1_macro" class="turret" alias="turret_arg_m_beam_02_mk1_macro">
    <component ref="turret_arg_m_beam_01_mk1" />
	<!-- this refers to the component linked to this weapon listed in Assets/props/weaponsystems/energy information about the model of the weapon indicated in these 
         files -->
    <properties>
      <identification name="{20105,4164}" basename="{20105,4161}" shortname="{20105,4165}" makerrace="argon" description="{20105,4161}" mk="1" />
      <!-- The name here will show up everywhere but the shoppinglist -->
	  <bullet class="bullet_gen_turret_m_beam_01_mk1_macro" />
	  [b]<!-- This refers to the FX of the weapon,the bullet/beam etc, leaving the weapon. Found in Assets/fx/macros-->[/b]
      <rotationspeed max="90" />
      <reload rate="0.5" time="1" />
	  <!-- not sure what this does yet -->
      <hull threshold="0.2" integrated="1" />
    </properties>
  </macro>
</macros>
There are two links that are important here, first the component, listed in Assets/props/weaponsystems/energy. Altering this file results in a different look for the weapon. However, the file I'm more interested in is the bullet class located in Assets/fx/macros/bullet_gen_turret_m_beam_01_mk1_macro.xml
Spoiler
Show

Code: Select all

<macros>
  <macro name="bullet_gen_turret_m_beam_01_mk1_macro" class="bullet">
    <component ref="bullet_gen_s_beam_01_mk1" />
	<!-- this referst to a XML file in the weaponFx folder. This xml file has fx information about the projectie, however it also indicates where the weapn is fired from this 
          will become more importand later->
    <properties>
      <bullet speed="7000" lifetime="1" range="2550" amount="1" barrelamount="1" icon="weapon_beam_mk1" maxhits="1" ricochet="0" scale="1" attach="1" />
      <reload time="3" />
      <damage value="58" repair="0" />
	  <!-- properties of the projectile, this is differnt for bullet or beam weapons -->
      <effects>
        <impact ref="impact_gen_m_beam_01_mk1" />
        <launch ref="muzzle_gen_m_beam_01_mk1" />
		<!-- referst to fx for impact and muzzle blast -->
      </effects>
      <weapon system="turret_shortrange" />
	  <!--for any non turret weapons use weapon_standart here. For turrets you can use turret_shortrange/ turret_midrange/ turret_longrange or turret_mining.
	  This value needs to reflect the type of weapon you are attaching the bullet to for turrets use turret_xxxx for mining use mining and or everything else use 
          Weapon_standard-->
    </properties>
  </macro>
</macros>
This is where we can edit the behaviour of the projectile itself, this also affects the fire rate and range. As stated before the code for beam weapons is different than for bullet and laser projectiles.

Beam:
Spoiler
Show

Code: Select all

    <properties>
      <bullet speed="7000" lifetime="1" range="2550" amount="1" barrelamount="1" icon="weapon_beam_mk1" maxhits="1" ricochet="0" scale="1" attach="1" />
      <!-- speed= m/s, lifetime= beam length in sec, range = max range for beam weapon -->
      <reload time="3" />
      <damage value="58" repair="0" />
NOTE: for this code, the max range for this weapon is 2550m if there was no max range indicated a 7000m long beam would travel infinitely.
Beam weapons are the only weapons on the game that have the scale=1 and attach=1 value if you create a new beam weapon make sure to set these to the right value.


Gatling:
Spoiler
Show

Code: Select all

<properties>
      <ammunition value="21" reload="1" /> <!-- rounds in clip, reload time of clip in sec. -->
      <bullet speed="1920" lifetime="2.5" amount="1" barrelamount="1" icon="weapon_gatling_mk1" timediff="0.025" angle="0.25" maxhits="2" ricochet="0.01"
       restitution="0.3" scale="0" attach="0" /> <!-- speed= ms/s, lifetime= sec alive., amount=rounds at the same time, barrel=how many barrels  -->
      <heat value="43" /> <!-- heat generated per shot -->
      <reload rate="14" /> <!-- rounds per sec. -->
      <damage value="23" repair="0" />
For example, to make a weapon fire faster you change the reload rate and lower the damage rate accordingly like done in the x4 tracer world mod.

If you are still here, thanks for reading and I hope you learned something from this. Feel free to ask questions :gruebel:

jmattspartacus2
Posts: 73
Joined: Wed, 5. Dec 18, 07:04

Re: [TUTORIAL] Beginners guide to weapons modding

Post by jmattspartacus2 » Tue, 11. Dec 18, 09:59

There's an excellent (and very relevant guide) to xml patching on the x-rebirth modding forum here
viewtopic.php?t=354310

It helped me make all the mods I've made so far (simple edits and whatnot, but a step)

Vaeo
Posts: 234
Joined: Wed, 27. May 09, 08:03
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Vaeo » Wed, 12. Dec 18, 12:35

Awesome topic. TY.

cirelli
Posts: 1
Joined: Fri, 30. Nov 18, 20:50
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by cirelli » Sun, 6. Jan 19, 15:02

I'm making a Mk2 version of the Behemoth weapon, it working well but, i can not figure out how to put a image of the weapon on the buy ship UI.

I noticed there the firing animation is much slower than the firing, is there a way to speed up the animation?

alexringess
Posts: 40
Joined: Tue, 25. Sep 18, 23:57
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by alexringess » Mon, 7. Jan 19, 11:43

Most of the peoples that want to do mods for X4 are dissuaded to start because of the data digging that must done before all (where the files are, what params must be changed, etc).
So many thanks for that usefull guide :)
+rep

pzgren
Posts: 1
Joined: Fri, 1. Feb 19, 00:04
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by pzgren » Fri, 1. Feb 19, 01:13

How do I create a new weapon mod which do not change any original weapon but also available in shipyards

User avatar
Shuulo
Posts: 1629
Joined: Mon, 14. Apr 08, 17:03
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Shuulo » Sun, 10. Mar 19, 23:47

Any info on how to mod gatling sound (or any other looping sound)? It seems to NOT be assigned via sound_library and effects file.

Skatsanni
Posts: 2
Joined: Wed, 16. Oct 19, 10:07

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Skatsanni » Mon, 21. Oct 19, 21:54

How can i change range for bullet projectiles?

teleportationwars
Posts: 158
Joined: Fri, 12. Jul 19, 14:03

Re: [TUTORIAL] Beginners guide to weapons modding

Post by teleportationwars » Tue, 22. Oct 19, 00:58

Skatsanni wrote:
Mon, 21. Oct 19, 21:54
How can i change range for bullet projectiles?
Lifetime * Speed

Range acts as a maximum travel distance.

Skatsanni
Posts: 2
Joined: Wed, 16. Oct 19, 10:07

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Skatsanni » Tue, 22. Oct 19, 10:34

teleportationwars wrote:
Tue, 22. Oct 19, 00:58
Skatsanni wrote:
Mon, 21. Oct 19, 21:54
How can i change range for bullet projectiles?
Lifetime * Speed

Range acts as a maximum travel distance.
Thanks!

Where can i change types of weapons which can i install?

Can i add more "fire sounds" for one weapon type?

teleportationwars
Posts: 158
Joined: Fri, 12. Jul 19, 14:03

Re: [TUTORIAL] Beginners guide to weapons modding

Post by teleportationwars » Tue, 22. Oct 19, 13:43

Skatsanni wrote:
Tue, 22. Oct 19, 10:34
teleportationwars wrote:
Tue, 22. Oct 19, 00:58
Skatsanni wrote:
Mon, 21. Oct 19, 21:54
How can i change range for bullet projectiles?
Lifetime * Speed

Range acts as a maximum travel distance.
Thanks!

Where can i change types of weapons which can i install?

Can i add more "fire sounds" for one weapon type?
The connection on the weapon and the connection on the ship are connected by customizable inclusive tags.

Max Bain
Posts: 1458
Joined: Wed, 27. Jun 18, 19:05
x3ap

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Max Bain » Wed, 30. Oct 19, 08:52

I have got a question.

We have turrets and we have projectiles. And both have reloadrate and reloadtime values.

I think that reloadrate defines the time between shooting two times until the magazin is empty. Then the reload timetime defines the time to reload the magazin, right?
But why do we have the same values for turrets and projectiles?

What is the difference?

WHat is the complete forumla for calculating DPS?
XR Ship Pack (adds several ships from XR) Link
Weapon Pack (adds several new weapons) Link
Economy Overhaul (expands the X4 economy with many new buildings) Link
X4 Editor (view stats of objects and make your own mod within a few clicks) Link

User avatar
Shuulo
Posts: 1629
Joined: Mon, 14. Apr 08, 17:03
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Shuulo » Wed, 30. Oct 19, 09:47

Max Bain wrote:
Wed, 30. Oct 19, 08:52
I have got a question.

We have turrets and we have projectiles. And both have reloadrate and reloadtime values.

I think that reloadrate defines the time between shooting two times until the magazin is empty. Then the reload timetime defines the time to reload the magazin, right?
But why do we have the same values for turrets and projectiles?

What is the difference?

WHat is the complete forumla for calculating DPS?
You are correct on reload rate (for rate of fire) and reload time (reload of magazine).
Turret values for reload are not used at all, it seems to be a redundancy after XR.
Last edited by Shuulo on Wed, 30. Oct 19, 09:59, edited 1 time in total.

User avatar
Shuulo
Posts: 1629
Joined: Mon, 14. Apr 08, 17:03
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Shuulo » Wed, 30. Oct 19, 09:51

Skatsanni wrote:
Tue, 22. Oct 19, 10:34
teleportationwars wrote:
Tue, 22. Oct 19, 00:58
Skatsanni wrote:
Mon, 21. Oct 19, 21:54
How can i change range for bullet projectiles?
Lifetime * Speed

Range acts as a maximum travel distance.
Thanks!

Where can i change types of weapons which can i install?

Can i add more "fire sounds" for one weapon type?
As for fire sounds - yes, you can make an entry in sound library to randomly choose one of few samples. Check vro mod how it is implemented

Max Bain
Posts: 1458
Joined: Wed, 27. Jun 18, 19:05
x3ap

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Max Bain » Wed, 30. Oct 19, 14:35

What about beam weapons and their damage?

An L Beamweapon has 112 Damage and 0 reloadrate and 5 reload time. I doubt that the DPS of the L turret is 112 until it overheats when an M railgun has 800 damage per shot and shoots once every second. I think it does 112 damage way more often than once a second.

Whats the tick rate per second in X4? Does anyone know that? Maybe 10 per second or 5? And am I right that beam weapons do the damage per tick instead of reload rate (reloadrate is 0)?
XR Ship Pack (adds several ships from XR) Link
Weapon Pack (adds several new weapons) Link
Economy Overhaul (expands the X4 economy with many new buildings) Link
X4 Editor (view stats of objects and make your own mod within a few clicks) Link

Cetus808
Posts: 12
Joined: Fri, 6. Aug 10, 15:16
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Cetus808 » Tue, 28. Apr 20, 15:08

What i have figured out so far is the following:

First "Bullets per second" should actually be called "shots per second" since you can multiply the "bullets per shot" with the barrelamount modifier which directly multiplies the MW per shot.

Reload rate equals shots per second
Ammunition reload is seconds of pause after ammo clip is empty

Means:
Time per burst = AmmoClipReload + AmmoClipAmount / ReloadRate

in this example:

Code: Select all

<diff>
	<replace sel="//ammunition/@value">16</replace>
	<replace sel="//ammunition/@reload">2</replace>
	<replace sel="//reload/@rate">4</replace>
</diff>
2s + 16 / 4/s = 6s
It takes 4 seconds to empty the clip followed by a 2 seconds reload time which results in a total burst time of 6 seconds

We also know that per burst we fire 16 shots which results in 16 / 6s = 2.666 shots per second.

Shots per Second = AmmoClipAmount / (AmmoClipReload + AmmoClipAmount / ReloadRate)

If the attribute "barrelamount" equals 1, we also know that per shot one bullet is fired. If it equals 2 it will double the effective bullets per second.

Lets say we have a damage value of 100 then barrelamount will multiply this value. With 2.666 shots per second and barrelamount of 1 we have an output of 266.66 MJ / s.
With 2 barrels 533.33 MJ / s and so on.


Also important is to know that each barrel has its own ammoclip. Means in this example the two barrels have a 16 shot clip each. So effectively 32 bullets with 100 MJ fired every 6 seconds.

In the game this is displayed wrong. If i increase the barrelamount from 1 to 2, the "bullets per second" (aka shots per second) stays the same but it will double the MW weapon output.

Energy per Second = DamageValue * BarrelAmount * Amount * AmmoClipAmount / (AmmoClipReload + AmmoClipAmount / ReloadRate) ~edited

*edit:
Looks like amount and barrelamount have the same effect and multiply each other.

With:

AmmoClipAmount = 16
AmmoClipReload = 4s
ReloadRate = 4 / s
Amount = 4
BarrelAmount = 4
and Damage = 100 MJ

we have the following caluculation for the energy:

100 * 4 * 4 * 16 / (4 + 16 / 4) = 3200 MJ / s

With Amount = 2 it will be 1600 MJ / s


And even amount doesn't affect the "shots per second" like barrelamount. Although one might think that at least with Amount = 4, per shot 4 bullets are fired at once and removed from the clip. But no... It still fires 16 times. Just the energy output increases.

Maybe both attributes are just an easy way to increase damage from M to L weapon scripts without changing damage and shield values directly.

*end edit



With different combinations of ReloadRate and AmmoClipReload you can create some simple burst patterns.


The following example:
4 shots per clip
4 shots per sec -> 1 clip per sec
2 sec clip reload

Code: Select all

<diff>
	<replace sel="//ammunition/@value">4</replace>
	<replace sel="//ammunition/@reload">2</replace>
	<replace sel="//reload/@rate">4</replace>
</diff>
will result in a pattern like: BAM - BAM - BAM - BAM - pauseonesec - pauseonesec - BAM - BAM - BAM - BAM - pauseonesec - pauseonesec ....



And as far as i can tell, the reload time and rate declared directly in the turret file have no effect.



*Edit:

Just to complete this a bit more. There are other modifier to adjust the weapons/bullets behavior.



1. #####
the damage element can have an shield attribute

Code: Select all

<diff>
	<replace sel="//damage/@value">100</replace>
	<add sel="//damage" type="@shield">-25</add>
</diff>
In this example we have a basedamage of 100 which is basicly the hull damage and if no shield attribut is applied also the shield damage.
If we add the shield attribute with -25 the weopon will do 100 hull damage and 100 + -25 = 75 damage to the shields.

The shield attribute is additive. So if we add +25 to shields the weapon will do more shield damage (125) than hull damage which is the case for ion cannons for example.



2. #####
ricochet is an attribute in the bullet element.

It represents a propability value between 0 and 1, a bullet can be reflected randomly and hits maybe something else.

Code: Select all

<diff>
	<replace sel="//bullet/@ricochet">0.1</replace>
</diff>
With ricochet = 0.1, 1 out of 10 bullets will be reflected and hits twice. But i can't say with which energy. Would make sense if its less.



3. #####
For flak turrets there is also the selfdestruct attribute in the bullet element.
Its simply a boolean 0 or 1.

I'm not sure but i think its working together with the areadamage element.
Regarding this element i can't say how the attributs value, time and lifetime are applied to the environment. Its hard to see the effects by numbers.

Code: Select all

<diff>
	<replace sel="//bullet/@selfdestruct ">1</replace>
	<add sel="//properties/"><areadamage value="75" time="1" lifetime="5"/></add>
</diff>
Could be that the areadamage also works for other bullets if they hit something. That i have to find out still.



4. #####
The attribut angle in the element bullet adds some inaccuracy to the weapon.
I've set it to 45 just to see what will happen. And indeed there was a cone with an angle of 45° where the bullets fly randomly.



5. #####
It looks like the timediff attribute in the bullet element adds a bit of randomness to the time between the shots. May be a nice effect for bolters which spit out lead in a more dirty fashion.


*end edit

RPINerd
Posts: 54
Joined: Fri, 8. Mar 19, 20:21
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by RPINerd » Mon, 29. Jun 20, 04:54

Any chance you (or another lovely person here) knows what the <use threshold="0.#"> means? Is this a scale of how preferable the faction is to equiping this weapon? If so, does that mean a 0 would make them NEVER equip said weapon?

|K.O.S.H.
Posts: 3724
Joined: Fri, 19. Dec 03, 10:36
x3tc

Re: [TUTORIAL] Beginners guide to weapons modding

Post by |K.O.S.H. » Sun, 17. Jan 21, 10:13

Thx this post.

Does anyone know, he to make the global rotation speed faster?

Edit: nerver min, i found it.

the weapon (not bullet) macro has values for "rotationspeed" and "rotationacceleration", but in the editor they were labled as "speed" and "acceleration" what confused me ;)
Wing Commander Mod - German Topic
06.07.11 - v1.1 RELEASED!

User avatar
Shuulo
Posts: 1629
Joined: Mon, 14. Apr 08, 17:03
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Shuulo » Mon, 18. Jan 21, 14:05

RPINerd wrote:
Mon, 29. Jun 20, 04:54
Any chance you (or another lovely person here) knows what the <use threshold="0.#"> means? Is this a scale of how preferable the faction is to equiping this weapon? If so, does that mean a 0 would make them NEVER equip said weapon?
necro, it directly relates to ships job level, it will use the weapons with same or below threshold values

Osbot
Posts: 108
Joined: Sun, 10. Jan 10, 19:49
x4

Re: [TUTORIAL] Beginners guide to weapons modding

Post by Osbot » Tue, 19. Jan 21, 06:33

Does this mean a higher value is better? IE Job is threshold 1, so the AI will more likely choose a .61 threshold over a .45?

Post Reply

Return to “X4: Foundations - Scripts and Modding”