Model Table of Parameters

Will be noted in each field as needed. Some may be stored in the compiled model as CHAR [32], some as CHAR [64] and some as CHAR [16]

Some have set options. Note for file/parent references the keyword NULL is recognised by the game as "blank/not set/invalid/don't look up" and is safe to use to not load anything in that instance.

Any references to a resman file need to be 16 characters or less to work properly.

UTF-8 windows CR LF is used by ASCII files by default although not sure what UTF-8 characters are valid for text fields.

Note that file name references - ie things loaded into the game from resman - rely on OS limitations that might have their own restrictions (especially on Windows)

Recommendation: Typically you should just use all lowercase for text fields simply for consistency, but it doesn't really matter - "classification ChArAaCtEr" is valid.

Text ASCII parameters usually translate into a binary flag/integer as appropriate. See Torlacks documentation if you are interested in this.

To Looks like 7 significant figures in most ASCII files, eg: -0.0934969 is valid. The game reads the float in converts it to the right number, and when compiling will save that number back in binary form.

To test maximum and minimum

The binary stores floats as 4 bytes, which implies a standard float32 that NWN tends to use. The ASCII is in text form so many not accurately represent the float value the game can read if hand edited.

Some decompilers shouldn't lose precision if it properly formats the float back into a string for viewing. This needs some testing!

newmodel <model_name>

This should match the .mdl file name, eg; helm_001.mdl → helm_001

Each model in the game should have a unique mdl file and therefore newmodel entry

While the compiled model has CHAR[64] as the length this should be kept to 16 characters or less (resman limitation).

donemode <model_name>

This must match the newmodel name so put the same value. This is at the end of the file signifying the file is done with this model.

It is likely only one model is loaded from a file so no newmodel is expected after this.

setsupermodel <model_name> <supermodel_name>

2 parts:

• Current model name as defined by newmodel
• Parent "super model" used to inherit animations or NULL

classification <classification>

If not left out of definition it should be on of these:

• effect
• tile
• character
• door

If not included no special classification is applied. This is entirely valid and happens on things like GUI models where this flag is simply not set (in binary it's set to 0). The other 4 all have some (unknown) level of changes in the engine when loaded, so while you can reference a door object in placeables.2da it is likely better to first of all make a copy of the model and alter this classification to match the character one. The engine may make further assumptions about the model classification however, depending on how it is loaded (eg; via. an appearance.2da line, GUI model, placeables.2da, visualeffects.2da, etc.) but this needs testing.

• Not set - this is common among GUI elements,
• effect or effects - These have some additional properties for effects
• tile - these are used as tiles in a tileset
• character - these are anything not covered by the other 3 (placeables, phenotype models, usual creature models, items, )
• door - additional properties for doors only

These classifications affects render order, hitchecks, highlighting and probably a bunch of other stuff.

If anyone has concrete information about what the engine does with this please let us know on Discord or get an account and edit this in.

ignorefog <on_off_boolean>

1 - Ignore fog

0 - Use fog

setanimationscale <scale>

Even if the model hasn't got animations, or the property isn't set, when compiled it will obtain a default value of 1

Obviously only applicable to things with animations, usually a creature model that is inheriting animations from a parent super model

beginmodelgeom <model_name>

endmodelgeom <model_name>

newanim <animation_name> <model_name>

Two parts which are likely limited to 16 characters:

• Name of the animation (in the example: "fog")
• The parent model name (in the example: "pnl_fog", this is the same as the newmodel name)

This starts an animation definition in the model.

You can have multiple animations tied to the parent model. These can also override the super model used for animations set with the setsupermodel parameter.

doneanim <animation_name> <model_name>

node dummy helm_001

node trimesh helm_001_g

node_type must be one of these:

• dummy
• trimesh
• animmesh
• danglymesh
• skin
• emitter
• light
• reference
• aabb

node_name has 3 things to keep in mind:

• a single dummy node needs to be the main "parent" of everything and should be defined with the same name as the model (ie newmodel entry). EG: if newmodel is "wplss_m_034" then there needs to be a dummy node named "wplss_m_034" as well.
• The name must be unique else the game may crash
• If not the parent dummy node this entry can be anything from 1 - 32 characters. Only tested basic A-Z, 0-9.

Each of these node types have a different set of valid parameters.

Notably some of these are undocumented or unused by Bioware. The main ones are:

Dummy: dummy

Geometry: trimesh, animmesh, danglymesh, skin (skinmesh)

Effects: emitter, light, reference

Axis Aligned Bounding Boxes: aabb

Any others like "patch" (used in some old Bioware models) default back to "dummy" it seems so are safely ignored or see the dummy section for them.

The order nodes are added to the MDL is important and defines the internal "part number" and thus if you use inherited animations the order becomes important for that.

Note the node_name should NEVER be longer than 32 characters since it truncates and this can cause to unforseen issues with a variety of engine situations - just...don't do it. Main issue is when you compile you might have 2 nodes the same name which can crash the game (loading from ASCII however loads more than 32 characters).

parent <node_parent>

parent rootdummy

position <X> <Y> <Z>

position 0.0 1.12739 1.99808

Position of the node relative to its parent. This property can be animated.

orientation <X> <Y> <Z> <A>

The rotation of this node relative to its parent, in axis-angle representation. The first three values define the axis, the fourth defines an angle in radian. This property can be animated.

ambient <R> <G> <B>

ambient 0.5 1.0 0.75

1.0 1.0 .1.0

OpenGL GL_Ambient material parameter. If it is lower then the texture on the model becomes quite dark.

The default is a sane 1.0 1.0 1.0 so it can be "safely" left out, but better to set it manually.

Note the old Bioware default was 0.2 0.2 0.2 where usually you'd want it set to 1.0 1.0 1.0 so if a model looks dark decompile it and change it to 1.0 1.0 1.0 (this was updated in patch 1.81.8193.17)

diffuse <R> <G> <B>

diffuse 1.0 1.0 1.0

1.0 1.0 1.0

Material diffuse colour, ie the RGB applied to the main texture0 file. It is a relatively cheap way to get a different coloured creature; say you wanted a "red" goblin you'd set it to 1.0 0.0 0.0. Frankly in this day and age creating a better replacement texture on a new model, or even using ReplaceObjectTexture, or shaders is a much better idea.

The default is a sane 1.0 1.0 1.0 so it can be "safely" left out, but better to set it manually.

Note the old Bioware default value were 0.8, 0.8, 0.8 which are awful. Use 1.0, 1.0, 1.0 by default in your own models else your texture will come out weird (this was updated in patch 1.81.8193.17)

render <on_off_boolean>

render 1

1 - this model is rendered in the game world

0 - this model is not rendered in the game world

Controls whether this object should be rendered. The geometry will still be loaded to the memory and casts shadows, even if this is unchecked. This is frequently used in conjunction with the Shadow attribute to create a low-poly shadow volume object. Valid values are either 0 (disabled) or 1 (enabled).

Please use 1 and 0 instead of things like "true" and "false" here.

shadow <on_off_boolean>

shadow 0

1 - shadows are attempted to be rendered for this object

0 - shadows are not rendered for this object ever

Shadow rendering only works with trimesh, not with skinmesh (and likely not animmesh or danglymesh). It also doesn't work well on models with high face counts - best idea to really do shadows well on a model is to have the usual model with render 0 and with shadow 0 set, and shadow version created as a much simpler trimesh with shadow 1 and render 0 set. Keep the new one much lower on the faces count (sub-100 or even lower) since it helps not have errors in the resulting shadows and keeps things running fast.

See this Model Shadows page for more information. It needs expanding to cover the ins and outs and all the different object types using them and how the game renders it, as well as debugging them and best practices.

Disabling shadows is also recommended for things generating their own light and which casting a shadow makes no sense (like ghosts or other see through things) since the shadows are quite "hard" and cannot be altered to be more transparent per-creature.

renderhint <renderhint_option>

renderhint 

NormalAndSpecMapped

NormalAndSpecMapped

NormalTangents

EE only.

Either option provides the same results. The model compiler seems to sets a flag to 1 if either are set.

Instructs the game to generate tangent and handedness vertex data for the associated model(s), provided that they are uncompiled and no tangent and handedness data exist. Also makes the game choose a shader with normal mapping enabled to render this content. Note: The renderhint can also be specified in a MTR material file.

beaming <on_off_boolean>

beaming 1

1 - beaming is on

0 - beaming is off

alpha <alpha_amount>

alpha 0.5

transparencyhint <transparency_priority>

transparencyhint 1

Values 0 through 9

0 - Transparency hint disabled - will be rendered before transparent items

1 - 9 - Transparency hint enabled - and will display in order, so 9 will be rendered last.

As transparency can be extremely costly to calculate from alpha values on a texture, this property gives the engine priority values of transparent objects.

An object with a transparency hint of 1 will be rendered after an object that has a value of 0.

The values appear to work up to 9 (10 values total) but this needs fully testing since the value stored in the compiled MDL is a UINT32 (then again boolean values have UINT32...silly Bioware)

(NEEDS TESTING MAY BE WRONG) This does not work on dynamic objects, it only affects static objects (this might mean only works with trimesh? - Jasperre)

selfillumcolor <R> <G> <B>

selfillumcolor 1.0 0.5 0.5

Makes the mesh glow without actually acting as a light source. It most likely corresponds to the GL_EMISSION material parameter in OpenGL. This property can be animated.

Note: In older mdl files this parameter might be spelled wrongly as seTfillumcolor. The mispelling of this parameter is one of the primary reasons that older models fail to compile using nwnmdlcomp.

Unusure - makes the trimesh light mapped presumably.

I think this is actually an on/off boolean. There are some Bioware models that use it such as t_door10.mdl

It appears the model compiler may put data in this field erroneously, eg compiling tnp_wyv.mdl adds some with higher values. Need to determine why!

materialname <material_filename>

materialname m_helm_002

EE only.

The MTR file is able to define textures, or override textures defined in the MDL (but you can specify textures0 through 2 in the MDL, so the MTR can partially define textures) for use with Standard material inputs (fancymaps).

Therefore a good use case is set texture0 for the diffuse in the MDL and have texture1 through texture4 defined in the MTR for fancymapping purposes, allowing one MTR file to be shared by multiple of the same model, but with different colours etc. - very useful for phenotype based armor.

texture0

texture0 <texture_filename>

texture0 c_aribeth_evil

Text or NULL

Texture file name (Priority of loading: MTR / DDS / PLT / TGA), so 16 characters maximum

Note MTR files take precedence (excepting PLT files)

Usually texture0 is the base texture used on this node of the model. Can be omitted or preferably set to NULL if the texture isn't going to be rendered (see render above). Textures not found (or no texture defined) default to blank white usually in game.

Cloaks have a special 2da that loads an overriding texture0 - see cloakmodel.2da (the prefix of the file is hardcoded and the ID number is from the 2da "TEXTURE" column).

There may be also default loading of texture0 for parts-based phenotype models. Needs checking.

As noted above bitmap is an alias but with MTR files using texture0 through texture15 the saner thing is to define just texture0 so it fits in and is more easily identifiable.

As per the fancymap specs if you use them; you could potentially have the MDL apply the Diffuse (base texture), Normal and Specular per-model and the MTR apply the rest.

tilefade <fade_option>

tilefade 1

Options:

• 0    Disabled    This object will never fade
• 1    Fade    This object will fade
• 2    Base    ???
• 3    Neighbor    This object will fade together with objects in neighboring tiles

rotatetexture <on_off_boolean>

rotatetexture 1

1 - rotate texture on this tile

0 - don't rotate this texture

verts <vertex_total>
    <X> <Y> <Z>

verts 4
   -1.1200000  0.2400000 0.0000000
   -1.1200000 -0.2400000 0.0000000
    1.1200000  0.2400000 0.0000000
    1.1200000 -0.2400000 0.0000000

Integer for vertex_total

Float for X/Y/Z

Vertices.

Every lines defines a single vertex. The faces section on a node references the indices of three vertices for every face.

It is recommended (and possibly required) to keep the vertex_total number the same across all of the geometry definitions in this section except the faces. Of course there are many reasons why they might be different (eg; a shadow only mesh wouldn't need any texture verts defining).

tverts <vertex_total>
    <U> <V> 0

tverts 4
   0.0625000 0.4062500 0
   0.0624999 0.2187500 0
   0.9375000 0.4062500 0
   0.9375000 0.2187500 0

Integer for vertex_total

Float for U/V

Last parameter is always 0

Positional data can be negative, positive or 0.0 for U/V

Usually defined the same amount as the verts.

Texture Vertices.

Every lines defines a single texture vertex (tvert). They are 2-dimensional -  the last value is always 0. The faces section on a node references the indices of three tverts for every face.

tverts1

tverts2

tverts3

tverts1 <vertex_total>
    <U> <V> 0

tverts1 4
  0.0625000 0.4062500 0
  0.0624999 0.2187500 0
  0.9375000 0.4062500 0
  0.9375000 0.2187500 0

Integer for vertex_total

Float for U/V

Last parameter is always 0

Positional data can be negative, positive or 0.0 for U/V

Usually defined the same amount as the verts.

Previously only one texture coordinate stream (named “tverts” in the model file) was supported per mesh. We now support three additional texture coordinate streams, named “tverts1”, “tverts2”, and “tverts3”, which will be linked to any shaders with the named attributes “vTcIn1”, “vTcIn2”, and “vTcIn3”.

faces <faces_total>
    <V1> <V2> <V3> <S> <UV1> <UV2> <UV3> <M>

faces 2
   0 1 2  1  0 1 2   1
   3 2 1  1  3 2 1   1

Integer for faces_total

Integer for all indexes (V1/2/3, S, UV1/2/3, M)

Each line defines a triangle:

• The first three values (v1 v2 v3) each reference a vertex from the vertex list. This is the index, not the actual coordinate.
• The 4th value (s) defines the shading group the face belong to. All neighboring faces belonging to same group will be rendered as smooth.
• The next three values (uv1 uv2 uv3) each reference a texture vertex (uv-vertex) from the tvert list. Again is the index, not the actual coordinate.
• The last value (m) defines a material index. This is only relevant when creating walkmeshes for tiles and determines the surface type of this face.

This number is primarily what you can use to check the model complexity.

colors <vertex_total>
    <R> <G> <B>

colors 4
    1 1 1
    1 1 1
    0.85882 0.70191 0.47843
    0.18823 0 0.47843

Integer for vertext_total

Float for R/G/B

Vertex colors. Each line contains the color for the corresponding vertex in the vertex list, as such the number of colors must match the number of vertices. Vertex colors are not used by the default shaders. Bioware rarely used this so there isn't much loss to not having it (omitting it means smaller files all round). Changing the diffuse texture is recommended instead for changing colours, or using shaders and MTR parameters.

tangents <vertex_total>
    <X> <Y> <X> <S>

tangents 4
    0.001087 -0.92979 0.38287 1.0
    -0.04183 -0.99999 -0.00166 1.0
    0.00174 -0.92377 0.38285 1.0
    -0.00425 -0.99999 0.0 1.0

Integer for vertex_total

Float for X/Y/Z and S

Per-vertex tangent data. Each line contains the value for the corresponding vertex in the vertex list, as such the number of tangents must match the number of vertices.

• The first three X/Y/Z values defines the tangent vector
• The fourth value S defines the binormal/ bitangent sign

This is an NWN:EE only field.

Tangents can be generated by the in game compiler (which are added to compiled models automatically to save time generating them again next time the model is loaded), but can be included in the ASCII model if fine tuned. Most of the time it is much easier to leave them out of the ASCII MDL and compile it in game just before releasing the model.

Requires a normal map to be present (see MTR and Standard material inputs).

normals <vertex_total>
    <X> <Y> <Z>

normals 4
    0.208259 -0.78341 -0.58556
    0.34848 -0.65194 -0.67344
    0.087436 -0.52056 -0.84933
    0.25736 -0.83923 -0.47900

Integer for vertex_total

Float for X/Y/Z

Per-vertex normals. Each line contains the normal for the corresponding vertex in the vertex list, as such the number of normals must match the number of vertices.

Normals can be generated by the in game compiler (which are added to compiled models automatically to save time generating them again next time the model is loaded), but can be included in the ASCII model if fine tuned. Most of the time it is much easier to leave them out of the ASCII MDL and compile it in game just before releasing the model.

Note: will not be regenerated for already compiled models, you must have the file loaded from ASCII to generate them afresh (say if you alter the normal map file).

displacement <displacement_amount>

displacement 0.0350000001

Positive non-zero float to get an effect

Determines show far the vertices are allowed to move. This is further restricted by the constraints.

The value appears to be approximately 1/2 meter per unit.

Note: In animation files and others which don't really use the danglymesh defined, this and period/tightness are just set to 0 and no constraints list is present. Example: a_fa.mdl with head_g for instance.

period <period_amount>

period 8

Determines how quickly the vertices move and how fast they come to a rest.

This value can be up to 59 before the mesh begins to jiggle incorrectly. At 59.5 the mesh may spasm sporadically. At 60 or above, the mesh will jiggle insanely for up to 1 second and then no longer jiggle, becoming locked at the starting position.

Tile grass (as created by walkmesh surface material 3) uses effects equivalent a hardcoded value greater than 60. It appears to be the only thing which can use this high a value.

tightness <tightness_amount>

tightness 3

The ’tension’ in the object, restricting movement.

A tight object is difficult to move by wind. Tile grass may have an approximate tightness of 50 or more.

constraints <constraints_total>

    <list_of_constraints>

  constraints 4
    0
    50
    100
    255

Not sure there is a limit to the number of constraints since it is per-vertex.

Each value needs to be on a new line and be between 0 and 255 (byte size).

Each line contains the constraints for the corresponding vertex in the vertex list, as such the number of constraints must match the number of vertices.

Constraints act as a multiplier for the displacement value and range from 0 to 255, with their value equating to the multiplier range of 0 to 1.

If the maximum displacement is set to 2, then the associated vertex painted with 255 will be allowed to move approximately 1 meter during maximum strength wind.

weights <vertex_total>
    <N1> <W1> <N2> <W2> <N3> <W3> <N4> <W4>

weights 4
    torso_g 1.0
    torso_g 0.9 pelvis_g 0.1
    torso_g 0.98 pelvis_g 0.02
    torso_g 0.5 pelvis_g 0.5

Integer for vertex_total

N1 through N4 need to be MDL Text, node names

W1 through W4 are Float

N2 - N4 and W2 - W4 are optional

N1 through N4 need to be MDL Text, node names

W1 through W4 are Float between 0.0 and 1.0 (Sum of line must be 1.0)

Every skinmesh must specify weights which influence its movements. Each line contains the weights for the corresponding vertex in the vertex list, as such the number of entries must match the number of vertices.

• Every line consists of (name, weight) tuple, each defines the influence a node has over a single vertex.
• A line MUST have at least one (name, weight) tuple. It mustn't be empty.
• A line MUSTN'T have more than four (name, weight) tuples
• The weights are floating point numbers in the range of [0.0, 1.0]
• The sum of weights of must be 1.0 for each line.