point_script_use_target

Class hierarchy
CPointScriptUseTarget ↳CBaseEntity

point_script_use_target is a point entity available in 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 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 entity groups together with a use target script based on usetargets\base_buildable_target.nut.

See the scripts in left 4 dead 2\sdk_content\scripting\scripts\vscripts\ 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 CBaseEntity.

Function	Signature	Description
OnUseFinished	void OnUseFinished()	Called when the player has used this button for at least 'FinishTime' seconds.
OnUseStart	bool OnUseStart()	Called when the player begins to use this button. Return false to disable the third-person use animation. Bug:When declared, point_script_use_target cannot be interacted with, although OnUseStart() will still be ran. Use self.ConnectOutput() and hook a function to the OnUseStarted output instead.  [todo tested in?]
OnUseStop	void OnUseStop(float timeUsed)	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 self handle. The methods for CBaseEntity are also available.

Function	Signature	Description
CanShowBuildPanel	void self.CanShowBuildPanel(bool showPanel)	Sets if the UI panel for the button is shown.
GetUseModelName	string self.GetUseModelName()	Get the entity name of the prop bound to this button.
SetProgressBarText	void self.SetProgressBarText(string text)	Sets the use text for the button UI.
SetProgressBarSubText	void self.SetProgressBarSubText(string text)	Sets the subtext below the progress bar for the button UI.
SetProgressBarFinishTime	void self.SetProgressBarFinishTime(float time)	Sets the total time the button takes to use. If '0', the progress bar will always be empty.
SetProgressBarCurrentProgress	void self.SetProgressBarCurrentProgress(float time)	Sets the current use progress. It can be used to save the use progress when the user releases the use key.
StopUse	void self.StopUse()	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 CBaseEntity::GetEntityHandle() method.

Instance	Type	Description
UseModelEntity	entity handle	The Use Model prop associated with this entity.
PlayerUsingMe	entity handle	The current using player. Set to 0 if not being used.

Keyvalues

Use Model (model) <targetname>

The name of the entity the player will be using.

Name (targetname) <string>

The name that other entities refer to this entity by, via Inputs/Outputs or other keyvalues (e.g. parentname or target).
Also displayed in Hammer's 2D views and Entity Report.

See also:  Generic Keyvalues, Inputs and Outputs available to all entities

Outputs

OnUseStarted

Fired when a player starts using this target.

OnUseCanceled

Fired when a player use is canceled.

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.

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;
}