point_script_use_target

From Valve Developer Community
Jump to: navigation, search

<Left 4 Dead 2> 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.
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 <targetname>
The name of the entity the player will be using.

Targetname:

Name <string>
The targetname that other entities refer to this entity by.
Entity Scripts <scriptlist> (New with Left 4 Dead 2)
Space delimited list of VScript files (without file extension) that are executed after all entities have spawned. The scripts are all executed in the same script scope, later ones overwriting any identical variables and functions.
Script think function <string> (New with Left 4 Dead 2)
Name of a function in this entity's script which will be called automatically every 100 milliseconds (ten times a second) for the duration of the script. It can be used to create timers or to simulate autonomous behavior. The return value (if present) will set the time until the next call.
Note:Try to avoid expensive operations in this function, as it may cause performance problems.

Origin:

Origin (X Y Z) <origin>
The position of this entity's center in the world. Rotating entities typically rotate around their origin.

Inputs

Targetname:

Kill
Removes this entity and any entities parented to it from the world.
KillHierarchy
Functions the same as Kill, although this entity and any entities parented to it are killed on the same frame, being marginally faster than Kill.
AddOutput  <string>
Evaluates a keyvalue/output on this entity. It can be potentially very dangerous, use with care.
Format: <key> <value>
Format: <output name> <targetname>:<inputname>:<parameter>:<delay>:<max times to fire, -1 means infinite>
FireUser1 to FireUser4
Fire the OnUser outputs; see User Inputs and Outputs.
Use  !FGD
Same as a player invoking +use; may not do anything. Can also be invoked by creating an output that does not specify an input.
This input is not included in Valve's FGDs.
RunScriptFile  <script> (New with Left 4 Dead 2)
Execute a VScript file from disk, without file extension. The script contents are merged with the script scope of the receiving entity.
RunScriptCode  <string> (New with Left 4 Dead 2)
Execute a string of VScript source code in the scope of the entity receiving the input. String quotation may be needed when fired via console.
Bug: In <Left 4 Dead 2>, the code is executed in the script scope of the entity that fires the output, not the one receiving the input.
Warning: Never try to pass string parameters to a script function with this input. It will corrupt the VMF structure because of the nested quotation marks, which then must be removed manually with a text editor.
CallScriptFunction  <string> (New with Left 4 Dead 2) !FGD
Execute a VScript function in the scope of the receiving entity.
SetLocalOrigin  <coordinates> (New with Alien Swarm) !FGD
Send this entity to a spot in the map. If the entity is parented to something, it will be offset from the parent by this amount.
SetLocalAngles  <angles> (New with Alien Swarm) !FGD
Set this entity's angles.


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.

Targetname:

OnUser1 to OnUser4
These Outputs each fire in response to the firing of the like-numbered FireUser1 to FireUser4 Input; see User Inputs and Outputs.
OnKilled  (Only in the Left 4 Dead series)
This Output fires when the entity is killed and removed from the game.

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