User:ArthurAutomaton/sandbox

From Valve Developer Community
Jump to: navigation, search

Sandbox

Some notes to myself about modding DotA 2.

Addons and version control

The files comprising an addon are spread over two directories: one in dota_ugc/game/dota_addons and one in dota_ugc/content/dota_addons. For example, if your addon is called my_addon, it will have files in

/path/to/Steam/SteamApps/common/dota 2 beta/dota_ugc/game/dota_addons/my_addon
/path/to/Steam/SteamApps/common/dota 2 beta/dota_ugc/content/dota_addons/my_addon

Can we use one repository to keep track of both these directories?

Ideas:


Creating a unit that's controllable by a specific player

This code creates a mud golem at (0, 0, 0) on the Radiant team and makes it controllable by player 0:

 local unit_team = DOTA_TEAM_GOODGUYS
 local unit_name = "npc_dota_neutral_mud_golem"
 local player = PlayerResource:GetPlayer(0)
 local point = Vector(0, 0, 0)
 
 local unit = CreateUnitByName(unit_name, point, true, player, player:GetAssignedHero(), unit_team)
 unit:SetControllableByPlayer(player:GetPlayerID(), true)


Relevant links:

Triggers and shared mutable state

Problem

You have two triggers, trigger_get and trigger_set. When trigger_set is triggered, you want to save some information in a certain global variable. When trigger_get is triggered, you should be able to access that information.

An approach that doesn't work

Warning.pngWarning:Here is a common approach that DOES NOT WORK

1. Create scripts/vscripts/trigger.lua with the following content:

 FOO = 0 -- we want to save information in this global variable
 
 function SetSharedVar ()
    FOO = 1
    print("SetSharedVar called; FOO = " .. FOO)
 end
 
 function GetSharedVar ()
    print("GetSharedVar called; FOO = " .. FOO)
 end

2. In Hammer, edit the properties of trigger_get as follows:

  • Set Entity Scripts = trigger.lua.
  • Add an output like this:
My Output Target Entity Target Input Parameter Delay Only Once
Io11.png OnStartTouch trigger_get CallScriptFunction GetSharedVar 0.00 No

3. In Hammer, edit the properties of trigger_set as follows:

  • Set Entity Scripts = trigger.lua.
  • Add an output like this:
My Output Target Entity Target Input Parameter Delay Only Once
Io11.png OnStartTouch trigger_set CallScriptFunction SetSharedVar 0.00 No

The expected outcome: When a unit steps on trigger_set and then afterwards steps on trigger_get, we expect to see the following output in the console:

SetSharedVar called; FOO = 1
GetSharedVar called; FOO = 1

What really happens: What we actually see in the console is this:

SetSharedVar called; FOO = 1
GetSharedVar called; FOO = 0

This shows that the assignment FOO = 1 made by SetSharedVar is NOT visible to trigger_get.

My guess about why this happens: When you "bind" some Lua code to an entity by setting its Entity Scripts property, that code is "private" to the entity: The entity initially has ITS OWN "blank" Lua environment (with only the library functions and the game API visible), which no other entity can access. When the map is loaded, the game engine populates this environment by running the Lua file specified by the Entity Scripts property. In our case, we set Entity Scripts = trigger.lua on both triggers, but they both get THEIR OWN COPIES of the global variables in trigger.lua. So the assignment FOO = 1 made by trigger_set is not visible to trigger_get since it just changes trigger_set's copy of FOO.

An approach that works

Follow steps 1-3 above but replace Step 2 with this:

2'. In Hammer, edit the properties of trigger_get as follows:

  • DO NOT SET THE Entity Scripts PROPERTY
  • Add an output like this (note that we now use trigger_set as the target):
My Output Target Entity Target Input Parameter Delay Only Once
Io11.png OnStartTouch trigger_set CallScriptFunction GetSharedVar 0.00 No

With this solution we get the expected output in the console. Why? If the guess above is correct, it's because we're now using trigger_set as the target, hence GetSharedVar now accesses trigger_set's copy of FOO.

Holdout stuff

  • For the bosses they use the vscripts key (in npc_units_custom.txt) to set the AI file that should be used.
    • In the AI files the global variable thisEntity (which is not initialized anywhere in the files) seems to refer to the unit itself.
    • Also it seems that if there's a function called Spawn in the file, then it will be called (with a certain table as argument) when the unit is spawned.
    • How does Ogre Magi get its AI file hooked up?

Passing an argument to a thinker

Problem

You want to start a thinker at a certain time during the game, and you want this thinker to have access to some information that's only available at this time.

Solution

Take advantage of the fact that functions in Lua can access variables of their enclosing functions:

 -- addon_game_mode.lua

 function Activate ()
    ListenToGameEvent("entity_killed", ExactDelayedRevenge, nil)
 end

 -- Three seconds after an entity has been killed its attacker will be killed
 function ExactDelayedRevenge (keys)
    local attacker = EntIndexToHScript(keys.entindex_attacker)
    GameRules:GetGameModeEntity():SetThink(function ()
          -- We can access attacker since it's a variable of our enclosing function
          if attacker and attacker:IsAlive() then
             attacker:ForceKill(false)
          end
    end, 3)
 end

Almost interactive development

Tip.pngTip:Typing "script_reload_code test" in the console will cause the Lua code in scripts/vscripts/test.lua to be executed.

Changing properties of a hero on their first spawn

Problem

You need to initialize a hero through Lua when it spawns for the first time (which is normally when it gets selected by a player through the hero selection screen).

Solution

Register a listener on the "npc_spawned" event. The listener should check whether the spawned NPC is a real hero, in which case it should initialize the NPC and mark it as initialized (so that it doesn't get re-initialized the next time it spawns):

 -- addon_game_mode.lua

 local INIT_MARK = DoUniqueString("INIT") -- For marking a hero as initialized

 function Activate ()
    ListenToGameEvent("npc_spawned", OnNpcSpawned, nil)
 end

 function OnNpcSpawned (keys)
    local npc = EntIndexToHScript(keys.entindex)
    if npc and npc:IsRealHero() and not npc[INIT_MARK] then
       -- Initialize hero here, e.g.:
       npc:GetAbilityByIndex(0):SetLevel(3)
       npc[INIT_MARK] = true
    end
 end

Discussion

We can improve the above solution in at least two ways:

  1. The variable INIT_MARK is currently visible to the whole file. When there's a lot of code in the file, this can make it hard to figure out where the variable is used.
  2. We can make the OnNpcSpawned function easier to extend. Right now, if we want to use the function to initialize non-heroes, we have to change both the test and the body of the if statement.

We can solve both problems by introducing a "factory" function that takes an initialization function as argument:

 -- addon_game_mode.lua

 function Activate ()
    ListenToGameEvent("npc_spawned", MakeNpcInitializer(InitializeHero), nil)
 end

 -- Factory function for making listeners
 function MakeNpcInitializer (initFn)
    local initMark = DoUniqueString("INIT") -- private to this factory function
    return function (keys)
       local npc = EntIndexToHScript(keys.entindex)
       if npc and not npc[initMark] then
          initFn(npc)
          npc[initMark] = true
       end
    end
 end

 function InitializeHero (npc)
    if npc:IsRealHero() then
       -- Initialize hero here, e.g.:
       npc:GetAbilityByIndex(0):SetLevel(3)
    end
 end

Cancelling a thinker

Problem

You need to cancel a thinker that you have started.

Solution

Let the thinker return nil; this will cause it to stop:

 -- some_trigger.lua

 local IS_CANCELLED = false
 local THINK_INTERVAL = 1

 function OnStartTouch ()
    GameRules:GetGameModeEntity():SetThink(function ()
          if IS_CANCELLED then
             return nil -- Returning nil stops the thinker
          else
             print("not cancelled yet; proceeding")
             return THINK_INTERVAL
          end
    end)
 end

 function OnEndTouch ()
    IS_CANCELLED = true
 end

Discussion

The above example is quite crude. Provided that some_trigger.lua is set as the entity script of a trigger with the appropriate outputs, it will work like this: Every time a unit steps onto the trigger, a thinker will be started that prints every second. When a unit steps off the trigger, all these thinkers will stop. We can refine this as follows:

 -- some_trigger.lua

 local CANCEL_MARK = DoUniqueString("CANCEL")
 local THINK_INTERVAL = 1

 function OnStartTouch (keys)
    local activator = keys.activator
    activator[CANCEL_MARK] = nil
    activator:SetThink(function ()
          if activator and not activator[CANCEL_MARK] then
             -- Not cancelled yet; do some stuff here
             print(activator:GetName())
             return THINK_INTERVAL
          end
    end)
 end

 function OnEndTouch (keys)
    keys.activator[CANCEL_MARK] = true
 end

This code has the following effect: Every time a unit steps onto the trigger, a thinker starts that prints the unit's name every second. When a unit steps off the trigger, his thinker is cancelled.

Dota Hammer entities

Extracted from /path/to/Steam/SteamApps/common/dota 2 beta/dota_ugc/game/dota/tools/help/fgd/dota.txt:

npc_dota_spawner
Spawns NPCs based on scripts.
npc_dota_scripted_spawner
Spawns NPCs based on scripts for tutorials / single player / co-op.
dota_color_correction
An entity to control the color correction in the map.
dota_item_rune_spawner
A marker for where runes spawn.
dota_minimap_boundary
Used by the console command dota_minimap_create to define the min/max coordinates for taking minimap images. Two are required per map in opposite corners. The z difference between the two defines the image depth.
ent_dota_dire_candybucket
(used in Diretide event) Spawns a Dire candy bucket.
ent_dota_fountain
The Fountain
ent_dota_shop
Creates a Dota item shop.
ent_dota_tree
Creates a Dota tree. Trees have collision, block fog of war visibility, and can be destroyed. Note: it's far faster to place trees via the Tile Editor tool.
npc_dota_barracks
Creates a barracks, which spawns creeps at regular intervals and can be destroyed by enemy teams.
npc_dota_building
Creates a simple building.
npc_dota_fort
Creates an ancient. In standard Dota2 PvP, the win condition is to destroy the enemy team's ancient.
npc_dota_holdout_tower_heavyslow
(used in Frostivus event) Creates a heavily-damaging, slowly-attacking tower. This can also be edited in the npc_units.txt file.
npc_dota_holdout_tower_lightfast
(used in Frostivus event) Creates a lightly-damaging, fast-attacking tower. This can also be edited in the npc_units.txt file.
npc_dota_neutral_spawner
Spawns neutral units.
npc_dota_roshan_spawner
Spawns Roshan, the big boss in the standard Dota2 PvP map.
npc_dota_spawner_bad_bot
Spawns Dire creeps in the bottom lane of the standard Dota2 PvP map.
npc_dota_spawner_bad_mid
Spawns Dire creeps in the middle lane of the standard Dota2 PvP map.
npc_dota_spawner_bad_top
Spawns Dire creeps in the top lane of the standard Dota2 PvP map.
npc_dota_spawner_good_bot
Spawns Radiant creeps in the bottom lane of the standard Dota2 PvP map.
npc_dota_spawner_good_mid
Spawns Radiant creeps in the middle lane of the standard Dota2 PvP map.
npc_dota_spawner_good_top
Spawns Radiant creeps in the top lane of the standard Dota2 PvP map.
npc_dota_tower
Creates a Dota tower that attacks enemy units, provides vision of invisible enemies, and allows allies to teleport to it.
ent_dota_game_events
Fires outputs based on predefined game events.
dota_displacement_visibility
Entity that can hide a displacement
ent_sugar_rush
Sugar Rush spot for Roshan.
ent_dota_radiant_candybucket
(used in Diretide event) Spawns a Radiant candy bucket.
ent_dota_lightinfo
Controls localized lighting settings in a radius. This can override global settings.
ent_fow_blocker_node
Blocks fog of war along a line to its target.
ent_fow_revealer
Reveals fog of war in a radius.
info_player_start_goodguys
Spawn point for Radiant heroes.
info_player_start_badguys
Spawn point for Dire heroes.
env_occluder
A test entity for radius occluding for the fog of war system.
env_line_occluder
A test entity for line occluding for the fog of war system.
env_viewer
A test entity for viewing for the fog of war system.
dota_prop_customtexture
Custom texture prop.
dota_world_particle_system
Dota world particle system.
prop_dynamic_clientside
Client-side dynamic prop.
prop_player_cosmetic
Cosmetic player prop.
ambient_creatures
Client-side dynamic prop.
ambient_creatures_zone
Client-side func_brush.
world_bounds
Defines camera constraint coordinates.
dota_building
dota_building
npc_dota_holdout_tower_reducespeed
(used in Frostivus event) Creates a tower that reduces enemy movespeed. This can also be edited in the npc_units.txt file.
ent_dota_halloffame
The Hall of Fame.
info_courier_spawn_radiant
Spawns a Radiant team courier.
info_courier_spawn_dire
Spawns a Dire team courier.
trigger_shop
Region that defines the shop radius.
trigger_no_wards
Wards disallowed here.
trigger_boss_attackable
Boss (Roshan) is attackable from here.
trigger_hero
A trigger that's fired when a hero touches it.
tutorial_npc_blocker
The start or endpoint of an NPC blocking line.
info_roquelaire_perch
(used in Dota2 PvP tutorial) A perch point for Roquelaire to sit on.
env_global_light
Defines global light settings.
env_deferred_light
Deferred light entity.
env_deferred_spot_light
Deferred spot light.

Base Hammer entities

Extracted from /path/to/Steam/SteamApps/common/dota 2 beta/dota_ugc/game/core/tools/help/fgd/base.txt:

ai_speechfilter
An entity that can be used to control the idle speech patterns of a set of NPCs.
ambient_generic
Universal ambient sound. Use it to play and control a single sound.
ambient_music
Play L4D specfic music.
color_correction
An entity to control the color correction in the map.
color_correction_volume
An entity to control the color correction in the map.
cycler
An entity used to display a model for testing purposes. Shooting it with cycle through the model's animations.
devtest_hierarchy
Various hierarchy related unit tests - For use in devtest.
devtest_hierarchy2
Various hierarchy related unit tests - For use in devtest.
devtest_hierarchy_child
Various hierarchy related unit tests - For use in devtest.
env_beam
An entity that creates a visible beam between two points. The points can be attached to entities to make the beam move around.
env_beverage
HL1 Legacy: Beverage Dispenser.
env_blood
An entity used to spawn blood effects.
env_bubbles
An entity used to create a volume in which to spawn bubbles.
env_cubemap
An entity that creates a sample point for the Cubic Environment Map.
env_dof_controller
An entity that controls the depth of field settings for the player. Depth of field simulates camera blur of out-of-focus regions of the scene.
env_dustpuff
An entity that can emit dust puffs.
env_effectscript
An entity that allows you to script special visual effects via a script file.
env_embers
An entity used to create a volume in which to spawn fire embers.
env_entity_igniter
An entity that catches a target entity on fire. If the entity is an animating model, it will have sprite flames attached to its skeleton. Otherwise the entity will emit particle flame puffs.
env_entity_maker
Spawns the specified entity template at its origin. If set to auto-spawn, it will spawn the template whenever there's room and the player is looking elsewhere.
env_explosion
An entity that creates an explosion at its origin.
env_fade
An entity that controls screen fades.
env_fire
An entity that handles a single flame at its origin. The flame causes heat 'damage' to other env_fire entities around it, and will eventually ignite non-flaming env_fire entities nearby, causing the fire to spread.
env_firesensor
An entity that detects changes in heat nearby.
env_firesource
An entity that provides heat to all nearby env_fire entities. Cannot be extinguished.
env_fog_controller
An entity that controls the fog and view distance in the map.
env_funnel
HL1 Legacy: Large Portal Funnel
env_hudhint
An entity to control the display of HUD hints. HUD hints are used to show the player what key is bound to a particular command.
env_instructor_hint
An entity that allows for creation and control of instructor lessons by map logic
env_laser
An entity that creates a laser beam between itself and a given target.
env_lightglow
An entity that puts an additive glow in the world, mostly used over light sources.
env_message
An entity that draws a text message on player's HUDs.
env_microphone
An entity that acts as a microphone. It works in one of two modes. If it has a 'Speaker' set, it picks up all sounds within the specified sound range, and rebroadcasts them through the Speaker entity. In this Speaker mode, it ignores the Hears X spawnflags and does not fire the SoundLevel output. If it has no Speaker set, it measures the sound level at a point, and outputs the sound level as a value between 0 and 1. In Measuring mode, it only hears sounds that match the Hear X spawnflags.
env_particle_performance_monitor
An entity for turning on and off measuring and display of particle throughput.
env_particlelight
An entity that can be used to light the smoke particles emitted by env_smokestack entities. Does not light any other particle types.
env_particlescript
An entity that has special animation events that can be fired by a model with an animation inside its .qc designed foruse by this entity.
env_physexplosion
An entity that creates an explosion at its origin. If the no-damage spawnflag is set, the explosion won't be visible, but will apply force to any physics objects within its radius.
env_physimpact
An entity that will cause a physics impact on another entity.
env_player_surface_trigger
An entity that monitors the material of the surface the player is standing on, and fires outputs whenever it changes to/from a specific material.
env_projectedtexture
Projected texture entity.
env_rotorshooter
An entity that creates gibs when it's within the influence of a helicopter's rotor wash.
env_rotorwash_emitter
Creates rotorwash.
env_screeneffect
Allows screenspace effects to be played on the player's view.
env_screenoverlay
An entity that can display and control a set of screen overlays, to be displayed over the player's view. Useful for view effects like drunkenness, or teleporter afterimages, etc.
env_shake
An entity to control screen shake on players.
env_shooter
An entity that shoots models, or sprites, out of its origin.
env_smokestack
An entity that spits out a constant stream of smoke. See particlezoo.vmf for sample usage. You can place up to two env_particlelight entities near the smoke stack to add ambient light to its particles.
env_smoketrail
An entity that creates a smoke trail.
env_soundscape
An entity to control sound in an area. The active soundscape at any time is the last one that had line-of-sight to the player, and was within the radius.
env_soundscape_proxy
An entity that acts like a soundscape but gets all of its sound parameters from another env_soundscape entity.
env_soundscape_triggerable
An entity that works like env_soundscape except that it works in conjunction with trigger_soundscape to determine when a player hears it.
env_spark
An entity used to create sparks at its origin.
env_splash
An entity that creates a splash effect at its origin. If the 'find water surface' spawnflag is set, it will instead trace down below itself to find the water surface on which to create splashes.
env_sprite
An entity that controls the drawing of a sprite in the world.
env_sprite_oriented
A env_sprite that allows orientation.
env_spritetrail
A magical trail you can parent to anything you heart desires.
env_steam
An entity used to create a jet of steam.
env_sun
An entity to control & draw a sun effect in the sky.
env_texturetoggle
An entity that allows you to change the textures on other brush-built entities.
env_viewpunch
Causes a view punch on players.
env_wind
An entity to control wind in the map. Partially functional.
env_zoom
An entity that can be used to control the player's FOV. Useful for scenes where the player's view is being controlled, or player-usable binoculars/telescopes, etc.
filter_activator_class
A filter that filters by the class name of the activator.
filter_activator_context
A filter that filters by a context on the activator.
filter_activator_mass_greater
A filter that filters by the mass of the activator.
filter_activator_model
A filter that filters by the model of the activator.
filter_activator_name
A filter that filters by the name of the activator.
filter_damage_type
A damage filter that filters by the type of damage inflicted. This can only be used as a damage filter, not as an activator filter.
filter_enemy
A filter that filters a potential enemy entity by a set of criteria.
filter_multi
A filter that tests the activator against multiple filters. This allows you to build more complex filters, such as'Allow anyone on Team 1 who is also class engineer', or 'Allow everyone except classes npc_zombie and npc_headcrab'.
func_areaportal
A portal brush used to manage visibility in maps. Portals define areas, which are spaces that are connected in the map. Both sides of a portal cannot touch the same area, for example, a doughnut shaped map would require at least two portals to divide the map into two areas. A linear map could be divided into two areas with a single area portal.
func_areaportalwindow
An entity that can be used to optimize the visibility in a map. If you seal off an area with them, when the viewer moves the specified distance away from them, they will go opaque and the parts inside the area will not be drawn. The 'target' brush model should enclose the func_areaportal window so no parts of it are culled by the window. If you use the optional foreground brush model, then it should enclose the 'target' brush model.
func_breakable
A brush entity that can be broken from damage, or an input.
func_brush
An brush built entity with various features.
func_button
A brush entity that's designed to be used for a player-useable button. When used by the player, it moves to a pressed position.
func_clip_vphysics
A brush entity that's considered solid to vphysics.
func_conveyor
Conveyor Belt
func_detail_blocker
A brush entity that prevents detail sprites from being placed inside its volume.
func_door
A brush entity for use as a player-useable door.
func_door_rotating
A brush entity for use as a rotating player-useable door.
func_dustcloud
A brush entity that spawns a translucent dust cloud within its volume.
func_dustmotes
A brush entity that spawns sparkling dust motes within its volume.
func_fish_pool
Creates a school of interactive fish that swim near this entity.
func_guntarget
This is a moving target that moves along a path of path_tracks. It can be shot and killed.
func_illusionary
Legacy support. Use func_brush instead.
func_instance
An entity for placing an instance of a prefab map file. You may translate and rotate this entity. You can use the replace keys to do parameter changes on the instance contents. In a $ at the beginning of a variable name. Then just use the $variable name inside of the instance contents on any value portion of a key/value pair.
func_instance_parms
Place one copy of this entity inside of an instance. Whenever you add a $parameter for the instance, get the properties of this entity. It will auto-populate it with the variables and allow you to indicate the variable type.
func_ladderendpoint
An entity used to specify the endpoints of a ladder. This entity is functional, but has been replaced by the easier-to-use func_useableladder entity. Left in only for backwards-compatibility!
To be valid, a full sized player hull traced between the start and end points must not be obstructed at level activation time. The angle determines in which direction the player leaves the ladder if the player presses the +jump button.
Note: This entity is non-functional in Counter-Strike: Source. In CS:S, use func_ladder instead.
func_lod
Brush-built model that fades out over a specified distance. Useful for creating world detail that doesn't need to be drawn far away, for performance reasons.
func_movelinear
A brush entity that moves linearly along a given distance, in a given direction.
func_occluder
A func_occluder occludes objects behind it. It is used for rendering performance optimization. One use case is to put it into a doorway and toggle it based on whether the door is open or not. Note that geometry surrounding the doorway should have occluders as well, otherwise the benefit of the func_occluder is limited.
func_occluders should be as large as possible for best occlusion.
func_orator
A very simple model entity that has animations and response rules.
func_physbox
A brush entity that's physically simulated.
func_platrot
A brush entity that moves vertically, and can rotate while doing so.
func_precipitation
A brush entity that creates rain and snow inside its volume.
func_precipitation_blocker
A brush entity that prevents rain and snow inside its volume.
func_reflective_glass
Used to produce perfectly reflective glass that renders world + entities. Typically, you want your glass brush to have nodraw on all non-reflective surfaces and you want to use a shader like lightmappedreflective in your material applied to the non-nodraw surfaces. See hl2/materials/glass/reflectiveglass001.vmt for an example. NOTE: currently, you cannot use reflective glass in scenes with water, and you can only have 1 reflective glass in your view frustum ( + pvs ) at a time.
func_rot_button
A brush entity that's designed to be used for a rotating player-useable button. When used by the player, it rotates to a pressed position.
func_rotating
A rotating brush entity.
func_smokevolume
A brush entity that spawns smoke particles within its volume.
func_tanktrain
A moving train that follows a path of path_track entities, shoots at the player, and can be killed.
NOTE: Build your train so that the front of the train is facing down the X axis. When it spawns it will automatically rotate to face the next path_track on the path.
func_timescale
Adjust the time scale of the server and client.
func_trackautochange
An entity that works as a rotating/moving platform that will carry a train to a new track. It must be larger in X-Y planar area than the train, since it must contain the train within these dimensions in order to operate when the train is near it.
func_trackchange
An entity that works as a rotating/moving platform that will carry a train to a new track. It must be larger in X-Y planar area than the train, since it must contain the train within these dimensions in order to operate when the train is near it.
func_tracktrain
A moving platform that the player can ride. It follows a path of path_track entities.
NOTE: Build your train so that the front of the train is facing down the X axis. When it spawns it will automatically rotate to face the next path_track on the path.
func_traincontrols
When used by the player, this entity overrides the player's controls to let them drive a train.
func_useableladder
A Half-Life 2 ladder. Handles player auto mount/unmount, as well as +use to get onto the ladder.
See also 'info_ladder_dismount', used to specify ladder auto-dismount points.
Note: This entity is non-functional in Counter-Strike: Source. Use func_ladder instead.
func_viscluster
Any leaves touching this brush will have their vis merged together into a single cluster. Use multiple func_viscluster entities to reduce vis time
func_wall
Legacy support. Use func_brush instead.
func_wall_toggle
A brush entity that can be toggled on/off. When off, the brush will be non-solid and invisible. Does not cast lightmap shadows.
func_water_analog
A water brush entity that moves linearly along a given distance, in a given direction
game_end
An entity that ends a multiplayer game.
game_gib_manager
An entity to control the number of gibs in the world, for performance reasons.
game_player_equip
An entity that gives equipment to the player who activates it. To use, add new keys to this entity, where each key is the classname of a weapon/item, and the corresponding value is the number of those weapons/items to give to the player who uses this entity. If the 'Use Only' spawnflag isn't set, then players can just touch this entity to get the equipment.
game_player_team
An entity that changes the team of the player who activates it.
game_ragdoll_manager
An entity to control the number of ragdolls in the world, for performance reasons.
game_score
An entity that awards/deducts points from the player who activates it.
game_text
An entity that displays text on player's screens.
game_ui
An entity used to override player input when the player is looking at it.
game_weapon_manager
An entity used to limit the number of a particular weapon type in the world. Useful in places where NPCs are spawning rapidly, dying, and dropping weapons.
game_zone_player
An entity used to count the number of players within a zone.
gibshooter
An entity that shoots out gibs. Style of body part depends on language type.
gibshooterbase
hammer_updateignorelist
Specifies entities that are to be ignored by the hammer_update_safe_entities console command. Enter the targetnames of entities that you want to exclude into the list of fields here. Several of these may exist in a map.
info_camera_link
An entity that can use point_cameras to render images for materials used by entities. To author the material, use the special identifier _rt_Camera for the $baseTexture (or whatever texture you want, like envmap, etc.) in the .vmt then connect the 'target' field to the entity which uses that material, and the 'PointCamera' field to the point_camera you want to have appear on that entity's material
info_constraint_anchor
An entity used to attach constraints to a local position on an entity. Usually constraints will attach to the center of mass of an object. Attach the desired constraint to this entity, and then parent this entity to the entity you want the constraint to apply to.
info_hint
A hint that is not used for navigation. They don't go into the nodegraph, nor do they fall to the ground. Use these to provide some spatial context for NPCs, such as 'look here if you can't find the player' or 'throw rocks at this spot'.
info_intermission
An entity that defines an intermission spot where dead players will float until they respawn.
info_ladder_dismount
An entity to handle endpoints for multiple ladders that are too close to each other.
info_landmark
An entity that acts as a landmark for transitions to another level. There should be a corresponding info_landmark entity in the next map. Entities will be transitioned to the next level relative to the info_landmark entities.
info_lighting
An entity that can be used to change the lighting origin of a prop_static. Set the prop_static's Lighting Origin to point at this entity to make the prop_static light as if it was at the info_lighting's origin. Good for prop_static entities that are embedded in world geometry (like rocks/windows/etc).
info_mass_center
An entity that overrides the mass center of the target physics prop, or func_physbox, by moving it to the info_mass_center's location.
info_no_dynamic_shadow
Use this entity to mark surfaces that shouldn't receive dynamic shadows. Useful to apply to walls and floors where shadows are drawn improperly, giving away the location of enemies.
info_node
A navigation node for ground moving NPCs. Navigation nodes are baked into the nodegraph so that NPCs can move to them. Ground nodes fall to the ground when they spawn.
info_node_air
A navigation node for flying NPCs. Air navigation nodes are baked into the nodegraph so that NPCs can move to them. Air nodes do not fall to the ground when they spawn.
info_node_air_hint
A navigation node for flying NPCs that includes some context information for NPCs that are interested in it. The hint might indicate a window that could be looked into, or an item of interest that could be commented on. Many hint nodes are NPC-specific, so it's helpful to use naming conventions like 'Crow: Fly to point' in the hint choices list. The angles of a hint node indicate what direction the NPC should face to perform the hint behavior.
info_node_climb
A climb-node for AI navigation. Only usable by NPCs that can climb.
info_node_hint
A navigation node for ground moving NPCs that includes some context information for NPCs that are interested in it. The hint might indicate a window that could be looked out of, or an item of interest that could be commented on. Many hint nodes are NPC-specific, so it's helpful to use naming conventions like 'Crow: Fly to point' in the hint choices list. The angles of a hint node indicate what direction the NPC should face to perform the hint behavior.
It's important to understand the distinction between scripts, such as scripted_sequence and scripted_schedule, and info_hint entities. Scripts summon NPCs to specific cue points to play their parts, while hints provide context information to the AI that they use to perform their behaviors. Hints require code support in the NPC, while scripts are generic and may require only animations to play. Use a hint if the behavior is driven by the AI, use a script if the behavior is driven by the map.
info_node_link
A dynamic connection between two navigation nodes. You specify the node IDs of the start and end nodes, and then you can use entity I/O to turn on and off the connection. This could be used to create or destroy a connection in the nodegraph because of some event in your map (a bridge being created/destroyed, etc).
info_node_link_controller
An entity that controls all connections between nodes that intersect the controller's volume. This allows for mass enabling/disabling of all node connections through a volume.
info_npc_spawn_destination
NPC Spawn Destination. (Consult npc_template_maker help for more info)
info_null
An entity that's immediately removed on spawning. Useful as a spotlight target.
info_overlay_transition
Overlay Transition
info_particle_system
An entity that spawns a particle system built using the particle editor.
info_particle_target
An entity that is a target for particle system control points
info_player_start
This entity indicates the position and facing direction at which the player will spawn. Any number of info_player_start entities may be placed in a map for when working in cordoned-off portions of the map. When multiple info_player_start entities are present in a map, set the 'Master' spawnflag on one of them to indicate which one should be used when running the entire map.
info_projecteddecal
An entity that projects a decal onto the world (or props). If the decal has no target name, it will immediately apply itself when the level is loaded. If it has a name specified, it won't apply until it receives the 'Activate' input.
info_radial_link_controller
This entity automatically severs node connections that pass through its radius. If it moves, it will restore those connections.
info_spawngroup_load
Logical entity that starts async loading the next level.
info_spawngroup_unload
Logical entity that unloads a level.
info_teleport_destination
An entity that does nothing itself, but can be used to specify the destination for a trigger_teleport entity. An info_target can be used instead.
infodecal
An entity that places a decal on the world. If the decal has no target name, it will immediately apply itself when the level is loaded. If it has a name specified, it won't apply until it receives the 'Activate' input.
keyframe_rope
A node entity that marks a point in a rope. The first node in the rope should be a move_rope, followed by 1 or more keyframe_ropes.
keyframe_track
Animation KeyFrame
light
An invisible omnidirectional lightsource.
light_dynamic
An invisible lightsource that changes in some way over time.
light_environment
Sets the color and angle of the light from the sun and sky.
logic_active_autosave
An entity that is used to look for opportunities to autosave.
logic_auto
Fires outputs when a map spawns. If 'Remove on fire' flag is set the logic_auto is deleted after firing. It can be set to check a global state before firing. This allows you to only fire events based on what took place in a previous map.
logic_autosave
An entity that is used to force an autosave.
logic_branch
Tests a boolean value and fires an output based on whether the value is true or false. Use this entity to branch between two potential sets of events.
logic_branch_listener
Contains a list of logic_branch entities and fires outputs when the state of any of the logic_branches changes.
This entity is used to fire an event when a set of conditions are all satisfied.
logic_case
Compares an input to up to 16 preset values. If the input value is the same as any of the preset values, an output corresponding to that value is fired.
For example: if Case01 is set to 2 and Case02 is set to 5, and the input value is 5, the OnCase02 output will be fired.
This entity can also be used to select from a number of random targets via the PickRandom input. One of the OnCase outputs that is connected to another entity will be picked at random and fired.
logic_collision_pair
An entity that can be used to enables/disable vphysics collisions between two target entities.
logic_compare
Compares an input value to another value. If the input value is less than the compare value, the OnLessThan output is fired with the input value. If the input value is equal to the compare value, the OnEqualTo output is fired with the input value. If the input value is greater than the compare value, the OnGreaterThan output is fired with the input value.
logic_lineto
An entity that calculates and outputs a vector from one entity to another.
logic_measure_movement
An entity that can measure the movement of an entity relative to another entity and apply that movement to a third entity.
logic_multicompare
Compares a set of inputs to each other. If they are all the same, fires an OnEqual output. If any are different, fires the OnNotEqual output.
logic_navigation
An entity that is used to set navigation properties on other entities. Useful to make NPCs ignore physics props in their way that they can easily push.
logic_playerproxy
An entity that is used to relay inputs/ouputs to the player and back to the world.
logic_relay
A message forwarder. Fires an OnTrigger output when triggered, and can be disabled to prevent forwarding outputs.
Useful as an intermediary between one entity and another for turning on or off an I/O connection, or as a container for holding a set of outputs that can be triggered from multiple places.
logic_script
An entity that acts as a container for scripts
logic_timer
An entity that fires a timer event at regular, or random, intervals. It can also be set to oscillate betweena high and low end, in which case it will fire alternating high/low outputs each time it fires.
material_modify_control
An entity that can be used to directly control material vars. To use it, you need to read the .vmt of the material you intend to change. Parent this entity to a brush model entity who's material you want to control.
math_colorblend
Used to create a blend between two colors for controlling the color of another entity.
math_counter
Holds a numeric value and performs arithmetic operations upon it. If either the minimum or maximum legal value is nonzero, OutValue will be clamped to the legal range, and the OnHitMin/OnHitMax outputs will be fired at the appropriate times. If both min and max are set to zero, no clamping is performed and only the OutValue output will be fired.
math_remap
An entity that remaps a range of input values to a given range of output values.
momentary_rot_button
A brush entity that's designed to be used for rotating wheels, where the player can rotate them to arbitrary positions before stopping.
move_keyframed
Keyframed Move Behavior
move_rope
The first node in set of nodes that are used to place ropes in the world. It should connect to 1 or more keyframe_rope entities.
move_track
Track Move Behavior
npc_furniture
An entity used for non-NPCs that need to synchronise their animation with an NPC in a scripted_sequence. Usually a pieceof furniture or door that an NPC needs to manipulate within a scripted_sequence.
npc_puppet
Puppet entity that mimics the animations of a target NPC.
npc_template_maker
An entity that creates NPCs. The NPCs it creates are clones of a template NPC. NPCs are spawned around this maker's origin, or at specified destination points.
path_track
An entity used to build paths for other entities to follow. Each path_track is a node on the path, each holding the name of the next path_track in the path.
phys_ballsocket
A constraint that keeps the position of two objects fixed, relative to the constraint's origin. It does not affect rotation.
phys_constraintsystem
An entity used to manage a group of interacting constraints and keep them stable. All constraints on a set of entities should be placed in the same system, or they will fight each other during simulation.
phys_convert
Turns an arbitrary entity into a physically simulated entity. i.e. brush entities will behave like func_physbox, model entities behave like prop_physics.
phys_hinge
A physically simulated hinge. Use the helper to define the axis of rotation.
phys_keepupright
A controller that tries to keep an entity facing a particular direction.
phys_lengthconstraint
A constraint that preserves the distance between two entities. If the 'Keep Rigid' flag is set, think of it as a rod. If not, think off it as a virtual rope.
phys_magnet
An entity that acts like a magnet, attaching metallic physics objects to itself when they touch it.
phys_motor
An entity that tries to spin a target entity at a particular speed.
phys_pulleyconstraint
A constraint that is essentially two length constraints and two points. Imagine it as a virtual rope connected to two objects, each suspended from a pulley above them.The constraint keeps the sum of the distances between the pulley points and their suspended objects constant.
phys_ragdollconstraint
A constraint that fixes the position of two entities, relative to this constraint's origin. Also allows for limits on the rotation around each axis, in the space of this constraint.
phys_ragdollmagnet
An entity that acts like a magnet for ragdolls. Useful for crafting exaggerated ragdoll behavior (i.e. guys falling over rails on death). If the Bar Magnet spawnflag is set, the magnet works like it was a cylindrical magnet i.e. it attracts ragdolls to the nearest point on a line.
phys_slideconstraint
A constraint that constrains an entity along a line segment.
phys_spring
A physically simulated spring. 'Length' is what's known as the 'natural spring length'. This is how long the spring would be if it was at rest (nothing hanging on it or attached). When you attach something to the spring, it will stretch longer than its 'natural length'. The amount of stretch is determined by the 'Sprint Constant'. The larger the spring constant the less stretch the spring.
phys_thruster
An entity used to apply constant acceleration to a physics object. The force and torque is calculated using the position and direction of the thruster as an impulse. So moving those off the object's center will cause torque as well. Torque can be removed by unchecking the 'apply torque' flag. The position of the thruster can be forced to be at the object's center by checking to 'ignore pos' flag.
phys_torque
An angular thruster. Use it to apply angular force to an entity.
physics_cannister
A physically simulated gas cannister that can have its cap shot off, at which point gas will start escaping and cause the cannister to fly around. If it takes enough damage, it will explode.
point_anglesensor
An entity that detects if another entity points in a given direction for a period of time.
point_angularvelocitysensor
An entity that detects if another entity's angular velocity meets or exceeds a threshold value.
point_bonusmaps_accessor
An entity that relays bonus maps changes.
point_broadcastclientcommand
An entity that issues commands to each valid client's console, as if it was typed in by that player locally.
point_clientcommand
An entity that issues commands to the client console, as if it was typed in by the player (if activator is a player, or the local player in single player).
point_devshot_camera
An entity used by the -makedevshots system, which automatically takes screenshots at the position of every devshot camera in the level.
point_enable_motion_fixup
An entity used to move a motion-disabled prop when it enables motion. Parent this entity to the prop, and when the prop has its motion enabled, it will immediately teleport to the origin of this entity.
point_entity_finder
An entity that will find an entity and pass it along as the !Caller with the OutEntity output. Requires using !Caller as the parameter on the input.
point_gamestats_counter
Generic game statistics counter.
point_hurt
An entity that does damage to all entities in a radius around itself, with a specified delay.If 'Target Entity' is specified, the damage is only done to that entity.
point_levelstream
A point that indicates a seam to another world level.
point_message
An entity that displays a text message in the world, at its origin.
point_playermoveconstraint
An entity that constrains players to a radius around itself, slowing them down the closer they get to the edge of the radius.
point_posecontroller
An entity that controls a pose parameter of a prop and cycles the pose clientside.
point_proximity_sensor
An entity that detects another entity's proximity to a target position.
point_servercommand
An entity that issues commands to the server console.
point_spotlight
An entity to draw a spotlight. Will draw a beam when the player views it side on, and a halo when it's facing towards the player. Unless the 'No Dynamic Light' spawnflag is checked, it will also create a dynamic light wherever the end of the spotlight rests.
point_teleport
An entity that teleports a target entity to this position and angles. If 'Teleport Home' spawn flag is set, teleports the target entity to its spawn position instead.If object is physically simulated, simulation is turned off when teleported.
point_template
Turns an entity, or set of entities, into a single template that can be instanced anywhere, and multiple times. If there are interdependencies (entity I/O, hierarchy, or other name references) between the entities in the template, the entities in the template will have their names changed and the interdependencies will be reconnected to the changes names. The name change format is as follows: '<original name>&0000', where the 0000 will be replaced with the current global template instance, so wildcard searches for '<original name>*' will still find them.
If you don't want the name fixup to happen, because you're only spawning the template once, or you want inputs to trigger all instances of the template, check the 'Preserve entity names' spawnflag.
To spawn the template in other places, use an env_entity_maker.
point_tesla
An entity that creates tesla lightning arcs around its origin.
point_velocitysensor
An entity that detects and outputs an entity's velocity.
point_viewcontrol
A camera entity that controls the player's view. While it's active, the player will see out of the camera.
postprocess_controller
An entity that controls the postprocess settings in the map.
prop_detail
Detail Prop
prop_detail_base
prop_door_rotating
An entity used to place a door in the world.
prop_dynamic
A prop that can be placed in hierarchy and can play animations. It can also be configured to break when it takes enough damage. Note that the health of the object will be overridden by the health inside the model, to ensure consistent health game-wide. If the model used by the prop is configured to be used as a prop_physics (i.e. it should be physically simulated) then it CANNOT be used as a prop_dynamic. Upon level load it will display a warning in the console and remove itself. Use a prop_physics instead.
prop_dynamic_base
prop_dynamic_ornament
A way to attach one editormodel model to another as an ornament. It will render in the way that player/NPC weapons render.
prop_dynamic_override
A prop that can be placed in hierarchy and can play animations. It can also be configured to break when it takes enough damage.
prop_dynamic_override is a prototyping entity only. It will allow the use of models designed to be used as prop_physics.
prop_physics
A prop that physically simulates as a single rigid body. It can be constrained to other physics objects using hinges or other constraints. It can also be configured to break when it takes enough damage. Note that the health of the object will be overridden by the health inside the model, to ensure consistent health game-wide. If the model used by the prop is configured to be used as a prop_dynamic (i.e. it should not be physically simulated) then it CANNOT be used as a prop_physics. Upon level load it will display a warning in the console and remove itself. Use a prop_dynamic instead.
prop_physics_multiplayer
This class is the same as prop_physics, except the runtime collisions use a more bouncy method that avoids the prediction errors normal physics objects get.
prop_physics_override
A prop that physically simulates as a single rigid body. It can be constrained to other physics objects using hinges or other constraints. It can also be configured to break when it takes enough damage. Health can be overridden on this version.
prop_ragdoll
A prop that physically simulates and can be articulated with internal joints. The joint constraints are part of the physics model.
prop_static_base
prop_wall_breakable
A section of wall that's breakable just like doors are.
shadow_control
An entity to control the shadows in the map.
sky_camera
An entity used to control the 3D Skybox. Its origin is used to determine the 3D Skybox's position relative to the map. Place this entity, in the 3D Skybox, at the point where the origin of the map should be.
sound_mix_layer
Set a mix layer to a specific value.
tanktrain_ai
Train chase AI
tanktrain_aitarget
An entity that changes the target of a tanktrain_ai entity.
test_traceline
A debugging tool for testing tracelines.
trigger_autosave
A trigger volume that autosaves when the player touches it.
trigger_changelevel
An entity that triggers a level change.
Place an info_landmark in both maps that marks the 'same' location in each map.
TIPS & TRICKS: To fire events in the next level, use the OnLevelChange output to turn on an env_global in the current level. Create a logic_auto in the next level that checks for the state set by the env_global.
To control which entities go through the level transition, create one or more trigger_transitions and give them the same name as the landmark. Any entities within the trigger_transition(s) will go to the next map.
trigger_gravity
A trigger volume that changes the gravity on any entity that touches it.
trigger_hurt
A trigger volume that damages entities that touch it.
trigger_impact
A trigger volume that can be told to push all physics objects that are inside of it in the direction specified by this trigger's angles.
Also outputs the force at the time of impact for anyone else that wants to use it.
trigger_look
An entity used to trigger something when the player looks at something. It fires 'OnTrigger' when the player looks at a target entity for the given amount of time, while within the trigger volume. If the player leaves the trigger or looks away from the target entity the clock resets. If the 'Use Velocity instead of facing' spawnflag is checked, the trigger uses the player's velocity instead of the player's view, so it determines whenever the player is moving toward the target entity. Useful for triggering when players are driving a vehicle at something.NOTE: Only designed for single-player game.
trigger_multiple
A trigger volume that can be triggered multiple times.
trigger_once
A trigger volume that removes itself after it is triggered once.
trigger_playermovement
An entity that can be used to disable player's automatic ducking/unducking when jumping.
trigger_proximity
Measures the distance of the player within the trigger volume from a given point (and within a given radius). The NearestPlayerDistance output will be 0 when the player is at the center point, and 1 when the player is at the radius.
trigger_push
A trigger volume that pushes entities that touch it.
trigger_remove
A trigger volume that removes any entities that touch it. Be careful, removing some entities can cause instability. This is not the same as killing entities. i.e. NPCs removed in this manner will not fire their OnKilled outputs.
trigger_serverragdoll
A volume that forces any NPC inside it to create a server side ragdoll instead of a client one.
trigger_soundscape
Soundscape trigger. It is not necessary to create outputs for this trigger. It automatically will trigger the soundscape referred to by its 'Soundscape' property.
trigger_teleport
A trigger volume that teleports entities that touch it. Entities are teleported to the Remote Destination, and have their angles set to that of the Remote Destination's. If a Local Destination Landmark is specified, teleported entities are offset from the target by their initial offset from the landmark, and their angles are left alone.
trigger_tonemap
Changes tonemap controllers for players touching the trigger.
trigger_transition
A volume that's used to control which entities go through the level transition. Create one or more trigger_transitions and give them the same name as the changelevel landmark. Any entities within the trigger_transition(s) will go to the next map.See trigger_changelevel for more info.
trigger_wind
A trigger volume that pushes physics objects that touch it.
vgui_screen
A VGUI screen. Useful for in-world monitors.
vgui_screen_base
vgui_slideshow_display
Slideshow Display
water_lod_control
An entity used to control the LOD behavior of any water in the map. If your map has water, this entity is required.
worldbase