Script

Basics

Scripts in Shards Online are files written in Lua ending with .lua and containing the Lua code which does what your script should do.

A super primitive script:
helloworld.lua

print ("Always look at the bright side of life, and yes, 'Hello World!'")

This script being put into your mods scripts folder by itself does nothing.

To have your script doing something it needs to be attached to some Game Object (GameObj), like an NPC, a crate, a rock, anything that can exist in the SO world. A special case is globals.lua, which is automagically run on server start. Because globals.lua is not attached to any object, the this construct as a reference to the object a script is attached to does not work here. Using this in globals will throw errors / behave as nil.

So lets create an object and attach the script to it. You can do that with the the behavior tab on the "God Info" window (right click an object or use /info). An attached behavior is nothing but a synonym for an attached script.

RULE: Scripts can contain other scripts using the require function.

When doing so, you will see the text being printed to the server console which teaches us one thing:

RULE: Once a script gets attached to an object it runs immediately.

Attach the script to a second object and see the message again - as often as you attach it to an object.

RULE: You can attach a script to many different objects, but only once to any given object.

If then, you decide to backup and restart your server (/backup and /restart) and thus the object with the attached script gets saved, you will see the text again in your console after restart, exactly one time per object which teaches us:

RULE: When an object gets loaded from backup all scripts on it run once.

Events

So how can scripts add any persistent functionality to an object - do we have to keep them running or what? Hell, No ! A running script would block the server permanently, what we want is the script to wait for things to happen it should respond to. Scripts are mostly event controlled, the whole script architecture is based on events.

Most scripts define functions and register these functions as handlers for certain events - the Event Handlers. This is done with a special function called RegisterEventHandler.

Once such a function has been created and registered it is ready to answer (handle) triggered events, and this is where the fun begins. Once we can handle events we can react to stuff that happens in the world. To see a list of events check the official documentation.