Skip to content

Entity Templates

Jump to bottom
Roman Chistokhodov edited this page Oct 18, 2024 · 2 revisions

Overview and reasoning

Entity templates allow to define custom defaults applied to some entities (currently mostly monsters).

Consider that you want to use a second variation of a bullsquid throughout the mod, e.g. the one with a custom model, red blood, increased health and custom relationship classification. As a mapper you could set these parameters directly for each instance of the monster. But copying the chosen parameters each time you want to place such monster becomes tedious quickly. It's also prone to errors: consider the situation when you set the model, blood and health, but forgot to set classification. To make it even worse, if during the development you decide to change, for example, the health value for this kind of bullsquids, you would need to go through all your maps, find these bullsquids and set the new health value. Unacceptable!

This is where Entity templates come to the rescue. You define the template with custom parameters once and set the template name in the monster's properties (or you define the template for a monster class and it's applied to monsters of this classname automatically). Now instead of keeping an eye on the 4 parameters (in the example with bullsquid) you can stick to one (the template name). Moreover, the Entity templates allow to configure the Visuals and SoundScripts of the monster.

The Entity templates are configured via templates/entities.json. Each template has a name that is used by entities to refer to the template.

Examples

There's a list of some useful example to give you the idea of what templates are capable of. You can skip it and jump right to the format description.

Example 1: Custom bullsquids

Let's say you want to add two new bullsquid variations: the yellow bullsquid from Half-Life Alpha and the crocodile-like green bullsquid from earlier stages of Half-Life 2 development. You made fine models for both bullsquids and grabbed custom sounds for the crocodile-like one. You also want to use the old spit model instead of a sprite as a projectile visual for the yellow bullsquid.

Create a templates/entities.json with the following contents:

{
    "yellowbullsquid": {
        "own_visual": {
            "model": "models/yellowbullsquid.mdl"
        },
        "visuals": {
            "Bullsquid.Spit": {
                "model": "models/spit.mdl",
                "rendermode": "normal",
                "framerate": 1.0,
                "scale": 1
            }
        }
    },
    "crocsquid": {
        "own_visual": {
            "model": "models/crocsquid.mdl"
        },
        "soundscripts": {
            "Bullsquid.Attack": {
                "waves": ["bullsquid_hl2/attack2.wav", "bullsquid_hl2/attack3.wav"]
            },
            "Bullsquid.Growl": {
                "waves": ["bullsquid_hl2/attackgrowl1.wav", "bullsquid_hl2/attackgrowl2.wav", "bullsquid_hl2/attackgrowl3.wav"]
            }
        }
    }
}

Here, we created two templates called yellowbullsquid and crocsquid. Each defines the custom model (the own_model property). The yellow bullsquid defines a custom visual for its spit projectile. The crocodile-like bullsquid defines the custom soundscripts for spit attack and bite attack sounds.

Now, in the level editor all you have to do is to put some monster_bullchicken and set the desired template name in the Entity Template parameter (either yellowbullsquid or crocsquid). In the game these bullsquids will have the custom properties read from the template. Note that you still have access to the standard Half-Life bullsquid on your maps - just leave the Entity Template blank.

Example 2: Female NPC

The previous solution to making female NPCs (or more general NPCs with custom voice lines and pain/death sounds) included several steps: creating a file with sound replacement list, setting the path of this file in the monster_civilian or monster_scientist parameters, setting a custom model and providing a custom speech prefix. For each instance of the female NPC. Not ideal, as there are too many things to set and the sound replacement is not a scalable solution.

Now, with entity templates all you need to do is to write a template and set the template name in the monster parameters, like in the example:

{
    "female_civ": {
        "own_visual": {
            "model": "models/us_gal.mdl"
        },
        "soundscripts": {
            "Civilian.Pain": {
                "waves": ["colette/colette_pain0.wav", "colette/colette_pain1.wav", "colette/colette_pain2.wav", "colette/colette_pain3.wav"]
            },
            "Civilian.Die": {
                "waves": ["colette/colette_die0.wav", "colette/colette_die1.wav", "colette/colette_die2.wav"]
            }
        },
        "speech_prefix": "FEM"
    }
}

Example 3: Friendly Vortigaunt

Let's say your want a friendly vortigaunt variation in the mod, with a different model and beam effects. The default classification for the template can be changed via classify parameter:

{
    "vort_friendly": {
        "own_visual": {
            "model": "models/islavef.mdl"
        },
        "classify": "Player Ally",
        "visuals": {
            "Vortigaunt.ZapBeamColor": {
                "color": [255, 96, 180]
            },
            "Vortigaunt.ArmBeamColor": {
                "color": [128, 16, 96]
            }
        }
    }
}

Example 4: Modified default for a classname

If you give the template the same name as a monster's classname (e.g. monster_scientist), this template will be applied automatically to all instances of this class (unless the instance specifically refers to another template).

Let's assume you want to change the scale of the gibs for monster_babycrab and its default appearance - e.g. remove the default translucency (if you never noticed before - babycrabs in Half-Life are not fully opaque). You need to define the "monster_babycrab" template:

{
    "monster_babycrab": {
        "own_visual": {
            "rendermode": "normal"
        },
        "gib_visual": {
            "scale": 0.5
        }
    },
}

Now all babycrabs will use this template (unless the different template is set in the babycrab's properties).

Format of entities.json

The document is an object where each property presents a named entity template. Template names technically can be any string, but it's better to stick to some strict set of characters, like latin letters, digits and underscore symbol, to avoid potential problems with compilers, level editors and bsp.

Note about naming: it's better to avoid names starting with monster_ unless you create a default template for the existing monster class. Consider that you called a template monster_bodyguard and use it on some security guards in your mod. Then, at some point Featureful SDK gets updated and introduces a new monster called monster_bodyguard. The template you previously defined now automatically gets applied to the new monster class even though it wasn't your original intention.

Each template in the document may have the following properties:

own_visual

The visual definition or the name of the visual from the templates/visuals.json for the monster's own model. This allows to change the default model of the monsters belonging to the template, the model scale or, for example, make the monsters semi-transparent:

{
    "template_name": {
        "own_visual": {
            "model": "models/custom_model.mdl",
            "rendermode": "additive",
            "alpha": 100,
            "scale": 1.5
        }
    }
}

gib_visual

The visual definition or the name of the visual from the templates/visuals.json for the monster's gibs. This allows to change the default model or other render properties of the monster's gibs.

{
    "template_name": {
        "gib_visual": {
            "scale": 0.5,
            "rendermode": "texture",
            "alpha": 192
        }
    },
}

classify

Default relationship classification for the monsters belonging to this template. Possible values:

  • "None" - ignored by everyone and ignore everyone.
  • "Machine" - aggressive against players and aliens. Used by turrets and robots.
  • "Human Passive" - player ally who's afraid of enemies. Scientists and other civilians.
  • "Human Military" - enemy human grunts.
  • "Alien Military" - alien slaves, alien grunts and alien controllers.
  • "Alien Passive" - ignore everyone, but get attacked by humans.
  • "Alien Monster" - houndeyes, ichtyosaurus, zombies.
  • "Alien Prey" - headrabs.
  • "Alien Predator" - bullsquids. Attack each other and hunt alien preys.
  • "Player Ally" - ally security guards and monsters who are enemies by default but set to have a reversed relationship.
  • "Race X Predator" - pitdrones. Attack alien predators and alien preys.
  • "Race X Shock" - shock troopers and voltigores.
  • "Player Ally Military" - ally opfor soldiers. Will attack human passive and player ally if opfor_grunts_dislike_civilians feature is set to true (the Opposing Force behavior).
  • "Blackops" - used by blackops assassins (if blackops_classify feature is set to true). Act as enemies to everyone else.
  • "Snark" - used by snarks. Will attack gargs, but ignore alien military.
  • "Gargantua" - used by gargs. Will be attacked by snarks.

Example:

{
    "template_name": {
        "classify": "Player Ally"
    }
}

health

Default health amount for the monster belonging to this template. Currently only constant numbers are supported (i.e. it doesn't depend on the chosen game difficulty).

{
    "template_name": {
        "health": 100
    }
}

size

The object with properties min and max each is 3-element array defining the mins and maxs for the Bounding Box:

{
    "template_name":
    {
        "size": {
            "mins": [-40, -40, 0],
            "maxs": [40, 40, 200]
        }
    }
}

Instead of the object you can also set one of the named presets:

  • "snark" - same size as snarks: [-4, -4, 0] - [4, 4, 8].
  • "headcrab" - same size as headcrabs: [-12, -12, 0] - [12, 12, 24].
  • "small" - same size as houndeyes: [-16, -16, 0] - [16, 16, 36]. The resulting size (but not mins and maxs) also equals to the size of the crouching player.
  • "human" - same size as humanoid characters: [-16, -16, 0] - [16, 16, 72].
  • "large" - same size as bullsquids and alien grunts: [-32, -32, 0] - [32, 32, 64].
{
    "template_name": {
        "size": "headcrab"
    }
}

blood

Default blood color of the monster belonging to this template. Possible values:

  • "red" - red human blood.
  • "yellow" - yellow alien blood.
  • "no" - don't bleed.
{
    "template_name": {
        "blood": "red"
    }
}

field_of_view

Default field of view of the monster belonging to this template. A number in range [-1, 1] where -1 means the full view in all directions and values closer to 1 mean narrower angle. The angle at which the monster can detect enemies depends on the field of view. If the monster has a full view it can't be ambushed from the back.

{
    "template_name": {
        "field_of_view": -0.3
    }
}

One of the predefined presets can be used instead:

  • "full" - full view. Used by controllers and turrets.
  • "wide" - wide view. Used by humans and vortigaunts.
  • "average" - used by bullsquids and alien grunts.
  • "tunnel" - used by headcrabs and houndeyes.
  • "narrow" - narrow view. No monsters use it by default.
{
    "template_name": {
        "field_of_view": "wide"
    }
}

visuals

The object consisting of the entries of the visual replacements. The entry key must be the name of the existing visual, used by a monster (consult the Visuals page). The entry value should be either the name of the replacement visual from templates/visuals.json or the object defining the replacement visual.

Example:

{
    "bullsquid_template": {
        "visuals": {
            "Bullsquid.Spit": {
                "model": "sprites/mommaspit.spr",
                "color": [100, 255, 0],
                "scale": 1.5
            },
            "Bullsquid.Fleck": "CustomBullsquid.Fleck"
        }
    }
}

In this example we redefine some properties of the Bullsquid.Spit visual for a monster belonging to the bullsquid_template template. The Bullsquid.Fleck is also replaced with CustomBullsquid.Fleck which is expected to be defined in the templates/visuals.json. The latter approach allows to define the visual once and reuse it in many templates. The former approach might be more convenient because it allows you to define the visual in the template file.

soundscripts

The object consisting of the entries of the soundscript replacements. The entry key must be the name of the existing soundscript, used by a monster (consult the Soundscripts page). The entry value should be either the name of the replacement soundscript from sound/soundscripts.json or the object defining the replacement soundscript.

{
    "bullsquid_template": {
        "soundscripts": {
            "Bullsquid.Attack": {
                "waves": ["bullsquid_hl2/attack2.wav", "bullsquid_hl2/attack3.wav"],
                "pitch": 110
            },
            "Bullsquid.Growl": "Bullsquid_HL2.Growl"
        }
    }
}

In this example we redefine some properties of the Bullsquid.Attack soundscript for a monster belonging to the bullsquid_template template. The Bullsquid.Growl is also replaced with Bullsquid_HL2.Growl which is expected to be defined in the sound/soundscripts.json. The latter approach allows to define the soundscript once and reuse it in many templates. The former approach might be more convenient because it allows you to define the soundscript in the template file.

size_for_grapple

Defines the monster interaction with barnacle grapple (weapon_grapple). Possible values:

  • "no" - no interaction. Grapple can't latch on the target.
  • "small" - grapple pulls the target to the player (e.g. headcrabs).
  • "medium" - grapple pulls the player to the target.
  • "large" - currently the same effect as medium.
  • "fixed" - grapple pulls the player to the target and the barnacle's tongue tip stays at the point of latching. The target is expected to be unmovable.

speech_prefix

Defines the speech prefix for the monster's sentences. E.g. if the template is applied to the scientist, and the speech prefix is "FEM" the scientist will replace SC_ with FEM_ when playing the sentences: FEM_HELLO instead of SC_HELLO, etc.

Clone this wiki locally