Sol's Title System

Supports Minecraft Forge 1.16.5, 1.20.1!

Author: solmochi

Need help, want to suggest a feature, or found a bug?

Join our community to catch exclusive early previews and upcoming changelogs before they go live!

---

Overview

Sol's Title System adds a rich title progression system to Minecraft. Players earn titles by completing in-game achievements — slaying mobs, surviving, or defeating powerful bosses. Each title displays above the player's head and in chat, and can grant unique stat buffs while equipped. Server owners and modpack creators have full control over every title through a clean JSON config system, with no coding knowledge required.

Note: Must be installed on both server and client for multiplayer. Fully playable in single-player as well.

---

Features

🏆 59+ Built-in Titles

Over 59 hand-crafted vanilla titles spanning 9 rarity tiers — from easy starter titles to brutal endgame achievements requiring tens of thousands of kills. Every title has a lore description, clear unlock conditions, and balanced stat buffs.

Rarity Tiers (lowest → highest):

Tier	Difficulty
Common	Easy, mostly cosmetic
Uncommon	Moderate, small buffs
Rare	Notable effort required
Epic	Significant grind
Legendary	Server-wide prestige
Mythical	Only for dedicated players
Supreme	Near-impossible
Apex (new)	Extreme
Ultimate (new)	Pinnacle

---

📊 Progression System

Players progress naturally through gameplay:

• Kill specific mobs or any hostile mob
• Survive consecutive minutes without dying (timer resets on death)
• Kill specific NPCs/bosses by UUID (CustomNPCs, Citizens, etc.)
• Kill modded mobs by registry name

Progress is tracked permanently. Kill counts never reset. Survival time resets only on death.

---

💬 Chat Integration

Chat is fully redesigned with title-aware formatting:

• Format: [head] TitleName | PlayerName > message
• Player head avatars (8×8 pixels) rendered beside every message
• Title name displayed in bold with full animated chroma coloring
• Player name, divider, separator, and message text all tinted to match the title's rarity
• Players without a title get a clean, minimal format

---

📋 Tablist Revamp

A complete visual overhaul of the player tab list:

• Player head avatars beside each entry
• Title badge for each player with a rarity-tinted background and colored border
• Rarity-colored player names, sorted by rarity tier
• Your own row is highlighted with a subtle green tint so you can easily spot yourself in large player lists
• Real-time clock with auto-detected timezone and world day counter
• Ping indicator with color coding (green / yellow / orange / red)
• Configurable header title and subtitle (supports & color codes)
• Toggle heads, title badges, and ping display individually
• Fully compatible with Sol's Party System (renders above the party HUD)

---

🏷️ Nameplate Rendering

Every player with a title gets a styled nameplate above their head:

[ TitleName ]
  PlayerName

• Frame bracket color derived from rarity tier
• Semi-transparent rarity-tinted background panel
• Player name colored by their title's rarity
• Hidden in first-person and when sneaking

---

🔔 Join/Leave Messages

Custom join and leave messages with full title integration:

• Format: [head] TitleName | PlayerName joined the game
• Player head avatars rendered on join/leave messages
• Join sound: Note Block Bell (pleasant chime)
• Leave sound: Enderman Teleport (subtle departure)
• Configurable message text, toggle sounds, toggle messages entirely
• Vanilla join/leave messages automatically suppressed to prevent duplicates

---

🖼️ Title Selection GUI

A polished in-game GUI (opened from the inventory screen) lets players:

• Browse all titles in sequential order with pagination
• See clicked title details — name with chroma, rarity indicator, description, and buffs — shown at the top of the screen
• View their unlock progress for locked titles with animated progress bars
• Locked titles (shown as "???") animate with their rarity's chroma color
• Currently equipped title shown at the bottom with a player head avatar
• Equip or unequip titles with one click

Locked title hints are configurable: show full progress info, partial info (hides target numbers), or nothing at all.

---

⚔️ Combat Lock

Players cannot swap titles mid-combat. A configurable cooldown (default 15 seconds after last damage) prevents abuse. Server operators can bypass this restriction if needed.

---

📣 Title Unlock Broadcast

When a player unlocks a title at or above the configured rarity threshold (default: Legendary), the entire server receives a broadcast announcement. Supports all 9 rarity tiers including Apex and Ultimate. Configurable and optional.

---

⚙️ Admin Commands

Command	Description
/solstitle reload	Reload configs in-game, no restart needed
/solstitle grant <player> <id>	Grant a specific title (including admin-only titles)
/solstitle grantall <player>	Grant ALL titles to a player
/solstitle revoke <player> <id>	Revoke a specific title
/solstitle revokeall <player>	Revoke ALL titles from a player
/solstitle check <player>	Inspect a player's progress and data
/solstitle debug	Toggle debug mode for inspecting title rendering
/solstitle list	List all loaded titles
/st	Shorthand alias

All commands require OP level 2.

---

🗂️ Dual Config System

Titles are stored in two separate JSON files:

• vanilla_titles.json — The 59+ built-in titles. Auto-migrated on mod updates.
• custom_titles.json — Your custom titles. Never touched by the mod. 100% safe across updates.

Custom titles support any modded mob, UUID-based NPCs, modded damage multipliers, and the !player target for PvE-only damage bonuses.

---

🔧 Server Config (TOML)

Fine-tune the mod via solstitlesystem-common.toml:

• Combat lock duration and admin bypass
• Survival tick tracking interval
• Show/hide title in nameplate and chat
• GUI titles per page
• Locked title progress visibility (NONE / PARTIAL / FULL)
• Title unlock broadcast and minimum rarity threshold (supports all 9 tiers)
• Tablist: toggle revamp, set header/subtitle, toggle heads/badges/ping, max players per column
• Join/Leave: toggle custom messages, custom message text, toggle notification sounds

---

🔄 Automatic Config Migration

Install a new version and let the mod upgrade itself. New titles are added to your config automatically. Your custom titles and all player progress are always preserved. No manual editing required.

---

📦 Compatibility

• Minecraft: 1.16.5 & 1.20.1
• Forge: Compatible with standard Forge installs
• Modded mobs: Works with any mod — target mobs by registry name or UUID
• Modpack-friendly: JSON-driven, fully configurable, no hardcoded dependencies
• Sol's Party System: Tablist renders correctly above the party HUD

---

🗒️ Notes

• Buffs are active only while a title is equipped — removing it removes all buffs immediately
• Kill counts are stored per-player in world data (NBT capability system)
• Survival timer is consecutive — dying resets it to zero
• The Admin title (Ultimate rarity) can only be assigned via /solstitle grant — it has no unlock conditions