Version

This page contains information specific to scripts executed by script components.

See LogicScript, RenderScript and Script for the components API reference.

Script components are executed by a script VM (short for Virtual Machine).

Render scripts are executed by the render VM directly on the rendering thread. Logic scripts are executed by several logic VMs.

Execution context

Scripts can be executed under two different contexts:

  • The edition context when editing resources using the editor.
  • The stand-alone context, when executing the application.

A script component can specify the execution context under which it should be executed by writing a combination of values from [ScriptExecutionContext] to the execution_context variable.

If not specified the script will only run when executing the application (eg. in a published project or when previewing it in the editor).

-- declare that this script is to be executed under all execution contexts
execution_context = hg.ScriptExecutionAll

The current execution context can be read from the current_execution_context variable.

Execution environment

Each script component is executed in its own sand-boxed environment which is initialized with the following variables.

1. Logic script environment

Variable Description
_G Self-reference to the sand-boxed environment table.
_S Global table shared between all logic script components running on the master logic VM.
hg API root symbol (see API reference).
this Node or Scene the script component belongs to.
engine Access to objects such as the RendererAsync or MixerAsync (see ScriptEnv).

2. Render script environment

Variable Description
_G Self-reference to the sand-boxed environment table.
hg API root symbol (see API reference).
this Node or Scene the script component belongs to.
renderer The Renderer object.
render_system The RenderSystem object.

Event callbacks

A script can declare functions that will be called by the engine to handle important events.

1. Logic script callbacks

Function name Prototype Event description
Setup The script environment has been created.
Update Called once per frame.
Delete The script environment is about to be deleted.
OnCollision (Node with, Vector3 pos, Vector3 normal) The physic system reported a collision event involving the component's node.
OnParameterChange (string parm_name) A script parameter value has been updated.
MouseEvent ([MouseEvent] evt) The mouse device state changed.

2. Render script callbacks

Remember: Render scripts are always called from the rendering thread.

Function name Prototype Event description
Setup The script environment has been created.
BeginDrawFrame Beginning a new frame.
ClearFrame Clear frame, return True to skip the render sytem clear step.
EndDrawFrame Ending a frame.
EndRenderPass (RenderPass pass) Called after a render pass has complete.
PostProcess (RenderTarget fbo, Texture tex_in, Texture tex_out) Apply post-process, return True to swap input textures.
OnParameterChange (string parm_name) A script parameter value has been updated.

Note: OnParameterChange is called automatically by Set. To manually notify a parameter change (eg. when changing a value from script) use [ScriptSystem_NotifyParameterChange].

Communicating between scripts

It is possible for a logic script to retrieve another logic script's environment by using its [LogicScript_GetEnv] method as long as they both run on the master logic VM (see [LogicScript_SetRunOnMasterVM]).

-- a.lua is a logic script running on the master VM attached to node "A"
function Ping()
 print("Pong from A!")
end

-- b.lua is a logic script running on the master VM attached to node "B"
function Setup()
 -- retrieve the logic script component holding a.lua on node A
 a_lua = this:GetNode("A"):GetComponent("LogicScript")[1]
 a_lua:GetEnv().Ping()
end

Additionally, scripts running on the master VM share a common table which can be accessed through the variable _S defined in their environment.

-- a.lua
_S.str = "Hello"

-- b.lua
print(_S.str.." World!") -- note: must execute after a.lua or the table lookup will return nil

This is not possible with render scripts or logic scripts not running on the master logic VM.

The only way to communicate between such scripts is by using the Get and Set methods. These methods are thread-safe and asynchronous. Set calls will be carried out during the next system commit while Get calls will immediately return the value last exposed by the target script for a given variable (see Expose).

-- a.lua is a logic script attached to node "A"
Expose("myPI", 3.141592)

-- b.lua is a logic script attached to node "B"
function Setup()
 -- retrieve the logic script component holding a.lua on node A
 a_lua = this:GetNode("A"):GetComponent("LogicScript")[1]
 local myPI = a_lua:Get("myPI")
 print("myPI = "..myPI)
end

Note: Calling into a script across different threads is not supported at the moment.