Difference between revisions of "Targetname"
(Spam) |
Ninjaofsauce (talk | contribs) m |
||
(57 intermediate revisions by 33 users not shown) | |||
Line 1: | Line 1: | ||
− | + | {{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. 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 <code>!</code> or <code>*</code> characters (see below). |
+ | === 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 === | ||
+ | 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 [[player]] dies. The player who died is the [[!activator]]. | ||
+ | * <code>game_playerkill</code> - Fires every time a [[player]] kills another player, the killer is the [[!activator]]. | ||
+ | * <code>game_playerjoin</code> - Fires every time a [[player]] joins the game, the joining player is the [[!activator]]. {{bug|<code>game_playerjoin</code> is not fired by [[bot]]s.}} | ||
+ | * <code>game_playerspawn</code> - Fires every time a [[player]] spawns, the spawning player is the [[!activator]]. {{bug|<code>game_playerspawn</code> does not function in {{css}}{{csgo}}{{tf2}}.}} | ||
+ | * <code>game_playerleave</code> - Fires every time a [[player]] leaves the game, [[!activator]] will not work in this case as the [[player]] [[entity]] no longer exists. | ||
+ | {{Tip| Entities and outputs which pass on [[Use]] correctly include [[trigger_brush]]:OnUse and [[func_door]]:OnLockedUse.}} | ||
+ | |||
+ | === 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|parent]] field. The extended features are: | ||
− | |||
− | |||
*Wildcards | *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. |
− | *The [[Inputs_and_Outputs|I/O System]] | + | ::{{note|{{Game link|Mapbase}} has support for complex wildcard matching like '''*_door''', '''area*_door''', '''ar*a*_d*r''', <code>?</code> wildcards, etc.}} |
− | : | + | {{warning|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.}} | ||
+ | |||
+ | ; <code>!activator</code> | ||
+ | : The entity that began the current I/O chain. If a player walks into a [[trigger_multiple|trigger]] that fires a [[logic_relay]], the player is the <code>!activator</code> of the relay's output(s). | ||
+ | ; <code>!caller</code> | ||
+ | : The previous entity in the current I/O chain. If a player walks into a trigger that that fires a logic_relay, the trigger is the <code>!caller</code> of the relay's output(s). | ||
+ | {{bug|This does not appear to work correctly in {{tf2}}, instead selecting any entity in the I/O chain.}} | ||
+ | ; <code>!self</code> | ||
+ | : The entity from which the current output originates. If a player walks into a trigger that that fires a logic_relay, the relay is the <code>!self</code> of its output(s). | ||
+ | ; <code>!player</code> | ||
+ | : The player. | ||
+ | {{note|When testing an entity's name, this behaves as expected, matching if the entity is a player.<br/> | ||
+ | When finding an entity by name, this return the player in slot 1 (if any), which is generally only useful in singleplayer.}} | ||
+ | {{tip|To target all players in a server, use the <code>player</code> classname.}} | ||
+ | ; <code>!player_blue</code>{{Portal2}} | ||
+ | : In Portal 2 Coop, this targets ATLAS (player 1). | ||
+ | ; <code>!player_orange</code>{{Portal2}} | ||
+ | : 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. Only useful in single-player, and mostly only for debugging. Entities without collision can only be selected by aiming at their origin. | ||
+ | |||
+ | ==== 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 ==== |
− | |||
− | + | * The special targetnames [[!activator]] and [[!caller]] are defined on an output-by-output basis. This depends solely on how the output is implemented in the code. Many outputs in Source are coded to fire with the activator as the entity firing the output when it is expected to use a different entity. | |
− | ! | + | * Targetnames used in an output's target field are evaluated after the point at which the sending entity has chosen the new [[activator]] and [[caller]] values to be seen by the receiving entity. This causes [[!caller]] to evaluate to the sending entity in about 90% of cases. [[!self]] uses the [[caller]] value, and in this context always has the same value as [[!caller]]. |
− | ! | + | * 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 == | == See also == | ||
* [[Client Command by Trigger proximity]], a mini-tutorial explaining the process of letting the player(s) in your game execute a Client Command by a trigger. | * [[Client Command by Trigger proximity]], a mini-tutorial explaining the process of letting the player(s) in your game execute a Client Command by a trigger. | ||
+ | * [[User_Inputs_and_Outputs| User Inputs and Outputs]] | ||
+ | * <code>[[GetDebugName()]]</code>, for accessing an entity's targetname in C++. | ||
[[Category:Level Design]] | [[Category:Level Design]] | ||
[[Category:Technical]] | [[Category:Technical]] |
Latest revision as of 08:09, 16 January 2021
Targetname is a base 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
Contents
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).
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.
Player Events
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.game_playerspawn
- Fires every time a player spawns, the spawning player is the !activator.game_playerleave
- Fires every time a player leaves the game, !activator will not work in this case as the player entity no longer exists.

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

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

!activator
- The entity that began the current I/O chain. If a player walks into a trigger that fires a logic_relay, the player is the
!activator
of the relay's output(s). !caller
- The previous entity in the current I/O chain. If a player walks into a trigger that that fires a logic_relay, the trigger is the
!caller
of the relay's output(s).
!self
- The entity from which the current output originates. If a player walks into a trigger that that fires a logic_relay, the relay is the
!self
of its output(s). !player
- The player.

When finding an entity by name, this return the player in slot 1 (if any), which is generally only useful in singleplayer.

player
classname.!player_blue
- In Portal 2 Coop, this targets ATLAS (player 1).
!player_orange
- In Portal 2 Coop, this targets P-Body (player 2).
!pvsplayer
- 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.
!player
). !picker
- The first entity under the player's crosshair. Only useful in single-player, and mostly only for debugging. Entities without collision can only be selected by aiming at their origin.
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.
- To do:
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 fromCAI_PlayerAlly
. !enemy
- The current enemy of the
!caller
.
Keyword Notes
- The special targetnames !activator and !caller are defined on an output-by-output basis. This depends solely on how the output is implemented in the code. Many outputs in Source are coded to fire with the activator as the entity firing the output when it is expected to use a different entity.
- Targetnames used in an output's target field are evaluated after the point at which the sending entity has chosen the new activator and caller values to be seen by the receiving entity. This causes !caller to evaluate to the sending entity in about 90% of cases. !self uses the caller value, and in this context always has the same value as !caller.
- 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
- Client Command by Trigger proximity, a mini-tutorial explaining the process of letting the player(s) in your game execute a Client Command by a trigger.
- User Inputs and Outputs
GetDebugName()
, for accessing an entity's targetname in C++.