# Configuration

RconDataBridge exposes its admin-tunable settings through Project Zomboid's
native Sandbox Options system, the same "New Game, Sandbox Settings" screen
also reachable in-game via the server admin panel on an already running
server. This is a separate mechanism from the RCON `ServerOptions`
transport the protocol itself uses (see [Protocol
Reference](Protocol-Reference)); Sandbox Options is purely for these
runtime knobs.

All values live under the RconDataBridge Sandbox Options page, and are
applied live: an admin can change them at runtime with no server restart
required. There is, however, no "value changed" event for Sandbox Options
either, so a changed value takes effect the next time the relevant code
path reads it, such as the next tick for poll cadence settings, rather than
instantaneously.

## Options

### Debug Self-Tests

Boolean, default `true`.

Runs the mod's internal JSON and base64 codec self-tests and logs the
result on every server boot. Diagnostic only; doesn't affect protocol
behavior. Safe to turn off once you trust the install.

### Poll Interval (ticks)

Integer, default `30`, range 1 to 300.

How many server ticks pass between checks of the request mailbox
(`RconDataBridge_Request`) and the online player roster. A lower value
means more responsiveness to incoming requests and player connect or
disconnect changes, at the cost of doing that check more often.

### Idempotency Window (seconds)

Integer, default `60`, range 1 to 3600.

How long a repeated request `id` replays its cached response instead of
re-running the operation. Protects side-effecting operations, such as
triggering a save, from duplicate execution on client retries. See
[Protocol Reference, Idempotency](Protocol-Reference#6-idempotency).

### Rate Limit: Max Requests

Integer, default `10`, range 1 to 1000.

Maximum number of bridge requests allowed within one rate-limit window; see
the next setting. This limit is global, not per connection, since RCON
requests carry no distinguishable caller identity, so it's the only way to
bound total load.

### Rate Limit: Window (seconds)

Integer, default `10`, range 1 to 3600.

Length of the rolling rate-limit window, in seconds. Combined with the
setting above, the default is 10 requests per rolling 10 seconds.

A running server's current values for the rate-limit pair, reflecting any
admin change and not just the defaults, are also readable at any time via
the `get_bridge_status` operation. This is useful for a client that wants
to self-tune its polling instead of hardcoding assumptions. See [Operations
Reference](Operations-Reference#get_bridge_status).

## What's not configurable here, and why

Two protocol-level values are intentionally not exposed as Sandbox
Options, even though they look like they could be:

- **Max request payload size** (4096 bytes decoded) and the underlying RCON
  option's max length are hardcoded. They're sized against the fixed
  capacity of the RCON option storing the request, after base64 expansion.
  An admin-set larger value here, with no matching change to that
  underlying capacity, could silently truncate a request instead of
  cleanly rejecting it with an error. Since that failure mode is worse than
  simply always rejecting payloads over the fixed limit, it isn't offered
  as a tunable.
- **Protocol identifiers**, meaning the protocol version number, the fixed
  `RconDataBridge_*` option names, and the standard error codes, are
  fixed, documented, client-facing constants, not server-tunable behavior.