AstralRanks Overview

How progression works

Each rank is a RankConfiguration (one YAML file under ranks/) with an id, a permission node, and a next-rank id pointing at the following rank in the chain (null /absent on the last rank). RankService builds the chain by starting at config.yml's default-group and following next-rank pointers (RankService#sortedRanks), stopping if a next-rank points at an id that doesn't exist or a cycle is detected.

Nothing about a player's current rank is stored by the plugin. Instead, RankService#getNextRank (and the matching isNextRank) walk that chain from the front: for each rank in order, if the player has its permission, that becomes the current candidate and the walk continues; the first rank the player does not have permission for stops the walk. The rank after the last one the player holds permission for is their "next rank" — the one whose missions are currently active. If a player holds none of the chain's permissions at all, getNextRank falls back to the configured default-group rank, while isNextRank simply returns false in that case.

This means the permission plugin (LuckPerms) is the actual source of truth for "what rank is this player" — AstralRanks only reads it, via Player#hasPermission, and expects a player's permissions to form a contiguous prefix of the chain starting at default-group.

Missions & categories

A rank's requirements map (keyed by requirement id, e.g. eco, jobs-level, oak_log) groups individual requirements under a category field. Categories themselves are defined separately in categories.yml (RequirementCategory: a display item and a rewards map of PaperActionLists). Progress and completion flow through RankService:

• Per-requirement progress is advanced by the update-rank-requirement action, which calls the matching RankRequirement#take and stores the result in the player's PlayerRankData progress map.

• Category completion — RankService#hasCompletedCategory checks every requirement in the rank sharing that category id against the player's progress. The first time a requirement completion pushes a category to fully-complete, RankService#updateRequirement marks it completed (PlayerRankData#setCategoryCompleted) and runs that category's rewards action list for the rank.

• Rank completion — unlocking is triggered by the unlock-rank action; the shipped rank-details menu fires [unlock-rank] %parameters_rank_id% from a button gated by [compare] %parameters_rank_unlockable% == true (backed by RankService#canUnlock, which checks every requirement in the rank against its amount regardless of category). A successful unlock runs the rank's own actions list — in the shipped ranks this is a pair of [console] lp user %player_name% parent add/remove <group> lines, i.e. a LuckPerms group swap — and broadcasts unlock-broadcast (skippable per-rank via ignore-broadcast in config.yml).

See Ranks & Progression and Requirements & Missions for the full YAML shape and category/reward mechanics.

Requirement types

Every requirement resolves to a RankRequirement, selected by its type key:

Commands

See Commands for the full subcommand/permission table.

Player data & sync

Progress is persisted through AstralSync as PlayerRankData, registered by RankSnapshotAdapter under snapshot key astralranks:data. It carries:

• progress — Map<rankId, Map<requirementId, Integer>>, the accumulated amount per requirement per rank.

• completedCategories — Map<rankId, Set<categoryId>>, which category/rank pairs have already paid out rewards (guards against re-granting rewards).

• categoryQuestsDisplay — the category id (or "all") the player has toggled on for the compact quest display placeholder, or null if disabled.

Configuration surface

Only ranks/default.yml is copied out of the jar automatically when the ranks/ folder doesn't exist yet (RankService#load); every other rank file is loaded if present but nothing else is auto-extracted. The menu filenames don't match their ids — MenuService opens menus by id (ranks-list, rank-details, ranks-requirements), not by filename. See Configuration.

Highlights

Registered extension points

Dependencies

Where to go next

• Configuration — config.yml, categories.yml, messages.yml in full.

• Commands — /ranks and /mission subcommands and permissions.

• Ranks & Progression — the per-rank YAML shape and the permission chain in detail.

• Requirements & Missions — requirement types, categories, and reward flow.

• Placeholders — the ranks/rank/category/requirement namespaces.

• Messages — the message-key catalogue.

• Developer API — RanksAPI, registered actions, and requirements.