Ranks

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