Mapadd Command Reference (Non-LUA)

This page is a command reference for those familiar with mapadd structure. For some much-needed brevity, only SMOD-specific commands or keys will be covered in detail. For more help with other keys (like OnWake or velocity), try searching the Valve Developer Community wiki.



Precache section

"Precache"
    {
    "entity" "npc_citizen" // Loads an entity and its associated assets (sounds, models, etc)
    "model" "models/weapons/v_mp5.mdl" // Loads a specific model.
    "model" "models/weapons/w_mp5.mdl"
    "sound" "buttons\button17.wav" // Loads a sound through its filename path.
    "sound" "Weapon_SVD.Fire" // Loads a sound through its SoundID.
    }

Randomspawn section

<classname>

Top Glance Commands Example

At a glance

Spawns an entity type at one or more randomly selected nodes throughout the map. Won't have an effect unless the map has AI nodes, which can be placed with the nodemaker tool or generated with the console.

Commands/values

  • count <integer> ( Default: 0 )
    Sets the number of entities spawned from this block. This line is exclusive to the Randomspawn section.

  • values <string>
    Sets the typical keyvalues of each entity spawned from this block. Outside the Randomspawn section, the closet equivalent is keyvalues.

  • grenade <integer> ( Default: 0 )
    Sets the number of grenades (or if elite, AR2 orbs) each entity spawned from this block will carry. If not set, the enemies_hasgrenade convar will take effect. This line is exclusive to the Randomspawn section.

  • model <string>
    Sets the model used by each entity spawned from this block. Outside the Randomspawn section, this line must be set within keyvalues.

(DBDB: Once able, test to see if npc_replace_model overrides this. Pretty sure, but double-checking wouldn't hurt.)

  • patrol
    Each entity spawned from this block will act as if given the StartPatrolling input. Will only work on NPCs capable of patrolling, such as citizens or Combine soldiers. This line works exactly the same outside the Randomspawn section.

  • patrolrandom
    Filler; DBDB. Never went and tested this myself and won't be able to for a while now. Perhaps it works independent of nodes?

  • stabilize <float>
    Set the angle at which entities spawned by this block will fall. If one of these is tilted at an angle less than this, it can force itself upright. Only useful for certain entities like friendly turrets or justaways.

  • targetname <string>
    Sets the targetname shared by each entity spawned from this block. Outside the Randomspawn section, this line must be set within keyvalues.

(DBDB: Confirm.)

  • weapon <classname>
    Sets the weapon type used by each entity spawned from this block. Mind that set weapons can be overridden by override_class or npc_weapon_randomize. This line doesn't function outside the Randomspawn section.

(DBDB: Confirm.)

(DBDB: Test if relation, longrange, and the other "new" SMOD keys in Entities work here or not, once able.)

In practice

1
2
3
4
5
6
7
8
9
10
"Randomspawn"
    {
    "npc_combine_c"
        {
        "count" "4"
        "values" "targetname ghost squadName squad_ghost spawnflags 256"
        "grenade" "4"
        "weapon" "weapon_mp5"
        }
    }

Lines 3 and 4 begin a block for some cloaked soldiers.

Line 5's count sets the number of soldiers this block will spawn to 4.

Line 6 uses values to set the targetname and squad name shared by each soldier, then enables the long range flag, 256.

Line 7 uses grenade to set the number of grenades used by the group, with 4 grenades for each soldier.

Line 8 uses weapon to arm each soldier with a suppressed MP5.

Removenodes

Top Glance Commands Example

At a glance

These blocks are used to designate an area of ground nodes that shouldn't be used for randomly spawning entities. All the affected nodes be ignored when NPCs and the like are randomly spawned, but will remain intact for navigation. Typically used to give the player breathing room and time to get their bearings, before moving on to the fight ahead.

Commands/values

  • radius <float> ( Default: 0 )
    Sets the area of effect, starting from the entity's origin. Ground nodes within this area will be ignored by randomized spawn blocks.

In practice

1
2
3
4
5
6
7
8
"Randomspawn"
    {
    "removenodes"
        {
        "origin" "250 0 -125"
        "radius" "1000"
        }
    }

Lines 3 and 4 begin the removenodes block.

Line 5 picks the coordinates [250, 0, -125] as a starting point.

Line 6 sets a radius of 1000 units that uses the starting point above as its center. Ground nodes within this area will be ignored when the random spawn script considers nodes to spawn entities at.

Removeairnodes

Top Glance Commands Example

At a glance

These blocks are nearly indentical to removenodes, but instead affect air nodes like those used by hunter-choppers.

Commands/values

  • radius <float> ( Default: 0 )
    Sets the area of effect, starting from the entity's origin. Air nodes within this area will be ignored by randomized spawn blocks.

In practice

1
2
3
4
5
6
7
8
"Randomspawn"
    {
    "removeairnodes"
        {
        "origin" "400 50 1000"
        "radius" "800"
        }
    }

Lines 3 and 4 begin the removeairnodes block.

Line 5 picks the coordinates [400, 50, 1000] as a starting point.

Line 6 sets a radius of 800 units that uses the starting point above as its center. Air nodes within this area will be ignored when the random spawn script considers nodes to spawn entities at.

Entities section

<classname>

Top Glance Commands Example

At a glance

Spawns an entity type at a specific point in the game world, or modifies its behavior.

Typical commands/values

  • alwaysthink
    Usually, AI won't analyze other entities that aren't inside their PVS (essentially, their field of vision). With this key present, AI can process entities outside their PVS. The same effect can be applied by the spawnflag, 1024 ("Think outside PVS").
  • freeze
    Disables the entity's motion, for use with mobile props. The same effect can be applied by the spawnflag, 8 or the DisableMotion input. Frozen props can be unfrozen by an EnableMotion input or the player's kick if kick_unfreezephysics is enabled.
  • longrange
    NPCs' senses usually only work within a certain distance, which can leave them helpless against the player on large, open maps. This key enables long-range behavior so that NPCs can see at any distance. The same effect can be applied by the spawnflag, 256.
  • patrol
    Each entity spawned from this block will act as if given the StartPatrolling input. Will only work on NPCs capable of patrolling, such as citizens or Combine soldiers.
  • relation <target><disposition><integer|rank>
    Special SMOD keyvalue used to set how the subject NPC behaves toward others, without using an ai_relationship. Multiple relationships can be set on one line with each spaced apart. If relationships may conflict, the one with (DBDB: higher/lower?) rank is given priority.
This key uses single characters to describe the target type and relationship.
Target NPC type Literal value Disposition Literal value
Antlions A Hate; attack the target on sight. H
Combine soldiers C Fear; flee from the target. F
Gordon, the player G Like; don't attack the target and if applicable, follow and guard it. L
Aliens, headcrab zombies included. L Neutral; don't attack the target. N
Citizens P
S Stalkers
V Vortigaunt (DBDB: verify)
  • stabilize <float>
    Set the angle at which entities spawned by this block will fall. If one of these is tilted at an angle less than this, it can force itself upright. Only useful for certain entities like friendly turrets or justaways.

In practice

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
"Entities"
    {
    "npc_kscanner"
        {
        "origin" "1000 0 200"
        "angle" "90 0 0"
        "longrange"
        "keyvalues"
            {
            "targetname" "kscan01"
            "health" "200"
            "relation" "gl1 ch2"
            }
        }
    }

Lines 3 and 4 begin a killer scanner block.

Lines 5 and 6 sets coordinates for the scanner's starting position and facing.

Line 7 uses SMOD's longrange key to enhance the scanner's senses for long-range fights.

Line 8 begins a keyvalues block, used for housing most keyvalues. Lines 10 and 11 within the block set the scanner's targetname and boost its health.

Line 12 makes the scanner friendly to the player, and hostile toward Combine soldiers.

Event

Top Glance Commands Example

At a glance

Similar to a relay, this trigger can send inputs to other entities.

Commands/values

  • targetname <targetname>
    Rather than setting the trigger's targetname, this defines a target the trigger will influence.
  • action <string>
    Names an input to be sent to the target entity.
  • value <string>
    If the input requires data (ex. SetHealth needs a number), that can be defined here.
  • delaytime <float> ( Default: 0 )
    Sets a delay in seconds before the input takes effect.

In practice

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
"Entities"
    {
    "event"
        {
        "targetname" "Hound01"
        "action" "setsquad"
        "value" "sq_hound"
        "delaytime" "6"
        }
    "npc_houndeye"
        {
        "origin" "50 500 0"
        "keyvalues"
            {
            "targetname" "Hound01"
            }
        }
    }

Lines 3 and 4 begin the event block.

Lines 5 sets the houndeye as a target, and lines 6 and 7 set a new squad name for it.

Line 8 defines a 6-second delay until the command is actually carried out.

Instant_trig

Top Glance Commands Example

At a glance

A trigger specially made for mapadd scripts. This is used as an alternative to Source's typical trigger entities because mapadds can't create or in many cases, interact with brush entities like them.

Commands/values

  • label <string>
    Sets a label section that this entity will activate once triggered. (DBDB: test ml)
  • OnHitTrigger <targetname> or <classname>,<command>,<value>,<float|delay>,<integer|# of fires>
    Similar to label, but interacts with entities instead of labels, using a pretty standard output. Can only be activated by an entity's touch. (DBDB: verify if it can also trigger if trig is run)


  • radius <float> ( Default: 0 )
    Sets a triggering radius, centered on this entity's origin. The trigger will routinely check this area and if it finds other entities within it, the trigger can fire off events.
  • touchname <targetname or classname>
    Sets a specific entity (type) to monitor its radius for, and ignore all others. (DBDB: memory's a bit foggy on this one. Once able, check if classnames were indeed valid.)
  • timer <float> ( Default: 0 )
    Once spawned in the game world, a countdown timer is started. Once this reaches 0, the trigger will fire off its events.
  • islived <targetname>
    Periodically checks the status of another entity. Once the monitored entity is killed or deleted, the trigger fires off its events.


  • group <integer> ( Default: 0 )
    Defines the trigger's group number, used for deleting trigs when they're no longer needed.
  • removegroup <integer> ( Default: 0 )
    If set, this trigger will, once activated, remove all the triggers sharing this group number. (DBDB: upon activation or when it fires off events?)
  • noclear <boolean> ( Default: 0 )
    By default, this trigger type removes itself after activation. With this key enabled, it can only be removed by a removegroup or kill action.

In practice

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
"Entities"
    {
    "instant_trig"
        {
        "origin" "420 0 150"
        "keyvalues"
            {
            "group" "1"
            "noclear" "1"
            "radius" "200"
            "touchname" "!player"
            "label" "exterminatus"
            "OnHitTrigger" "relay_emsg,Trigger,,1,-1"
            }
        }
    "instant_trig"
        {
        "origin" "1000 40 0"
        "keyvalues"
            {
            "timer" "30"
            "removegroup" "1"
            }
        }
    }

Lines 3 and 4 begin an instant_trig block.

Lines 5 sets coordinates for the trigger's starting position.

Lines 8 set the trigger's group to 1, and line 9 marks the trigger as repeatable.

Line 10 sets its triggering radius, and line 11 limits touch triggering to the player.

Line 12 sets a label to execute once the player sets off the trigger.

Line 13 adds an output that will wait a second before sending the Trigger command to a relay.

Line 21 sets a 30-second timer after which…

Line 22 deletes all the triggers in group 1, including the previous example trigger.

Lua

Top Glance Commands Example

At a glance

As the beginning of Getting Started says, SMOD can take advantage of LUA scripts to create complex, dynamic events. For example, LUA can spawn a group of rebels who each randomly carry either a shotgun, MP7, or AR2, and then make them all ammo carriers for their weapon type. This block makes use of the LUA side of SMOD's mapadd system.

Commands/values

  • callfunc <string>
    Calls on a function within the map's LUA script.

In practice

1
2
3
4
5
6
7
"Entities"
    {
    "lua"
        {
        "callfunc" "Spawn_CombineA1"
        }
    }

Lines 3 and 4 begin the lua block.

Lines 5 calls on the Spawn_CombineA1 function defined in <mapname>.lua.

Relation

Top Glance Commands Example

At a glance

Similar to an ai_relationship, this will change how NPCs behave towards others. One big difference is that this will keep these relationships constant, while an AI_R will only affect the NPCs present whenever it's applied.
(DBDB: Confirm.)

Commands/values

  • classname <classname>
    Used to affect the entities in the area or entire map that share this classname.
  • targetname <targetname>
    Used to affect the entities in the area or entire map that share this targetname.
  • radius <float>
    Sets the area of effect, starting from the entity's origin. By default, the entire map is considered for this event.
  • relation <target><disposition><integer|rank>
    Sets how the subject NPC(s) will behave toward others. Multiple relationships can be set on one line with each spaced apart. If relationships may conflict, the one with (DBDB: higher/lower?) rank is given priority.
This key uses single characters to describe the target type and relationship.
Target NPC type Literal value Disposition Literal value
Antlions A Hate; attack the target on sight. H
Combine soldiers C Fear; flee from the target. F
Gordon, the player G Like; don't attack the target and if applicable, follow and guard it. L
Aliens, headcrab zombies included. L Neutral; don't attack the target. N
Citizens P
S Stalkers
V Vortigaunt (DBDB: verify)

In practice

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
"Entities"
    {
    "relation"
        {
        "origin" "400 0 0"
        "radius" 500"
        "classname" "npc*"
        "relation" "gl1 ch2"
        }
    "npc_houndeye"
        {
        "origin" "400 0 0"
        }
    "npc_antlion"
        {
        "origin" "400 50 0"
        }
    }

Lines 3 and 4 begin the relation block.

Lines 5 and 6 set the starting point and area of effect for the trigger, covering both NPCs with plenty of room to spare.

Line 7 uses a wildcard (*) to mark the target as any NPC the trigger can find within its radius.

Line 8 defines those NPCs' relationship to be friendly toward the player, and hostile toward Combine soldiers.

Removeentity

Top Glance Commands Example

At a glance

This block is used to specify an entity or group of entities to be removed as if they were given a kill input.

Commands/values

  • radius <float>
    Sets the area of effect, starting from the entity's origin. By default, the entire map is considered for this event.
  • classname <classname>
    Used to instantly delete all the entities sharing this classname from the area or map.
  • targetname <targetname>
    Used to instantly delete all the entities sharing this targetname from the area or map.

(DBDB: Test if these can be used at the same time.)

In practice

1
2
3
4
5
6
7
8
9
10
11
12
"Entities"
    {
    "removeentity"
        {
        "origin" "320 10 0"
        "keyvalues"
            {
            "radius" "1000"
            "targetname" "jprop*"
            }
        }
    }

Lines 3 and 4 begin an removeentity block.

Lines 5 sets coordinates for the trigger's starting position.

Lines 8 defines the removal radius around the origin.

Lines 9 defines the targetname of the entity or entities to be removed within the radius. A wildcard (*) is used here, so if there were two entities nearby named jprop01 and jprop02, both would be deleted.

Sound

Top Glance Commands Example

At a glance

Simply plays a sound at maximum volume from either another entity or a specified location.

Commands/values

  • targetname <targetname>
    Rather than setting the trigger's targetname, this defines an entity the sound will issue from. Overrides the effect of origin.
  • origin <X Y Z>
    Determines the origin of the sound within the game world, as well as the entity's. Targetname has priority when deciding the sound's location.
  • soundname <string>
    Defines the sound to be played. Both sound IDs (like those within scripts\games_sounds.txt) and raw paths (ex. buttons\button17.wav) can be used, though sounds need to be precached first when using paths.

(DBDB: Could swear it needed precaching even if the entity (and presumably, its sounds) was loaded. Wouldn't hurt to double-check when I can, though.)

In practice

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
"Precache"
    {
    "soundname" "houndeye/he_idle1.wav"
    "soundname" "Weapon_AK47.Fire"
    }
"Entities"
    {
    "sound"
        {
        "targetname" "Hound01"
        "soundname" "houndeye/he_idle1.wav"
        }
    "sound"
        {
        "origin" "700 0 0"
        "soundname" "Weapon_AK47.Fire"
        }
    }

Lines 3 and 4 load the needed sounds beforehand.

Lines 10 and 11 will force the houndeye to play a specific idle sound straight from its file path.

Lines 15 sets the location of a sound, and line 16 defines this sound as an AK-47's firing sound, using its unique ID.

Label Sections

Labels' blocks are identical to Entities, with one exception…

Player

Top Glance Commands Example

At a glance

This block is used to instantly move, message, or manipulate the player in certain ways. Only seems to function within labels and isn't any use in Entities.

Commands/values

  • fadein <float>
    Makes the player's screen go black immediately before using a cinematic "fade in" effect to bring it back. The number determines the amount of time in seconds until the screen fully returns to normal.

(DBDB: See if RGB arguments work like they do with the console command. Unlikely, but…)

  • fadeout <float>
    Dead similar to fadein, this key will gradually bring the player's screen to full black. The number determines the amount of time in seconds until the screen is fully black. Mind that after the effect has runs its course, it will not stay there like an env_fade can.
  • kill
    Immediately kills the player, just like the console command, kill. Note that the player entity will never be deleted upon death, and continue to process inputs and outputs.
  • message <string>
    Passes a message to the player. The font will be bold, white, and centered, similar in style to the chapter messages found in the Half-Life2 campaign ("WE DON'T GO TO RAVENHOLM"). This text will remain for about 5 seconds, regardless of length.
  • music <string>
    Plays a music piece as if the player had entered the play command. Both the music file's path and its sound ID (found in scripts\level\sounds_music.txt) can be used.

(DBDB: Does it only work with music or can chimes and other sounds be used here? Verify hunch about paths.)

In practice

1
2
3
4
5
6
7
8
9
10
11
"Entities:Init_Plr"
    {
    "player"
        {
        "origin" "-136 -1094 -1149"
        "angle" "-2 73 0"
        "fadein" "10"
        "message"    "Clear the building."
        "music" "song_hl1_stinger8"
        }
    }

Lines 3 and 4 begin a player block, itself contained in a label started by lines 1 and 2.

Lines 5 and 6 set new coordinates for the player's position and facing, immediately transporting them there.

Line 7 makes the player's screen go instantly to black, before gradually fading back in over 10 seconds.

Line 8 sends a message to the player while their screen is still dark.

Line 9 plays a short, ominous bit of music from the Ravenholm chapter.


Customization

Mapadd Command Reference (Non-LUA)Command Reference (LUA)Getting StartedPorts 'n' Doors
Alarm, Alarm!Color Correction in SMODDoor BreachingMobile APCsWorking With Dropships
Supply Drop (LUA)Countdown (LUA)
kh0rn3's Mapadd Generator
Scripts addcontentsoverride_classsmod_custom_explosivesmodaclistSMOD Soundscripts

npc_gib_modelnpc_replace_modelnpc_shieldsetnpc_weapon_randomizenpc_weaponweight

excludeweaponsweapon_categoryweapon_customConsole Command List
Other Crosshair CustomizationGenerating AI NodesUsing the NodemakerSubViewCam
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License