config

@gwigz/slua-modules/config reads settings notecards and applies parsed values to a typed config object in-place. The same reference stays valid across reloads.

How defaults work

The config object you pass in defines which keys are accepted and how values are coerced. The type of each default value determines the parsing behaviour:

Keys in the notecard that do not exist in your defaults object are silently ignored, this lets you keep comments or unrelated keys in the notecard without errors. The lljson parser assigns matching keys directly without type coercion.

Formats

Both parsers are gated by compile-time flags set via the define option on @gwigz/slua-tstl-plugin. When a flag is false (or omitted), the parser code is stripped from the Lua output.

{
  "tstl": {
    "luaPlugins": [
      {
        "name": "@gwigz/slua-tstl-plugin",
        "define": {
          "CONFIG_YAML_PARSER": true,
          "CONFIG_LLJSON_PARSER": true,
        },
      },
    ],
  },
}

YAML

# Comment
PRIVATE_CHANNEL: -1731704569
WELCOME_MESSAGE: Hello\nWorld
ADMIN_KEYS: key1, key2, key3

Lines starting with # are treated as comments and ignored.

lljson

Full JSON via lljson.sldecode, with native support for vectors, rotations, and UUIDs. Provide appropriate defaults (e.g. Vector.zero, Quaternion.identity, NULL_KEY).

Usage

import { loadConfig, onConfigChanged } from "@gwigz/slua-modules/config"

const config = {
  PRIVATE_CHANNEL: -1731704569,
  WELCOME_MESSAGE: "Welcome",
  ADMIN_KEYS: ["00000000-0000-0000-0000-000000000000"],
}

loadConfig("settings.yml", { config }, (ok, error) => {
  if (!ok) {
    console.log(`Config load failed: ${error}`)
    return
  }

  ll.Say(config.PRIVATE_CHANNEL, config.WELCOME_MESSAGE)

  onConfigChanged("settings.yml", { config }, (ok, error) => {
    if (!ok) {
      console.log(`Config reload failed: ${error}`)
      return
    }

    ll.Say(config.PRIVATE_CHANNEL, "Config reloaded")
  })
})

The callback receives ok (whether the notecard was read successfully) and an optional error string. On timeout, ok is false and error is "timeout". When loading fails, the config object retains its default values.

Using lljson (requires CONFIG_LLJSON_PARSER: true):

const config = {
  SPAWN_POS: Vector.zero,
  SPAWN_ROT: Quaternion.identity,
  OWNER: NULL_KEY,
  RADIUS: 10,
}

loadConfig("config.json", { config, type: "lljson" }, (ok) => {
  if (!ok) return
  ll.SetPos(config.SPAWN_POS)
})

API

ConfigOptions<T>

ConfigCallback