Adding Display Models to Entities

A strongly visual editor like Trenchbroom means that it is important to be able to see the models of your entities. Only point entities will be covered because you cannot add models to brush entities because the brushes themselves comprise the 'model'. Note that the definition formats themselves will not be covered here, only the method of attaching models to the definitions.

DEF Format Syntax

/*QUAKED item_armorInv (0 .5 .8) (-16 -16 0) (16 16 32)
{ model(":progs/armor.mdl" 2); }
Red armor, gives 200 armor points.
*/

The syntax for attaching a model to an entity definition for DEF files is: model(":MODELPATH"); and it is placed under the first line of the definition.

As an example, if your model resided in the progs/model.mdl file, then the resulting declaration would look like this: model(":progs/model.mdl");

Note the colon ( : ) in front of the pathname, this is required.

Specifying Skin and Frame numbers

The previous section shows how to attach a model to an entity and by default, Trenchbroom will use the first skin (skin 0) and first frame (frame 0) in the model file to display in the viewport. Usually this is sufficient, but not all monsters have a good frame for display in the editor on frame 0. There might also be times when a monster has a different skin. For these times, you will need to specify which skin and frame you want to see. This is done with the following syntax: model(":MODELPATH" #SKIN #FRAME);.

#SKIN is a number which specifies which skin you want to be displayed. Note that this is zero-based, in other words the first frame is 0, the second 1, etc...

#FRAME is a number which specifies which frame you want to be displayed. Like the skin number, the frame number is also zero-based.

The skin and frame numbers are optional and if they are omitted, Trenchbroom defaults to skin 0, frame 0 and if you only want to specify a skin number, then you do not need to put a 0 afterwards for the frame number but if you want to specify only a frame number, you MUST put a 0 before the frame number otherwise Trenchbroom has no way to know if you are talking about skins or frames!

Conditional Models

Up to this point, we have been able to attach a model to an entity so that it is displayed in Trenchbroom. This is nice, but what if the entity uses different models depending on settings? Things like ammo boxes appear larger if the "BIG" spawnflag is checked and Gaunts in Quoth appear on the group if the 'perch' key is set to '1'.

There are a few options available which allow you to specify which model an entity should show depending on what keys are set on it in the editor. This can be done the following way: model(":MODELPATH" CONDITION);

Conditions are defined a couple of ways:

As a literal

When you need to define a model for a specific value on an entity, you can do so like this: KEYNAME = "KEYVALUE". This will make Trenchbroom use the specified model if the KEYNAME is exactly the KEYVALUE.

As an example, model(":progs/model2.mdl" state = "1"); would use progs/model2.mdl only when the state key on the entity is set to 1.

As a flag value

When you are using spawnflags or other flag-like keys, a litteral value will not work so you must use a flag condition. This is done by omitting the quotes (") around the condition's value: model(":progs/model2.mdl" spawnflags = 1);. This would use progs/model2.mdl whenever the first spawnflag is set instead of only when the first spawnflag is set.

Combining skins, frames and conditionals

Let's look at an example, the Voreling from Quoth.

/*QUAKED monster_voreling (1 0 0) (-16 -16 -24) (16 16 32) AMBUSH
{
    model(":progs/voreling.mdl");
    model(":progs/voreling.mdl" 0 13 dangle = "1");
}


Voreling, 65 health points

Flags:
"AMBUSH"
the monster will only wake up on
really seeing the player, not another
monster getting angry
"dangle"
hang from cieling

*/

The voreling has two states, either as a normal monster, standing on the ground, or hanging from the ceiling. There are two model declarations, the first has no skin or frame setting, so Trenchbroom will use skin 0 and frame 0, and it has no conditionals, so that means this is going to be the default visual model used to display this monster in the editor.

The second model declaration has a skin setting of 0 and a frame setting of 13. If you look in the model file, you will see this is the frame where the Voreling is hanging upside down. Finally, we can see that the conditional dangle = "1" tells Trenchbroom to only use this declaration if the dangle key is set to 1.

For the DEF format, each different model declaration has it's own line ending in a semicolon (;).

Another example

/*QUAKED item_health (.3 .3 1) (0 0 0) (32 32 32) ROTTEN MEGAHEALTH
{
    model(":maps/b_bh25.bsp");
    model(":maps/b_bh10.bsp" 0 0 spawnflags = 1);
    model(":maps/b_bh100.bsp" 0 0 spawnflags = 2);
}

Health box. Normally gives 25 points.

Flags:
"rotten"
gives 15 points
"megahealth"
will add 100 health, then rot you down to your maximum health limit
one point per second
*/

This is an example of more complex usage of the new model syntax for DEF files. As you can see, there are three models attached to the Health kit, maps/b_bh25.bsp, maps/b_bh10.bsp and maps/b_bh100.bsp. This is because the Health kit uses three different models depending on what spawnflags are checked. If ROTTEN is checked, it uses maps/b_bh10.bsp which is the dim (rotten) health kit and if MEGAHEALTH is checked, then it uses maps/b_bh100.bsp which is the megahealth powerup. If neither are checked, it uses the standard health kit.

This is done by adding spawnflags = 1 to the second model declaration which is the rotten kit model and spawnflags = 2 to the megahealth model declaration.

Multiple conditions

In the previous example, note that if both ROTTEN and MEGAHEALTH were checked, it would display the megahealth model. In the case where multiple conditionals evaluate to true, Trenchbroom will use the last one that evaluates to true as the model to display. For this reason, do not put a model declaration with no condition as the last one in the definition because that will override everything else!

FGD Format Syntax

@PointClass size(-16 -16 0, 16 16 56) base(Item, Appearflags) model(":progs/armor.mdl" 2) =
item_armorInv : "200% armor (Red)" []

The syntax for attaching a model to an entity definition for FGD files is: model(":MODELPATH"); and it is placed in the first line of the definition (before the equals (=) sign).

As an example, if your model resided in the progs/model.mdl file, then the resulting declaration would look like this: model(":progs/model.mdl")

Note the colon ( : ) in front of the pathname, this is required.

Specifying Skin and Frame numbers

The previous section shows how to attach a model to an entity and by default, Trenchbroom will use the first skin (skin 0) and first frame (frame 0) in the model file to display in the viewport. Usually this is sufficient, but not all monsters have a good frame for display in the editor on frame 0. There might also be times when a monster has a different skin. For these times, you will need to specify which skin and frame you want to see. This is done with the following syntax: model(":MODELPATH" #SKIN #FRAME).

#SKIN is a number which specifies which skin you want to be displayed. Note that this is zero-based, in other words the first frame is 0, the second 1, etc...

#FRAME is a number which specifies which frame you want to be displayed. Like the skin number, the frame number is also zero-based.

The skin and frame numbers are optional and if they are omitted, Trenchbroom defaults to skin 0, frame 0 and if you only want to specify a skin number, then you do not need to put a 0 afterwards for the frame number but if you want to specify only a frame number, you MUST put a 0 before the frame number otherwise Trenchbroom has no way to know if you are talking about skins or frames!

Conditional Models

Up to this point, we have been able to attach a model to an entity so that it is displayed in Trenchbroom. This is nice, but what if the entity uses different models depending on settings? Things like ammo boxes appear larger if the "BIG" spawnflag is checked and Gaunts in Quoth appear on the group if the 'perch' key is set to '1'.

There are a few options available which allow you to specify which model an entity should show depending on what keys are set on it in the editor. This can be done the following way: model(":MODELPATH" CONDITION)

Conditions are defined a couple of ways:

As a literal

When you need to define a model for a specific value on an entity, you can do so like this: KEYNAME = "KEYVALUE". This will make Trenchbroom use the specified model if the KEYNAME is exactly the KEYVALUE.

As an example, model(":progs/model2.mdl" state = "1") would use progs/model2.mdl only when the state key on the entity is set to 1.

As a flag value

When you are using spawnflags or other flag-like keys, a litteral value will not work so you must use a flag condition. This is done by omitting the quotes (") around the condition's value: model(":progs/model2.mdl" spawnflags = 1). This would use progs/model2.mdl whenever the first spawnflag is set instead of only when the first spawnflag is set.

Combining skins, frames and conditionals

Let's look at an example, the Gaunt from Quoth.

@PointClass base(Monster) size(-32 -32 -24, 32 32 64)
    model(":progs/gaunt.mdl" 0 24, ":progs/gaunt.mdl" perch = "1")

    = monster_gaunt : "Gaunt"
[
    perch(choices) : "Starting pose" : 0 =
    [
        0 : "Flying"
        1 : "On ground"
    ]
]

The Gaunt has two states, either hovering in the air or perched on the ground. There are two model declarations, the first has a skin setting of 0 and a frame setting of 24 (this is the flying frame of the gaunt), and it has no conditionals, so that means this is going to be the default visual model used to display this monster in the editor.

The second model declaration has no skin or frame setting, which means Trencbroom will use skin 0 and frame 0. If you look in the model file, you will see this is the frame where the Gaunt is perched on the grund. Finally, we can see that the conditional perch = "1" tells Trenchbroom to only use this declaration if the perch key is set to 1.

For the FGD format, each different model declaration is in the same braces, separated by commas (,).

Another example

@PointClass
size(0 0 0, 32 32 16)
base(Appearflags)
model(
    ":maps/b_bh25.bsp",
    ":maps/b_bh10.bsp" spawnflags = 1,
    ":maps/b_bh100.bsp" spawnflags = 2
)
=
item_health : "Health pak"
[
    spawnflags(flags) =
    [
        1 : "Rotten" : 0
        2 : "Megahealth" : 0
    ]
]

This is an example of more complex usage of the new model syntax for FGD files. As you can see, there are three models attached to the Health kit, maps/b_bh25.bsp, maps/b_bh10.bsp and maps/b_bh100.bsp. This is because the Health kit uses three different models depending on what spawnflags are checked. If ROTTEN is checked, it uses maps/b_bh10.bsp which is the dim (rotten) health kit and if MEGAHEALTH is checked, then it uses maps/b_bh100.bsp which is the megahealth powerup. If neither are checked, it uses the standard health kit.

This is done by adding spawnflags = 1 to the second model declaration which is the rotten kit model and spawnflags = 2 to the megahealth model declaration.

Multiple conditions

In the previous example, note that if both ROTTEN and MEGAHEALTH were checked, it would display the megahealth model. In the case where multiple conditionals evaluate to true, Trenchbroom will use the last one that evaluates to true as the model to display. For this reason, do not put a model declaration with no condition as the last one in the definition because that will override everything else!