pz-rcon-data-bridge/wiki/Operations-Reference.md

# Operations Reference

This page describes every operation RconDataBridge currently registers,
along with the shared data structures they return. For how to actually
send a request and read a response, see [Protocol
Reference](Protocol-Reference).

Operation names are flat, verb-first `snake_case`, such as `get_player`.
Query `RconDataBridge_ProtocolVersion`'s `ops` array for the authoritative,
currently registered list; this page may lag a build that added or removed
an operation.

Each operation below is documented with an EmmyLua-style stub: a compact
comment block giving its arguments, return shape, and possible error
codes. This is documentation notation, not literal Lua you can call; an
operation is invoked by sending its name and an `args` object over the
wire protocol described in [Protocol Reference](Protocol-Reference), not
by calling a function directly.

Response examples are shown as JSON5, with aligned fields and comments,
purely for readability on this page. The actual wire format is always
strict, compact JSON, no comments, no trailing commas, no whitespace, see
[Protocol Reference § 4](Protocol-Reference#4-request-envelope).

## `get_world_stats`

```lua
--- World telemetry. Not player-related; see get_player / list_players.
--- @return WorldStats
fn get_world_stats()
```

```json5
{
  "worldAgeHours":  6.6,
  "worldAgeDays":   0.27,
  "nightsSurvived": 0,
  "date":           {
    "year":   1993,
    "month":  6,                   // 0-indexed: 0 = January ... 11 = December
    "day":    8,
    "hour":   13,
    "minute": 37
  },
  "isNight":        false,
  "isRaining":      true,
  "timeMultiplier": 4.8,           // current game-speed multiplier
  "generatedAt":    1787749440066  // ms epoch, when this snapshot was cached
}
```

This is the cached value, refreshed roughly once a minute 
in the background. The same data is also mirrored directly
to `RconDataBridge_WorldStats`, so you can read it there 
without spending a request/response round trip at all.

The cache only advances while the world clock is actually running. 
On a server configured with `PauseEmpty=true`, the game clock, and 
therefore this data, freezes while no players are connected; this 
reflects the world's real state rather than a stale bridge.

## `get_player`

```lua
--- Returns a player snapshot (see "Player snapshot structure" below).
--- @param  id string  Exact, case-sensitive username.
--- @return PlayerSnapshot
--- @error  PLAYER_NOT_FOUND  No snapshot exists yet for that id, meaning
---     either the username never connected to this server, or it hasn't
---     been observed by the bridge yet.
fn get_player(id)
```

A successful lookup also publishes or refreshes
`RconDataBridge_PlayerStats_<id>`, described below, 
so subsequent checks on that specific player can skip 
the request/response cycle entirely.

## `list_players`

```lua
--- Lists every player the bridge has ever seen, online and offline.
--- @param  limit number?   Page size. Default 50, capped at 200. A
---     non-numeric or absent value falls back to the default rather than
---     erroring. Optional.
--- @param  cursor string?  The last `id` from a previous page's results;
---     omit for the first page. Optional.
--- @return { players: PlayerSnapshot[], nextCursor: string? }
fn list_players(limit, cursor)
```

```json5
{
  "players":    [ /* PlayerSnapshot objects, sorted by id */ ],
  "nextCursor": "bob"  // absent, not null, once you've reached the last page
}
```

`players` includes every player the bridge has ever seen, 
online and offline, not just currently connected ones.

## `save_server`

```lua
--- Triggers a world save. Confirms the save was triggered, not that it
--- completed; there's no separate completion signal.
--- @return { triggered: true }
--- @error  SAVE_FAILED  The underlying save call threw.
fn save_server()
```

## `get_bridge_status`

```lua
--- Bridge health and introspection: uptime, current rate-limit window
--- usage, and the live runtime configuration. Useful for a client to
--- self-tune, for example backing off polling when the rate-limit 
--- window is nearly full, instead of guessing at hardcoded defaults.
--- @return BridgeStatus
fn get_bridge_status()
```

```json5
{
  "version":       1,
  "bootedAt":      1787740000000,  // ms epoch, server's last boot time
  "uptimeSeconds": 9440.2,
  "paused":        false,          // true when PauseEmpty=true and 0 players are online
  "rateLimit":     {
    "currentWindowRequests": 3,
    "maxRequests":           10,
    "windowSeconds":         10
  },
  "config":        {
    "maxPayloadBytes":        4096,
    "rateLimitMaxRequests":   10,  // mirrors the live Sandbox Options value
    "rateLimitWindowSeconds": 10   // mirrors the live Sandbox Options value
  }
}
```

`paused` doesn't affect this operation itself; the bridge keeps 
responding either way. It does tell you the world clock is frozen, so
`get_world_stats` and `RconDataBridge_WorldStats` won't advance until a
player joins. `config` mirrors the bridge's current settings, not just the
defaults, see [Configuration](Configuration): if an admin changed them at
runtime, this reflects the live values.

## `get_audit_log`

```lua
--- Read-only tail of the bridge's own audit trail, the same record of
--- every processed and rejected request that's written to the server
--- console and an internal ring buffer.
--- @param  limit number?  Max entries to return. Default 50, capped at
---     200. A non-numeric or absent value falls back to the default
---     rather than erroring. Optional.
--- @return { entries: AuditEntry[] }
fn get_audit_log(limit)
```

```json5
{
  "entries": [
    {
      "id": "ex1",
      "op": "get_world_stats",
      "ok": true,
      "ts": 1787749440066          // ms epoch
    },
    {
      "id":   "ex2",
      "op":   "get_player",
      "ok":   false,
      "code": "PLAYER_NOT_FOUND",  // present only when ok is false
      "ts":   1787749430012
    }
  ]
}
```

Entries are returned newest first. There's no cursor or pagination beyond
`limit`; this is a log tail, not a stable dataset to page through. The
underlying store holds at most the 500 most recent entries; `limit`
can't retrieve more history than that.

## Player snapshot structure

Returned by `get_player`, embedded in `list_players`'s `players` 
array, and published to `RconDataBridge_PlayerStats_<id>`:

```json5
{
  "id":          "alice",
  "online":      false,
  "characterId": 42,             // live session id; not stable across reconnects
  "lastSeenAt":  1787486000123,  // ms epoch: last refresh online, or disconnect/death time offline
  "stats":       {
    "hoursSurvived": 17.4,       // frozen at the last known value once offline
    "zombiesKilled": 83          // frozen at the last known value once offline
  }
}
```

Only these fields are ever collected: no position, no Steam ID, 
and no online ID beyond `characterId`.

Refresh triggers are a periodic sweep of the online roster, roughly once a
second by default, player death, and connect/disconnect detection, which is
also polled, since there's no connect or disconnect event available in the
engine.

## `RconDataBridge_PlayerStats_<ID>`, the read-only side channel

This option exists purely as a convenience cache, not a source of truth;
the request/response cycle via `get_player` always works and is
authoritative. Two things to know before relying on it:

- **It's lazy.** The option for a given player is only created the first
  time someone calls `get_player` for that id, from any client, including
  the one reading it now, or a previous session. Don't assume it exists
  for a player you haven't explicitly queried at least once.
- **`<ID>` is sanitized**, not the raw username: any character outside
  `[A-Za-z0-9_]` in the username is replaced with `_` to form a valid RCON
  option name. The `id` field inside the JSON payload is still the real,
  unsanitized username; use that as the source of truth if you need to
  disambiguate.