This guide covers some general principles that apply to all GearBlocks Lua scripts, whether they be for scenarios or script mods.

For information specifically on making script mods, refer to:
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=3082621095
For information specifically on making scenarios, refer to:
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=3083650307

If a Lua script defines an Update() function, the game will call it every frame.

This should be used for any regular updates a script needs to do, such as polling input:

If a Lua script defines a FixedUpdate() function, the game will call it once per simulation time step.

This should be used when applying physics forces, for example:

If a Lua script defines a Cleanup() function, the game will call it when the script is unloaded.

This should be used for tidying up, such as reverting changes to global variables, removing global event handlers, destroying UI windows, and so on.

As an example:

For a scenario to support saving and loading of progress, its Lua script must define Save() and Load() functions. The game will call these functions when saving or loading a scene.

NOTE: Typically it only makes sense to define these functions in a scenario script, not a script mod.

The Save() function should return a string containing the serialized data that the scenario script wants to save. The built-in Json module can be used to serialize a table of data as a string:

The Load() function takes a string containing the previously serialized data. The built-in Json module can be used to deserialize the string and get back the table of data:

NOTE: Refer to the included "Kit Build" scenario for an example of implementing save / load functions. It can be found here: C:\Program Files (x86)\Steam\steamapps\common\GearBlocks\GearBlocks_Data\StreamingAssets\Scenes\Kit Build (or equivalent if you installed GearBlocks to a different location).

The game has many global events that are exposed for use in Lua scripts.

A handler can be added to an event in order to respond to it:

NOTE: Event handlers should be removed when no longer needed, hence the use of the Cleanup() function in this example.

Events can also be raised from Lua scripts:

NOTE: Caution is advised when raising events as some can put the game in a non-functioning state!

For a full list of the available events, open up the debug console (press the "backquote" key, or your keyboard's equivalent). Then type "listevt" and hit enter, this will list all the events:

---

You can type "help" followed by an event name to get more info on it.

The game has many global variables that are exposed for use in Lua scripts.

A variable can be read from:

Or assigned to:

NOTE: Caution is advised when assigning to variables as some can put the game in a non-functioning state!

For a full list of the available variables, open up the debug console (press the "backquote" key, or your keyboard's equivalent). Then type "listvar" and hit enter, this will list all the variables:

---

You can type "help" followed by a variable name to get more info on it.

The game exposes many global objects to Lua scripting, these provide all sorts of functionality. Such as: spawning in parts or constructions, manipulating constructions, creating custom UIs, creating vectors, quaternions, and much more.

We've seen examples of this already in this guide: polling input using Input, and creating a UI window using Windows.

Here are some more examples:




A comprehensive reference of all available objects is beyond the scope of this guide, and more features and functionality will be added to the API over time anyway. For full documentation, refer to the GearBlocks Lua Script API[www.gearblocksgame.com].

Players, constructions, and parts have a unique scene ID that can be used to identify them.

Each of these have an ID property that can be read, and can be retrieved from the scene using the Players, Constructions, and Parts global objects respectively.

For example:

A tutorial on the Lua language itself is beyond the scope of the guide, there are many resources online for this.

It is worth mentioning though that GearBlocks uses MoonSharp for its Lua integration, which has some slight differences and additions compared to "standard" Lua. More information can be found at Differences vs Lua[www.moonsharp.org] and Additions vs Lua[www.moonsharp.org].

To learn more about Lua scripting for GearBlocks, the included script mods and scenarios are a good reference, you'll find them here (or equivalent paths for your installation):

• Script mods: C:\Program Files (x86)\Steam\steamapps\common\GearBlocks\GearBlocks_Data\StreamingAssets\ScriptMods
  
• Scenarios: C:\Program Files (x86)\Steam\steamapps\common\GearBlocks\GearBlocks_Data\StreamingAssets\Scenes

Finally, here is the full documentation for the GearBlocks Lua scripting API[www.gearblocksgame.com]. This will evolve over time as I expose more features and functionality in the API, so bookmark it for future reference!