View source for SteamVR/Environments/Scripting/Linking Lua with Hammer

This tutorial shows how to link functions in a [[VScript]] Lua script to Hammer entity logic.


== Scripts Called by Map Entities ==

If you would like entities in your map to call script functions (such as triggers), you’ll need to create another Lua script file to your <code>scripts\vscripts</code> directory.

Launch Hammer from the SteamVR Workshop Tools and create a new map from File > New.

[[File:logic_script_entity_scripts.png|320px|thumb|right|Properties for the logic_script.]]

Create a <code>logic_script</code> with the Entity Tool (light bulb icon on the tools bar).  The location does not matter, but it will be easy to find if you place it near the world origin.  Double click on it to open its properties:

In the <code>Name</code> field, call it what you want.  This is what other entities on your scene will reference it as.  

:{{warning|Do not reference <code>addon_game_mode.lua</code> in the map entities or your script will run multiple times.  If you have map entities that call script functions, you will need to create another Lua file that is not called <code>addon_game_mode.lua</code>.  
Arcade Toss only has <code>arcade_toss.lua</code> (not an <code>addon_game_mode.lua</code>) for simplicity purposes.}}

Click on the + sign next to Misc and put the name of the Lua file you want to call (you will not need the .lua extension).

{{clr}}

Create the basic map requirements such as the floor, an [[info_player_start]], and a [[light_omni]].

Create a [[trigger_multiple]] (again, you can use the [[SteamVR/Environments/Turret_Tutorial| Turret Tutorial]] for instructions on creating mesh entities).  Open its properties by double-clicking on it or selecting it and pressing {{key|Alt}}+{{key|Enter}}.

In the Outputs tab, add an output named "OnStartTouch".  Set the <code>logic_script</code> as the target.  The input should be "CallScriptFunction" and the parameter should be the name of the function you want to be called.

::{| class=standard-table
!   || My Output || Target Entity || Target Input || Parameter || Delay || Only Once
|-
| [[File:Io11.png]] || OnStartTouch || logic_script_name || CallScriptFunction || MyFunction || 0.00 || No
|}

In your Lua file referenced by your <code>logic_script</code>, add a simple function to print a message in the console:

<source lang="lua">
function MyFunction()
	print("Trigger has been activated")
end

</source>

Compile the map and you should now be able to walk into the [[trigger_multiple]] in the game and see the message printed in the console.

=== Example 1 ===

[[File:hammer_outliner_trigger.png|320px|thumb|right|Using the outliner to find entities in Hammer.]]

There’s a [[trigger_multiple]] that detects if a player has crossed the line to throw balls into the targets.  It’s called “red_team_check”.  

You can find it in the outliner in Hammer by typing “red_team_check” in the filter field:

{{clr}}

[[File:trigger_outputs_redteamcheck.png|320px|thumb|right|The Outputs of the trigger_multiple.]]

If you double click on it and click on the Outputs tab, you can see it references the <code>logic_script</code> and uses <code>CallScriptFunction</code> with a parameter override of the name of the function you want to call in the Lua file.

{{clr}}

You will then need to create a function in the Lua script that matches the one you are calling in the Entity I/O:
<source lang="lua">
---------------------------------------------------------------------------
--Red Team
---------------------------------------------------------------------------
function RedTeamCheckStartTouch()
	--A player is over the line on the Red Team side
	red_team_counter = red_team_counter + 1
end

function RedTeamCheckEndTouch()
	red_team_counter = red_team_counter - 1
end

</source>

To create a function, you'll need to follow this same syntax with <code>function</code> MyFunction() and <code>end</code> to close it.

{{tip|Two dash marks <code>--</code> will tell Lua to ignore that line of text.  This will comment out a line.  This helps to organize your script so you can remember what each part does and will help other people see how you did it.  You can also divide your script into different sections with comments as seen above.}}

In this example, there’s an integer variable in the script called <code>red_team_counter</code> and it starts at 0.  

<source lang="lua">

-- Global Variables
local red_team_counter = 0 -- Players behind the Red Team Line
local blue_team_counter = 0 -- Players behind the Blue Team Line

</source>

When a player touches the trigger, the number increases by 1.  When a player is no longer touching the trigger, the number decreases by 1.  

The [[Dota 2 Workshop Tools/Scripting/ThinkerFunctions| think function]] shown in the [[SteamVR/Environments/Scripting/Lua Scripting Intro| Lua Scripting Intro]] checks every second if the counter is higher than 0.  If so, no points are awarded and there’s a message displayed on the board.

This chunk in the <code>Think</code> function in Arcade Toss checks if any player is over the line:

<source lang="lua">

	if red_team_counter > 0 then
    	print("Red Team is over the line!")
    	RedTeamOverTheLine()
    else
    	RedTeamBehindTheLine()
    end

</source>

These functions are called if a player is over the line or if all players are in legal positions:

<source lang="lua">

function RedTeamOverTheLine()
	bIsRedTeamBehindTheLine = false
	--Panel popup for notification
	DoEntFire( "red_team_check_panel", "AddCSSClass", "Activated", 0, self, self  )
end

function RedTeamBehindTheLine()
	bIsRedTeamBehindTheLine = true
	DoEntFire( "red_team_check_panel", "RemoveCSSClass", "Activated", 0, self, self  )
end

</source>

=== Example 2 ===

[[File:trigger_blueteam_hole1.png|320px|thumb|right|The trigger_multiple for the green hole on the Team Blue side.]]

There's a [[trigger_multiple]] in each of the target holes for the balls to make contact with to tell the script when the player has scored.

Open the trigger_multiple in the green target hole on the Team Blue side (named “blue_team_hole_1”).  Find this trigger in Hammer and double click on it or select it and press {{key|Alt}}+{{key|Enter}}.

{{clr}}

[[File:trigger_blueteam_hole1_expanded.png|320px|thumb|right|Expanding spawnflags.]]

Each of the fields that have a + mark beside it can be expanded:

{{clr}}

[[File:filter_activator_name_blueball.png|320px|thumb|right|The filter_activator_name.]]

It is set to trigger when Physics Objects touch it.  It also has a filter (filter_activator_name) that says it will only trigger when an object named “blue_ball” touches it.

This is what the filter_activator_name looks like:

{{clr}}

This tells it that it will only activate when a physics object named “blue_ball” collides with it.

[[File:trigger_outputs_blueteam_hole1.png|320px|thumb|right|The trigger_multiple's outputs.]]

The output of the [[trigger_multiple]] calls the <code>CallScriptFunction</code> in the <code>logic_script</code> file and in the parameter is the name of the function you want to call in the Lua script.

::{| class=standard-table
!   || My Output || Target Entity || Target Input || Parameter || Delay || Only Once
|-
| [[File:Io11.png]] || OnStartTouch || arcade_toss_script || CallScriptFunction || BlueHoopRow1 || 0.00 || No
|}

{{clr}}

In the Lua file, you wil need to create any function you call in the entity logic.  In this example, you’ll need to create a function called <code>BlueHoopRow1</code>.

Note: You don’t need to include the () in the Hammer I/O, just in the Lua function.

<source lang="lua">

function BlueHoopRow1(trigger)
	--Calls another function for scoring with the parameters for the team and the number of points
	UpdateScoreboard(2, 5)
	--Specifies which info_particle_system to start for the scoring effects
	local hoop = "blue_trigger_bot_particle"
	HoopEffects(hoop, 2)
end

</source>

== Spawning Entities ==

[[File:prop_physics_settings.png|320px|thumb|right|The settings icon in the prop_physics_override properties.]]

Many times you will need to spawn entities into the world.

For example, in Arcade Toss, the <code>Think</code> function checks every second to see how many red balls exist.  If there are less than 4, it will spawn more unless red balls exist in the spawner locations.

See the <code>BallReplenish</code> function in the Arcade Toss script.

To spawn an object, you will need to create a table that contains the <code>Raw Data</code> for the entity you wish to spawn.  To make this easier, you can place one of the entities you want to spawn in Hammer and then open its properties.

Click on the settings icon to view the <code>Raw Data</code>.

{{clr}}

[[File:prop_physics_rawdata.png|320px|thumb|right|Raw Data enabled.]]

This is the properties box with <code>Raw Data</code> enabled:

{{clr}}

From this, we know what to call the keys in the table:

<source lang="lua">

function RedBallLeftSpawner()
	--print("Spawning a Red Ball")
	local ballTable = 
	{
		origin = "224 128 24",
		targetname = "red_ball",
		model = "models/props_gameplay/red_ball001.vmdl"
	}
	ballTable["spawnflags#6"] = "1"
	local redBall = SpawnEntityFromTableSynchronous( "prop_physics_override", ballTable )
	redBall:Attribute_SetIntValue( "objectID", 1 )
	EmitSoundOn( "ball_spawn", redBall )
end

</source>

You don’t need to include the keys and values for the default properties.

Note: For the [[prop_physics_override]] entity used in the example above, a change in the spawnflags was required.  Because of Lua’s scripting syntax, the <code>#</code> symbol could not be read except as an insert later.  
To change a spawnflag, you will need to have a similar method with “1” being checked on and “0” being checked off.


=== Precaching Resources ===

If you spawn an entity that does not exist in your Hammer map, you will need to precache the resources.  For example, spawning the red and blue balls in Arcade Toss needed this code in the <code>arcade_toss.lua</code> file:

<source lang="lua">

function Precache( context )
	PrecacheModel( "models/props_gameplay/red_ball001.vmdl", context )
	PrecacheModel( "models/props_gameplay/blue_ball001.vmdl", context )
end

</source>

Other resources can be precached with these functions:

{| class="standard-table" style="width: 100%;"
! Function 
! Signature 
! Description 
|-
| PrecacheModel
| <code>( string modelName, context )</code>
| Manually precache a single model.
|-
| PrecacheModelFolder
| <code>( string folderName, context )</code>
| Recursively precache models within a folder.
|-
| PrecacheParticle
| <code>( string particleName, context )</code>
| Manually precache a single particle.
|-
| PrecacheParticleFolder
| <code>( string folderName, context )</code>
| Recursively precache particles within a folder
|-
| PrecacheSoundFile
| <code>( string soundFileName, context )</code>
| Manually precache a single sound file
|-
|}

[[Category:SteamVR]]
[[Category:SteamVR Home]]
[[Category:Scripting]]