Half-Life: Alyx Workshop Tools/Lua Scripting/Hello Gordon

Hello Gordon: an introduction to integrating scripts with Hammer for HL: Alyx

If you have any programming experience, you know what is coming. The objective of this example is simply to show how you can get a script running on top of the source engine.

Before Getting Started

• First make sure you have the Half-Life: Alyx Workshop Tools installed!
• Then make sure you have your scripting folders set up!

Create a new script

In order to execute code in game, we need the code in the right place for the Source Engine to find

Where to put the new script

The Source engine by default looks in scripts/vscripts and any folders inside for any scripts

• Go to your scripts/vscripts folder and make a new folder for your scripts, in this example the folder will be called HelloGordon
• inside the folder create a new file called HelloGordon.lua (You can create a text file and change the end to .lua)

• 

  Use folders to keep scripts organized.

Write Code

• Open your script in your favorite editor (sublime text/ notepad/ vs code) and input the following:

-- this code will simply print to the command line (that's how we know it is working)
print("Hello Gordon")

• save the file.

Connect The Code in Hammer

To get the code that we wrote working with source, we need to connect it to entities in the engine that will trigger the execution.

Open a new (or existing) project

• launch a new/existing addon
• open from template or use an existing map

• 

  Launch your addon.

• 

  Open template/launch existing.

Create a logic_script entity

The logic_script entity will hold a reference to your script so that we can call it later

• Using the entity tool (Shift + E) create an entity of any type somewhere on your map, double click it to open the settings
• Change the entity to a logic script by typing logic_script in the class field

• 

  Change the entity to logic_script.

• 

  The entity model should change and the properties should look different

• Give the script a name in the name field (i.e. MainLogic). This will be used to target this entity when we want to call the script.
• Put the path to your script in the misc-> Entity Scripts field (i.e HelloGordon/HelloGordon.lua)
• There is no need to include scripts/vscripts in the path since that is already the base path of where source searches for the scripts.

• 

  Add a name and Entity Script path

Create a logic_auto entity and run the script

In order to run a script, there must be some entity that can call it. In this case a logic_auto will do.

• create a logic_auto entity the same way you created a logic_script (by renaming a new entity's class) and give it a name.

• 

  Create a logic_auto entity.

• in order to run the script attached to the logic_script we need to make an output from this logic_auto and program it to call the code when the level loads.
• click the outputs tab in the properties view on the logic auto and click add to add a new output.
• Set the output name as: OnMapSpawn, this will make it so that this output runs as soon as the map loads.
• Set the target as the NAME of the logic_script that you made. It must be exactly the same name.
• "via this input" determines what will happen when this output is triggered. In our case, we want the logic_script to run the code attached to it. (RunScriptCode)
• If done correctly when you check the input of your logic_script, you should see that your logic_auto is set as an input.

• 

  Create an output that will trigger when the map loads.

• 

  logic_script input if done correctly

Build and Run

At this point you are finally ready to see the code in action!

• press F9 to open your build menu. Choose fast compile and then run the Build
• Changes made to code are reloaded every time you reload your map (Run (Skip Build)) which allows you to quickly debug your code.
• When the build is complete open your half life alyx window and press the tilde key (~) to see the console. If all went well you should see the message in your console!

• 

  The message showing in the console!

Why This Is Important

This example really is just the first step in making more complex scripts.

• The first step in being able to write complex scripts is knowing how to connect your scripts to the game engine.
• Part of figuring out if your code works or not is by printing to the console or to the screen
• Once you have scripts running you will able to create content that is difficult to make with hammer alone

Up Next

• coming soon

More Examples

Lua Scripting