|
|
| (3 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| − | 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.
| + | This page has moved to: https://docs.sine.space/v/scripting/ |
| − | | + | |
| − | '''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:
| + | |
| − | | + | |
| − | [[File:Exampleluascript.png]]
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | ==An Additional Example: Subscribing To/Manually Firing Events==
| + | |
| − | | + | |
| − | Following is an additional example, scraped from the Space Beta Tester's skype channel.
| + | |
| − | | + | |
| − | [[File:Additionalexampleluascript.png]]
| + | |
| − | | + | |
| − | Note that in addition to the script, there is a custom event wired to the directional light in the scene.
| + | |
| − | | + | |
| − | The first six lines output various arbitrary properties, specifically the time, some statistics on the resources associated with the script, and objects associated with the scene.
| + | |
| − | These lines don't perform any logically associated operations beyond illustrating how to retrieve (and log) these values in the context of the scripting runtime.
| + | |
| − | | + | |
| − | The next line uses the SScript class' 'find' method directly to rename the directional light in the scene.
| + | |
| − | | + | |
| − | The next three lines instantiate a local reference to a game object named "GameObject", then invoke methods on that instance to subscribe to it's events. An appropriate message is written to the console in the interest of instrumentation.
| + | |
| − | | + | |
| − | The next four lines are quite interesting, and provide an excellent example of taking a reference to an anonymous function. The anonymous function is declared typographically starting with the text 'function()', and ending with the text 'end'. The function logic is in the body, and in this case produces text output indicating that the event fired and was serviced, and the time and mouse position are logged as well.
| + | |
| − | | + | |
| − | The next three lines register the method, wiring it up to the 'OnMouseDown' event (mouseclick), write to the log confirming the event method has been registered, and then manually invoke the event.
| + | |
| − | | + | |
| − | {{Scripting Navbox}}
| + | |
