Skip to content
DarkBladeDev Docs

Lua Scripting and Safety Watchdog

CraftingEngine integrates an embedded, high-performance LuaJ 3.0.1 scripting runtime that allows server administrators and developers to author dynamic conditions, procedural calculations, and custom stage actions.

1. Sandbox Architecture and Security

To protect server integrity, Lua execution is isolated by a strict security sandbox:

  • No System/OS Access: Calls to io.*, os.execute, and file-system manipulation are stripped from the environment.
  • Instruction Quota: Script execution is bounded by scripting.max-instructions: 10000 to prevent infinite loops (while true do).
  • Wall-Clock Watchdog: Any script exceeding scripting.execution-timeout-ms: 50 is forcibly interrupted.

2. Global Context Bindings

Every Lua script evaluated in a crafting context receives predefined globals:

-- Context variables injected into the Lua environment
local player_name = context.player.name
local player_uuid = context.player.uuid
local player_level = context.player.level


-- Station state variables
local temp = context.station.get_variable("temperature")
local pressure = context.station.get_variable("pressure")


-- Stage telemetry
local strikes = context.stage.strikes_count

3. Authoring Lua Scripts (presets/scripts/*.lua)

You can save reusable scripts in plugins/CraftingEngine/presets/scripts/:

Example: Dynamic Temperature Formula (calculate_cooling.lua)

function evaluate(current_temp, ambient_temp, elapsed_seconds)
    local k = 0.05 -- Cooling constant
    local result = ambient_temp + (current_temp - ambient_temp) * math.exp(-k * elapsed_seconds)
    return math.max(ambient_temp, result)
end

Referencing in Blueprints

stages:
  - id: "custom_cooling"
    on_tick:
      - action: "lua:presets/scripts/calculate_cooling.lua"

4. Inline Mathematical Expressions

For simple calculations, CraftingEngine supports inline AST math expressions directly in YAML conditions:

requirements:
  conditions:
    - id: "heat_balance"
      condition: "math:(station.temperature * 1.5) > (player.level * 10)"

Next Steps