GENERAL

In Ace Squared you may write lua scripts.
Lua scripts are loaded from StreamingAssets\xlua and gamemode scripts are placed in StreamingAssets\xlua\gamemodes.

They are loaded at startup, and whenever they are changed or added at runtime. Deleted scripts are unloaded at runtime as well.

Lua scripts must have '.lua' file extension.

There is no debugger support as of now but you may use print() function call to print out stuff to the console. Also there are some Draw* methods in the server proxy that could be useful.

First time the script is loaded it is also executed. If the script loads successfully you should see console messages such as

Loaded script 'script.lua'

You have 2 options for interacting with the server:

• hooks
• proxy objects

Global variable _STREAMING_ASSETS_PATH contains path to the StreamingAssets/ folder. You may access various proxy objects by the g-prefix. For example you can access server proxy by typing gServerProxy.

Other important information

Ace Squared uses xlua for lua scripting. It is fast with performance comparable to C#. Originally Ace Squared used MoonSharp but that was too slow.

With the scripting api you have access to C# classes, methods etc.

You can for example create C# objects, lists, use C# file io etc:

-- example
local nobuild_zone_color_green = CS.UnityEngine.Color32(100, 255, 100, 255)
local content = CS.System.IO.File.ReadAllText(path)
local platformMin = CS.UnityEngine.Vector3Int(minX, minY, minZ)

CS.System prefix for System namespace and CS.UnityEngine for unity stuff. Certain Ace Squared specific definitions are located in CS.AceSquared.

What makes xlua awesome it feels almost like writing C# but in lua. Babel gamemode is written in xlua using hooks and proxy objects. I have found that any good LLM like chat gpt is good at helping writing xlua code.

Gamemode scripting

Gamemode scripts should be placed in StreamingAssets\xlua\gamemodes. Gamemode script is such a script that is loaded when the round with the gamemode is going to start and unloaded when the round stops. Gamemode's filename must be unique gamemode string, so you can not use any of the built-in names (like CaptureTheFlag). When you have such a script in the gamemodes directory the server will register that gamemode and know about it's existence.

Gamemode script MUST have corresponding config file named GAMEMODE_config.lua (where GAMEMODE is name of the gamemode script). This file contains gamemode specific information such as round time and cvars. These cvars are only used for the round where this gamemode script is active. The gamemode config file MUST not do anything else than initialize the gamemode config object and return it.

For example script see StreamingAssets\xlua\gamemodes\babel.lua and StreamingAssets\xlua\gamemodes\babel_config.lua

Hooks

Hooks that are documented will be in a separate page. To use a hook you must register it at the top level (e.g. after all function definitions) with a function call:

RegisterScriptCallback("HookName", YourLuaFunctionName)

First parameter is the hook's name, this must be a valid string documented in the API. Second parameter is name of your lua function.