View source for Use

{{LanguageBar}}
{{TabsBar|main=gs|base=Use}}
{{toc-right}}
All entities have a <code>Use</code> [[input]], though many do nothing in response to it. Any entity can have a custom use functionality set up (see {{↓|Programming}}) and if it doesn't have one the default behavior is forwarding the use to the entity's [[parent]]. Typically, use performs the action players most expect when interacting with the entity (e.g., opening/closing a door, picking up a physics object). There are several methods to invoke it:

# A player looking at the entity and using the <code>+use</code> console command (commonly bound to the {{key|E}} key).
# An entity [[output]] that specifies the <code>Use</code> input, or doesn't specifying any input.
# The {{cmd|firetarget}} [[cheat]] command. (directly calls ''Use method'' with type USE_TOGGLE)
# In code directly calling the C++ function.

== ConVars ==
{{varcom|start}}
{{varcom|sv_debug_player_use|0|bool|4=Visualizes +use logic. Green cross=trace success, Red cross=trace too far, Green box=radius success}}
{{varcom|end}}

== Player use logic ==
({{todo}} general description)
Defined by PlayerUse method of player entity. https://github.com/ValveSoftware/source-sdk-2013/blob/39f6dde8fbc238727c020d13b05ecadd31bda4c0/src/game/shared/baseplayer_shared.cpp#L1274-L1398
May be overriden:
* {{hl2}} - https://github.com/ValveSoftware/source-sdk-2013/blob/39f6dde8fbc238727c020d13b05ecadd31bda4c0/src/game/server/hl2/hl2_player.cpp#L2824-L2950
* {{tf2}} - https://github.com/ValveSoftware/source-sdk-2013/blob/39f6dde8fbc238727c020d13b05ecadd31bda4c0/src/game/server/tf/tf_player.cpp#L20581-L20592
* {{asrd}} - https://github.com/ReactiveDrop/reactivedrop_public_src/blob/3f55ae9c37064d7d1013feb63c81e64656e24a33/src/game/shared/swarm/asw_player_shared.cpp#L1169-L1341

== Programming ==
Although there is always a [https://github.com/ValveSoftware/source-sdk-2013/blob/39f6dde8fbc238727c020d13b05ecadd31bda4c0/src/game/server/baseentity.cpp#L4512-L4515 <code>Use</code> input] and a [https://github.com/ValveSoftware/source-sdk-2013/blob/39f6dde8fbc238727c020d13b05ecadd31bda4c0/src/game/server/baseentity.cpp#L2640-L2656 ''Use method''] available as those are parts of CBaseEntity, the actual '''Use function''' of an entity starts as null. The '''Use function''' in this context refers to the function that <code>m_pfnUse</code> field was set as which can be assigned at any time with <code>SetUse( void *SomeFunc([[CBaseEntity]] *pActivator, CBaseEntity *pCaller, USE_TYPE useType, [[float]] value) )</code>. The '''Use function''' also must be defined in the given entity's [[Data Descriptions]] using <code>[[Data_Descriptions#DEFINE_USEFUNC|DEFINE_USEFUNC]]( our_func )</code> . 

{{Note|[https://github.com/ValveSoftware/source-sdk-2013/blob/39f6dde8fbc238727c020d13b05ecadd31bda4c0/src/game/server/buttons.cpp#L60C2-L60C31 func_button] and several other entities use DEFINE_FUNCTION to put their '''Use function''' pointer into data desc. There doesn't seem to be any effective difference but it's more proper to use DEFINE_USEFUNC.}}

The <code>CBaseEntity::Use</code> method simply checks if a '''Use function''' was set (i.e. <code>m_pfnUse</code> is not null) and if it was set then it's called; otherwise if we have a parent then the ''Use method'' of the parent is called. Many entities usually override the ''Use method'' instead of setting a '''Use function'''. Benefit of setting a '''Use function''' instead of overriding the ''Use method'' is the ability to dynamically change it to a different one, for example as response to inputs.

=== Use types ===
Defined in [https://github.com/ValveSoftware/source-sdk-2013/blob/39f6dde8fbc238727c020d13b05ecadd31bda4c0/src/game/shared/shareddefs.h#L556-L562 shareddefs.h]
<syntaxhighlight lang=cpp>
typedef enum
{
	USE_OFF = 0, 
	USE_ON = 1, 
	USE_SET = 2, //signifies we are passing a value
	USE_TOGGLE = 3
} USE_TYPE;
</syntaxhighlight>

=== Use type in I/O ===
It is not possible to specify <code>USE_TYPE</code> or <code>value</code> through the I/O system when mapping.
Use input uses outputID property to specify USE_TYPE. Which means specifying Use input's USE_TYPE via I/O system can be done only in code by specifying the outputID parameter of AcceptInput or AddEvent functions as the desired USE_TYPE. It is set that way for [https://github.com/ValveSoftware/source-sdk-2013/blob/39f6dde8fbc238727c020d13b05ecadd31bda4c0/src/game/shared/baseplayer_shared.cpp#L1378-L1390 players performing use action] and the USE_TYPE is set based on the entity's [[ObjectCaps]]. 

OutputID parameter being used as USE_TYPE also results in following behavior:
* {{cmd|ent_fire}} sets outputID to 0 which means use fired through it is always of type USE_OFF
* use input fired from the first loaded output in the given game (which has outputID 1) session will USE_ON, from the 2nd USE_SET, 3rd USE_TOGGLE and the rest bogus valus that are usually interpreted as USE_TOGGLE
* {{cmd|firetarget}} calls Use function directly with use type USE_TOGGLE
{{example|
{{expand|title=Example where to observe this behavior|
Create a map with only {{ent|npc_grenade_frag}} which has 4 outputs <code>OnUser1-4 !self,Use</code>. Assuming those are the only outputs in the given map and it's the very first loaded map in the given game session then when using FireUser1-4 one of them will be able to pick the grenade up while the rest won't be. (Most likely FireUser3 will be the one that can pick it up, activator must be the player for picking up the grenade) 
That's because one of those outputs ids will be 3 which in terms of USE_TYPE is USE_TOGGLE and that's what [https://github.com/ValveSoftware/source-sdk-2013/blob/39f6dde8fbc238727c020d13b05ecadd31bda4c0/src/game/shared/basegrenade_shared.cpp#L243-L258 CBaseGrenade::Use] method is checking for to pick the grenade up. Ent_fire will '''not''' be able to pick the grenade up while firetarget will be able to.
}}}}

[[Category:Level Design]]
[[Category:Programming]]