• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.


Item-Making Tutorial

Page history last edited by posfan12 9 years, 6 months ago


Item-making Tutorial for JA2 1.13



This guide deals with creating new items using the JA2 1.13 XML format. Due to new tags being added and removed as work on the 1.13 progresses, some of the information here may become outdated with time, or
require revision. Please note this when you go to work on the XMLs.


For a partial explanation of the various tags used inside XMLs, visit this page:

Modding and Costumization




Make backups of your XML directory (by default, JA2/Data-1.13/Tabledata) so that if you make a mistake, you can go back to a working version of the game. If you screw things up, I ain't responsible :P





There are several ways to handle XML files. In essence, these are simply text files without any binary component, and therefore it is possible to simply use the basic windows Notepad to edit them. However (at least on my machine), the sheer size of files like Items.XML may cause this process to take a very long time. Therefore it is recommended to seek one of the many free XML editing programs for this, such as XML Marker, XMLFox, etc.


All XML files for JA2 1.13 are located in the directory DATA-1.13/TABLEDATA, which would be directly inside your installed JA2 folder. MAKE BACKUPS.



XML files are built as trees, meaning that they branch out. Tags are opened, data is input between them, and then they are closed.

Tags can contain other tags, which is what makes a tree.




















As you can see, each tag has an opening (with <> brackets) and a closing (with </> brackets) much like HTML code. It is very important that each opening has a closing, and that they are placed in the right locations. If one wants to add a new magazine, it had to go where it says "PLACEHOLDER" (It wouldn't actually say that in any file though, hehehe). It must have <MAGAZINE> to start it, and a </MAGAZINE> to close it, otherwise the code will fail. Each tag inside the magazine definition must have each of <uiIndex>, <ubCalibre>, <ubMagSize>, and <ubAmmoType>, followed by their appropriate values, and of course tag closers for

each of these (</uiIndex>, </ubCalibre>, etcetera).





Let's have a look at Items.XML


This rather large XML file, this one contains all items in the game. It is used to define their basic characteristics, includes sorting info, and if neccesary also contains info that would later be used when this item is referenced in other XML files.


When we begin creating a new item, it first has to have an entry in Items.XML, which will include all the basic data. JA2 1.13 can handle a lot more items than original versions of the game - the release already contains several hundred objects that did not exist in regular JA2. However, if you peruse the items.xml file, you'll quickly notice that many of the items listed there are "NADA" (empty) items.

There are two methods to add a new item to the game, the first is to add a new entry for the item, at the bottom of the items list. The second is to replace NADA items.




The easiest way to add a new basic item would be to append the list with a new entry. You can do this by copying one of the existing items (Everything between and including an <ITEM> line and a </ITEM> line), and pasting it at the bottom of the list. Do make sure, however, that the </ItemsList> line remains the LAST LINE IN THE FILE. As explained above, this line closes the entire file, and should therefore always be the last line. Anything that is placed after that line will be disregarded.




Basically, Nada Items are simply placeholders inside the file - items that have no description, values, nothing aside from their uiindex number. Their data can be changed, overwritten with the values of your new item, keeping only the nada item's uiIndex.

There are roughly 100 of these "empty slots" inside the items.xml. Since the XML is mostly arranged by item types (weapons grouped together, magazines grouped together, etc), these palceholders allow you to create new items that are listed adjacently to other items of the same type, rather than at the bottom of the list, making the whole thing much more orderly. Coversely you may actually PREFER to keep all your new items at the end of the file, but it's your choice.
So Nada items are simply there to allow you to better arrange your items. Note that this doesn't affect the sorting order of items in the game (that's handled by a different value).


If you do choose to replace Nada items, however, note that two of them should NOT be messed with. Specifically, the first item on the list, and the 70th item on the list are purposefully empty and shouldn't be used.




The first and most important part of adding new items is to make sure that they have a UNIQUE uiindex value! This value is a reference number that the game uses to track each and every item in the game. Most importantly, this number will be used in other XMLs whenever we want to reference an item.


If you're editing a previously unedited version of items.XML, the last item on the list should have a uiIndex of 1026 (it's the Trigger Group item). Therefore, if you copy/paste an item to the end of the list in order to make a new item, change this new item's uiIndex to 1027. The next item would have 1028, the next would have 1029, and so on. If you accidentally skip a number, the game will crash. If
you use the same number twice, the game will crash. If you mess up the order (1029 before 1028), guess what, the game will crash.

Excercise caution.


If you're simply overwriting an existing NADA item, don't change its UIIndex! Nada Items are meant as placeholders, so that you can use their UIindex. Otherwise, what's the point.


Also note that the UiIndexes must ALWAYS be sorted! You can't put an item with UiIndex number 1000 at the top of the list. It has to be placed right after the item with the UiIndex #999. Otherwise, you can guess what happens. I'll help you - it's a crash.
This is true also for most other XMLs that use UiIndexes to sort their entries.


Always make sure to write down the uiIndexes of all your new items, so that you can easily input the number in other XML files, whereever needed.




Once you've made a new item and given it a unique uiIndex number (or replaced a NADA item), you need to change all the important bits of data so that your item appears properly in the game. Before you start defining the characteristics of the item, you'll need to set some important values for it.


The first value is the item's Class. This is determined by the <ubItemClass> tag. Basically, this defines which group of items your new creation will belong to:


2 = Gun (anything that fires bullets, darts, minirockets, etc. (incl. one-shot disposable missile))

4 = Knife (slashing weapons)

8 = Throwing Knife (weapons thrown to inflict DIRECT damage)

16 = Launcher weapons (Grenade Launchers and shoulder-launched missiles (those that use attached ammo, not one-shot disposable ones))

64 = Thrown non-weapon objects (Rocks...)

128 = Blunt melee weapon (Brass Knuckles, crowbar...)

256 = Thrown or launched explosives (grenades, magazines for grenade launchers, rockets)

512 = Bombs you can set (but also includes Mortar Shells for some reason)

1024 = Magazines

2048 = Armour

4096 = Medical Kit (Including First Aid kits)

8192 = Other battle kits

32768 = Face Items

65536 = Keys

268435456 = Misc. Items (anything that doesn't fit above)

536870912 = Money


It's important to know exactly which group your new item is going to belong to, because not only will the game treat it differently, but it will also be affected by values from other XML files.




Despite its name, the ubClassIndex is only partially connected to the item's class (see above). More importantly, it points to data defined in OTHER xml files. Such XML files as Weapons.xml, Armours.xml, and a few others, have entries of their own, definitions of templates. These templates however, are standing on their own, and not directly connected to any items. Instead, an item's entry in Items.XML points the game to look into these other XMLs for specific templates, and draw data from there. Sounds complicated? It's really not. I'll explain.


Let's take the simple example of T-Shirts.


There are three kinds of T-Shirts in the game. They look differently, they have different descriptions. As separate items, each has its own UiIndex (Otherwise the game would CRASH :) hehehehe ).


But all these t-shirts offer the EXACT same protection values when they are worn (really shitty protection values, too). This is because they all point to the same entry in armours.xml, Entry #17, which defines a specific low protection and high degradation value.
Simply put, they all share the same ClassIndex.

When the game reads a T-shirts into memory, it sees that the T-shirt is an armour-class item, and that the class index is 17. The game then goes directly to entry #17 in Armours.xml to see what armour data it should apply to the t-shirt. It gives all T-shirts the same protection and degrade values as defined in entry #17.
So while we have three different items, they all have the same protection value.

Now let's say we wanted to make the "I Love Arulco" t-shirt better than the others. WAY better. We can change its ClassIndex value from 17 to 8. This would give it the same armour properties as a Coated Spectra Vest. :) The other two t-shirts are uneffected, because they still reference entry #17 in armours.xml, which gives them really low protection values.


Alternately, if we went into Armours.xml, we could edit Entry #17 to have higher protection values. This would change any armour item in the game that points to entry #17, giving it higher protection values in the game. So in fact, we'd be making ALL t-shirts much stronger than they are.


Note, the SKS, 40mm Tear Gas Grenade, and 15-round 9mm MAG AP also have Classindex 17, but since they aren't ARMOUR items, they don't draw data from Armours.xml at all. This is what the ItemClass value is for. See above.




When making a new item, however, you're usually looking to make something that has characteristics NOT used by any existing item. Therefore, you need to give the item a new, unique ClassIndex, and add a new bunch of data in the appropriate XML file, which would be referenced by this item.


Let's have a brief explanation of each XML file that is referenced in this way.



All items of class 2048 draw data from Armours.xml. This XML contains values on protection, degradation, etcetera. If you're looking to make a piece of armor that has unique properties, you'll need to make a new entry in armours.xml, and reference it in the item's ClassIndex. For unedited versions of the XML files, the new ClassIndex would be 83 (82 is the last one currently used, by the Leg Protectors). This will be the number of the entry you'll add at the bottom of Armours.xml (as explained later).



All items of classes 256 and 512 need to choose an explosion entry from explosives.xml. If you want your item to have the same explosion as an existing item, find that item's ClassIndex and copy it to your newly created item. If you're interested in defining a whole new explosion, you'll need to add an entry in explosives.xml (this is explained later), and give your new item a corresponding ClassIndex number. For unedited versions of the game, both the item's ClassIndex as well as the UiIndex of the new explosion entry, would be 56 (55, last entry in explosives.xml, is the explosion for a VOG-25P grenade).



All items of classes 2, 4, 8, 16, 64 and 128 are going to draw data from entries in weapons.xml. For weapons, the ClassIndex number HAS TO BE THE SAME as the item's uiIndex!! With unedited versions of the XMLs, the last uiIndex is 1026, so you can use UiIndex and ClassIndex values of 1027+. Alternately, you can use NADA item numbers (see above). If this is the case, make sure the weapons.xml entry goes in the right place.



This last group is very tricky. Magazines.xml defines data for items of class 1024. It dictates the caliber of the magazine, how many bullets fit inside, and the type of ammo. However, the sorting of the Magazines.xml is very very rigid. If you're going to add a NEW CALIBER to the game, then things are somewhat easier. Give your new item a unique ClassIndex, one higher than the last classindex used. In unedited versions, it should be 267 (with 266 being the last one currently used, for a 7-bullet clip of .50 AE). Then add the new magazine.xml entry at the bottom of the list (explained later). HOWEVER, if you're simply making a different size magazine for a caliber that already exists in the game, you're going to have to give it a VERY SPECIFIC ClassIndex number, and you're going to have to mess with the entire index listing in Magazines.XML... Yes, it's a bitch.
Hopefully, this will be addressed by the developers at some point. Nonetheless, I'll later explain the exact order that needs to be followed in Magazines.XML.


Any items that belong to classes 4096 and above do not need ClassIndex numbers at all. (Except, keys? Not sure about this).


Always note down the ClassIndex of your item, just in case you need to input it later.





Now that the item has an entry in Items.xml, you can set all its attributes. Visit xml_items for a short explanation of each tag.





Aside from creating the item in items.xml, you would probably want to create entries in other XMLs that define more stats for the

item, depending on the kind of item you were creating.
We will start with the most basic items.




If the item you're creating is a weapon (ItemClass 2, 4, 8, 16, 64, or 128), it must have a corresponding entry in weapons.xml. I won't go into great length here as to the various tags in weapons.xml - they are briefly explained here:



Do note two things:


A) in weapons.xml, the <uiIndex> tag should equal the item's <ubClassIndex> tag.

B) The entries in weapons.xml have to be sorted by <uiIndex>. It's possible to skip numbers, but it has to be an incremental order -

so entry #357 can't come before entry #248, for instance. If you want to avoid a mess, look for the last entry in Weapons.XML, and note down its number. Make your new item have a larger uiIndex and ClassIndex number. Again I'll remind you that for weapon items, their uiIndex and Classindex have to be the same. After you set the item's numbers, make a new entry in weapons.xml that corresponds to that number, and place it at the bottom of the list.




Let's say we're making a new weapon called the "BFG-9000".

First off, we look at weapons.xml, and find that the last entry is used by the RPO-A. The uiIndex of that entry is 918. If we look in Items.xml, we can see that RPO-A's uiIndex is also 918, as is its ClassIndex. Again this is a because weapons need to have the same number in all of these.


Now, if we want to add our BFG, we need to give it a higher number. However the uiIndex 919 is already taken by the Discarded RPO-A item. In fact, the next free Item UiIndex is 1027 (with 1026 used by the Trigger Group item). So we go to the bottom of items.xml, after the Trigger Group item, and make a new item called BFG-9000, with uiIndex 1027.

Conforming to the restrictions on weapons, we put the ClassIndex at 1027 as well. The ItemClass tag should equal 2, 4, 8, 16, 64, or 128, depending on the kind of weapon we're trying to make (see above for a list of Item Classes). Our item is now a weapon.


Next, we go to Weapons.XML, and make a new entry there, below the entry for the RPO-A. We give it a UiIndex of 1027. It doesn't matter that there are no entries 919-1026, it's much more important that we use the same value for the BFG's uiIndex, the BFG's Classindex, and its corresponding weapon entry uiIndex. Very important.





Items of class 2048 are armor items, and will draw data from Armours.xml. Therefore, we need to decide whether we want to use existing armor characteristics or make up new ones. If old armor characteristics are needed (say, to make a camo spectra vest), all we need is to make the item's classindex value similar to that of a Spectra Vest (8).


However, to make a new piece of armor that reacts differently to bullets, we need a new entry in Armours.xml.


We go to the bottom of Armours.XML, and see that the last entry is #82. This defines the protection properties of Leg Protectors.

We copy/paste a new entry right below that one, and change its uiIndex value to 83.


Now you can go to xml_armours to see what each tag means, and change it to fit your needs.


Once you're done making the entry, go back to items.xml and look at the bottom item in the list. This should be the Trigger Guard item, #1026. Copy/Paste a new entry right below it, and change its UiIndex value to 1027. In the ItemClass tag, put in the number 2048 to indicate that this item is an armor. In ClassIndex, set the number to 83, so that our new item reads its armor values from entry #83 which we just made. You can make any number of items that use armor entry #83, if you like.





Items of classes 256 and 512 are capable of exploding. Therefore, we must decide what kind of explosion they produce. The file Explosives.xml is a big list of many kinds of explosions. For instance, Entry #11 has a blast radius of 7 tiles, and causes 65 points of damage. This explosion is used by the C-4 item. Entry #46 creates a cloud of Mustard Gas which lasts of 6 turns. This explosion is used by 40mm Mustard Gas grenades, magazines, and MS Magazines.


We could use an existing explosion for our new item, by setting the item's ClassIndex to the entry number of the explosion we desire.

Alternately, we could make a whole new kind of explosion that doesn't yet exist in the game, by creating a new Explosives.XML entry.


To do this, go to the bottom of the weapons.XML entry, and note the uiIndex. This should be 55, a large-radius, low-damage explosion used by VOG-25P grenades. Now copy/paste a new entry right under it, and give it a uiIndex of 56. You can visit xml_explosives to get an idea of the effect of all these tags.


Now, go to the bottom items.xml, and note the uiIndex of the last item in the list. This should be item #1026, the Trigger Group.

Copy/Paste a new item right below it, and give it a UiIndex of 1027.
For ItemClass, put in 256 for a thrown or launched explosive, or 512 for a settable explosive (or a mortar shell...).

In the ClassIndex of this item, put 56.
We've created an item that will explode with the same parameters you input into explosives.XML.





As explained above, magazines are far tricker than other items, because of the special sorting method used in the file Magazines.XML. If you're going to make new magazines for existing calibers, be ready to work hard.


In most XMLs, items need to be sorted by an incremental UiIndex value. In some, there's even no sorting art all. However, for Magazines, the sorting system relies on TWO things - first, all magazines must be sorted by their Calibers, and only then sorted by incremental UiIndex.


If you look at Magazines.xml, you'll quickly see this - all magazines for caliber 1 come right after one another, then all magazines of caliber 2, then all magazines of caliber 3, etc. And, as in all other XMLs, the UiIndex goes 0, 1, 2, 3, 4, etc.












This is only a small part of the list, which originally contains 266 such entries. As you can see, the magazines with ubCaliber 1 are listed first, and only then the magazines from ubCalibre 2. Also, as you can see, the UiIndexes are incremental (2,3,4,5). If we were to add another magazine that uses calibre 1, it would have to come right in the middle, so that it stays grouped with the other calibre 1 magazines. The trick is, such a new magazine would then have to be UiIndex 4. So what's now #4 has to be changed to #5, and #5 has to be changed to #6, #6 to #7, and so on and so on over the entire 266 magazine list!!! So each new entry would require us to go over the whole file, changing the uiIndexes.


So yes, it's a bitch.


Of course, you might also be trying to add a whole new calibre to the game. This is much simpler, because you'll be making a new group of magazines that can simply be added to the end of the list.

To do this, go to the bottom of the list, and look at the last entry:





This defines the value for the 7-round .50 AE clip.


Now, Copy/paste a new entry below this one. Change the uiIndex to 267.

Now, you can set the ubCalibre to 36, a new calibre. You'll have to define this calibre in AmmoStrings.xml, but we'll cover that later.

In the meanwhile, since this is a new calibre, the new entry can go at the bottom of the list and constitutes its own group. We can later add more magazines for calibre 36 by adding them below this one. But, as the complication explained above still applies, if we would suddenly want to add a magazine of calibre 35 (.50 AE), it would have to be 267, so we'd have to change the UiIndexes of all the new caliber 36 magazines we just made!


Yes, it's a bitch.


After you've set up a new magazine entry, go into Items.xml. Find a free slot where you can put the item (either by overwriting a NADA item or by putting a new item at the end of the list, with a new UiIndex), and change its ClassIndex value so that it equals the UiIndex of the entry in Magazines.xml.


Also, several notes:

A) Weapons can only use one kind of calibre. If you make magazines for a new calibre, make sure you make weapons that can fire them, or edit previously existing weapons so that they use calibre #36.


B) If you make a weapon that can take an irregular number of rounds, you have to make a magazine that can contain the exact same number of rounds.

Example: Currently we have the M-16 which can take a 30-round magazine of 5.56mm ammo. We also have a Minimi that can take a

100-round magazine of 5.56mm ammo. Say we make a new weapon that can take 70 rounds of 5.56mm ammo - we would need to make a magazine that can hold 70 such rounds, because one doesn't exist yet. If we don't make such a magazine, the game will crash.


C) If you make a new magazine size, you need to make several instances of it, for all ammotypes supported by other magazines of the same caliber.


Example: Currently, the 5.56mm ammo comes in AP, HP, Glaser, Cold AP, Cold HP, Cold Glaser, Tracer, and Match. Say we want to make a new weapon that can hold 70 rounds of 5.56mm. We would need to make no less than 8 magazine items, one for each ammo type! This means making making 8 entries in magazines.xml which differ from one another only in the <ubAmmoType> value, and 8 items in Items.xml, with each item's ClassIndex equalling the UiIndex for the appropriate new entry.


Yes, it's a bitch.


D) the <ubAmmoType> value points to entries in Ammotypes.xml. Check out xml_magazines to see the choices you get by default. You can edit Ammotypes.xml to add new types.



So far we've learned how to make a new entry in Items.XML, and make it point to new entries in other XMLs, as neccesary.

If you're still confused about some of the tags, visit modding_and_customizing for a rather useful list of

all tags used and a brief explanation on each.


So this is the first part of the tutorial, and hopefully it has helped some.


In the next part, I'll try to explain how to make attachments and merges.


See also

Comments (0)

You don't have permission to comment on this page.