GUI Leaderboard

GUI leaderboard backed by Typewriter facts

ManifestProvided by GUI

Reusable definition of a fact-backed leaderboard rendered by an OpenGUI layout.

Fields

Field	Type	Default	Description
source	Ref<GuiLeaderboardSourceEntry>	—	When set, rows come from this source (another extension's statistics, every player online or not); facts, scope, group, population, worlds and scoreMode are not used. order, limit, includeZero and the row texts still apply.
facts	List<Ref<ReadableFactEntry>>	empty	Facts whose values are aggregated into the row score.
scope	LeaderboardScope	PLAYER	Rows are individual players, worlds, or Typewriter groups.Values:PLAYERWORLDGROUP
group	Ref<GroupEntry>	—	Group entry used when scope is GROUP. Leave empty for a player/world leaderboard.
population	Ref<GuiLeaderboardPopulationEntry>	—	Optional artifact used to retain the last known values of players who are offline.
worlds	List<Var<Position>>	empty	Optional world selectors resolved as native Typewriter positions. Empty means every world.
scoreMode	LeaderboardScoreMode	SUM	How multiple selected facts are combined for one row.Values:SUMMAX
order	LeaderboardOrder	DESCENDING	Whether scores are sorted from highest to lowest or the reverse.Values:ASCENDINGDESCENDING
limit	Int	100	Maximum number of ranked rows considered before pagination.
includeZero	Boolean	false	If false, rows with a zero score are hidden.
rowItem	Var<Item>	—	Item displayed for every ranked row. Empty uses PAPER.
rowName	Var<String>	<white>{rank}. {name}	Row name. Tokens: {rank}, {name}, {score}, {group}, {world}; with a source also {score_raw} and {value_<key>}.Colors
rowLore	List<Var<String>>	—	Row lore. Supports the same tokens as rowName and {score_<fact_id>} for individual facts, or {value_<key>} for the values of a source.ColorsMulti-line

How to use it

1. Create a gui_leaderboard entry and list the facts to rank in facts.
2. Choose scope: PLAYER ranks individuals, WORLD adds up the players of each world, GROUP adds up the members of the group set in group.
3. scoreMode combines several facts: SUM adds them, MAX keeps the highest. order is DESCENDING or ASCENDING. Rows with a score of zero are hidden unless includeZero is on, and limit caps the number of ranked rows.
4. Style the rows with rowItem (paper by default), rowName and rowLore. Tokens: {rank}, {name}, {score}, {group}, {world} and {score_<fact_id>} for one fact.
5. In an Open GUI, add a leaderboard layout pointing at this entry. x, y, width and height reserve the rectangle of the rows; previousButton and nextButton page through the ranking.
6. Set autoRefreshTicks on the Open GUI if the ranking must update while the menu is open.

Use worlds to restrict a ranking to the worlds of the given positions. Without a population artifact, only online players are ranked: see GUI Leaderboard Population.

Rows from another extension (source)

Since GUI 0.20, source can name a leaderboard source: an entry of another extension that supplies the rows itself, for every subject, online or not. Dungeon provides one, Dungeon Leaderboard Source, that ranks the statistics of its runs. An extension supplies a source by implementing GuiLeaderboardSourceEntry.

• With a source, facts, scope, group, population, worlds and scoreMode are not used. order, limit, includeZero and the row texts still apply.
• Besides {rank} and {name}, the row texts accept {score} (the ranking value as the source writes it), {score_raw} (the number the ranking compares) and {value_<key>} (the extra values of the source, named by their key).
• The texts of a source are plain text. The layout ranks on that raw text and escapes only what it displays, so a name that looks like a MiniMessage tag, such as <red>, shows as typed and no longer changes the order.