Scripting in Massive Loop SDK⚓︎

Massive Loop SDK supports user scripting using LUA programming language. Before we start diving in, let's clear out few things:

Small Q/A⚓︎

What happens if I add C# scripts?

Absolutely nothing. You can add C# scripts, they just won't work, almost as if they were never there. Massive Loop only allows Lua Scripts to be recognized, transferred, and executed. Adding C# scripts only work on the editor, not in the Massive Loop client.

However, you can create C# editor scripts to help you and your team to streamline your development process.

What about DLLs?

Same as C# scripts. They won't get transfered, recognized, or executed by Massive Loop.

Can I use Assets from Unity Asset Store?

It depends. You can use any assets that:

Don't contain any non-editor C# script. These already include Models, Textures, Materials, Animations, Sounds, Skyboxes, Shaders.

Unity Editor tools.

Finally, there is a complete library of approved assets that you can use to make your Massive Loop worlds dynamic. These include assets for UI, Weather, Videos, and more. Check Out the list of Approved Scripted External Assets.

Attention!

Do not purchase any paid assets from asset store! Unless if these assets fall into what is described in "Can I use Assets from Unity Asset Store?", don't purchase any assets unless you are confident that it will work within Massive Loop. Besides the scripting limitations, make sure that the Unity versions are compatible as well. Massive Loop uses Unity Version 2019.3.11f1.

Introduction to Lua Scripts⚓︎

It's important to talk about the tread of execution within Massive Loop. It will help us understand how and where the Lua scripts will be executed. The Lua scripts will only get executed when they are attached to a Unity GameObject or called using Import function.

Lua scripts that are attached to a Game Object executed by User Callbacks. Most of these callbacks are happens by the Unity Engine. You can check out the Unity execution call back here.

First pass: This is the first time that a Lua script gets executed. This phase happens for all Lua scripts in the world at the very first frame of the game. If there are any Syntax, Compilation, or Interface errors in your code, those will surface in this phase. Depending on the structure of the code, you might have others errors surface at this phase too. This is also where all the code which are outside of the user callback functions will be executed.
Start: In this phase, the start function in your code will be called. This happens on beginning of the next frame after initial pass.
FixedUpdate: Fixed update may called multiple time per frame. This sub loop often called physics loop, which makes Fixed Update useful for physics calculation.
OnTriggerXXX: Trigger events.
OnCollisionXXX: Collision events.
Update: In this phase, the update function gets called on every frame.
Coroutine.Yield: The suspended coroutines resume here.
LateUpdate: Called latest on the frame.

We will discuss more about the start and update function in Script Structure.

graph TD;
    subgraph compile
    A
    end
    A("First Pass")-->B(["Start"]);
    B-->C("Fixed Update");
    C-->D("OnTriggerXXX");
    D-->E("OnCollisionXXX");
    E--"Physics Loop"-->C;
    E-->F("Update");
    F-->G["coroutine.yield()"];
    G-->H("Late Update");
    H--"Game loop"-->C

Check out All User Callback to learn more about callback functions.

In Game thread of execution⚓︎

Massive Loop like most of the games uses a single thread to execute the game logic. This ensures a simpler design and keeps the integrity of data and events. The Lua scripts will also be executed in this thread. It means that on every frame the update function of all the Lua scripts gets executed.

Creating a LUA script in Unity⚓︎

To add a Lua script to a GameObject, first, you need to attach a LuaScript component to it.

To do so, select the desired GameObject from the scene Hierarchy, in the Inspector, click on .

Then Select MassiveLoop > LuaScript.

Lua Script⚓︎

You can attach your Lua scripts to the LuaScript component. As you notice, there are few options on the LuaScript Component.

: if checked, this script only get executed on the master client. To learn more about master client and general network structure in Massive Loop click here.
You can drag and drop the Lua Script assets to this field. The scripts must have a .lua extension.

The easiest way to create a new script is to press Create New Lua Script. This will brings up a new window and allows us to name the new script. Then automatically adds that to the field.

Editing Lua Scripts⚓︎

LUA scripts can be edited with many IDEs and any text editor. We recommend using the VS Code. Right click on the LUA script and select “always open with this program” to bind LUA scripts.

Scripting in Massive Loop​ SDK⚓︎