targetname

GoldSrc

Source Engine

edit

targetname is a keyvalue available in all Source games. A targetname (also known simply as Name) is the name of an entity. A targetname is not required for an entity to exist, but generally must be present for an entity to play a part in the I/O System.

Notes

• Entities may also be targeted by their classname (e.g. prop_dynamic).
• Targetnames do not need to be unique, they can be shared (and inputs will be sent to each one). Duplicated targetnames are displayed in bold font.
• Targetnames cannot contain ! or * characters (see below).
• Targetnames also cannot contain , characters if you intend to use the entity as a parent, as this is used to set an attachment point.
• Naming certain entities, such as lights, can alter their behavior.

Instances

• Instances may use prefix or postfix name fixups, and will auto-generate a prefix if no parameters are specified.
• Prefixes and Postfixes are separated by a single dash e.g. hall_a3-door_02.
• Placing an @ symbol at the beginning of a targetname (e.g. @exit_door) will bypass a naming fixup for that particular entity. If @exit_door and exit_door_relay were part of an instance prefixed as Door_01, the names of the entities would be @exit_door and Door_01-exit_door_relay.

Name Matching

While searching for an entity, Source can use a few extended matching features that are useful in a variety of situations. They are used to target an entity with an unknown or partially known name, and they are most commonly used in I/O chains, but they can also be used in KeyValues which target entities, like the filter KV in filter_activator_name/class or an entity's parent field. The extended features are:

• Wildcards

Source supports * wildcards to a limited extent. This means searching for area1* will match any targetnames that start with area1, like area1_portal or area1_door, but not area2_door. These wildcards are also limited to trailing *, which means more complex wildcards like *_door or area*_door will not function.

Note:Hammer does not recognize most of these forms of matching and will see them as errors in the editor, but they will work in-game.

Note: Mapbase has support for complex wildcard matching like *_door, area*_door, ar*a*_d*r, ? wildcards, etc.

The I/O System also supports classname matching, which matches by an entity's classname rather than its targetname. This uses all of the same extended matching features listed above. Some other parts of Source support classname matching, but this usually isn't the case unless stated otherwise.

Important:It's not possible to target by targetname and classname at once. If some entity has targetname prop_window for example and we want to target all entities where classname starts with prop_ by doing ent_fire prop_* kill the prop_* will first try matching all targetnames and will only use classname if entity with no such targetname is found making classname matching unreliable. Likewise if some entity is named player and we try to target all players by using their classname player it won't work as the entity named player would be the target.

Tip:Although not feasible for some situations, most implementations of VScript support standalone entity iteration and contain string comparison tools, regex, etc., allowing for virtually any type of name matching.

Special targetnames

The following special targetnames can be used to dynamically select an entity.

Those evaluated based on activator/caller

Every output when fired creates an IO event added to the event queue (printable by dumpeventqueue), which is processed at proper time based on specified delay. IO events hold additional information about so called activator and caller which are set up by how a specific output is fired in the entity's code. Sometimes activator and caller can be set to NULL which in other words means nobody is considered activator or caller.

Activator is usually the entity that caused the output to fire. Examples:

• OnPressed output of func_button when fired will set the player that pressed it as the activator
• OnStartTouch output of trigger_multiple when fired will set the entity that touched it as the activator
• logic_relay
  • OnSpawn will make the activator the logic_relay itself
  • OnTrigger will use the Trigger input's activator. (for example if Trigger input came from OnPressed output mentioned above then that activator is passed)
• logic_auto - All its outputs set the activator to NULL.

Caller is almost always the entity where the output is defined, but there are special cases where this differs and the output sets something else as caller. Examples of such special cases:

• OnGetValue output of math_counter will set its caller as the the entity that was the caller of GetValue input which caused the output to fire
• OnReachedFloor output of info_elevator_floor sets caller (activator too) as the func_elevator entity that reached the given floor
• OnFoundEntity output of point_entity_finder sets caller as the found entity
• OnEventFired output of logic_eventlistener sets caller (activator too) to NULL.

Wiki Note:Entity pages can specify who the activator and caller is evaluated for each output. It is shown as small grey text under the name of the output. (See for example prop_physics#Outputs, math_counter#Outputs pages). Specifying activator/caller for outputs can be done using Template:O's parameters

When used as 'Target entity'

!self

In this context !self will use the caller making it equivalent to !caller which can lead to confusion in outputs mentioned as special cases (i.e OnGetValue, OnFoundEntity, OnReachedFloor ...)

!pvsplayer

The first player found in an entity's PVS. The PVS used is taken from the caller, or the activator if no caller entity exists. If no activator exists either, behaves same as !player

When used as an input parameter

Note:Because input parameters are processed in the entity accepting the input not all inputs can evaluate these targetnames. Examples:

• SetParent input considers only the activator in its entity searches which means !activator will work and !pvsplayer will consider the activator for its PVS check
• SetFogController input of player can only use the targetname of the deisred env_fog_controller.

!self

The entity that is accepting the input.

Example:If a logic_relay fires ForceSpawnAtEntityOrigin !self to an env_entity_maker with OnTrigger, the !self entity is the env_entity_maker itself.

!pvsplayer

The first player found in an entity's PVS. The PVS used is taken from the entity accepting the input.

Behaves the same as both

!activator

Will use the activator of the output (See explanation of activator above ↑). Can be also thought of as the entity that began the current I/O chain.

Example:In OnStartTouch output of trigger_multiple it's the entity that touched the trigger whether used as 'Target entity' or an input's parameter

!caller

Will use the caller of the output (See explanation of caller above ↑).

Example:If a logic_relay fires the following from OnTrigger output:

• env_entity_maker ForceSpawnAtEntityOrigin !caller
• or !caller Kill

then the !caller entity is the relay itself in both cases

Note:If activator/caller was set to NULL in an output's firing process or those entities were removed(killed) while the IO event is waiting in queue because of its delay then using !activator/!caller/!self as 'Target entity' is safe and is logically equivalent to using a targetname that no entity has.

Those evaluated by other means

!player

Targets the player.

In multiplayer games, it targets the first player that joined the server.

Tip:To target all players in a server, use the player classname.

!picker

The first entity under the player's crosshair; mostly only for debugging. Entities without collision can only be selected by aiming at their origin.

In multiplayer games, it uses the first player that joined the server.

!bill / !zoey / !louis / !francis / !nick / !rochelle / !coach / !ellis (only in )

Targets the respective survivor.

!player_blue / !player_orange (only in )

In coop mode, this targets ATLAS (player 1/blue) or P-Body (player 2/orange).

FindNamedEntity Keywords

These keywords are only available in FindNamedEntity, a method specific to NPCs which is only searched by specific systems (e.g. choreographed scenes) and not by things like the I/O System.

Todo:  Mapbase makes this available to I/O searches. Is this the case in any other branch?

!speechtarget

The entity at which the !caller is looking due to a Look At Actor or Face Actor choreography event.

!friend

The !caller's nearest friendly NPC. This returns the player on NPCs which don't descend from CAI_PlayerAlly.

!enemy

The current enemy of the !caller.

Player Events

In most multiplayer games, any entity with the following targetnames will have a Use input sent to them when that event occurs.

• game_playerdie - Fires every time a player dies. The player who died is the !activator.
• game_playerkill - Fires every time a player kills another player, the killer is the !activator.
• game_playerjoin - Fires every time a player joins the game, the joining player is the !activator.
  Bug:game_playerjoin is not fired by bots.  [todo tested in ?]
• game_playerspawn - Fires every time a player spawns, with the spawning player as the !activator.
  Bug:game_playerspawn does not function in .
• game_playerleave - Fires every time a player leaves the game. !activator will not work in this case, as the player entity no longer exists.

Confirm:In what games do game_playerjoin and game_playerspawn actually work?

Tip:In , use VScript event hooks which also offer extra information with each event (such as the attacker on death etc). Equivalent event names are player_spawn, player_death and player_disconnect.

See also

• User Inputs and Outputs
• GetDebugName(), for accessing an entity's targetname in C++.

Stub

This article or section is a stub. You can help by expanding it.