View source for Targetname

{{LanguageBar}}
{{TabsBar}}
{{This is a|keyvalue|name=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]].
* Naming certain entities, such as [[light]]s and [[env_sprite|sprites]], can alter their behavior.

== 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'''.

== 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|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|{{Game link|Mapbase}} has support for complex wildcard matching like '''*_door''', '''area*_door''', '''ar*a*_d*r''', <code>?</code> wildcards, etc.}}

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.
{{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 <code>ent_fire prop_* kill</code> 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 <code>player</code> 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 <span id="Keywords" \> ==
The following special targetnames can be used to dynamically select an entity. 

=== Those evaluated based on activator/caller <span id="Concept of activator / caller" \> ===
Every output when fired creates an IO event added to the event queue (printable by {{cmd|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 {{ent|func_button}} when fired will set the player that pressed it as the '''activator''' 
* OnStartTouch output of {{ent|trigger_multiple}} when fired will set the entity that touched it as the '''activator''' 
* {{ent|logic_relay}} 
** OnSpawn will make the '''activator''' the <kbd>logic_relay</kbd> itself
** OnTrigger will use the <kbd>Trigger</kbd> input's '''activator'''. (for example if <kbd>Trigger</kbd> input came from OnPressed output mentioned above then that '''activator''' is passed)
* {{ent|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 {{ent|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 {{ent|info_elevator_floor}} sets '''caller''' ('''activator''' too) as the func_elevator entity that reached the given floor
* OnFoundEntity output of {{ent|point_entity_finder}} sets '''caller''' as the found entity
* OnEventFired output of {{ent|logic_eventlistener}} sets '''caller''' ('''activator''' too) to NULL.
{{seealso|[[Special:WhatLinksHere/Template:O/CallerUseCheck|Entity pages that have an output with special caller]]}}
{{wikinote|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' ====
; <code>!self</code>
: In this context <code>!self</code> will use the '''caller''' making it equivalent to <code>!caller</code> which can lead to confusion in outputs mentioned as special cases (i.e OnGetValue, OnFoundEntity, OnReachedFloor ...)

; <code>!pvsplayer</code>
: 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 <code>!player</code>

==== 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:
* <kbd>SetParent</kbd> input considers only the '''activator''' in its entity searches which means <code>!activator</code> will work and <code>!pvsplayer</code> will consider the '''activator''' for its PVS check
* <kbd>SetFogController</kbd> input of {{ent|player}} can only use the targetname of the deisred env_fog_controller.}}

; <code>!self</code>
: The entity that is accepting the input.
: {{example|If a logic_relay fires <code>ForceSpawnAtEntityOrigin !self</code> to an {{ent|env_entity_maker}} with <code>OnTrigger</code>, the <code>!self</code> entity is the env_entity_maker itself.}}

; <code>!pvsplayer</code>
: The first player found in an entity's [[PVS]]. The PVS used is taken from the entity accepting the input. <!-- there should be no way this is null in this case right? -->

==== Behaves the same as both ====
; <code>!activator</code>
: Will use the '''activator''' of the output ({{↑|Those evaluated based on activator/caller|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 {{ent|trigger_multiple}} it's the entity that touched the trigger whether used as 'Target entity' or an input's parameter}}

; <code>!caller</code>
: Will use the '''caller''' of the output ({{↑|Those evaluated based on activator/caller|See explanation of '''caller''' above}}).
<dd>{{Example|If a {{ent|logic_relay}} fires the following from <code>OnTrigger</code> output:
* <code>env_entity_maker ForceSpawnAtEntityOrigin !caller</code>
* or <code>!caller Kill</code>
then the <code>!caller</code> entity is the relay itself in both cases}}</dd>


{{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 <kbd>!activator/!caller/!self</kbd> as 'Target entity' is safe and is logically equivalent to using a <kbd>targetname</kbd> that no entity has.}}

=== Those evaluated by other means ===
; <code>!player</code>
: 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 <code>player</code> classname.}}

; <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.
: In multiplayer games, it uses the first player that joined the server.

; <code>!bill</code> / <code>!zoey</code> / <code>!louis</code> / <code>!francis</code> / <code>!nick</code> / <code>!rochelle</code> / <code>!coach</code> / <code>!ellis</code> {{l4d2|only}}
: Targets the respective survivor.

; <code>!player_blue</code> / <code>!player_orange</code> {{Portal2|only}}
: In coop mode, this targets ATLAS (player 1/blue) or P-Body (player 2/orange).

=== 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>.

== 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|hidetested=1|<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>.}}
Or logic_playerproxy for player death.
* VMF Example: http://gtamike.tsgk.com/gtamike_TSGK/logic_playerproxy.rar

== 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?-->
[[Category:IO System]]

{{stub}}