Operator tunables

Expose bounded configuration values through Warden's Tuning tab. Operators can change declared settings without editing Lua or restarting the resource.

A resource declares which of its numbers are tunable, with bounds and a description written for an operator. Warden's Tuning tab renders that declaration as a form, and the owner moves the values live. The panel can only move a value inside the declaration, and it never edits Lua.

Open77.tunables is server-side only. It does not exist in the client runtime.

The API#

The owning resource — and no other — receives onTunableChanged(key, value, pending) after every accepted write.

Declaring#

-- shared/config.lua — data, beside everything else you tune
Config.tunables = {
    bustRadius = { value = 15.0, min = 5.0, max = 50.0, unit = "m", apply = "next_match",
                   label = "Bust radius", group = "Chase",
                   description = "How close the cop must be for the pursuit meter to fill." },
    meterFill  = { value = 3.0, min = 0.5, max = 30.0, unit = "s", apply = "live",
                   label = "Meter fill", group = "Chase" },
}

-- server/main.lua — the call is server-only
Tune = Open77.tunables.declare(Config.tunables)

That split is not cosmetic. The table is data and belongs with the rest of your configuration; the declare call must be server-side, because Open77.tunables does not exist on the client. Put declare in a shared_script and every connecting player fails the resource set. The declaration table itself is downloaded to clients, so keep its prose publishable.

Limits: 128 tunables per resource, 64 KiB of declaration, 32 choices, 256-character strings.

The declaration is a contract, not a hint. min/max, the type and the choice list are enforced on every write — from the panel, from the console, and from your own Open77.tunables.set. Pick bounds inside which your resource is still doing something sensible; anything outside them is not a setting, it is a bug report.

Write the description for someone who has never read your code. It is the only thing standing between an owner and a number they will change by feel.

Read at the point of use#

The proxy returned by declare reads through to the host on every access. Tune.bustRadius is a call, not a field.

-- correct
if distance <= Tune.bustRadius then bust(playerId) end

-- wrong, and quietly so
local radius = Tune.bustRadius              -- file scope: frozen at load
CreateThread(function()
    while true do
        Wait(200)
        if distance <= radius then bust(playerId) end
    end
end)

The second reads its value once, at load, and never again. The panel goes on reporting the new number, so the symptom is "live tuning does nothing" and the cause is three files away.

A local inside a function is fine — it lives for one call. A local at file scope is the bug.

A misspelled key raises rather than returning nil, which is the one thing that makes this catchable at all.

When a change is allowed to land#

Three tools, in increasing strength.

The middle row has a limit that is easy to miss: promote() is per-resource, not per-match. If match A can be in flight while match B is created — one routing bucket each — promoting at B's creation moves A's finish line too. Capture instead:

-- creating a match
match.tune = Open77.tunables.capture()

-- every rule inside that match, for its whole life
if distance <= match.tune.bustRadius then ... end

A resource that captures does not need promote() at all: declare those keys live and let the capture do the holding.

Where the values live#

Values are owned by the host, so they survive a reload and a stop, and come back after a restart from tunables.json next to server.jsonc.

Stopping a resource for an evening must not quietly undo an afternoon of tuning, so the reset lever for a tunable is an explicit reset — not a restart. (This is deliberately unlike Open77.state, whose bag a stop does drop, so an operator keeps a "come up as at boot" lever.)

A key declared next_round or next_match is stored and persisted immediately but does not reach Open77.tunables.get until the resource calls promote().

See also#

• Writing a gamemode — choosing what to expose.
• The join-time readiness gate — the other host-owned cross-resource mechanism.
• The Lua resource runtime — manifests, permissions and the sandbox.