Extending GDAs tutorial

From Dragon Age Toolset Wiki
Revision as of 11:33, 3 August 2016 by DarthParametric (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Dragon Age makes extensive use of 2DAs to define things. As such, a fundamental requirement for many mods is editing the information contained within one or more 2DAs, be it changing existing values or adding additional content. As the game can only address a single copy of any one file, problems would occur if multiple mods each included edited copies of the same 2DA. Fortunately, the 2DA system makes provision for this via M2DAs (Multiple 2DA). This system allows most 2DAs to be extended (only replacing specific content/adding new content) rather than overridden (replacing the entire file). In this way, edits of a single 2DA across multiple mods can effectively stack without conflicting with one another.

A note on file formats/nomenclature. Whilst 2DAs are essentially just simple spreadsheets and the source files are provided in XLS (Excel) format, the game (and toolset) requires that they be encapsulated in the GFF formatted version known as GDAs in order to be useable.

Overview

In order to illustrate the process of extending a GDA, we will use a set of armour as an example. Weapons and armour collectively are one of the most common types of mod, and both are functionally identical in terms of GDA extension. The general principles are also applicable to all other types of GDA extension.

In this particular instance, we will make a new set of massive armour comprising the chest piece, gloves, and boots. Rather than override the appearance of existing items, we will take advantage of GDA extension to add these to the game as an additional set of item appearances. In terms of DA items, this is referred to as adding a new variation. Note that a variation is just a physical appearance (i.e. a specific model and texture combination) and separate from the concept of an item in its in-game usage (i.e. stats and properties). A single item can use any of the different variations that have been defined for that particular item type by the appropriate GDA.

Source File Preparation

To begin with, we need the model files and associated textures. Models may be custom made, or, as in this example, simply renamed copies of base game models. In either case, it is important to follow the appropriate DA naming conventions. The Human male models for our example will be named as follows:

Chest piece: hm_arm_goldena_0
Boots: hm_boo_goldena_0
Gloves: hm_glv_goldena_0

Models for LODs and other sex/races should follow the same format.

Now we need to obtain the relevant 2DAs. The source files for the game’s 2DAs are located in <DA install dir>\tools\Source\2DA\ and its sub-folders. For M2DAs, a list is given in the M2DA_base sheet of 2DA_base.xls. Note that M2DA_base only lists the worksheet name, not the file name. As many 2DAs are often stored together as separate worksheets in a single file, particular 2DAs are sometimes difficult to locate due to obscure/unintuitive file naming on Bioware’s part. In these instances it may be more expedient to simply extract the compiled GDA version of the 2DA from the game files and convert it to an XLS using GDApp. Alternatively, refer to this table of 2DA files/worksheets.

In this case we are interested in the worksheets armor_massive_variation, boots_massive_variation and gloves_heavy_variation. These can be found in ItemVariations.xls, located in <DA install dir>\tools\Source\2DA\rules\. Rather than editing the source file, copy these 3 worksheets to a new file (keeping each to their own worksheet).

2DA Editing

Using the existing rows as a guide, add a new row to each sheet with the pertinent info for the corresponding model. This is why following the proper file naming convention is important. You can duplicate the cell values of the existing rows for the icon, material and sound columns. The label column dictates what name for the variation will appear in the toolset, so use a value in this cell that is descriptive enough to recognise later. Finally, we need to add a custom ID number for each row. The original intention for this system was to allow IDs to range up into the billions, thereby reducing the likelihood of incompatibilities between mods due to ID clashes. Unfortunately, due to the presence of a bug in the GFF item file format (UTI), items can only use IDs up to 255. Therefore, if you are releasing your mod publicly there is a high likelihood of it being incompatible with some other mods due to ID clashes. Bearing this in mind, choose a suitable ID higher than the existing values but below 255 for each sheet. These don’t have to be the same – each ID number is only relevant to the specific item class of its associated variation 2DA.

Once each worksheet has a fully filled out row for each of your new item variations, you can delete the other existing rows except for the two header rows. You should be left with something like this:

Extended armor_massive_variation Worksheet
ID LABEL MODELTYPE MODELSUBTYPE MODELVARIATION ICONNAME DEFAULTMATERIAL SoundMatType
int string string string string string int int
105 Golden Armour arm golden a **** 2 13
Extended gloves_massive_variation Worksheet
ID LABEL MODELTYPE MODELSUBTYPE MODELVARIATION ICONNAME DEFAULTMATERIAL
int string string string string string int
105 Golden Gloves glv golden a **** 2
Extended boots_massive_variation Worksheet
ID LABEL MODELTYPE MODELSUBTYPE MODELVARIATION ICONNAME DEFAULTMATERIAL
int string string string string string int
105 Golden Boots boo golden a **** 2

The final remaining step is to give each worksheet an appropriate name. In accordance with the M2DA system, each worksheet name must have a unique epithet appended to it. However, the character limit for the full worksheet name is capped at 27. Because the epithet must be prefixed with an underscore, many extended variation GDAs only have room for extremely short epithets. In the case of the current example, the chest piece and boots worksheet names both have 23 characters, whilst the gloves worksheet has 24. With 1 character lost to the underscore, that leaves 3 characters available for the former and only 2 for the latter. In the current example, the following was chosen:

armor_massive_variation_gld

boots_massive_variation_gld

gloves_massive_variation_gd

N.B. As with the ID number bug, the restrictions of the epithet length greatly increase the likelihood of clashes in some instances, so keep this in mind if publicly releasing a mod.

Compiling GDAs

With the 2DA worksheet editing finished, they now need to be compiled into the GDA format so that they are useable by the game and toolset. Move/paste a copy of the XLS into <DA install dir>\tools\ResourceBuild\Processors\ and then drag and drop it over ExcelProcessor.exe. A command-line window (i.e. DOS box) will briefly appear. If there are no problems, the window will close and one GDA for each worksheet will appear in the folder. If the window stays open, there has been some sort of error, which the processor should detail (commonly worksheet names longer than 27 characters). If this is the case, fix the XLS and try again.

The GDAs can now be moved to the appropriate folder for your Addin. You may first wish to check them with GDApp to confirm all the values are correct. GDApp will allow you to edit GDAs directly, saving the need for recompiling from source XLS files.

Testing

With the toolset open and your module loaded, either open an existing item or create a new one. In either case, make sure it is the appropriate type for the variation/s you have created. Now you should be able to go to the Item Variation section and select your newly added variation from the drop-down list. If all went to plan, you should get something like this:

Extending GDA Toolset.jpg

If everything works as expected then you can export your items/module for use in the game. Make sure you test any content in the game before releasing it publicly.

Extending GDA Game Test.jpg

Troubleshooting

The two most likely issues to occur are either your variation not appearing in the drop-down list, or when selecting it for there to be no model present. Both can be caused by GDA issues, but the latter may also be caused by problems with the model/s.

If the variation doesn’t appear in the list, check that the GDA filename (i.e. 2DA worksheet name) is correct. Also check if there is a clash between your chosen ID number and those of any other mods you may have installed.

If there is no model visible when you select your variation in the toolset, ensure that your GDA specifies the correct model name/s. Also make sure that you have models for the specific race/sex combination you are making an item for. As you will have noticed, when adding the filename information to the 2DA, you don’t enter any MainClass (i.e. race/sex) detail. Thus, a single row makes provision for all race/sex combinations. Therefore the toolset will apply your variation to any item of that class, expecting there to be a model present. Additionally, when extending GDAs outside of items, be aware that you may have to extend multiple GDAs to get the toolset to recognise your custom content. This is primarily the case in instances such as custom monsters/races, where specific creature/part variation GDAs may need to be extended as well as the appearance GDA.

If your item appears in the toolset but not in the game, it is almost always due to the aforementioned high ID bug. Check your GDA and lower the ID number under 255 if necessary.

Resources

The source material used for the above example is available here.