Skip to main content

Lua Scripts

The standard set of actions and conditions is enough for the vast majority of stories: give an item, change a relation, show text based on a condition. But the game engine (the core module, in Kotlin, using LuaJ) can also run arbitrary Lua code — a "hatch" for cases where the declarative condition/action language isn't enough.

How it's wired up​

You can specify the script command (synchronous) or asyncScript (asynchronous, without blocking the UI) in the actions of a stage, point, or squad:

"actions": {
  "script": ["print(\"LUA IS AWESOME\")"]
}

In the story editor, this command opens a full code editor (CodeMirror) instead of a plain text field — a sign that this is deliberately a more "programmer" tool than the other actions.

What's available inside a script​

From the game's code, it's clear the engine passes at least the controller and soundManager objects into the Lua context, meaning a script can control part of the game's systems directly. However, the full list of available objects and methods, along with their signatures, is not documented in public sources as of this writing.

Before writing a Lua script
  1. Check whether you can achieve the result with standard actions instead — it's more reliable and easier to understand for other authors who will read/modify your story.
  2. If a script is still needed, coordinate it with the game (pda) developers, so you don't end up relying on undocumented behavior that could change in the next version of the engine.
  3. Keep scripts short and predictable: a bug in a stage's Lua code isn't the same as a bug in a JSON action, and it's harder to diagnose through the editor.

See also Open Questions — it collects every place where this documentation relies on signals in the code rather than an explicit description of the API.