GUI Leaderboard

The GUI Leaderboard turns one or more Typewriter facts into a ranking. It is a reusable definition: create it once, then draw it wherever you need with a leaderboard layout inside an open_gui pool.

Type: Manifest Entry Entry ID: gui_leaderboard Requires: OmniGUI v0.14 or later

Configuration

Field	Type	Default	Description
facts	Ref<ReadableFactEntry>[]	[]	Facts aggregated into each row's score. Nothing is ranked while this is empty.
scope	PLAYER | WORLD | GROUP	PLAYER	What a row represents.
group	Ref<GroupEntry>	empty	Group entry used when scope is GROUP.
population	Ref<gui_leaderboard_population>	empty	Artifact retaining the values of offline players. See below.
worlds	Var<Position>[]	[]	World selectors. Empty means every world.
scoreMode	SUM | MAX	SUM	How several facts combine into one score.
order	DESCENDING | ASCENDING	DESCENDING	Sort direction.
limit	Int	100	Maximum ranked rows before pagination.
includeZero	Bool	false	Keep rows whose score is zero.
rowItem	Var<Item>	PAPER	Item drawn for every row.
rowName	Var<String>	<white>{rank}. {name}	Row display name.
rowLore	Var<String>[]	<gray>Score: <white>{score}	Row lore.

Row tokens

Usable in rowName and rowLore:

Token	Value
{rank}	Position in the ranking, 1-based and continuous across pages.
{name}	Player name, world name, or group id depending on scope.
{score}	Combined score, as decided by scoreMode.
{group}	Group id of the row, empty when no group is selected.
{world}	World of the row, empty when unknown.
{score_<fact_id>}	The value of one selected fact, so a lore can break the total down.

Offline players

Typewriter's public API deliberately exposes no way to read a fact for a player who is not connected. Left alone, a leaderboard therefore ranks only the people currently online.

Point population at a gui_leaderboard_population artifact to lift that limit. The extension refreshes the snapshot while players are online and once more when they quit, then merges it with live values at render time. The official engine is not modified.

Drawing it

A leaderboard layout reserves a rectangle and fills it with ranked rows, page by page:

{
  "case": "leaderboard",
  "value": {
    "id": "ladder_rows",
    "leaderboard": "my_leaderboard",
    "x": 1, "y": 1, "width": 7, "height": 2,
    "previousButton": { "x": 0, "y": 5, "item": { "material": "ARROW" }, "displayName": "<yellow>Previous" },
    "nextButton": { "x": 8, "y": 5, "item": { "material": "ARROW" }, "displayName": "<green>Next" }
  }
}

Field	Role
leaderboard	The gui_leaderboard entry to render.
x, y	Top-left corner of the rank area.
width, height	Size of the rank area. width * height rows fit on one page.
previousButton, nextButton	Optional slots, positioned by their own x/y. Each is drawn only when that page exists.

Combine it with a simple layout through a composite layout to get a frame around the ranks, and set autoRefreshTicks on the open_gui entry if the scores must move while the menu is open.

Startup validation reports a rank area that falls outside the inventory, and a layout that references no gui_leaderboard.