View source for Point script use target

{{CD|CPointScriptUseTarget}}
{{this is a|point entity|name=point_script_use_target|game=Left 4 Dead 2}} It makes an other entity behave like a button similar to [[func_button_timed]]. The entity is intended to be programmed from an attached [[L4D2_Vscripts|VScript]] instead of using Hammer, and calls hook functions in its own scripting scope as well as normal entity outputs. It is mainly used for run-time created [[L4D2_EMS/Appendix:_Spawning|entity groups]] together with a use target script based on <code>usetargets\base_buildable_target.nut</code>. 

See the scripts in <code>left 4 dead 2\sdk_content\scripting\scripts\vscripts\</code> for more examples of use.

== Game engine hooks ==
These VScript methods are called by the entity on the script set in the '''Entity Scripts''' keyvalue, in addition to the ones for [[Left 4 Dead 2/Script Functions#CBaseEntity|CBaseEntity]].
{| class=standard-table
! Function 
! Signature
! Description
|-
|<code>OnUseFinished</code>
|<code>void OnUseFinished()</code>
|Called when the player has used this button for at least 'FinishTime' seconds.
|-
|<code>OnUseStart</code>
|<code>bool OnUseStart()</code>
|Called when the player begins to use this button. Return false to disable the third-person use animation.<br> {{bug|When declared, <code>point_script_use_target</code> cannot be interacted with, although <code>OnUseStart()</code> will still be ran. Use <code>self.ConnectOutput()</code> and hook a function to the <code>OnUseStarted</code> output instead.}}
|-
|<code>OnUseStop</code>
|<code>void OnUseStop(float ''timeUsed'')</code>
|Called when the player stops using this button. Passes the time this button has been used (time between StartUse and now).
|-
|}

== Script methods ==
These VScript methods can be called from the script, using the <code>self</code> handle. The methods for [[Left 4 Dead 2/Script Functions#CBaseEntity|CBaseEntity]] are also available.
{| class=standard-table
! Function 
! Signature
! Description
|-
|<code>CanShowBuildPanel</code>
|<code>void self.CanShowBuildPanel(bool ''showPanel'')</code>
|Sets if the UI panel for the button is shown.
|-
|<code>GetUseModelName</code>
|<code>string self.GetUseModelName()</code>
|Get the entity name of the prop bound to this button.
|-
|<code>SetProgressBarText</code>
|<code>void self.SetProgressBarText(string ''text'')</code>
|Sets the use text for the button UI.
|-
|<code>SetProgressBarSubText</code>
|<code>void self.SetProgressBarSubText(string ''text'')</code>
|Sets the subtext below the progress bar for the button UI.
|-
|<code>SetProgressBarFinishTime</code>
|<code>void self.SetProgressBarFinishTime(float ''time'')</code>
|Sets the total time the button takes to use. If '0', the progress bar will always be empty. 
|-
|<code>SetProgressBarCurrentProgress</code>
|<code>void self.SetProgressBarCurrentProgress(float ''time'')</code>
|Sets the current use progress. It can be used to save the use progress when the user releases the use key.
|-
|<code>StopUse</code>
|<code>void self.StopUse()</code>
|Stops the current use action.
|-
|}

==== Script Members ====
These variables are only available in the Entity Script after the entity has spawned. They contain entity handles, which differ from normal script handles, and can be compared with the output of the <code>[[#CBaseEntity|CBaseEntity]]::GetEntityHandle()</code> method.

{| class="standard-table" style="width: 100%;"
! Instance
! Type
! Description
|-
| <code>UseModelEntity</code>
| <code>entity handle</code>
| The Use Model prop associated with this entity.
|-
| <code>PlayerUsingMe</code>
| <code>entity handle</code>
| The current using player. Set to 0 if not being used. 
|}

== Keyvalues ==
{{KV|Use Model|intn=model|target_destination|The name of the entity the player will be using.}}
{{KV Targetname}}

== Outputs ==
{{IO|OnUseStarted|Fired when a player starts using this target.}}
{{IO|OnUseCanceled|Fired when a player use is canceled.}}
{{IO|OnUseFinished|Fired when a player use is complete.}}

== Example script ==
This is a script that demonstrates the functions. It sets the use time to 5 seconds, prints the players name to the UI panel when used, and disables the button being successfully used.

The script also shows a way to find which player is using the button.


<source lang="cpp">
Enabled <- false; // Variable to keep track of if the button is usable.
 
// Called when the entity spawns.
function OnPostSpawn()
{
	self.SetProgressBarText( "Press me for 5 seconds" );
	self.SetProgressBarSubText( "I get disabled afterwards" );
	self.SetProgressBarFinishTime( 5 );
	self.SetProgressBarCurrentProgress( 0.0 );
	self.CanShowBuildPanel( true );
	EntFire( self.GetUseModelName(), "startglowing" );
	Enabled = true;
}
 
// Called when a player tries to use the button.
// Return false to disable the third-person use animation.
function OnUseStart()
{
	self.SetProgressBarText( GetUsingPlayer().GetPlayerName() +
		" is pressing me" );
	self.SetProgressBarSubText( "" );

	return Enabled;
}

// Called when a player stops using the button.
function OnUseStop( timeUsed )
{
	self.SetProgressBarText( GetUsingPlayer().GetPlayerName() +
		" stopped pressing me" );
	self.SetProgressBarSubText( "Time pressed: " + timeUsed );
}
 
// Called when the progress bar is full.
function OnUseFinished()
{
	Enabled = false;
	EntFire( self.GetUseModelName(), "stopglowing" );
	self.CanShowBuildPanel( false );
}

// Utility function
// Iterates through the players to find the one using the button.
function GetUsingPlayer()
{
	local player = null;
	while( player = Entities.FindByClassname( player, "player" ))
	{
		if( player.GetEntityHandle() == PlayerUsingMe )
		{
			return player;
		}
	}
	
	return null;
}
</source>