Creating auto-loading scripts

Overview

Issues with addons, and setting up autorun scripts.

The issue

In current implementation of addons in Half-Life Alyx, when there are conflicting files between multiple enabled addons, the latest enabled addon will overwrite every other addon’s conflicting files.

This becomes a critical issue when multiple addons use the same initialiser script files that are executed by the server automatically, causing all addons except one to fail to load.

Solution

//scripts/vscripts/game/gameinit.lua

for addon in Convars:GetStr(“default_enabled_addons_list”):gmatch(“[^,]+”) do if not pcall(require,addon) then pcall(require,addon..”.init”) end end

This simple piece of code which needs to be saved in your /game/gameinit.lua file, and placed in your mod directory /Half-Life Alyx/game/hlvr_addons/<addonid>/scripts/vscripts/ will iterate through all enabled addons, and try to execute /<addonid>.lua or /<addonid>/init.lua file if the previous execution fails.

The purpose of this is to run every addon’s initialiser script regardless of which addon was overwritten. The reason addon ID is used is because there is no way to read files or directories in VLua.

One problem with this approach is that the addon ID becomes the workshop submission ID after uploading the addon. Since it is not possible to know the submission ID before upload, you will have to reupload right after creating a new submission.

1. Create new submission
2. Change placeholder initialiser file/folder name
3. Update submission

The execution order of “<addonid>.lua;<addonid>/init.lua” comes from the default path lookup behaviour of the ‘require’ function.

pcall is used to try to find and run the files, and continue without printing noise if they were not found. If xpcall were to be used, (compilation) error messages would have to be manually printed to a console channel different than the vscript error channel, ruining channel filtering and hinder debugging.

If the developer wishes to see compilation errors, the initialiser script can be a buffer to include another script with ‘IncludeScript’. This is the suggested method for the best development experience.

“IncludeScript(‘myscript.lua’)” > <addonid>.lua

Code execution on player spawn

The ‘player_connect_full’ event can be used to listen to player spawn. Alternatively you can use vs_library, which automates things.

local function Init() print(“Player has spawned”) end VS.OnPlayerSpawn( Init )

See for more info: [link]

Notes

The initialiser scripts are automatically executed on both client and server side. It is important to run your script only where it is needed. You can use IsClient() and IsServer() to control where your script it executed.

Put this condition check at the top of your script files to make sure they are executed only on server side:

if not IsServer() then return end

The following files and directories are reserved for the game files, creating these may lead to unwanted issues:

//scripts/vscripts/animationsystem/ //scripts/vscripts/core/ //scripts/vscripts/framework/ //scripts/vscripts/game/ //scripts/vscripts/modelprocessing/ //scripts/vscripts/utils/ //scripts/vscripts/response_rules.lua //scripts/vscripts/init.lua

It is also important not to use generic file names, such as ‘main.lua’. Keep files organised in your working directory.

Epilogue

Let Valve know of this problem. This issue will move on to future Source 2 titles if this is not changed.

Until then, the community needs to agree on a standard to follow.

Half-Life: Alyx Guide