MODELDEF

MD2s normally have actual frame names so you can reference them by name.

Model <ActorName>
{
   Path <"path">
   Model <model index> <"model file">
   Skin <model index> <"skin file">
   Scale <X scale> <Y scale> <Z scale>

   Frame <XXXX> <X> <model index> <"frame name">
}

(New from 4.10.0)

IQMs can hold multiple named animation sequences, so you can reference frames by the name of the animation and a frame index in it, separated by a colon.

Model <ActorName>
{
   Path <"path">
   Model <model index> <"model file">
   Skin <model index> <"skin file">
   Scale <X scale> <Y scale> <Z scale>

   Frame <XXXX> <X> <model index> <"animation name:frame number">
}

MD3s do not contain any useful names that you can use. You would use frame indexes instead of frame names. More information below.

Model <ActorName>
{
   Path <"path">
   Model <model index> <"model file">
   Skin <model index> <"skin file">
   Scale <X scale> <Y scale> <Z scale>

   FrameIndex <XXXX> <X> <model index> <frame number>
}

In the two above examples, <ActorName> is the name of the actor (as used in DECORATE, etc), <XXXX> is the sprite lump (example POSS), and <X> is the sprite frame (example A). The rest can be found in the Properties section.

The Frame property does not need to use an actual sprite name. It can be an arbitrary set of letters or numbers (MODL or MDLA are some of the commonly used examples) and it doesn't have to correlate to any real sprite (but it can, it won't affect anything), because the sprite itself will never be rendered, it's just a way of attaching models to actors. There are a few limitations to that rule, however:

• If a non-existent sprite name is used as the very first frame in an actor's Spawn sequence, it won't be spawned at map start and will instead be replaced with an error marker. This will happen even if the actor has a model attached to it, despite the fact that that sprite isn't used in the game and won't be drawn. This can be circumvented by using an existing sprite name, or by adding TNT1 A 0 as the very first frame of Spawn.
• Similarly, using a non-existent sprite name as the very first frame of the Ready sequence in weapons will also cause issues, even if you attach a model do it.
• Using non-existent sprite names everywhere will flood the console with errors if running GZDoom with -developer 2 parameter, which defines much stricter rules for potential issues. It doesn't cause any issues in practice, however.
• Models can't be attached to TNT1 A 0, since TNT1 is an internal shorthand for disabling the rendering of the object completely.

There are a number of flags that you can use in MODELDEF.

• PITCHFROMMOMENTUM

Adjusts the model's pitch to match the momentum of the actor; useful for rocket projectiles.

• IGNORETRANSLATION

Ignores the actor's translation.

• INHERITACTORPITCH (deprecated)

Model's pitch adjusts to match the actor's pitch, deprecated because of the unintended pitch inversion and bad name choice

• INHERITACTORROLL (deprecated)

Model's roll, adjusts to match actor's roll. Same as USEACTORPITCH, deprecated because of bad name choice.

• INTERPOLATEDOUBLEDFRAMES

Workaround to smooth the model interpolation of actors that use the same frame twice in a row. Most of the standard Doom monsters do this in their see state.

• ROTATING

Makes the model rotate, useful for pickup models a la Quake 3. Related properties must be defined AFTER this flag.

• NOINTERPOLATION

Forces uninterpolated animation.

• USEACTORPITCH

Model's pitch adjusts to match actor's pitch.

• USEACTORROLL

Model's roll, adjusts to match actor's roll.

• DONTCULLBACKFACES

Forcefully disables backface culling.

• USEROTATIONCENTER

Makes Rotation-Center affect actor angles (the property must be set AFTER this flag to work). Useless unless any of the actor rotation flags are also used.

• NOPERPIXELLIGHTING

Disables per-pixel lighting on the model.

• SCALEWEAPONFOV

Scales the weapon's model along with the user's FOV to reduce distortion.

• MODELSAREATTACHMENTS

Model indices will be treated as belonging to the same armature as model index 0. Therefore each model will just get attached to the model and animation data at index 0. Each model needs to have the same exact armature or unwanted

behavior may occur. Having this flag defined takes priority over the Animation property. This flag should be used especially if there are a lot of attachments like heads, hats, weapons, etc. This flag only has an effect on skeletal formats.

• CORRECTPIXELSTRETCH (New from 4.10.0)

By default, models stretch when their pitch or roll changes, in a way that matches aspect ratio correction. This flag disables that behavior so the model always retains the same size without any distortion.

Note: Although technically a bug, the stretching can nevertheless be useful, for example, to ensure that a beam-shaped model retains the same length in map units regardless of orientation.

• AngleOffset angle

Changes model yaw angle by the given floating point value in degrees. Keep in mind this and the other angles are applied after scaling and offsets.

• Model model-index model-file

Defines model to use. You can define multiple models to use with different indexes.

• Path path

Path to model file in the ZIP/PK3. This parameter is entirely optional, its reason for existence is to avoid repeated typing of the path if it is used for the model itself and several skins. This will just get prepended to the specified names, so if it is left out, the ZIP/PK3's root will be used and all paths to the files have to be fully given with their respective properties.

• PitchOffset angle

Changes model pitch angle by the given floating point value in degrees.

• Offset xoffset yoffset zoffset

Sets actor x/y/z offsets.

• RollOffset angle

Changes model roll angle by the given floating point value in degrees.

• Rotation-Center float float float

Specify the x, y and z coordinate of the center of the rotation. Without either the ROTATING or USEROTATIONCENTER keywords, this does nothing

• Rotation-Speed float

Specify the speed of the rotation. Without the ROTATING keyword, this and the other rotation properties do nothing

• Rotation-Vector float float float

Specify the x, y and z component of the vector of the rotation

• Skin model-index skin-file

Defines skin to use for the model of the same index. The skin-file can be of any format that ZDoom supports.

• SurfaceSkin model-index surface-index skin-file

Defines skin to use for the specified MD3 surface index on model-index model. This can only be used on MD3 files, otherwise it gets ignored.

• Scale float float float

Defines the x, y, and z scaling of the model.

• ZOffset float

Adjusts the model's height, useful if you don't have access to a model editor.

• Animation animation-index model-file

Defines the animation data to use for the model of the same index. This property only has an effect on skeletal formats such as IQM.

There is a known issue with defining an animation with multiple models used in the same frame: The frame has to be defined in full consecutively, otherwise only the last defined model animation plays properly. For instance, this sequence results in issues:

//first model
FrameIndex FRAM A 0 0
FrameIndex FRAM B 0 1
FrameIndex FRAM C 0 2
//second model
FrameIndex FRAM A 1 0
FrameIndex FRAM B 1 1
FrameIndex FRAM C 1 2

To work properly, it has to be reordered like so:

FrameIndex FRAM A 0 0
FrameIndex FRAM A 1 0
FrameIndex FRAM B 0 1
FrameIndex FRAM B 1 1
FrameIndex FRAM C 0 2
FrameIndex FRAM C 1 2

The model index order inside a frame does not matter.