Lua doc lua_script_params

Lua Script Parameters

Reference documentation generated from lua_script_params.md.

Lua Script Parameters

Scripts can declare named parameters in a meta header at the top of the file. Parameters are exposed to the script as the global params table and allow scripts to be configured at launch time without modifying the script itself.

Declaring Parameters

Parameters are declared using --- @param annotations at the very top of the script, before any code. The parser stops reading declarations at the first non-comment, non-empty line.

--- @param <name> <type> [= <default>]
  • name — identifier used to access the value via params.name
  • type — one of int, float, string, boolean
  • = <default> — optional default value used when no override is provided at launch

Example

--- @param patrol_range int = 5000
--- @param scan_interval float = 2.5
--- @param target_faction string = "pirate"
--- @param aggressive boolean = true

function on_init()
    if params.aggressive then
        print("Aggressive mode, patrol range: " .. params.patrol_range)
    end
end

Types

TypeLua typeExample declarationNotes
intnumber (integer)--- @param speed int = 500Parsed as a 32-bit integer
floatnumber (decimal)--- @param rate float = 1.5Parsed as a double-precision float
stringstring--- @param faction string = pirateSurrounding " or ' in the default are stripped
booleanboolean--- @param aggressive boolean = trueMust be true or false

Default Values

If a parameter has a default and no override is passed at launch, the default is used. If a parameter has no default and no override is passed, the key is absent from the params table — accessing it returns nil.

--- @param max_targets int = 3
--- @param label string

function on_init()
    local n = params.max_targets  -- 3 (default)
    local l = params.label        -- nil (no default, no override)
end

String defaults may optionally be wrapped in quotes — both forms are equivalent:

--- @param faction string = pirate
--- @param faction string = "pirate"

Passing Overrides at Launch

When sending a run_script command, include override values as extra parameters with the param_ prefix. The prefix is stripped before the value is placed into the params table.

{
    "action": "run_script",
    "scriptId": "patrol",
    "script": "...",
    "shipId": "42",
    "param_patrol_range": "8000",
    "param_aggressive": "false"
}

Override values are strings and are coerced to the declared type automatically. If coercion fails (e.g. "abc" for an int), the raw string is used as a fallback.

Debug Mode

Passing "debug_mode": "true" with the run_script command enables debug logging. Two things happen:

  1. At startup — a client message is sent listing every declared parameter and its effective value (override or default): [Debug] patrol_range (int) = 8000, aggressive (boolean) = false, target_faction (string) = pirate

  2. On every event call — a client message is sent showing the function name and its arguments before it executes: [Debug] on_init() [Debug] on_timer("tick") [Debug] on_sector_target_locked("42", "17") 

{
    "action": "run_script",
    "scriptId": "patrol",
    "script": "...",
    "shipId": "42",
    "debug_mode": "true"
}

Compile-time Inspection

The compile_script command returns the parsed parameter list in its response, which can be used by a client UI to show a configuration form before running the script.

{
    "status": "ok",
    "action": "compile_script",
    "data": {
        "script_id": "patrol",
        "params": [
            { "name": "patrol_range", "type": "int",     "default_value": "5000", "has_default": true },
            { "name": "aggressive",   "type": "boolean", "default_value": "true", "has_default": true },
            { "name": "label",        "type": "string",  "default_value": null,   "has_default": false }
        ]
    }
}

Backward Compatibility

Parameters set on a ship's Role (Role.Parameters) are still applied to the params table before meta-declared parameters. Meta params take precedence over role params when names conflict.

← Back to Wiki