View source for Targetname

{{LanguageBar}}

{{KV info|Targetname}}
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 [[Inputs and Outputs|I/O System]].
== Notes ==
* Entities may also be targeted by their [[classname]] (e.g. <code>prop_dynamic</code>).
* 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 <code>!</code> or <code>*</code> characters (see below).
* Targetnames also cannot contain <code>,</code> characters if you intend to use the entity as a parent, as this is used to set an [[attachment point]].
== Instances ==
* [[Instance]]s 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 <code>@</code> 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'''.
== Player Events ==
In most multiplayer games, any entity with the following targetnames will have a [[Use]] input sent to them when that event occurs.
* <code>game_playerdie</code> - Fires every time a {{ent|player}} dies. The player who died is the '''<code>!activator</code>'''.
* <code>game_playerkill</code> - Fires every time a {{ent|player}} kills another player, the killer is the '''<code>!activator</code>'''.
* <code>game_playerjoin</code> - Fires every time a {{ent|player}} joins the game, the joining player is the '''<code>!activator</code>'''. {{bug|<code>game_playerjoin</code> is not fired by [[bot]]s.}}
* <code>game_playerspawn</code> - Fires every time a {{ent|player}} spawns, with the spawning player as the '''<code>!activator</code>'''. {{bug|<code>game_playerspawn</code> does not function in {{css}}{{csgo}}{{tf2}}.}}
* <code>game_playerleave</code> - Fires every time a {{ent|player}} leaves the game. '''<code>!activator</code>''' will not work in this case, as the <code>player</code> entity no longer exists.
{{confirm|In what games do game_playerjoin and game_playerspawn actually work?}}
{{tip|In {{tf2}}{{l4d2}}, use [[Team Fortress 2/Scripting/Script Functions#Hooks|VScript event hooks]] which also offer extra information with each event (such as the attacker on death etc). Equivalent event names are <code>player_spawn</code>, <code>player_death</code> and <code>player_disconnect</code>.}}

== 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 {{ent|filter_activator_name}}/<code>[[filter_activator_class|class]]</code> or an entity's [[parent]] field. The extended features are:

*Wildcards
:Source supports <code>*</code> 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 <code>*</code>, which means more complex wildcards like '''*_door''' or '''area*_door''' will not function.
::{{note|{{Game link|Mapbase}} has support for complex wildcard matching like '''*_door''', '''area*_door''', '''ar*a*_d*r''', <code>?</code> wildcards, etc.}}
::{{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.}}

The [[Inputs and Outputs|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.

{{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.}}
== Keywords ==
The following special targetnames can be used to dynamically select an entity.

{{note|Not all entity parameters can evaluate these targetnames. For example SetParent input can evaluate <code>!activator</code> parameter but player's SetFogController input is not able to evaluate <code>!activator/!caller</code> and needs to use the desired env_fog_controller's targetname.}}

; <code>!activator</code>
: The entity that began the current I/O chain.
: &nbsp;&nbsp;If a player walks into a [[trigger multiple|trigger]] that fires a {{ent|logic_relay}}, the player is the <code>!activator</code> of the relay's output(s).
; <code>!self</code>
: The entity from which the current input originates. 
: &nbsp;&nbsp;If a player walks into a trigger that fires a logic_relay, the relay is the <code>!self</code> of its output(s).{{ExpandBox|
* If a logic_relay fires <code>ForceSpawnAtEntityOrigin !self</code> to an env_entity_maker with <code>OnTrigger</code>, the <code>!self</code> entity is the env_entity_maker itself.
|Special case:}}
; <code>!caller</code>
: The entity from which the current output originates. 
: If a player walks into a trigger that fires a logic_relay, the trigger is the <code>!caller</code> of the relay's output(s).{{ExpandBox|
* If a logic_relay fires <code>ForceSpawnAtEntityOrigin !caller</code> to an env_entity_maker with <code>OnTrigger</code>, the <code>!caller</code> entity is the relay itself.
* For entities such as <code>filter_activator_[xxxx]</code> or {{ent|logic_case}}, the <code>!caller</code> of a <code>TestActivator</code> or <code>PickRandom/PickRandomShuffle</code> is the <code>filter_activator_[xxxx]</code>/<code>logic_case</code> itself, not the entity that fired the input.
|Special case:}}
: {{note|Individual inputs can override the entity targeted by <code>!caller</code>! This is done by {{ent|point_entity_finder}}, {{ent|math_counter}}, {{ent|logic_case}}, and filter entities.}}
; <code>!player</code>
: Targets the player.
: &nbsp;&nbsp;In multiplayer games, it targets the first player that joined the server.
{{note|When testing an entity's name, this behaves as expected, matching if the entity is a player.}}
{{tip|To target all players in a server, use the <code>player</code> classname.}}
{{bug|In Portal 2, entities parented using the <code>parentname</code> parameter fail to parent on map startup.}}
:{{workaround|Use a [[logic auto]] and a <code>SetParent</code> input instead.}}
; <code>!player_blue</code>{{Portal2|only}}
: In Portal 2 Coop, this targets ATLAS (player 1).
; <code>!player_orange</code>{{Portal2|only}}
: In Portal 2 Coop, this targets P-Body (player 2).
; <code>!pvsplayer</code>
: The first player found in the entity's [[Potential Visibility Set]]. The PVS used is taken from the entity doing the searching, or the activator if no searching entity exists. If no activator exists either, the first player in the game is returned (i.e. <code>!player</code>).
; <code>!picker</code>
: The first entity under the player's crosshair; mostly only for debugging. Entities without collision can only be selected by aiming at their origin.
: &nbsp;&nbsp;In multiplayer games, it uses the first player that joined the server.

=== FindNamedEntity Keywords ===
These keywords are only available in <code>FindNamedEntity</code>, 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|{{Game link|Mapbase}} makes this available to I/O searches. Is this the case in any other branch?}}

; <code>!speechtarget</code>
: The entity at which the <code>!caller</code> is looking due to a [[Choreography creation/Creating Events/Other Events#Look at Actor|Look At Actor]] or [[Choreography creation/Creating Events/Other Events#Face Actor|Face Actor]] choreography event.
; <code>!friend</code>
: The <code>!caller</code>'s nearest friendly NPC. This returns the player on NPCs which don't descend from <code>CAI_PlayerAlly</code>.
; <code>!enemy</code>
: The current enemy of the <code>!caller</code>.

=== Keyword Notes ===
* Both <code>!activator</code> and <code>!caller</code> can be different for specific inputs, which depends on each input's implementation. In most cases this is in an undesired manner, like <code>GetValue</code> for {{ent|math_counter}}.
* When an output's "Target Entity" is empty, <code>!self</code> is ''not'' set to the <code>!caller</code> value.
* Targetnames used in an output's parameter override field are evaluated by the entity that ''receives'' the output, not the one that sends it.

== See also ==
* [[User Inputs and Outputs]]
* <code>[[GetDebugName()]]</code>, for accessing an entity's targetname in C++.

 <!-- Because hammer -->

[[Category:Source]]
[[Category:Glossary]]
[[Category:Level Design]]<!--Why?-->


{{stub}}