Creating your first script

Our first script will simply print Hello World, from my first script! to the ingame chat box when it is loaded. In the later sections we will expand on this.

Create a new folder for your script in the ub script directory (default C:\Games\Decal Plugins\UtilityBelt\scripts\) called HelloWorld. The full directory path should be C:\Games\Decal Plugins\UtilityBelt\scripts\HelloWorld\.

[!WARNING] Script names should only contain alpha-numeric characters and spaces. They should be named something unique, as two different scripts cannot share the same name.

Inside that folder create a new empty file called index.lua. The main entry lua file for a script is always called index.lua, and its entire contents will be executed upon loading the script. The full file path should be C:\Games\Decal Plugins\UtilityBelt\scripts\HelloWorld\index.lua. Open the file in Visual Studio Code and add the following contents:

print("Hello World, from my first script!")

You should already be familiar with the print function, as it is built into lua. If not, you might want to go back and check out some of the resources in the Lua section.

Running your script

Open the game and log in to a character. From there open the UtilityBelt Scripts Manager window using the UB Hud Bar. Look for your HelloWorld script on the left column, select it, and hit the Start button.

From here you should see the text Hello World, from my first script! in the game chat window. If you don't see that text, look for any errors output to the chat window, and make sure you input the script exactly as it appears above. Alternatively you can run the script with the command /ub script start HelloWorld to get the same result.

Scripts can be started and stopped using both the Scripting UI and command line. For detailed command line / UI instructions, see the Scripts tool. You can also set individual scripts to start automatically for all clients, certain accounts, or individual characters.

Running the same code from the command line

The /ub lexec command will run the specified lua code in a global script context. For more information about script contexts, see the Script Contexts guide under the advanced section. To run the same code as the script above, log into the game and type the following into the chat window:

/ub lexec print("Hello World, from my first script!")

Notice that running that command is the same as starting the HelloWorld script above. We can run any valid lua code here that will fit in the chat input. This is handy for testing simple scripts without creating a whole new named script. Here's another example of adding some numbers together.

/ub lexec return 1+2+3+4+5

This will output the following in your chat window:

[UB] Evaluating script (context `Global`): "return 1+2+3+4+5"
[UB] Result: (System.Double) 15 (0.031ms)

[!NOTE] Notice the return statement at the beginning of our lexec command above. If we want to see the results from a statement we need to return them, and they will be output in chat after Result:. The Result: information also includes the data type of the result in the first set of parenthesis, which can be helpful when referencing the API Docs. The last set of parenthesis at the end of the Result: contains the time it took to execute the statement in milliseconds.