The Lua Script

A Lua Script can be loaded and executed through the use of a Lua Script Component, which is at the moment the only component that can have multiple instances of itself on an entity.

The user can directly work on the entity on which the Lua Script Component is sitting on by using the entity keyword, which is reserved for this type of behaviour. e.g. entity:GetTransformComponent(), entity.name()

Structure and functions

A Lua Script communicates with the source C++ code through a number of designated functions that handle different parts of the logic. The user can, of course, define their own functions, but with different signatures than the predefined ones.

Init()

This function is executed only once and that is when either the scene is loaded, or, if the entity is disabled, when the entity is enabled for the first time.

Update(ts)

The Update function runs once every frame for every script in the scene. The ts is a float value that represents the Delta Time, or the Time Step, which is the time in seconds that the program took to render the last frame.

FixedUpdate(fixedts)

The FixedUpdate function runs once every physics tick for every script in the scene. The fixedts is a float value that represents the Fixed Delta Time, or the Fixed Time Step, which is the constant time in seconds at which rate the program performs a physics tick. This value is at the moment always equal to 1/60.

CollisionEnter2D(contact)

This is a callback function that is executed one time if the current entity has detected a collision with another entity. The contact parameter is of type Contact2D, which is a variable type holding information about the collision overall (see the Physics 2D tab for more on Contact2D).

CollisionExit2D(contact)

This is a callback function that is executed one time if the current entity has stopped a collision with another entity. The contact parameter is of type Contact2D, which is a variable type holding information about the collision overall.

SensorEnter2D(other)

This is a callback function that is executed one time if the current entity has detected a collision with another entity's collider who is marked as a Sensor. The other parameter is of type Collider2D, which is a variable type from which the Box Collider 2D and Circle Collider 2D inherit from (see the Physics 2D tab for more about the Contact2D).

SensorExit2D(other)

This is a callback function that is executed one time if the current entity has stopped a collision with another entity's collider who is marked as a Sensor. The other parameter is of type Collider2D, which is a variable type from which the Box Collider 2D and Circle Collider 2D inherit from.

---

Communication between different Lua Script

There are many instances where one may want to retrieve a variable, or execute a function from another Lua Script. In Chimera that is done fairly easily. Since all Lua Scripts are Sol Environments (glorified tables) held together within a global Lua State, all one needs to do is declare their desired variable, or function as global ( things in Lua are global by default, so just make sure you didn't declare it as local ) and retrieve the Sol Environment, which is done through:

- GetLuaScriptComponent(int index)

Returns the table of the script located at the specified index within the Lua Script Component.

After that, all one has to do is access the variable or function as if they were working on a table. e.g.

local troll = GetEntityByName("Troll")

-- get the first script attached on the "Troll" entity and call its global function "ReduceHealth()" which takes a number parameter
troll:GetLuaScriptComponent(0).ReduceHealth(5)