This article relates to the game "Half-Life: Alyx". Click here for more information.
This article relates to the workshop tools for "Half-Life: Alyx". Click here for more information.
This article's documentation is for Source 2. Click here for more information.

Half-Life: Alyx Workshop Tools/Lua Scripting/Getting Started

From Valve Developer Community
< Half-Life: Alyx Workshop Tools‎ | Lua Scripting
Revision as of 13:58, 25 May 2020 by Jjl77 (talk | contribs) (Added installation steps for the bootstrap vscripts and renamed some sections)
Jump to: navigation, search

What is VScript?

Scripting in Half-Life: Alyx is done using Lua, an easily embeddable scripting language developed by PUC Rio. Source 2 and some branches of Source 1 implement an abstraction layer known as "vscript", which allows Valve to enable scripting for games in a variety of languages including: Lua, Squirrel, GameMonkey and Python. The vscript API for Half-Life: Alyx is much more limited than that of SteamVR Home, but in the future Valve may add new functions and API features. For now, it's not possible to add new weapons or tools, but hopefully that will change in the future.

  • NOTE: Valve does not ship any scripts with Half-Life: Alyx, meaning you will need to manually install the Source 2 runtime scripts which will initialize the entity subsystem, among other things. Without these scripts, many of the API functions will return nil.


1. Find your hlvr folder

  • The path should looks something like: D:\SteamLibrary\steamapps\common\Half-Life Alyx\game\hlvr, depending on where you installed it.

2. Create folders

  • Create a folder called: scripts. Inside that folder create another folder called: vscripts.
  • you should now be in a directory that looks like this: D:\SteamLibrary\steamapps\common\Half-Life Alyx\game\hlvr\scripts\vscripts

3. Install the required scripts

  • You can obtain the required runtime scripts here or from your SteamVR Home installation directory.
  • Clone or download the repo and move the vscripts folder to hlvr/scripts
  • If using SteamVR Home, copy the scripts/vscripts folder from SteamVR home to hlvr/scripts

Next Steps

At this point, you can begin writing scripts.

In order to load them, you'll need to move the scripts into the vscripts directory. Now they can be loaded using the script_reload_code and cl_script_reload_code console commands, which take a path to your script relative to the vscripts directory.

Starter Examples

These basic examples will show you how to connect the game world to the scripts that you write:

1. Hello Gordon: The classic example.

Example Index

Half-Life: Alyx Lua Scripting Examples