Difference between revisions of "Scripting/LUA"

Revision as of 06:05, 26 January 2017

Space supports two separate scripting runtimes - Lua and C#; for most uses, we strongly recommending using the Lua variant, as it is cross-platform compatible. (C#/.NET only work for Standalone clients). Our Lua runtime runs optimally in all platforms including WebGL; and utilises the same API as the C# variant.

Note: We had originally announced JavaScript as our cross-platform runtime, however after implementation we've found our Lua runtime performs considerably better and with greater stability.

Notes on the Lua implementation

• We do not place many limits on scripts, however scripts must return execution context every 5000 (configurable) instruction cycles (scripts are run in a deterministic single-threaded manner for compatibility with HTML5/WebGL where threading does not yet exist). Exceeding this will have your script forcibly interrupted.
• Using coroutines or binding to a regularly firing event (e.g. OnUpdate()) is a way of continuing a long running script.
• Scripts run in the client (for server scripts see Scripting/Server Scripts)

Creating a Lua Script in Space

Note: This documentation refers to the first fruits of Lua scripting in Space, and as such, it and everything it describes is subject to change at just about any time

• Lua scripts can be attached to any Game Object. This is done by selecting the game object, and in the inspector, "Add Component->Scripts->Scripting Runtime" (don't let it fool you that it has a little C# icon).
• Lua requires no preamble or compiler directives (at this time, at least), so no 'using' or 'includes' lines -- everything inherits from the parent Space object.
• Having attached the scripting runtime to your object, when you examine it via the inspector you will see an empty source code box, among other things (we'll get into those later). Thats where you type or paste your script source code. It will be saved with the scene, just like any other object property.
• In the Project tree, if you search 'Scripting Example' you will find a scene. In that scene is an empty game object with a sample 'Hello World' script attached. A quick exposition of the script's operational elements is provided following.

Example Lua Script

Here's the view in the inspector pane of the GameObject to which the example script is attached, along with a particle system:

That's the entire script in the source code box, it's really quite simple.

- The first line writes a text message on the console.

- The second line creates a script-local reference to the host object (the GameObject to which the script is attached).

- The next five lines set up a local variable referencing the host object's position, set the positional properties via the local variable, and finally store that position back to the host object, effectively setting it's position in world.

- after that, the attached particle system is invoked with 50 particles.

Note that in each of these operations, the reference to the host object has been used as a property selector. The last line uses a reference to the scene as a property selector, but does so directly, without creating any persistent references in advance of of doing so.

- That last line sets the text value to be rendered on the canvas in the hierarchy, producing the 'Hello World" message as 3D text rendered in the scene.

Hopefully this will be a sufficient 'jumping off point' for those of us eager to get busy with scripting interactive objects for Space.