Mapadd Command Reference (LUA)

This page is a reference sheet for learned mapadd creators who want to branch out into the system's Lua side. While teaching programming concepts or detailing Lua itself is beyond the scope of this wiki, we can point you to Lua 5.0's online reference manual. A few demonstrations of Lua's use within SMOD (ex. Supply Drop) are also planned for the wiki.



  • HL2.EntFire ( <targetname>, <activator>, <input>, <parameter>, <delay> )
    Analogous to the ent_fire console command. Sends an input to an entity.

  • HL2.HookKilledEvent ( <function> )
    When an NPC is killed, the specified function will be called. To cease monitoring deaths this way, just use HL2.HookKilledEvent().

  • HookFunction (Info)
    When called by HL2.HookKilledEvent, this function will have information on the dead entity passed to it. This includes:

    > Info.IsPlayer - Boolean; if this entity is the player, return 1. Otherwise, return 0.
    > Info.IsNPC - Boolean; if the entity's an NPC, return 1. Otherwise, return 0.
    > Info.Relation - String; the entity's relation string.
    > Info.DamageType - Integer; the damage flag of the killer's attack (e.g. CLUB, ENERGYBEAM). See trigger_hurt's "damagetype" keyvalue for a listing.
    > Info.Damage - Integer; the amount of damage the fatal attack inflicted.
    > Info.AmmoType - String; the ammotype used to kill the victim. See weapon_custom Bullet section.
    > Info.Attacker - String; the targetname of the victim's killer.
    > Info.KilledEnt - pEnt; The entity itself. Use HL2.GetEntInfo with this if you need more information like the victim's classname.

  • HL2.CreateTimer( <function>, <interval>, <extra arguments> )
    Calls a function to act on a timer. The called function will be regularly run according to its interval (in seconds). If the timer function returns a value of 0 (rather than 1), the timer stops. This is ideal for countdown timers, using HL2.TimeStr to format the time and HL2.ShowInfoMessage to broadcast it inside the player's HUD.

  • String = HL2.GetDateMD()
    Returns the month and date according to the computer's clock. Expressed in MMDD notation (e.g. Jan 22;"0122").

  • String = HL2.CurrentMapName()
    Returns the current map's name. Its use on Counter-Strike: Source's Aztec map, for example, will return "de_aztec".

  • HL2.CallMapaddLabel ( <label name> )
    Calls an Entities label from the TXT side of the mapadd script.

Player Handling


  • Integer = HL2.GetMoney()
    HL2.SetMoney ( <integer> )
    Return or set the player's current amount of SMOD money.

  • pEnt = HL2.GetPlayer()
    Returns the player as an ent.

Player Messages


  • HL2.ShowHUDMessage ( <string> )
    Displays a white text string in the center of the player's HUD, similar to typical env_message text. The text holds for five seconds and takes two seconds to fade in or out.

  • HL2.ShowInfoMessage ( <color>, <time>, <string> )
    Displays a message on the left-hand side of the player's HUD, usually in the lower corner on top of the existing HUD elements. The message's duration is measured in seconds and includes time given to fading. The only choices for color appear to be lime green (0) or bright red (nil, or any other value).

  • String = HL2.TimeStr ( <time> )
    Returns the specified number of seconds as a string in MM:SS clock notation. A time of 45 will return a string of "0:45", while 612 returns "10:20". This function doesn't format hours, so irregular values will break style and simply tack on extra minutes (e.g. 100m;"100:00"). If a float value is used, everything after the decimal point is ignored.

Entity Handling


  • Entinfo = HL2.GetEntInfo (pEnt)
    Stores a variety of information about an entity within a variable. These include:

    > Entinfo.Health - Integer; entity's current health.
    > Entinfo.Classname - String; entity's classname (e.g. npc_combine_ace).
    > Entinfo.ModelName - String; entity's model (models/combine_super_soldier.mdl)
    > Entinfo.IsAlive - Boolean; if the entity's alive, return 1. Otherwise, return 0.
    > Entinfo.IsNpc - Boolean; if the entity's an NPC, return 1. Otherwise, return 0.
    > Entinfo.IsPlayer - Boolean; if this entity is the player, return 1. Otherwise, return 0.
    > Entinfo.Owner - String; returns the targetname of the entity's owner.
    > Entinfo.Name - String; returns the entity's targetname.

  • Vector = HL2.GetAbsOrigin (pEnt)
    Vector = HL2.GetAbsAngles (pEnt)
    Return the absolute (world-relative) origin/angle vectors of an entity.

  • Vector = HL2.GetAbsVelocity (pEnt)
    Returns the absolute (world-relative) velocity vectors of an entity.

  • HL2.SetAbsOrigin ( pEnt, <vector> )
    HL2.SetAbsAngles ( pEnt, <vector> )
    Set the absolute (world-relative) origin/angle vectors of an entity.

  • Vector = HL2.EyePosition (pEnt)
    Vector = HL2.EyeAngles (pEnt)
    Returns the origin/angle vectors of an entity's "eyes" attachment point.

  • HL2.KeyValue ( pEnt, <key>, <value> )
    Sets or adds a keyvalue to the entity. Mind that this command can also add outputs, as they are technically considered keyvalues.

  • HL2.SetEntityParent ( <pEnt parent>, <pEnt child> )
    HL2.SetEntityParent ( <pEnt parent>, <pEnt child>, <attachment point> )
    Tie an entity's movement to another. The "child" will perfectly mimic the movement of its parent and can be directly attached to a parent's attachment points ("head", "lefthand"). Analogous to the SetParent and SetParentAttachment inputs.

  • HL2.SetEntityOwner ( <pEnt owner>, pEnt )
    Sets the owner of an entity. For example, the player is considered the owner of any grenades they throw.

  • HL2.SetEntityMoveType ( pEnt, <movetype> )
    Changes an NPC's movement type (e.g. "Ground", "Fly").

  • HL2.SetEntityRelationship ( <pEnt A>, <pEnt B>, <disposition>, <priority> )
    HL2.SetEntityRelationship ( <pEnt A>, <classname B>, <disposition>, <priority> )
    HL2.SetEntityRelationshipName ( <pEnt A>, <targetname B>, <disposition>, <priority> )
    HL2.SetEntityRelationshipName2 ( <targetname A>, <targetname B>, <disposition>, <priority> )
    Analogous to the SetRelationship input, these functions are used to alter NPCs' attitudes toward others. See ai_relationship.

  • HL2.SetEntityPhysVelocity ( pEnt, <vector> )
    Sets the velocity vector of a physics object.

  • HL2.SetEntityPhysFreeze ( pEnt, <flag> )
    Freezes a physics object in place, akin to the DisableMotion input or "spawnflags 8" keyvalue.

  • HL2.SetModel ( pEnt, <model name> )
    Replaces an entity's model with another.
  • pEnt = HL2.CreateEntity ( <classname>, <origin>, <angle> )
    Specifies an entity to be created at a certain position. Use HL2.KeyValue to set its properties and then HL2.SpawnEntity to properly spawn it.
  • HL2.SpawnEntity (pEnt)
    Properly spawn a created entity. Entities that are "created" but not spawned will function abnormally (if at all).

  • pEnt = HL2.FindEntityByName ( pEnt, <targetname> )
    pEnt = HL2.FindEntityByClassname ( pEnt, <classname> )
    Searches the map's entity table and if possible, returns an entity with the specified classname/targetname. Substitute nil for the latter pEnt to return the first instance or substitute the var itself to return the next instance. Returns nil if it cannot find another entity in the list.

  • HL2.RemoveEntity (pEnt)
    Deletes the specified entity, best used only with entities created by HL2.CreateEntity that aren't properly spawned yet. Once spawned, many entities like items or NPCs can't be removed by this cleanly and are better handled with the Kill input.

Vectors (General)


  • Vector = HL2.Vector (x, y, z)
    Specifies a vector in Source units.

  • String = HL2.VectorString ( <vector> )
    Converts a vector to string format.

  • Float = HL2.DotProduct ( <vector A>, <vector B> )
    Returns the dot product of two vectors.

  • Float = HL2.VectorLength ( <vector A>, <vector B> )
    Returns the distance between two vectors.

  • Vector = HL2.AngleVectors ( <angle> )
    Angle = HL2.VectorAngles ( <vector> )
    See AngleVectors().

Spaces and Traces


  • Boolean = HL2.CheckRoom ( <origin>, <Mins>, <Maxs> )
    Checks to see if there's a certain amount of space around an origin. Mins and Maxs are vectors that specify the negative/positive range of the box, using the origin as its center (0,0,0). As an example, having Mins at (-8,-16,-32) and Maxs at (8,16,32) will check to see if there's a 16x32x64 cube's worth of space around the origin. If there's enough space, returns 1. Otherwise, returns 0.

  • Visinfo = HL2.CheckVisible (pEnt A, pEnt B)
    Does a traceline check to see if Ent A can see Ent B and stores the relevant information. Only functions with NPCs that have a sense of sight (e.g. not prop objects or proximity triggers) to test against Ent B's position. The information stored includes:

    > Visinfo.IsVisible - Boolean; if Ent A successfully spots Ent B, then return 1. Otherwise, return 0.
    > Visinfo.Length - Float; the distance between entities A and B.
    > Visinfo.AngleYaw - Vector; the yaw angle from Ent A that the check was performed at.
    > Visinfo.AnglePitch - Vector; the pitch angle from Ent A that the check was performed at.

Random Numbers


  • HL2.RandomSeed ( <number> )
    Half-Life 2 uses a seed number to influence the outcome of randomized events. This command specifies a new seed number to use.

  • Integer = HL2.RandomInt ( <min>, <max> )
    Float = HL2.RandomFloat ( <min>, <max> )
    Returns a random number within the specified range.



  • HL2.PlaySoundPos ( <sound name>, <origin> )
    Plays a sound from the specified origin vector. Sound names should be specified as a soundscript entry.

  • HL2.PlaySoundEntity ( <sound name>, pEnt )
    Plays a sound from the specified entity. If this entity can lip-sync (e.g. npc_citizen) and the sound is suitable, it will do so.

Node Information


  • Integer = HL2.GetNodeCounts()
    Returns the number of nodes in the map's node list.

  • pNode = HL2.GetNodeData (NodeID)
    Returns the information of a particular node. This includes:

    > pNode.x
    > pNode.y - Float; the X, Y, or Z value of the node's origin vector.
    > pNode.z
    > pNode.yaw - Float; the node's yaw angle.
    > pNode.type - Integer; the node's number type, such as ground (2) or climb (4).

    Note that as in the SNL file itself, numbering starts at 0; a NodeID of "100" will actually retrieve the 101st node in the list.

Saving Strings


Note that since Lua can automatically convert numbers to strings and vice versa, these functions work fine for numbers too.

  • HL2.SaveString ( <index>, <string>)
    String = HL2.LoadString ( <index> )
    Stores or returns a string within a temporary variable. This acts as an array, so index specifies an index within the table. This table will be wiped at the end of the map's session.

  • HL2.StoreWorkVar ( <index>, <string> )
    String = HL2.GetWorkVar ( <index>)
    Stores or returns a string within the _luaworkvar1 variable. This is an array, so index specifies an index within its table. _luaworkvar1 keeps its data between map loads until the game is restarted.


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


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