Configuration

The paper module reads a single config.yml, deserialized into LeaderboardsConfiguration (@ConfigSerializable). /leaderboard reload re-reads it without a restart. The master module has no YAML configuration of its own — it only copies a database.properties JDBC file on load.

`config.yml`

leaderboards:
  player-economy:
    id: "player-economy"
    display:
      material: "GOLD_INGOT"
      name: "Player Economy"
      lore:
        - "Top players by economy"
  fastest-parkour:
    id: "fastest-parkour"
    sort: ASC
    format-type: TIME_MILLISECONDS
    display:
      material: "FEATHER"
      name: "Fastest Parkour"
      lore:
        - "Fastest parkour times this week"

builtin-leaderboards:
  blocks: "blocks"
  kills: "kills"
  fished: "fished"

`leaderboards`

Map<String, Entry> — the map key is only used to iterate the config; the leaderboard's real id (used in commands, placeholders and packets) is the id field inside each entry, and the two should match.

Field	Type	Description
`id`	String	The leaderboard id. Used by `/leaderboard set`, `%leaderboards_<id>%`, and as the primary key on the master's `leaderboards`/`entries` tables.
`display`	`ItemStackWrapper`	Icon shown for this leaderboard in menus (material, name, lore — standard AstralCore item). Also the target of `%leaderboard_display%`.
`suffix`	`ComponentWrapper` (optional)	A MiniMessage component appended after a formatted score, e.g. a unit label. `null` if omitted. Exposed as `%leaderboard_suffix%`/`%entry_suffix%`.
`format-type`	`FormatType`	How a raw `double` score is rendered by `%entry_formattedScore%`. Not `@Nullable` — see the warning below.
`sort`	`SortDirection` (optional)	Ranking direction. `null` in config is treated as `DESC` (higher score ranks first) via the `sort()` accessor override; the only other value is `ASC` (lower score first — e.g. race times).

Config/code mismatch: the shipped config.yml sets format-type only on fastest-parkour; the other four sample leaderboards (player-economy, blocks, kills, fished) omit it even though formatType is a required (non-@Nullable) record component. LeaderboardEntryPlaceholder calls leaderboard.formatType().function() unconditionally when resolving %entry_formattedScore%, so any leaderboard missing format-type risks a null FormatType there. Always set format-type explicitly for every leaderboard.

There is no per-leaderboard period: config key — Entry has no period record component. Every leaderboard is tracked in all three period windows at once (see Architecture); the window is chosen when reading a leaderboard (%leaderboards_<id>_weekly%, _monthly%, _allTime%), not when declaring it. The shipped config.yml's header comment documents this correctly.

`FormatType`

Controls how %entry_formattedScore% renders LeaderboardEntry.score() (a double).

Value	Renders as
`FORMATTED_NUMBER`	Space-grouped integer (`NumberFormatUtils.formatWithSpaces`), e.g. `12 345`.
`NUMBER`	Comma-grouped integer (`%,d`), e.g. `12,345`.
`TIME_SECONDS`	Human-readable duration, score treated as seconds (multiplied by 1000 before formatting).
`TIME_MILLISECONDS`	Human-readable duration, score treated as milliseconds directly.

`SortDirection`

Value	Ranking
`DESC` (default)	Higher score ranks first — economy, kills, blocks.
`ASC`	Lower score ranks first — timed leaderboards such as `fastest-parkour`.

`builtin-leaderboards`

Map<BuiltinLeaderboard, String> — maps a built-in tracked stat to the leaderboard id it should write to. Only BLOCKS, KILLS and FISHED exist as BuiltinLeaderboard values. If a built-in stat's key is missing from this map, PlayerDataListener skips flushing it on quit for that stat (logged, not an error).

builtin-leaderboards:
  blocks: "blocks"
  kills: "kills"
  fished: "fished"

See Developer API for what each built-in tracker counts.

`database.properties` (master only)

A standard JDBC properties file copied from the master module's jar on onLoad; it reuses AstralCore's connection model. See the AstralCore database docs.

Last modified: 25 July 2026

Configuration

config.yml

leaderboards

FormatType

SortDirection

builtin-leaderboards

database.properties (master only)