GUI Leaderboard

GUI leaderboard backed by Typewriter facts

マニフェスト提供元: GUI

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

フィールド

フィールド	型	デフォルト	説明
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.値: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.値:SUMMAX
order	LeaderboardOrder	DESCENDING	Whether scores are sorted from highest to lowest or the reverse.値:ASCENDINGDESCENDING
limit	Int	100	Maximum number of ranked rows considered before pagination. With display SINGLE_ITEM, the number of lines listed in the lore.
includeZero	Boolean	false	If false, rows with a zero score are hidden.
display	LeaderboardDisplay	ROWS	ROWS: one item per ranked row, paginated over the layout area. SINGLE_ITEM: one item, at the first slot of the layout, whose lore lists every ranked row (summaryName, summaryLore, summaryLine).値:ROWSSINGLE_ITEM
rowItem	Var<Item>	—	Item displayed for every ranked row, or the single item with display SINGLE_ITEM. 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>}.カラー
rowLore	List<Var<String>>	["<gray>Score: <white>{score}"]	Row lore. Supports the same tokens as rowName and {score_<fact_id>} for individual facts, or {value_<key>} for the values of a source.カラー複数行
summaryName	Var<String>	<gold>Leaderboard	Display SINGLE_ITEM: name of the single item, resolved for the viewer.カラー
summaryLore	List<Var<String>>	["{rows}"]	Display SINGLE_ITEM: lore of the single item. A line holding only {rows} is replaced by one summaryLine per ranked row; without such a line the rows are added at the end.カラー複数行
summaryLine	Var<String>	<gray>{rank}. <white>{name} <gray>- <yellow>{score}	Display SINGLE_ITEM: one lore line per ranked row. Supports the same tokens as rowLore.カラー

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.

The whole ranking on a single item (display)

By default (display: ROWS) each ranked player gets an item of its own. To show the whole top on one item, for example a "Top 10 kills" item whose lore lists ten players and their scores, set display to SINGLE_ITEM (since GUI 0.22):

1. Set limit to the number of lines you want in the lore, for example 10.
2. summaryName is the name of the item.
3. summaryLore is its lore. A line holding only {rows} is replaced by the ranking, one line per player; the lines before and after it stay as written (header, footer). Without a {rows} line, the ranking goes at the end of the lore.
4. summaryLine is the template of one ranking line. It accepts the same tokens as rowLore: {rank}, {name}, {score}, {score_<fact_id>}, and with a source {score_raw} and {value_<key>}.
5. The item itself is rowItem (paper by default). In the leaderboard layout of the Open GUI, the item sits at x, y: set width and height to 1. previousButton and nextButton are not used.

Example: limit: 10, summaryName: <gold>Top 10 kills, summaryLore: ["<gray>Best hunters", "{rows}", "", "<dark_gray>Updated live"], summaryLine: <yellow>#{rank} <white>{name} <gray>- <red>{score} kills.

To show several statistics of each player on that line, list them in facts and use one {score_<fact_id>} token per fact, for example <white>{name} <gray>kills <red>{score_kills} <gray>deaths <red>{score_deaths}.

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.