Difference between revisions of "2DA"

Revision as of 01:02, 25 January 2010

Many of the properties of objects in the toolset make reference to 2DAs (two-dimensional arrays). These are read-only arrays containing various data used by scripting and the game engine. For example, the set of local variables that an object supports is defined in a 2DA.

Overview

Simplified the 2DAs can probably be seen as laying the stack of cards which is swords, enemies, and variables to them. In which context the games rules set by the Gameengine and Scripts would tell who can draw which card, and the Gamedesigner distributes these cards to participants.

There is a tight connection between all 3 of those, and linking to and from and inbetween 2DA's is done via ID's. An Designer creating an Item for example links to ID's of BITM_base and ItemVariations giving the Item a Base Type with which the Gameengine can apply rules, and a Model to display it if Basetype properties allow ,set in a 2DA as well. Also it is the Gameengine who knows what column to look for Values, and it allows setting a Base Type in the first place, so that the link to BITM_base exists.

Of course it is a bad idea to break any of those links. However, adding anything is possible, which requires to stay with the original layout and knowledge about the sources needed. Only a Designer would have to "lay the new cards". Or creating entirly new 2DA's is also possible, which additionally requires to create Scripts ,so the Gameengine will know the new 2DA exists.

The source files for 2DAs are Microsoft Excel worksheets. This allows a wide variety of sophisticated techniques to be used to generate the values of the 2DA fields, such as macros and formulas. It also makes editing much easier since the columns can be annotated and formatted in helpful ways, and multiple related worksheets can be grouped into one file. Before they can be used by the toolset or the game, 2DAs must be converted from Excel files into a more efficient form. Processed 2DAs are stored in files with the .GDA extension.

Excel file formatting

Data in a 2DA is identified by a row number, with the first row (row zero) usually being reserved for internal use (undefined value, etc.) by convention. Each row has an arbitrary number of columns identified by strings. The grey fields in this example table are very specific to the 2DA, the white fields are arbitrary data which the Gameengine identifies for that 2DA.

The ID of a Row is the reference for the Game to access and link to them. As such they are unique across the 2DA, and any M2DA that extends it. The contents of each column is specific to the 2DA given, and arbitrary. When extending a 2DA, new ID's have to be given, and Columns have to be exactly the same.

Guidelines

• Cell A1 will contain "ID". This is checked by the processor and the worksheet will fail if this is not the case.
• Column A starting at line 3 will contain an integer row ID number that is unique to that row across all files (unless creating an M2DA override). Row IDs will be listed from smallest to highest within the same file and do not need to be consecutive.
• A blank row or column will determine the dimension of the spreadsheet in that direction. Everything past that point is ignored by the binarizer.
• Column names are case sensitive. This is because of the CRC32 algorithm used to generate the hash key. Changing the case of a column name after it is in use will break the game. White space before and after a column name will be removed before hashing.
• Row 2 will be a "types" row. Each is a single word: int, string (single chars as well), resource, float or bool. A special type "comment" can be used to exclude a column from export.
• Any column with string data that refers to files should have a type of "resource" and not "string". This is because the "resource" type is used to determine dependencies for the 2DA file.
• 'bool' type may be one of: a zero or non-zero number, Yes or No (case insensitive), or words beginning with T or F (such as True! and False!). NOTE: You cannot use TRUE and FALSE because Excel converts those to a special keyword the binarizer can't parse properly at this time. Note: the scripting language doesn't have a function for retrieving boolean values from a 2DA, and the behavior of Get2DAInt when retrieving a boolean is untested. It is probably safer to just use an integer for scripting purposes.
• If you wish to leave a cell unfilled, the string "****" (four asterisks) can be inserted instead of a value.
• Any worksheets that are not exportable 2DA data will have an underscore prepended to their name - the resource builder will subsequently ignore them.
• Worksheets need to have unique names among all excel files, duplicates will overwrite each other as each worksheet is exported as a file
• You cannot have the workbook open in Excel at the same time as running the binarizer on it.
• Strings have a maximum length of 768 characters. Anything longer will be truncated.
• ExcelProcessor.exe constrains the name length of a worksheet to 27 characters.

Extending the game via M2DAs

An "M2DA" is a "Multiple 2DA" that stacks a number of 2DA files into one larger table. They work much like single 2DA files except they can be patched or expanded later by adding more resources. These are useful for any table that lists other resources, such as appearance tables, so that new resources can be added later without having to modify a monolithic table. 2DAs are merged row by row, keyed on the ID column.

This is especially important for third-party modders, since BioWare might release an update to a core table at a later date that would overwrite any changes third parties had made to it. By using an M2DA with a unique name, and by using a range of ID numbers significantly separated from those already in use, you can ensure that your additions won't conflict with other portions of the M2DA.

A list of all M2DAs used by the game can be found in 2DA_base.xls. Every 2da listed in M2DA_base is treated as a M2DA, except for those with an ID between 10000 and 10999 which are handled as regular 2DAs. Each M2DA has a label that describes the subject covered by the M2DA and a worksheet prefix that all components of that M2DA must use.

Every worksheet listed in the 2DA_base.xls file is actually a prefix. The system reads this prefix and then searches through all the 2DAs for the ones starting with this prefix and merges them together as one 2DA. For example: M2DA ID 0 is "ANIM_". The system looks through its list of 2das and finds "ANIM_base", "ANIM_combat" and "ANIM_walk". It will read and merge all 3 2DAs into an M2DA called "ANIM_".

This example 2DA "MonstersCustom" would be merged into the original 2DA "Monsters", if "Monsters" were one of the worksheets listed in the M2DA_base.

Converting XLS files into 2DA files

In the "Dragon Age\tools\ResourceBuild\Processors" folder there is an executable named "ExcelProcessor.exe". This is the file that handles conversions from XLS to 2DA format. Below are described 3 ways in which this file may be used.

Drag & Drop Method

1. Copy ExcelProcessor.exe and source .XLS files to a new directory (not explicitly neccessary, but advised)
2. Select source .XLS files and drag them onto ExcelProcessor.exe
3. Cut & Paste resulting .2DA files, which will be located in the same directory as the source .XLS files, to your desired location (usually to "My Documents\BioWare\Dragon Age\AddIns\yourmodulename\module\overrides\")

Adding 2DA export to the Windows XP file explorer

Here's an easy way to add a context (ie, right-click) menu item that quickly converts new or updated Dragon Age Excel files into GDA format:

Setup:

1. Open Windows Explorer and click Tools | Folder Options.
2. In the File Types tab, select the XLS extension from the list and click the Advanced button.
3. Click the New button and put 'Binarize 2DA' in the Action field.
4. Paste the following in the Application field and click OK (update the drive and folder names to match your client): "C:\Program Files\Dragon Age\tools\ResourceBuild\Processors\ExcelProcessor.exe" "%1" -outdir="C:\Documents and Settings\YOURNAME\My Documents\BioWare\Dragon Age\packages\core\override"
   1. For the Steam version, use the following: "C:\Program Files\Steam\steamapps\common\dragon age origins\tools\ResourceBuild\Processors\ExcelProcessor.exe" "%1" -outdir="C:\Documents and Settings\YOURNAME\My Documents\BioWare\Dragon Age\packages\core\override"

Note that paths with spaces in them can cause Windows trouble, if your paths have spaces in them remember to wrap them in quotation marks.

Usage:

1. Using Windows Explorer, navigate to your 2DA folder (in my case C:\DA\tag\main\data\Source\2DA) and select the Excel file(s) to process. Right click and select 'Binarize 2DA' from the context menu.
2. Confirm a corresponding GDA file is created in your override folder (in my case C:\DA\tag\main\build\packages\core\override) for each Excel file processed.

An example of how setting this up in Windows XP looks

Using a .BAT file

The following method may work better for you instead:

• Create two folders called C:\2DA\ and C:\2DA\Override\
• Copy ExcelProcessor.exe to C:\2DA\
• Copy the Excel spreadsheets containing the 2DA you want to use in the game to C:\2DA\
• Create a batch file with the following line in it (change "placeables.xls" to whatever Excel file you're working with):

C:\2DA\ExcelProcessor.exe placeables.xls -outdir=C:\2DA\override\

• Run your batch file
• Find the GDA file from the C:\2DA\Override\ directory and copy it to the game's override directory. Remember to take into account the naming conventions of M2DAs; you may need to rename your 2DA files with a new suffix unique to your module to allow it to add to the core 2DAs without conflict.
• If you copied your new 2DA file in your Override directory while Dragon Age Game was running, you will need to exit to windows and re-run the game to let your changes to work.

2DA XLS files used in Dragon Age

Note: This list is very incomplete right now

Bear in mind that 2DAs names are actually based on the names of the worksheets inside these Excel files, not the names of the files themselves. Some of these files contain a large number of individual 2DAs within them. They are bundled together into Excel files based on the nature of the 2DAs for convenience. They can be found under the toolsets directory

*Installdir*\Dragon Age\tools\Source\2DA\

Creatures

• APR_base.xls - appearance types for creatures
• ABI_base.xls - integrates all talents and spells into the game
• ANIM_base.xls
• ANIM_combat.xls
• ANIM placeables.xls
• SyncAnimations.xls
• CLA_base.xls - Defines the character classes used throughout the game
• background.xls - defines the various origin stories available to each race and class.

Objects

• placeables.xls - interactive object types
• BITM base.xls - item types
• ItemVariations.xls - item appearance variations (eg, all the different ways a longsword can look)
• PRJ_base.xls - how various projectiles look and behave
• VFX_base.xls - Visual effects

Areas and plots

• worldmaps.xls - world maps for open-ended travel between areas
• plottypes.xls - how plots are grouped at the highest level in the game GUI (codex entry types, story, etc.)
• areadata.xls - sets various properties for specific areas
• rewards.xls - rewards for plot completion

Adding to the official campaign

• PRCSCR - specifies scripts to run when an area or area list is loaded or entered.

Adding Strings

When adding strings to a 2DA, you have two options. The simplest is to enter **** for the StringID column. In that case, the name column will be used in the game.

The other approach is to use the toolset's string editor to create a new string. When that happens, you'll get a new StringID. Next enter that number into the StringID column in the 2DA.

The second approach works better when translating your module, at the cost of portability. If someone else wanted to reuse your 2DA, they'd have to generate their own strings, then update the StringID number based on these IDs.

Attention:

• The current version of the "ExelProcessor"-App is buggy as it can't hanlde INT values above 8388607! Many thanks to elys for figuring that out.
• Also note that the original toolset (v1.0) core-talktable contains wrong ids as well - don't forget to delete it from the "packages\core\override\toolsetexport" directory if you are still using that version.

Workaround:

• Create and export your talktable, delete the core-talktable override.
• Create your M2DA File that you want to refer to your talk-table strings. Never Mind using the real IDs at this stage.
• Use the "Exelprocessor" to create the GDA file.
• Open the GDA-File with the toolset or elys's GDA-Editor App (http://social.bioware.com/project/755/)

• Change the StringIDs to the StringIDs in your talktable.

Remark:

The previous Version stated: Take that StringID and add 16777216 to the number. this appears to be wrong and is likely a holdover from NWN.

Reserved ID Ranges

While M2DA files avoid some of the problems associated with ordinary 2DA files, the IDs in each row of the final M2DA must still be unique across all 2DAs associated with it.

To help ensure compatibility between authors' custom content, you should make sure that the ranges you choose don't conflict with ones already in use: 2DA_ranges_in_use.

Users of Open Office

• Users of Open Office may find that no .gda file is created when they use ExcelProcessor.exe - one workaround is to copy a worksheet from an existing .xls file (such as placeable_types from placeables.xls), process the file, then remove the extraneous .gda file (e.g. placeable_types.gda). Alternately, upload your .xls file to Google Docs and then download the file as Excel format, then process the file with ExcelProcessor.exe.