Sunday, May 6, 2012

Creating New Life with the Expotron and Max, Part 2: 2DA Files for Creatures

This is Part 2 of my tutorial on bringing new creatures to NWN2 using 3DS Max and the Expotron. Part 1 of this series may be found here.

To bring new creature models to NWN2, you will need to edit a few 2DA files. The term “2DA” stands for two-dimensional array. Every 2DA file is a text file comprising a number of rows of text. Within each row is a number of strings that are delimited by tabs or spaces to form a set of columns. With the exception of the first few header lines, the number of columns is the same from one row to the next. Hence, the text can be arranged into a two-dimensional array that is readily apparent with the right software.

All the game resources created by Obsidian Entertainment can be found in the Data subfolder of your Neverwinter Nights 2 installation folder. The 2DA files may be found in 2DA.zip, 2DA_X1.zip (which is present if you installed Mask of the Betrayer), and 2DA_X2.zip (which is present if you installed Storms of Zehir). Never edit any of the original game resources in their installation folders. Always put a copy of the relevant files in the folder ‘My Documents\Neverwinter Nights 2\override” and edit those copies.

You can edit 2DA files in a text editor like Notepad, but then the tab-delimited text may be difficult to read because it is not obvious which column the strings in each row belong to. I prefer to open 2DA files in Microsoft Excel because it can automatically arrange the text into rows and columns. What’s more, you can freeze panes in Excel so that the topmost row and the LABEL column are always in view. When you edit 2DA files and save them, Excel will preserve the tab-delimited format.

If you don’t have Excel, you can find a number of 2DA editors at the Neverwinter Vault. The ones I tried replace all the tabs with several spaces so that the columns can be read easily in a text editor. My advice is to never ever replace each tab with more than one space. Doing so will cause the engine to take up more time reading 2DA files. Reading five spaces is five times slower than reading one tab. NWN2 is slow enough as it is without custom content. Don’t make it unnecessarily hard for the engine to do its job. If you can find a good 2DA editor that preserves the tab-delimited format instead of replacing tabs with spaces, use it.

Appearance.2da

When you create a new creature for NWN2, the first 2DA file to edit is appearance.2da. If you have the Storms of Zehir expansion installed, the latest version of appearance.2da can be found in 2DA_X2.zip. If you have only the Mask of the Betrayer expansion, you can extract appearance.2da from 2DA_X1.zip. If you don’t have any of the NWN2 expansions, then you will find the file in 2DA.zip.

Perhaps the easiest way to add an entry for your new creature model is to copy one of the rows whose LABEL column isn’t set to “****” and paste it as a new row at the end of the file. Change the numerical index of the new row (i.e., the leftmost data on that row) so that it will be equal to one plus the index of the previous row. Set the LABEL column of the new row to be the name of your creature. Don’t use spaces in the label. If you need to separate two or more words within the same column, use an underscore instead. Unless you’ll be using and distributing a custom TLK file with your model, set the STRING_REF column of your row to “****” (without the quotes).

There are other columns to edit on your new row, many of which may appear perplexing. You can try to understand more about them by reading the page on appearance.2da at the NWN2 Wiki, but I’ve found that the information on some of the columns is missing or erroneous. I know about the mistakes in the Wiki because I managed to download Bioware’s original documentation on the format of creature-related files for the Aurora engine, and there are discrepancies between it and the Wiki page.

To help you and me navigate this file, I have assembled a guide on the columns to enter. I admit that a lot of this information came from the NWN2 Wiki, but I’ve also inferred which data are probably wrong and edited them accordingly. I’ve tried to fill in missing information as best I could, but there are still three columns that I cannot explain. In all likelihood, these columns have no effect in the game proper. I cannot guarantee with absolute certainty that all of my descriptions are correct, so I invite readers to post comments on any errors that they find.


Column
Description
INDEX (no actual name)
Sequential and unique row number. When appending a new row at the end of the file, always set this value to be one plus the INDEX of the previous row.
LABEL
Name of the model, for the reference of human readers. May be used as the model’s name in the Toolset if the "STRING_REF" column is blank (****).
STRING_REF
A unique numerical identifier that points to a DIALOG.TLK entry, which is the name of this model as it appears in the Appearance dropdown box of a creature’s Properties in the toolset. If blank (****), the toolset uses the LABEL instead.
BodyType
0 if the entire model is in a single MDB file; 1 if the model is split into two or more MDB files (say, for the body, head, tail, etc.) Note that alternative heads, clothing, accessories, cloaks, and wings may only appear on models whose BodyType = 1. Tails, on the other hand, may appear on any model.
Segments
Unknown use. Always set to 0
NWN2_Scale_X
Width scaling. Pre-scales the model used by the appearance entry. Also affects the scale of any weapon models and accessory models
used by the model. A value of 1 retains the model’s original scale. Note that this entry affects the speed of animations along the x-axis by its inverse. Hence, setting this entry to 1.5 (three-halves) will reduce animation speed along the x-axis to two-thirds of its original speed.
NWN2_Scale_Y
Depth scaling. Pre-scales the model used by the appearance entry. Also affects the scale of any weapon models and accessory models
used by the model. A value of 1 retains the model’s original scale. Note that this entry affects the speed of animations along the y-axis by its inverse. Hence, setting this entry to 1.5 (three-halves) will reduce animation speed along the y-axis to two-thirds of its original speed.
NWN2_Scale_Z
Height scaling. Pre-scales the model used by the appearance entry. Also affects the scale of any weapon models and accessory models
used by the model. A value of 1 retains the model’s original scale. Note that this entry affects the speed of animations along the z-axis by its inverse. Hence, setting this entry to 1.5 (three-halves) will reduce animation speed along the z-axis to two-thirds of its original speed.
AnimationSpeed
Changes the speed of animations by 1 plus the value of this entry. A value of 0 will not change the animation speed. Setting this entry to 1 will double the animation speed, and setting it to 2 will triple it.
NWN2_Model_Body
Prefix of the body model to use. Models for player races must strictly adhere to the naming convention explained in the NWN2 Wiki, but non-player creature models may use any name that uniquely identifies them. A question mark (?) in this column is a wildcard for the creature’s gender. The game will replace the “?” with “F” or “M” depending on the creature’s sex.
NWN2_Model_Helm
Prefix of the helmet model to use. Helmets for player races must strictly adhere to the naming convention explained in the NWN2 Wiki, but helmets for non-player creature models may use any name not used by other helm models. A question mark (?) in this column is a wildcard for the creature’s gender. The game will replace the “?” with “F” or “M” depending on the creature’s sex.
NWN2_Model_Head
Name of the head model to use. Head models for player races must strictly adhere to the naming convention explained in the NWN2 Wiki, but head models for non-player creature models may use any name that uniquely identifies them. A question mark (?) in this column is a wildcard for the creature’s gender. The game will replace the “?” with “F” or “M” depending on the creature’s sex. . If the model’s head is not stored in a separate MDB file, this entry should be blank (****).
NWN2_Model_Hair
Name of the hair model to use. Hair models for player races must strictly adhere to the naming convention explained in the NWN2 Wiki, but non-player hair models may use any name that uniquely identifies them. A question mark (?) in this column is a wildcard for the creature’s gender. The game will replace the “?” with “F” or “M” depending on the creature’s sex. For models whose BodyType = 1, this entry is not blank even if there is no separate MDB file for the hair model.
NWN2_Head_Skeleton
Name of the skeleton (GR2 file) that the head model will use. Skeletons for player races must strictly adhere to the naming convention explained in the NWN2 Wiki, but non-player skeletons may use any name that uniquely identifies them as long as the name ends with  “ _skel. ”  A question mark (?) in this column is a wildcard for the creature’s gender. The game will replace the “?” with “F” or “M” depending on the creature’s sex.  This entry is blank (****) if BodyType = 0.  If BodyType = 1, this column should not be blank even if the model does not have a separate MDB file for its head. If the head and body use the same skeleton, then this entry should be the same as that of NWN2_Skeleton_File.

Note that the skeleton structure of NWN2_Head_Skeleton and NWN2_Skeleton_File are essentially the same. The only difference is in the placement of bones, which may be slightly different, and in the animations used. Otherwise, the number of bones in both files, their names, and their placement in the hierarchy are the same.
NWN2_Skeleton_File
Name of the skeleton (GR2 file) that the body model will use. Skeletons for player races must strictly adhere to the naming convention explained in the NWN2 Wiki, but non-player skeletons may use any name that uniquely identifies them  as long as the name ends with  “ _skel. ”  A question mark (?) in this column is a wildcard for the creature’s gender. The game will replace the “?” with “F” or “M” depending on the creature’s sex. The entry for NWN2_Head_Skeleton and NWN2_Skeleton_File may be the same.
NWN2_AccessorySize
Unknown use. Changing its value has no effect on the size of accessories worn by the model.
NWN2_AccessoryType
A short code that uniquely identifies the armor/clothing accessory models that this creature may use. A question mark (?) in this column is a wildcard for the creature’s gender. The game will replace the “?” with “F” or “M” depending on the creature’s sex. If this column is left blank (****), the creature will not use armor/clothing accessories.

The actual name of accessory models will be based on the code given in this column as well as the body part on which the accessory will be worn. This name must follow the naming convention for accessories found in the NWN2 Wiki, but with the RaceGender code replaced by the entry in this column. For example, the value of NWN2_AccessoryType for  NPCKingOfShadows (INDEX = 586) is L. Hence, the left bracer model that the King of Shadows may wear is stored in A_L_LBracer1.MDB.
ToolsetUseStubModel
Set to 1 if the toolset should use a small yellow pyramid instead of the creature’s actual model to represent the creature. Set to 0 otherwise. Creatures with no visible model should have this entry set to 1. All other creatures should have this value set to 0. The value of this column will only affect the creature’s appearance in the toolset, not in the game.
Mount
An integer value apparently intended for a Mount feature that never made it to NWN2. This entry may be safely set to 0.
NAME
An identifier or descriptor of the model for the developers’ reference. For playable characters, this is set to “Character_model”. This column does not seem to have any impact on the toolset or the game, and it may be safe to set it to any non-blank string.
RACE
This is an obsolete holdover from NWN. For playable races (MODELTYPE = P), this is a single uppercase letter that indicates which part-based models may be used.

D - Dwarf
E - Elf
G - Gnome
A - Halfling
H - Human and Half-elf
O - Half-orc

For all other creatures, this is supposed to be the unique identifier for the creature’s MDL file (an NWN file format similar to that of NWN2’s MDB files).

This column is not linked to racialtypes.2da or racialsubtypes.2da.  As a code for filtering part-based models, this column has been superseded by other columns; namely, NWN2_Model_Body, NWN2_Model_Helm, NWN2_Model_Head, NWN2_Model_Hair, and NWN2_AccessoryType. It is likely that this column has no actual use in NWN2.
ENVMAP
This is a holdover from NWN that refers to the environment map applied to the texture’s alpha channel. In NWN, a blank entry (****) allowed parts of the creature to be transparent where the alpha channel of the corresponding area in the texture was black. “Default” was for creatures with some reflective surfaces such as on their armor. An iridescent rainbow hue effect was applied on creatures with “evmap_irrid” set in this column. ENVMAP is obsolete in NWN2 and may be left blank (****) or set to “default” (without the quotes).
NWN2_BLOODTYPE
Reference number for a row located in the NWN2_BloodTypes.2da that defines which SEF files are used for this model’s blood visual effect.
MODELTYPE
This appears to be an obsolete holdover from NWN. This column indicated the type of model that creatures of this appearance had. The following values were valid for this column in NWN:

P  - Player. The model is composed of multiple body parts stored in their own MDL files (the NWN equivalent of NWN2’s MDB file). All colors are selectable for this model’s meshes. P models also have nodes that allow tails and wings to be attached to them in the game, particularly for Red Dragon Disciples.
S  - Simple. The model is completely stored in a single MDL file, and its colors are fixed. The model’s appearance does not change when wearing armor or equipping weapons.
F  - Similar to Simple, but weapons appear when wielded on the left or right hand.
L  - Large. Similar to F, but weapons appear only on the right hand of the creature.
FW - Full, with Wing node
FT - Full, with Tail node
FWT - Full, with both Wing and Tail nodes

In NWN2, this column seems to have been replaced by BodyType. Obsolescence aside, this column should probably be set to the most appropriate code to be on the safe side.
WEAPONVISUALSCALE
A floating point number indicating the scale of weapons wielded by the model. This is cumulative with the scaling done by NWN2_SCALE_X, NWN2_SCALE_Y and NWN2_SCALE_Z.
WEAPONATTACKDISTANCESCALE
Scales the weapons’ PreAttackDist value found in Baseitems.2da to match any visual scaling done through the entry on WEAPONVISUALSCALE.
WING_TAIL_SCALE
Scale of wings and tail to appear on the model
HELMET_SCALE_M
Scale of helmets to appear on male creatures.
HELMET_SCALE_F
Scale of helmets to appear on female creatures.
MOVERATE
Default movement speed of the model. Specifies a row in creaturespeed.2da  that has this value in its 2DAName column to determine the creature’s rate of walking and running in meters per second. Possible values are the following:

VSLOW - Very Slow
SLOW  - Slow
NORM  - Normal
FAST  - Fast
VFAST - Very Fast
WALKDIST
Distance in meters traversed by the creature from the start to the end of its walk animation.
RUNDIST
Distance in meters traversed by the creature from the start to the end of its run animation.
PERSPACE
Personal space. The minimum amount of space in meters from the creature’s center (i.e., the pivot position of its mesh in 3DS Max) to other non-creature objects. Used to determine if the creature will fit through an opening.
CREPERSPACE
The minimum amount of space in meters from the creature’s center to other creatures’ center. Used during combat.
HEIGHT
This is supposed to be the height of the creature in meters, although in NWN2, this does not seem to consistently be the case. In NWN, this entry was used for path finding under obstacles and to determine the zoom-in camera height. This column may be obsolete in NWN2.
HITDIST
How far an attacker must be from this creature to hit it in melee, not counting the attacker’s reach. In combat, this value is subtracted from the actual distance in meters between the creature and its attacker before comparing the result to the attacker’s PREFATCKDIST. If the result is less than or equal to the attacker’s PREFATCKDIST, then the creature is within reach of the attacker. Note that distances between objects are always measured from their centers (i.e., the pivot positions of their mesh in 3DS Max), so a wide creature would need a high HITDIST value.
PREFATCKDIST
Preferred distance in meters from which to attack a target. This value may be thought of as the creature's reach in melee.
TARGETHEIGHT
The height at which the creature's attacks will strike. H if the creature strikes high or L if the creature strikes low.
ABORTONPARRY
1 if the creature’s attack animation aborts when its enemy parries its attack; 0 otherwise
RACIALTYPE
In NWN, this was supposed to be an index into racialtypes.2da, indicating the creature’s default racial type. In NWN2, however, this does not seem to be the case any longer. Since a creature's race may be selected in the toolset by setting its Subrace, this column is probably obsolete.
HASLEGS
1 if the creature has legs, which can be targeted with a called shot; 0 otherwise
HASARMS
1 if the creature has arms, which can be targeted with a called shot; 0 otherwise
PORTRAIT
This is supposed to be the name of the portrait file to use as the creature’s icon in the game. Setting this to a non-blank value (****) will not load any portrait file, however. It seems that the only way to make the game load a portrait is to set the creature's Custom Portrait attribute in the toolset to the name of the portrait file.
SIZECATEGORY
A numerical index to creaturesize.2da . Valid values are as follows:

1 = TINY (-2 attack, +2 AC)
2 = SMALL (-1 attack, +1 AC)
3 = MEDIUM (0 modifiers)
4 = LARGE (+1 attack, -1 AC)
5 = HUGE (+2 attack, -2 AC)
PERCEPTIONDIST
Index into a row number in Ranges.2da that sets the creature’s default perception range.
FOOTSTEPTYPE
Index into footstepsounds.2da indicating which set of footstep sounds to use on each type of terrain. A value of -1 indicates that the creature will make no sound when moving.
SOUNDAPPTYPE
Index into appearancesndset.2da to indicate the creature’s sound set
HEADTRACK
1 if the creature’s head tracks nearby creatures, speaking creatures, or objects being moused over by the player; 0 otherwise. This is an obsolete column left over from NWN. Head tracking is not implemented in NWN2.
HEAD_ARC_H
Maximum horizontal arc in degrees for head movement. This is an obsolete column left over from NWN. Head tracking is not implemented in NWN2.
HEAD_ARC_V
Maximum vertical arc in degrees for head movement. This is an obsolete column left over from NWN. Head tracking is not implemented in NWN2.
HEAD_NAME
Name of the head node in the model’s skeleton to rotate when tracking objects. This is an obsolete column left over from NWN. Head tracking is not implemented in NWN2.
BODY_BAG
Which body bag type to use when the creature is killed (see bodybag.2da)
TARGETABLE
1 if the creature can be targeted when the mouse hovers over it; 0 otherwise
SELECTION_CAPSULE
Unknown use. It may have been intended as a boolean value (0 or 1) that controlled whether a selection circle should appear at the base of the creature when the player right-clicks it. Regardless of its value, however, a selection circle will appear at the base of a right-clicked creature.
SELECTION_SIZE
An integer value that controls the size of the selection circle that appears at the base of the creature when a player right-clicks the creature in the game.
SEF
Special effect SEF to apply to appearance


Wingmodel.2da

If your creature model includes a wing mesh in a separate MDB file, you should edit a copy of wingmodel.2da to include data on the wing mesh. If you have the Mask of the Betrayers expansion, you can find the most updated copy of this file in 2DA_X1.zip. Otherwise, you’ll have to use the file found in 2DA.zip.

As with appearance.2da, you add an entry for a new wing model by appending a new line at the end of wingmodel.2da and setting the index of the new row to be one plus the index of the previous row. Below are details on each column of wingmodel.2da.

Column
Description
INDEX (no actual name)
Sequential and unique row number. When appending a new row at the end of the file, always set this value to be one plus the INDEX of the previous row.
LABEL
Name of the wing model, for the reference of human readers. Can be used as the model’s name in the Toolset if the "STRING_REF" column is blank (****).
STRING_REF
A unique numerical identifier that points to a DIALOG.TLK entry, which is the name of this wing model as it appears in the Wings dropdown box of a creature’s Properties in the toolset. If blank (****), the toolset uses the LABEL instead.
NWN2_Model_NAME
Name of the wing model to use. This should also be the name of the MDB file where the mesh is stored. This can be any name that uniquely identifies the model.
NWN2_Skeleton_File
Name of the skeleton (GR2 file) that the wing model will use. This can be any name that uniquely identifies the skeleton as long as it ends with “_skel.”
NWN2_BaseAnims
Prefix of the animation files to use.
MODEL
This is an obsolete holdover from NWN. It was supposed to be a unique identifier for the wings’ MDL file (a file format similar to NWN2’s MDB). To be safe, just set the value of this column to be the same as LABEL.

Tailmodel.2da

If your creature model includes a tail mesh in a separate MDB file, you should edit a copy of tailmodel.2da to include data on the tail mesh. If you have the Mask of the Betrayers expansion, you can find the most updated copy of this file in 2DA_X1.zip. Otherwise, you’ll have to use the file found in 2DA.zip.

As with appearance.2da, you add an entry for a new tail model by appending a new line at the end of tailmodel.2da and setting the index of the new row to be one plus the index of the previous row. Below are details on each column of tailmodel.2da.

Column
Description
INDEX (no actual name)
Sequential and unique row number. When appending a new row at the end of the file, always set this value to be one plus the INDEX of the previous row.
LABEL
Name of the tail model, for the reference of human readers. Can be used as the model’s name in the Toolset if the "STRING_REF" column is blank (****).
STRING_REF
A unique numerical identifier that points to a DIALOG.TLK entry, which is the name of this tail model as it appears in the Tail dropdown box of a creature’s Properties in the toolset. If blank (****), the toolset uses the LABEL instead.
NWN2_Model_NAME
Name of the tail model to use. This should also be the name of the MDB file where the mesh is stored. This can be any name that uniquely identifies the model.
NWN2_Skeleton_File
Name of the skeleton (GR2 file) that the tail model will use. This can be any name that uniquely identifies the skeleton as long as it ends with “_skel.”
NWN2_BaseAnims
Prefix of the animation files to use.
MODEL
This is an obsolete holdover from NWN. It was supposed to be a unique identifier for the tail’s MDL file (a file format similar to NWN2’s MDB). To be safe, just set the value of this column to be the same as LABEL.

Conclusion

I have explained the three 2DA files that modders use to bring new creature models to NWN2. In my next blog post, I will discuss naming conventions more thoroughly.

No comments: