GUI Leaderboard Population Artifact

Typewriter's public API exposes no way to read a fact for a player who is not connected. A gui_leaderboard left on its own therefore ranks only the people currently online — a ladder that empties every time the server quiets down.

This artifact is the extension's answer: a last-known snapshot it owns and maintains itself, so offline rows keep their place without the official engine being modified.

Type: Artifact Entry Entry ID: gui_leaderboard_population Requires: OmniGUI v0.14 or later

Configuration

Field	Type	Default	Description
artifactId	String	auto-generated	Unique identifier for this snapshot.

Usage

1. Create one gui_leaderboard_population entry.
2. Set it as the population field of your gui_leaderboard.

Several leaderboards may share one artifact; each records only the facts and groups it actually selects.

When it is written

• Whenever a leaderboard is rendered, for every player currently online.
• Once more for a player who quits, before the engine drops their session.

Writes are debounced and performed off the main thread, so a busy leaderboard does not turn into a stream of disk writes.

Stored data

{
  "version": 1,
  "players": {
    "5c1e...": {
      "name": "Aeliana",
      "position": { "world": "…", "x": 0, "y": 64, "z": 0, "yaw": 0, "pitch": 0 },
      "facts": { "kills_fact": 420, "wins_fact": 18 },
      "groups": { "guild_ref": "guild_north" }
    }
  }
}

A snapshot only ever holds what a leaderboard asked for. position backs the {world} token and the worlds filter; groups backs GROUP scope.

nota

The file is a cache, not a source of truth. Deleting it loses the offline rows until each player reconnects once — no fact value is lost, since facts live in Typewriter's own database.