> For the complete documentation index, see [llms.txt](https://docs.cozycrafters.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cozycrafters.net/plugin-docs/cozyranks.md).

# CozyRanks

### What It Does

CozyRanks manages rank progression for the server.

Players use the rank menu to view their active goal, deposit PlayerPoints, Vault money, and required items, then claim ranks when requirements are complete. Admins can inspect player rank state, force-set ranks, reset players, refund deposits, sync LuckPerms groups, reload configuration, and run migration tools.

The bundled configuration describes 20 ranks across 4 tiers: Iron, Gold, Diamond, and Netherite.

### Main Features

| Feature                         | Description                                                                                                    |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Rank menu                       | `/ranks` opens the active goal menu for players.                                                               |
| Rank path menu                  | `/ranks list` opens the rank path menu.                                                                        |
| Rank requirements               | `ranks.yml` defines points, money, and item requirements for each rank.                                        |
| Rank rewards                    | `ranks.yml` defines permissions, cosmetic permissions, and on-claim commands.                                  |
| Deposit progression             | Players deposit toward the next rank over time.                                                                |
| Rank claiming                   | Completed goals can be claimed from the player menu.                                                           |
| LuckPerms integration           | Rank claims and admin rank changes can dispatch LuckPerms group updates.                                       |
| Admin inspection                | `/ranksadmin <player>` opens a read-only admin inspect GUI for an online admin player.                         |
| Admin recovery tools            | Admins can reset rank state, refund deposits, sync LuckPerms groups, and rerun the deposit recovery migration. |
| Legacy migration                | Admins can scan and migrate legacy AxRankMenu groups through migration commands.                               |
| PlaceholderAPI support          | CozyRanks exposes rank and progress placeholders when PlaceholderAPI is available.                             |
| Optional visuals and broadcasts | Oraxen can be used for GUI visuals, and DiscordSRV can be used for tier-completion broadcasts.                 |

### Basic Admin Workflow

1. Install CozyRanks and the integrations your setup requires.
2. Start the server once so the plugin creates its files.
3. Review `config.yml`, `tiers.yml`, `ranks.yml`, `messages.yml`, `migration.yml`, and `admin-menu.yml`.
4. Give players `cozyranks.use`.
5. Give trusted staff `cozyranks.admin` only if they should use admin tools.
6. Use `/ranksadmin list` to check the active ladder.
7. Use `/ranksadmin reload` after supported config changes.
8. Use `/ranksadmin sync <player>` if rank data is correct but LuckPerms is out of sync.

### Notes

* The player command is `/ranks`; `/rank` is its alias.
* The admin command is `/ranksadmin`; `/cozyadmin` and `/cozyranksadmin` are aliases.
* No `/rankup` command is registered in `plugin.yml`.
* `plugin.yml` declares Vault, PlayerPoints, LuckPerms, PlaceholderAPI, DiscordSRV, and Oraxen as soft dependencies.
* The README lists Vault, PlayerPoints, LuckPerms, and PlaceholderAPI as required dependencies.
* The README lists DiscordSRV and Oraxen as optional dependencies.
* `ranks.yml` is the source for configured rank IDs, rank names, costs, permissions, cosmetic permissions, and on-claim commands.
* `/ranksadmin reload` reloads config, messages, tiers, ranks, migration config, and the admin menu config. Failed files keep their old active values.
* If a database commit succeeds but LuckPerms dispatch fails, the admin guide says to run `/ranksadmin sync <player>`.

### Common Use Cases

| Use Case                           | Command                                      |
| ---------------------------------- | -------------------------------------------- |
| Player opens active rank goal      | `/ranks`                                     |
| Player opens rank path             | `/ranks list`                                |
| Admin opens read-only inspect GUI  | `/ranksadmin <player>`                       |
| Admin checks a player's rank state | `/ranksadmin info <player>`                  |
| Admin prints the ladder            | `/ranksadmin list`                           |
| Admin force-sets a rank            | `/ranksadmin set <player> <rank> [--silent]` |
| Admin resets a player              | `/ranksadmin reset <player> --confirm`       |
| Admin refunds pending deposits     | `/ranksadmin refund <player> --confirm`      |
| Admin re-syncs LuckPerms           | `/ranksadmin sync <player>`                  |
| Admin reloads configuration        | `/ranksadmin reload`                         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cozycrafters.net/plugin-docs/cozyranks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.