Difference between revisions of "Targetname"

From Valve Developer Community
Jump to: navigation, search
(Spam revert)
(Undeleted 'parameter override' comment I had misread. Added sad truth about !self in outputs.)
 
(55 intermediate revisions by 32 users not shown)
Line 1: Line 1:
=== Caveats ===
+
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]]
*A targetname is not required for an entity to exist, but in some cases must be present for an entity to play a part in the [[Inputs_and_Outputs|I/O System]].
+
=== Notes ===
*A targetname must be stored in the map's entity data block, so avoid naming entities that don't need a name (i.e. aren't ever referenced by another entity). The comment field in Hammer is useful for describing entities that don't need targetnames, and doesn't get saved into the <code>.bsp</code> entity data block.
+
* Entities may also be targeted by their [[classname]] (e.g. prop_dynamic).
*Targetnames do not need to be unique. As many entities as the mapper wants can share the same name, and they will all respond to the same inputs. Duplicated targetnames are displayed in bold font.
+
* 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 are also useful for categorizing entities (area1_name, area2_name, etc.).
+
* Targetnames cannot contain <code>!</code> or <code>*</code> characters (see below).
*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.}}
  
=== Notes ===
+
=== Name Searching ===
 
There are several extended features to name searches that are useful in a variety of situations. The most common use is to target an entity with an unknown name that is somehow involved in the current I/O chain. The extended features are:
 
There are several extended features to name searches that are useful in a variety of situations. The most common use is to target an entity with an unknown name that is somehow involved in the current I/O chain. The extended features are:
 +
 
*Wildcards
 
*Wildcards
 
:Name searching supports trailing * wildcards only. So searching for '''area1*''' will match any targetnames that start with '''area1''' (i.e. '''area1_portal''' and '''area1_door''', but not '''area2_door''').
 
:Name searching supports trailing * wildcards only. So searching for '''area1*''' will match any targetnames that start with '''area1''' (i.e. '''area1_portal''' and '''area1_door''', but not '''area2_door''').
 
*The [[Inputs_and_Outputs|I/O System]] is classname friendly, but Hammer isn't.  This is the case that doesn't require a targetname for the [[Inputs_and_Outputs|I/O System]].
 
*The [[Inputs_and_Outputs|I/O System]] is classname friendly, but Hammer isn't.  This is the case that doesn't require a targetname for the [[Inputs_and_Outputs|I/O System]].
 
:An example of this is use of [[ent_fire]] with a classname as opposed to a targetname.
 
:An example of this is use of [[ent_fire]] with a classname as opposed to a targetname.
 +
=== Keywords ===
 +
The following special targetnames can be used to dynamically select an entity.
 +
 +
{{note|Not all entity parameters can evaluate these targetnames.}}
  
== Keywords ==
+
; <code>!activator</code>
The following generic targetnames can be used in place of entity or class names, for situations where specifying either would be too restrictive:
+
: 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>!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>!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.
 +
:
 +
==== Keyword Notes ====
  
{| style="margin:auto; width:95%;"
+
: The special targetnames [[!activator]] and [[!caller]] are not managed by the I/O system itself, rather, each entity in the chain chooses the values to be passed on to the next. Often, this choice is stupid. About 10% of outputs pass [[self]] where they should have passed on [[activator]], and about 10% preserve [[caller]] when they should have replaced it with [[self]].
!style="width:7em;"| Keyword
+
: 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]].
! Result
+
: Targetnames used in an output's parameter override field are evaluated by the entity that ''receives'' the output, not the one that sends it.
|-
 
|!player
 
|The player. Only useful in singleplayer.  {{note|To target all players in a multiplayer game use <code>player</code>. This method can also target the player in a singleplayer game.}}
 
|-
 
|!activator
 
|The entity that started the current I/O chain. For example:
 
*If an NPC walks into an appropriately flagged [[trigger_multiple]], that NPC will be the '''!activator''' for the '''[[Trigger]]''' and '''OnStartTouch''' outputs, and any resulting I/O outputs from them.
 
*If an entity kills another, it will be the '''!activator''' for its '''OnKilledNPC''' output.
 
|-
 
|!caller
 
|The entity that triggered the current I/O command. For example:
 
*If an NPC walks into an appropriately flagged [[trigger_multiple]], the [[trigger_multiple]] will be the '''!caller''' for the '''[[Trigger]]''' and '''OnStartTouch''' outputs only.
 
|-
 
|!self
 
|The entity from which the Output originates.
 
*If a NPC kills another, it will be the '''!self''' for the '''OnKilledNPC''' output.
 
|-
 
|!pvsplayer
 
|The first player found in the entity's [[Potential Visibility Set|PVS]].
 
*The PVS used is taken from the entity doing the searching, or the activator in no searching entity exists.
 
*If no activator exists, it returns the first player in the game (equivalent to '''!player''').
 
|-
 
|!speechtarget
 
|The entity at which the caller is looking, as defined by the [[Choreography creation/Creating Events/Other Events#Look_at_Actor|Look At Actor]] and [[Choreography creation/Creating Events/Other Events#Face_Actor|Face Actor]] choreography events.
 
|-
 
|!picker
 
|The entity that the player is looking at. Only useful in single-player, and mostly only for debugging. Note that this only finds entities that are solid (i.e. can be hit by the invisible "bullet" fired to find the entity under the crosshair).
 
|}
 
  
 
== 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 18:09, 25 September 2019

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

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.
    Bug: game_playerspawn does not function in <Counter-Strike: Source><Counter-Strike: Global Offensive><Team Fortress 2>.
  • game_playerleave - 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 Searching

There are several extended features to name searches that are useful in a variety of situations. The most common use is to target an entity with an unknown name that is somehow involved in the current I/O chain. The extended features are:

  • Wildcards
Name searching supports trailing * wildcards only. So searching for area1* will match any targetnames that start with area1 (i.e. area1_portal and area1_door, but not area2_door).
  • The I/O System is classname friendly, but Hammer isn't. This is the case that doesn't require a targetname for the I/O System.
An example of this is use of ent_fire with a classname as opposed to a targetname.

Keywords

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

Note:Not all entity parameters can evaluate these targetnames.
!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).
Bug: This does not appear to work correctly in <Team Fortress 2>, instead selecting any entity in the I/O chain.
!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.
Note:When testing an entity's name, this behaves as expected, matching if the entity is a player.
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 player classname.
!player_blue[Portal 2]
In Portal 2 Coop, this targets ATLAS (player 1).
!player_orange[Portal 2]
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).
!speechtarget
The entity at which the !caller is looking due to a Look At Actor or Face Actor choreography event.
!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.

Keyword Notes

The special targetnames !activator and !caller are not managed by the I/O system itself, rather, each entity in the chain chooses the values to be passed on to the next. Often, this choice is stupid. About 10% of outputs pass self where they should have passed on activator, and about 10% preserve caller when they should have replaced it with self.
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