Difference between revisions of "Inputs and Outputs"

From Valve Developer Community
Jump to: navigation, search
m (being solid doesn't matter)
m (Added note about data descriptions article having information on internal usage)
 
(33 intermediate revisions by 18 users not shown)
Line 1: Line 1:
[[Category:Level Design]]
+
{{otherlang2
Inputs and outputs are useful to allow entities to trigger actions by other entities.
+
|de=Inputs and Outputs:de
 +
|ru = Inputs and Outputs:ru
 +
|zh-cn=Inputs_and_Outputs:zh-cn
 +
}}
  
==Overview==
+
{{toc-right}}
  
Entities have two methods for communication: sending an <i>output</i> to another entity, or receiving an <i>input</i> from another entity. One entity may send an output when it is killed to another entity's input which causes it to change color. That same output could also be used to trigger another entity's spawning input. The outputs are matched to the inputs via a <i>connection</i>, which controls what extra data is relayed to the receiver, how much of a delay there is before the output is received, and whether the output should be allowed to be sent again later. Outputs can be linked to any input and vice versa. This allows complex and powerful interactions between entities.
+
'''Inputs''' and '''Outputs''' (collectively "I/O") are the means by which [[Entity|entities]] communicate between each other in [[:Category:Level Design|maps]]. Entities have two methods for communication: sending an "output" to another entity, or receiving an "input" from another entity. One entity may send an output when it is killed to another entity's input which causes it to change color. That same output could also be used to trigger another entity's spawning input. The outputs are matched to the inputs via a "connection", which controls what extra data is relayed to the receiver, how much of a delay there is before the output is received, and whether the output should be allowed to be sent again later. Outputs can be linked to any input and vice versa. This allows complex and powerful interactions between entities.
  
As an example, a <code>[[logic_timer]]</code> entity may send an <code>OnTimer</code> output, which triggers when the time condition is met for the entity. That output might be hooked to the <code>Show</code> input on an <code>[[env_sprite]]</code>, causing it to become visible when the timer has reached its desired time. You could also hook the <code>OnTimer</code> output for the <code>[[logic_timer]]</code> to a <code>SparkOnce</code> input on an <code>[[env_spark]]</code> to cause it to emit sparks. By using the connection properties, you could also cause the output to be triggered after a two second delay, or to trigger once but never again.
+
Consider a [[logic_timer]] entity. It might be configured to "fire" its <code>OnTimer</code> output when it hits its time limit, which "triggers" (or "calls") the <code>ShowSprite</code> input of an [[env_sprite]]. When the timer hits its limit, the sprite appears. By using the connection properties, you could also cause the output to be triggered after a two second delay, or to trigger once but never again.
  
For users more familiar with the original Half-Life method of entity communication, the <code>targetname</code> and <code>target</code> fields are now obsolete and the entity I/O system is a superset of that functionality. Instead of a <code>[[trigger_multiple]]</code> entity only firing its target entity, it may now use any number of its outputs to do the same, including: <code>OnStartTouch</code>, <code>OnEndTouch</code>, <code>OnTouch</code>, etc. These outputs may be connected to an arbitrary number of entities all at once with unique delays per output, making <i>multi-managers</i> obsolete as well. Likewise, the <code>killtarget</code> field is now replaced by connecting an output to the <code>Kill</code> input of another entity.
+
== Inputs ==
  
==Outputs==
+
'''Inputs''' are commands that cause an entity to change what it is doing. They are "triggered" (or "called") by outputs - they cannot be manipulated directly.
  
[[Image:hammer_entityio1.jpg|right]]
+
You can view a list of input events that an entity is receiving in the Inputs tab of the [[Hammer Object Properties Dialog|object properties dialog]]. Clicking the "mark" button will take you to the entity that the input is being received from.
  
Outputs are events that are fired when an entity's state changes. This could be a timer reaching its end, a button being pressed or a door coming to a close. Any number of outputs can be specified by a programmer internally in an entity to trigger on any number of criteria. Specifying outputs is done in the '''Outputs''' tab in an entity's properties. The '''Ouputs''' tab of the [[Hammer Object Properties Dialog|Object Properties]] dialog displays all the outputs that are connected from this entity to other entities.
+
== Outputs ==
  
# Name of the output to be triggered.
+
[[File:Output.png|thumb|Hammer's "Object Properties" dialog]]
# Name of the entity to receive the output (click an entity with Eye Dropper tool to paste its name here).
 
# Input on another entity that will receive the output. This is where you will choose what action on the target entity you want the output to activate.  For instance, if you want a [[npc_combine_s]] soldier to rappel, you would use the BeginRappel input.
 
# Parameter override to use if data is accepted by the target input. Often this is a number used by the input function (see Inputs section below).
 
# Amount to delay sending the output (in seconds). 1/10th of a second is expressed as "0.1" seconds.
 
# Whether to fire the output once.
 
 
===Sample outputs===
 
* '''OnTrigger''' - When this entity is triggered, it will fire this output.
 
* '''OnMapSpawn''' - When this map is loaded, this output will be fired.<br style="clear:both">
 
* '''OnNewGame''' - When a new game is created, this output will be fired.<br style="clear:both">
 
* '''OnLoadGame''' - When a saved game is loaded, this output will be fired.<br style="clear:both">
 
  
==Inputs==
+
'''Outputs''' are events that fire when an entity's state changes. For example, a [[logic_timer|timer]] will have an output for reaching its end, a [[func_button|button]] an output for being pressed, and a [[prop_door_rotating|door]] an output for coming to a close.
  
[[Image:hammer_entityio2.jpg|right]]
+
Output events are created in the Outputs tab of the [[Hammer Object Properties Dialog|object properties dialog]]. This interface provides a list of the outputs already emitting from the entity, configuration fields for the one(s) currently selected, and buttons for creating new and deleting old. Finally, the button in the bottom left labelled "mark" will take you to the target entity of the current output.
  
Inputs connect to outputs of any type. Here we see the '''Inputs''' tab on the [[Hammer Object Properties Dialog|Object Properties]] dialog. It shows all of the outputs that are connected from other entities to this entity.
+
The output configuration fields are:
  
Because any output can connect to any input, there are a multitude of combinations that can be used to make complex interaction occur. Timers can orchestrate a countdown sequence using blinking sprites, sounds and special effects all without any need for special entities. By clicking the '''Mark''' button or double-clicking on an entry in the list, the user is able to go to the entity sending the output to the input in question.
+
; Output name
 +
: What event causes the output to fire. For example, a [[trigger_multiple]] entity can fire an '''OnTrigger''' output when a player steps into it.
 +
; Target entity
 +
: The [[targetname]] or [[classname]] of the entity that will receive input. Accepts the * character as a search wildcard.
 +
:* A bold name means that the targetname points to multiple entities
 +
:* A red name means that the targetname doesn't point to anything {{bug|Valid classname and wildcard values and [[Targetname#Keywords|special targetnames]] will also appear red. Don't worry: the engine will recognise them!}}
 +
; Input name
 +
: The input on the target entity that will be triggered. This too will be context sensitive. For example, if sending an output to a Door entity, some of the available inputs will be "Close" or "Open".
 +
; Parameters
 +
: You can pass data to the target entity with parameters. A parameter might be anything: how loud to play [[ambient_generic|a sound]], the [[targetname]] of another entity, or perhaps [[color255|a color]]. It all depends on what the input accepts. If it doesn't accept anything, this field will be greyed out.
 +
: Some outputs, like [[math_counter]]'s <code>OutValue</code>, generate parameters themselves. To use a generated parameter, just leave the field reading <code><none></code>. {{note|If the output value is a [[targetname]], remember that it may not be unique!}}
 +
; Time delay
 +
: The number of seconds to wait after the output event occurs before firing.
 +
; Fire once only
 +
: The output will be deleted after it fires if this is checked.
  
If a connection is displayed in red, it is invalid. This means that either the output does not exist in the source entity, or the input is not present in the destination entity. Invalid connections are benign but should be fixed before map compilation because the [[Hammer_Check_For_Problems_Dialog|Check For Problems]] menu command will report them as an error.<br style="clear:both">
+
== Setting up a simple trigger ==
 +
This is an example of how to make a simple trigger using inputs and outputs, so a sound is played when the player enters a specific area.
  
==Outputs with values==
+
Open up a map and add an [[ambient_generic]] (in the Name field, type in "<code>ambient_1</code>"). Go into its '''Object Properties''' and choose a sound file for it to play, and on the '''Flags''' tab make it set to "'''Start Silent'''". Select the "<code>tools/toolstrigger</code>" texture and create a cube brush with this texture. Right-click on this brush and using the "[[Brush entity|Tie to Entity]]" command, make it into a [[trigger_once]] entity. Go to the '''Outputs''' tab and click the '''Add...''' button.
  
Very few outputs give off values. A case of this is [[math_counter]]'s '''OutValue''' output. These outputs are linked to inputs that take a parameter, and will fill in a value for that parameter when triggered. For example, on a [[math_counter]] there might be the following input: <code>OutValue mover SetPosition &lt;none&gt;</code> where ''mover'' is a [[func_movelinear]]. The position of ''mover'' can then be changed through the simple arithmetic operations of the [[math_counter]].
+
Set "My output named" to "<code>OnStartTouch</code>". This causes the output (and thus the trigger) to occur when the player starts touching this brush in the game.  
  
==Setting up a simple trigger==
+
Set "Targets entities named" to "<code>ambient_1</code>" using the pull-down arrow. This makes the trigger output target the <code>ambient_generic</code> you placed earlier.
This is an example of how to make a simple trigger using inputs and outputs, so a sound is played when the player enters a specific area.
 
  
Open up a map and add an '''[[ambient_generic]]''' (naming it "ambient_1"). Go into its properties and choose a sound file for it to play, and in its flags make sure it starts Off. Select the '''"toolstrigger"''' texture with the texture window and create a cube brush with this texture. Right click on this brush and using '''"Tie to Entity"''', make it a "'''trigger_once'''". Go to the outputs tab and click the '''"Add..."''' button.
+
Set "Via this input" to "<code>PlaySound</code>". This chooses the <code>PlaySound</code> action from the target <code>ambient_generic</code>'s list of actions, which of course causes its sound to start playing.
  
For "''My output named''", select ''OnStartTouch''. This causes the output (and thus the trigger) to occur when the player starts touching this brush in the game.  
+
Click the '''Apply''' button to save your changes to the trigger, and close it. Now we have the trigger set up so that as soon as the player touches it, it sends a command to the <code>ambient_generic</code> which makes it start playing its sound.
  
For "''Targets entities named''", select "'''ambient_1'''" using the pulldown arrow. This makes the trigger output target the ambient_generic you placed earlier.
+
If you open up the properties for the <code>ambient_generic</code>, you can see how the '''Output''' from the trigger has automatically been converted to an '''Input''' for the <code>ambient_generic</code>.
  
For "''Via this input''", select "''PlaySound''". This chooses the PlaySound action from the target ambient_generic's list of actions, which of course causes its sound to start playing.
+
If you want to compile and test your new trigger, make sure you have all the basics (player start, lighting, etc) and have assigned a sound effect to the <code>ambient_generic</code>.
  
Click the "''Apply''" button to save your changes to the trigger, and close it. Now we have the trigger set up so that as soon as the player touches it, it sends a command to the ambient_generic which makes it start playing its sound.
+
== Debugging ==
  
If you open up the properties for the ambient_generic, you can see how the Output from the trigger has automatically been converted to an Input for an ambient generic.
+
Source provides various debugging tools for when an I/O chain is not working as expected.
  
If you want to compile and test your new trigger, make sure you have all the basics (player start, lighting, etc) and have assigned a sound effect to the ambient_generic!
+
Foremost among them is the object properties dialog itself. Invalid inputs outputs are highlighted red in the entity's input or output list; the I/O icons at the bottom of the dialoge also change accordingly. Invalid outputs also show up in [[Hammer Check For Problems Dialog|Check For Problems]] ({{key|Alt+P}}). It's a good idea check for problems before every compile.
  
==Debugging==
+
{{bug|Valid classname and [[Targetname|wildcard values]] will be flagged as errors. Don't worry: the engine will recognise them!}}
  
Because the nature of how entities communicate has become more complex and powerful, so too has the debugging capabilities of the engine to help you track down problems. If a chain of I/O logic is not working as expected, the tools below will aid greatly in solving the error.
+
Away from Hammer, there are a number of [[Developer console|console]] commands and variables that will help you spot errors while your map is running:
  
;<code>developer 0/1/2</code>
+
; <code>developer <0-2></code>
:By setting this [[console variable]] to a value of "2", you'll receive a detailed log of how the entities are interacting via the entity I/O system. This is useful for seeing the exact chain of events taking place in complex interactions.
+
: [[Developer|Developer mode]] reports all entity I/O to the console, and unless you're playing on a [[dedicated server]] that enables [[sv_cheats|cheats]] (which is needed for all of the commands below). If you are in <code>developer 2</code>, you will also get the last eight lines of the console displayed at the top of your screen.
;<code>ent_messages_draw 0/1</code>
+
; <code>ent_messages_draw <[[bool]]></code>
:Setting this [[console variable]] to a value of "1" will display visual information about how entities are communicating with one another. This is very similar to using the developer [[console variable]], but can sometimes be more immediately intuitive to the viewer.
+
: This displays the same information as developer mode, except that instead of appearing in the console it's drawn in the 3D world at the location of the entities in question.
;<code>ent_fire <entity name> <input name> <input value></code>
+
; <code>ent_fire <[[targetname]] or [[classname]]> <input> <parameter></code>
:This [[console command]] allows you to manually fire inputs on an entity from the console. This can be very useful for testing settings for entities in real-time. To fire the "Open" input for an entity named "testentity" with an input parameter of "3", you would type <code>ent_fire&nbsp;testentity&nbsp;open&nbsp;3</code> . You can also fire any entity that is under your crosshair using "!picker" as the entity name. More information in [[Targetname]].
+
: This ''extremely'' useful command allows you to manually fire inputs on any entity at any time. If you want to unlock a door ahead of time, you would type <code>ent_fire my_door unlock</code>, followed if you're feeling lazy by <code>ent_fire my_door open</code>.
;<code>ent_pause</code>
+
: Like the "output target" field in Hammer, <code>ent_fire</code> supports classnames and wildcards. If you want to <code>ent_fire npc_* ignite</code>, you can! {{tip|<code>ent_fire</code> is where the special <code>[[!picker]]</code> targetname comes in. Use it to target whatever is under your crosshair.}}
:This [[command]] pauses entities in the map. If entered again, the entities will resume their normal behavior. This is most useful when use with the <code>ent_step</code> [[command]], described below.
+
; <code>ent_pause</code>
;<code>ent_step <number of steps></code>
+
: This command pauses all entities in the map except the player; submit it again to unpause. It is designed for use with <code>ent_step</code>.
:When used with the <code>ent_pause</code> [[console command]], this [[command]] allows the user to slowly step through an entity's chain of execution for input and output. Any number of steps can be iterated through at one time, as specified by a value entered after the [[command]] (i.e. <code>ent_step 3</code> would execute three steps at once).
+
; <code>ent_step <number of steps></code>
 +
: When used with <code>ent_pause</code>, this command makes entities perform a specified number of I/O steps before pausing again (default is 1).
  
==See Also==
+
== See also ==
  
[[Entity Creation]]
+
* [[Data Descriptions]] - Some information on how inputs and outputs function internally can be found here.
 +
* [[Entity Creation]]
 +
* [[List of entities]]
 +
* [[Targetname]]
 +
* [[User Inputs and Outputs]]
 +
* [[AddOutput]]
  
[[List of entities|List of Entities]]
+
[[Category:IO System]]
 
+
[[Category:Level Design]]
[[Targetname]]
 

Latest revision as of 20:58, 20 November 2018

Deutsch Русский 简体中文

Inputs and Outputs (collectively "I/O") are the means by which entities communicate between each other in maps. Entities have two methods for communication: sending an "output" to another entity, or receiving an "input" from another entity. One entity may send an output when it is killed to another entity's input which causes it to change color. That same output could also be used to trigger another entity's spawning input. The outputs are matched to the inputs via a "connection", which controls what extra data is relayed to the receiver, how much of a delay there is before the output is received, and whether the output should be allowed to be sent again later. Outputs can be linked to any input and vice versa. This allows complex and powerful interactions between entities.

Consider a logic_timer entity. It might be configured to "fire" its OnTimer output when it hits its time limit, which "triggers" (or "calls") the ShowSprite input of an env_sprite. When the timer hits its limit, the sprite appears. By using the connection properties, you could also cause the output to be triggered after a two second delay, or to trigger once but never again.

Inputs

Inputs are commands that cause an entity to change what it is doing. They are "triggered" (or "called") by outputs - they cannot be manipulated directly.

You can view a list of input events that an entity is receiving in the Inputs tab of the object properties dialog. Clicking the "mark" button will take you to the entity that the input is being received from.

Outputs

Hammer's "Object Properties" dialog

Outputs are events that fire when an entity's state changes. For example, a timer will have an output for reaching its end, a button an output for being pressed, and a door an output for coming to a close.

Output events are created in the Outputs tab of the object properties dialog. This interface provides a list of the outputs already emitting from the entity, configuration fields for the one(s) currently selected, and buttons for creating new and deleting old. Finally, the button in the bottom left labelled "mark" will take you to the target entity of the current output.

The output configuration fields are:

Output name
What event causes the output to fire. For example, a trigger_multiple entity can fire an OnTrigger output when a player steps into it.
Target entity
The targetname or classname of the entity that will receive input. Accepts the * character as a search wildcard.
  • A bold name means that the targetname points to multiple entities
  • A red name means that the targetname doesn't point to anything
    Bug: Valid classname and wildcard values and special targetnames will also appear red. Don't worry: the engine will recognise them!
Input name
The input on the target entity that will be triggered. This too will be context sensitive. For example, if sending an output to a Door entity, some of the available inputs will be "Close" or "Open".
Parameters
You can pass data to the target entity with parameters. A parameter might be anything: how loud to play a sound, the targetname of another entity, or perhaps a color. It all depends on what the input accepts. If it doesn't accept anything, this field will be greyed out.
Some outputs, like math_counter's OutValue, generate parameters themselves. To use a generated parameter, just leave the field reading <none>.
Note:If the output value is a targetname, remember that it may not be unique!
Time delay
The number of seconds to wait after the output event occurs before firing.
Fire once only
The output will be deleted after it fires if this is checked.

Setting up a simple trigger

This is an example of how to make a simple trigger using inputs and outputs, so a sound is played when the player enters a specific area.

Open up a map and add an ambient_generic (in the Name field, type in "ambient_1"). Go into its Object Properties and choose a sound file for it to play, and on the Flags tab make it set to "Start Silent". Select the "tools/toolstrigger" texture and create a cube brush with this texture. Right-click on this brush and using the "Tie to Entity" command, make it into a trigger_once entity. Go to the Outputs tab and click the Add... button.

Set "My output named" to "OnStartTouch". This causes the output (and thus the trigger) to occur when the player starts touching this brush in the game.

Set "Targets entities named" to "ambient_1" using the pull-down arrow. This makes the trigger output target the ambient_generic you placed earlier.

Set "Via this input" to "PlaySound". This chooses the PlaySound action from the target ambient_generic's list of actions, which of course causes its sound to start playing.

Click the Apply button to save your changes to the trigger, and close it. Now we have the trigger set up so that as soon as the player touches it, it sends a command to the ambient_generic which makes it start playing its sound.

If you open up the properties for the ambient_generic, you can see how the Output from the trigger has automatically been converted to an Input for the ambient_generic.

If you want to compile and test your new trigger, make sure you have all the basics (player start, lighting, etc) and have assigned a sound effect to the ambient_generic.

Debugging

Source provides various debugging tools for when an I/O chain is not working as expected.

Foremost among them is the object properties dialog itself. Invalid inputs outputs are highlighted red in the entity's input or output list; the I/O icons at the bottom of the dialoge also change accordingly. Invalid outputs also show up in Check For Problems (Alt+P). It's a good idea check for problems before every compile.

Bug: Valid classname and wildcard values will be flagged as errors. Don't worry: the engine will recognise them!

Away from Hammer, there are a number of console commands and variables that will help you spot errors while your map is running:

developer <0-2>
Developer mode reports all entity I/O to the console, and unless you're playing on a dedicated server that enables cheats (which is needed for all of the commands below). If you are in developer 2, you will also get the last eight lines of the console displayed at the top of your screen.
ent_messages_draw <bool>
This displays the same information as developer mode, except that instead of appearing in the console it's drawn in the 3D world at the location of the entities in question.
ent_fire <targetname or classname> <input> <parameter>
This extremely useful command allows you to manually fire inputs on any entity at any time. If you want to unlock a door ahead of time, you would type ent_fire my_door unlock, followed if you're feeling lazy by ent_fire my_door open.
Like the "output target" field in Hammer, ent_fire supports classnames and wildcards. If you want to ent_fire npc_* ignite, you can!
Tip:ent_fire is where the special !picker targetname comes in. Use it to target whatever is under your crosshair.
ent_pause
This command pauses all entities in the map except the player; submit it again to unpause. It is designed for use with ent_step.
ent_step <number of steps>
When used with ent_pause, this command makes entities perform a specified number of I/O steps before pausing again (default is 1).

See also