Script Mods: How to Use and Create Them

Lua script mods can implement extended features in the game, such as new user interfaces and tools. Here's how to use them, and get started making your own.

Loading a Script Mod

Enter the SCRIPT MODS screen, and select the "built-in examples" tab. Then select one of the script mods, and click the "Load and Run" button:

---

Script mods can create a UI window, as seen here with the Player HUD:

---

You can launch as many script mods as you like, and drag the windows around to rearrange them:

Unloading a Script Mod

A script mod can be stopped and unloaded by clicking the close button on its UI window:

---

NOTE: Another way to unload a script mod, is to select it in the SCRIPT MOD screen, and click the "Unload" button. Script mods don't necessarily have to create a UI, so they might not have a window to close.

Creating Your First Script Mod

Before launching the game, navigate to %USERPROFILE%\AppData\LocalLow\SmashHammer Games\GearBlocks, and create a folder named ScriptMods:

---

In the ScriptMods folder, create a subfolder for your new script mod, let's call it MyScriptMod.

In the MyScriptMod folder, create an empty text file and name it main.lua. Edit the main.lua file, type in the following Lua code, and save it:

print( 'Hello world!' )

Now launch the game, enter the SCRIPT MOD screen, and you'll be able to run your script mod:

---

Nothing much seems to have happened! However, if you open up the debug console (press the "backquote" key, or your keyboard's equivalent), you'll see some output showing that the Lua script was loaded, and it printed out the "Hello World!" text:

---

NOTE: The folder for a new script mod has to be created before launching the game, in order for it to be picked up. However, once created, you can modify and reload a script mod while the game is running.

The Included Hello World Example

In the SCRIPT MODS screen, under the "built-in examples" tab, there is a HelloWorld example. If you run it, a UI window will be created showing the "Hello World!" text:

---

Let's take a look at this script mod's Lua code.

The first section creates a UI window, then sets its position and size on screen. It also registers a handler with the window's OnClose event to unload the script mod when the window is closed. Lastly, it shows the window.

local win = Windows.CreateWindow()
win.SetAlignment( align_HorizCentre, 0, 200 )	-- Centre horizontally, width 200.
win.SetAlignment( align_VertCentre, 0, 100 )	-- Centre vertically, height 100.
local function onWindowClose()
	UnloadScript.Raise( ScriptName )	-- Window closed, so unload this script.
end
win.OnClose.add( onWindowClose )
win.Show( true )

The next block of code creates a text label inside the window, and assigns a text string to it.

local label = win.CreateLabel()
label.SetAlignment( align_HorizEdges, 10, 10 )	-- Align to window's left and right edges, with border of 10.
label.SetAlignment( align_VertEdges, 10, 10 )	-- Align to window's top and bottom edges, with border of 10.
label.Text = 'Hello world!'

Finally, there's the Cleanup() function. This is a special function called by the game into a Lua script when it is unloaded. In this instance, we make sure to destroy the UI window, in case we unloaded the script mod from the SCRIPT MOD screen, rather than by closing the window.

----- Entry functions -----

function Cleanup()
	Windows.DestroyWindow( win )
end

NOTE: Making the script mod unload itself in the window OnClose handler, and destroy the window in the Cleanup() function, is a good pattern to follow when writing your own script mods, in order to make them well behaved.

Modifying the Hello World Example

Let's try modifying the included HelloWorld example.

In the SCRIPT MODS screen, under the "built-in examples" tab, select the HelloWorld script mod, and click the "Open Containing Folder" button.

This will open WIndows Explorer at the HelloWorld folder.

Rather than directly modify the built-in version, first copy the HelloWorld folder into your local script mod directory (%USERPROFILE%\AppData\LocalLow\SmashHammer Games\GearBlocks\ScriptMods).

Exit the game, and then launch it again, so that it picks up your copy of the HelloWorld script mod, which should now appear under the "locally saved" tab:

---

In your copied HelloWorld folder, you'll find the main.lua file.

NOTE: You'll also see a meta.json file, all saves can have one of these, it contains the save name, description, and tags.

Open up main.lua in a text editor. Try changing something, for example you could make the window bigger:

win.SetAlignment( align_HorizCentre, 0, 400 )	-- Centre horizontally, width 400.
win.SetAlignment( align_VertCentre, 0, 300 )	-- Centre vertically, height 300.

And change the text colour and font size:

label.FontSize = 50
label.Text = '<color=yellow>Hello world!</color>'

You can reload the script mod while the game is running to immediately see the effect of your changes:

Taking it Further

This guide only scratches the surface of what's possible with script mods.

The included script mods are a good reference. In the SCRIPT MODS screen, select the "built-in examples" tab. Select one of the script mods, and click the "Open Containing Folder" button to take a look at it.

Read through their Lua scripts to get an idea of how they work. Try modifying them (copy them into your local ScriptMods folder first though!)

To learn more about general GearBlocks Lua scripting principles, refer to:
https://steamcommunity.com/sharedfiles/filedetails/?id=3084588433
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!