Ranks - Community Progression System

Ranks is a server-side progression mod for NeoForge 1.21.1 that adds an automatic ranking system
based on real player activity. With 30 grades, 12 tracked statistics, community objectives validated
by admins, and full chat & tab list integration, Ranks turns your server into a rewarding
progression experience.

---
Key Features

30 Grades across 10 Phases

Players progress through 30 grades organized into 10 thematic phases, each with its own color:

┌───────┬───────────────┬────────┬───────────────────────────────────────────────────────────────┐
│ Phase │ Theme │ Color │ Grades │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 1 │ Arrival │ Gray │ Naufrage, Echoue │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 2 │ Survival │ Green │ Rescape, Survivant │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 3 │ Connection │ Cyan │ Cueilleur, Defricheur │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 4 │ Development │ Yellow │ Explorateur, Voyageur, Eclaireur │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 5 │ Economy │ Orange │ Batisseur, Artisan, Architecte │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 6 │ Participation │ Blue │ Apprenti Marchand, Negociant, Commercant │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 7 │ Contribution │ Purple │ Resident, Habitant, Citoyen │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 8 │ Recognition │ Pink │ Intendant, Conseiller, Magistrat │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 9 │ Influence │ Red │ Notable, Dignitaire, Senateur │
├───────┼───────────────┼────────┼───────────────────────────────────────────────────────────────┤
│ 10 │ Prestige │ Gold │ Gouverneur, Regent, Chancelier, Patriarche, Legende, Mythique │
└───────┴───────────────┴────────┴───────────────────────────────────────────────────────────────┘

All grades, thresholds, and colors are fully configurable via grades.json.

---
12 Automatically Tracked Statistics

Every player is tracked in real-time across 12 different metrics:

- Active playtime (built-in AFK detection)
- Distinct login days
- Blocks placed / Blocks broken
- Distance traveled (with anti-teleport cap)
- Mobs killed
- Items crafted / Crops harvested
- Money earned / Money spent (economy integration)
- Trades completed
- Unique chunks visited (exploration)

Promotion is automatic: once a player meets all thresholds for the next grade, they are promoted
instantly.

---
Community Objectives

On top of automatic statistics, each grade can require qualitative objectives that must be manually
validated by an administrator:

- Build a shelter, a house, a shop
- Connect to the railway network
- Create a town with streets and lighting
- Help new players get started
- Organize a community event
- Build major infrastructure
- ...and more (fully configurable)

Promotion requires: all stats met + all objectives validated.

Admins have a full GUI interface to manage and validate objectives.

---
Chat & Tab List Integration

The player's grade is displayed everywhere:

Chat:
[Batisseur] Steve > Hello everyone!

Tab list:
[Batisseur] Steve

Player names in chat retain hover (shows UUID) and click (suggests /msg command) functionality.

---
Promotion Announcement

When a player ranks up, all players see a festive announcement:

★══════════════════════════════★
⬆ P R O M O T I O N ⬆
Steve : Survivant ➜ Batisseur
Grade 10 / 30 — Phase 5
★══════════════════════════════★

With dynamic colors matching the grade reached.

---
Graphical Interface (GUI)

Press R or /rank — Opens the progression panel:
- Colored phase band highlighting the current phase
- Current grade and next grade progress
- Progress bars for every statistic
- Community objectives section with validated/pending status
- Scrollable if content exceeds screen size

---
Rewards System

Commands are automatically executed on each promotion (configurable in rewards.json):
- Give items, experience, effects
- Execute any server command
- Available placeholders: {player}, {rank}, {rank_name}, {rank_number}

---
Full Admin Toolkit

Commands:

Command: /rank
Description: Show your grade + open GUI
────────────────────────────────────────
Command: /rank info [player]
Description: Detailed info with progress
────────────────────────────────────────
Command: /rank top
Description: Top 10 players by grade
────────────────────────────────────────
Command: /rank check
Description: Force a promotion check
────────────────────────────────────────
Command: /rank objectives
Description: View your objectives for the next grade
────────────────────────────────────────
Command: /rank admin set <player> <grade>
Description: Set a player's grade
────────────────────────────────────────
Command: /rank admin reset <player>
Description: Reset a player's data
────────────────────────────────────────
Command: /rank admin reload
Description: Reload all configuration
────────────────────────────────────────
Command: /rank admin validate <player> <objective>
Description: Validate an objective
────────────────────────────────────────
Command: /rank admin unvalidate <player> <objective>
Description: Remove a validation
────────────────────────────────────────
Command: /rank admin objectives <player>
Description: Admin GUI: view/validate a player's objectives
────────────────────────────────────────
Command: /rank admin manage
Description: Admin GUI: manage objective definitions (add/remove)

Admin GUIs:
- Objective validation (/rank admin objectives <player>): lists all objectives with Validate/Remove
buttons, sorted by grade order
- Objective management (/rank admin manage): view all grades with their objectives, add or remove
objectives through the GUI

---
AFK Detection

Playtime only counts when the player is active:
- Movement check every 20 seconds
- Configurable movement threshold (3 blocks by default)
- AFK timeout: 5 minutes of inactivity

---
Configuration

All config files are auto-generated on first launch in world/ranks/:

┌─────────────────┬─────────────────────────────────────────────┐
│ File │ Content │
├─────────────────┼─────────────────────────────────────────────┤
│ config.json │ AFK, promotion, economy, distance intervals │
├─────────────────┼─────────────────────────────────────────────┤
│ grades.json │ All 30 grade definitions with thresholds │
├─────────────────┼─────────────────────────────────────────────┤
│ rewards.json │ Reward commands per grade │
├─────────────────┼─────────────────────────────────────────────┤
│ objectives.json │ Community objectives per grade │
└─────────────────┴─────────────────────────────────────────────┘

Hot-reload with /rank admin reload.

---
Economy Integration

Compatible with HUDCreator (optional dependency) for money earned/spent tracking. Works without it
if HUDCreator is not installed.

---
Technical Info

- Minecraft: 1.21.1
- Mod Loader: NeoForge
- Side: Server-side (with client sync for GUI)
- Storage: Per-player JSON files, auto-save every 5 minutes
- Performance: Promotion check every 60 seconds, lightweight per-tick tracking

---
Installation

1. Install NeoForge 1.21.1
2. Place the .jar in the mods/ folder on both server and clients
3. Start the server — config files are generated automatically
4. Customize grades, rewards, and objectives to fit your server
5. /rank admin reload to apply changes