================================================================================
  Sol's Title System - Configuration Guide
  For Server Owners & Modpack Creators
================================================================================

Welcome! This guide explains how to set up and customize titles on your
server. No coding or programming experience needed.

Titles are unlockable achievements that give players a displayed name tag
and optional stat buffs. Players unlock titles by meeting conditions like
killing mobs or surviving for a certain time.

================================================================================
  QUICK START (5-minute setup)
================================================================================

  1. The mod works out of the box with 80 built-in titles.
  2. To add YOUR OWN titles, edit: custom_titles.json
  3. After editing, type /sol titlesystem reload in-game. No restart needed.
  4. That's it! See the sections below for details.

================================================================================
  WHERE ARE THE CONFIG FILES?
================================================================================

  All files are in this folder:
    config/solstitlesystem/

  You'll find these files:

    vanilla_titles.json   The 80 built-in titles (uses vanilla Minecraft mechanics).
    custom_titles.json    YOUR custom titles go here (modded mobs, NPCs, etc.).
    config_version.json   Tracks which config version is installed (auto-managed).
    instructions.txt      This file (auto-generated, safe to delete).

  +------------------------------------------------------------------------+
  |  RECOMMENDATION:                                                       |
  |  Always add your custom titles in custom_titles.json, NOT in the       |
  |  vanilla file. The vanilla_titles.json may be updated automatically    |
  |  when you install a new version of this mod. Your custom_titles.json   |
  |  is NEVER modified by the mod -- it's 100% yours.                      |
  |                                                                        |
  |  Avoid changing vanilla_titles.json unless you know what you're doing. |
  |  Future mod updates may rename, rebalance, or add new vanilla titles.  |
  |  Your changes will NOT be overwritten, but they won't receive the      |
  |  new improvements either.                                              |
  +------------------------------------------------------------------------+

================================================================================
  HOW THE FILE IS ORGANIZED
================================================================================

Both config files use the same format. Each file has a list of titles
inside a "titles" section.

  Here's what the file looks like:

  {
    "titles": [
      { ...title 1... },
      { ...title 2... }
    ]
  }

  Important: vanilla_titles.json also has a "config_version" number at the
  top -- don't change it. The mod uses it to track updates.

================================================================================
  TITLE FIELDS (what each setting does)
================================================================================

Each title has these settings:

  id            A unique number for this title. No two titles can share an ID.
                The built-in titles use IDs 1-80.
                Use IDs 100 and above for your custom titles.

  name          The title name players see in-game (e.g., "Dragon Slayer").
                Keep it short and cool-sounding!

  color         The title's text color. You can use:
                  Hex codes:       "#FF0000" (red), "#55FF55" (green), "#FFD700" (gold)
                  Minecraft names: "red", "gold", "yellow", "aqua", "white"
                NOTE: color is only used when rarity is NOT declared.
                If rarity exists, color is auto-removed on load/save.

  rarity        Preferred title tier field (replaces chroma in config files).
                The GUI can sort by ID or rarity; servers choose the join default.

                Valid rarity values:
                  common
                  uncommon
                  rare
                  epic
                  legendary
                  mythical
                  supreme
                  apex
                  ultimate

  description   A short text shown when the player selects this title.
                Tells them what they need to do or what the title represents.

  conditions    What the player must achieve to unlock this title.
                Can have one or more conditions -- ALL must be met.

  buffs         Stat bonuses the player gets while this title is equipped.
                Can be empty [] for cosmetic-only titles (just for show).
                Buffs are ONLY active while the title is equipped.

================================================================================
  CONDITIONS (how players unlock titles)
================================================================================

Each condition has three parts:
  - "type"     = what kind of achievement
  - "target"   = what object it tracks (mob/item/advancement, depends on type)
  - "required" = how many

  -----------------------------------------------------------------------
  TYPE: kill_any_hostile
  -----------------------------------------------------------------------
  Kill any hostile mob (zombies, skeletons, creepers, etc.)
  No "target" needed.

  Example -- Kill 500 hostile mobs (any type):
    { "type": "kill_any_hostile", "required": 500 }

  -----------------------------------------------------------------------
  TYPE: kill_mob
  -----------------------------------------------------------------------
  Kill a specific type of mob. "target" = the mob's registry name.

  Example -- Kill 100 zombies:
    { "type": "kill_mob", "target": "minecraft:zombie", "required": 100 }

  Example -- Kill 50 blazes:
    { "type": "kill_mob", "target": "minecraft:blaze", "required": 50 }

  Example -- Kill a modded mob (Twilight Forest naga):
    { "type": "kill_mob", "target": "twilightforest:naga", "required": 5 }

  -----------------------------------------------------------------------
  TYPE: kill_uuid
  -----------------------------------------------------------------------
  Kill a specific NPC by its unique UUID. Used for custom NPCs/bosses
  from mods like CustomNPCs, Citizens, etc.

  Example -- Kill an NPC boss 5 times:
    { "type": "kill_uuid", "target": "550e8400-e29b-41d4-a716-446655440000", "required": 5 }

  How to find a mob's UUID: Look at it with F3 enabled, or check the
  NPC mod's configuration files.

  -----------------------------------------------------------------------
  TYPE: survival_time
  -----------------------------------------------------------------------
  Stay alive for X consecutive minutes WITHOUT dying.
  The timer resets to 0 every time the player dies.
  No "target" needed.

  Example -- Stay alive for 60 minutes:
    { "type": "survival_time", "required": 60 }

  -----------------------------------------------------------------------
  TYPE: advancement
  -----------------------------------------------------------------------
  Unlock by completing a Minecraft advancement.
  "target" must be the full advancement ID, e.g. minecraft:story/mine_diamond
  Use "required": 1 for completion checks.

  Example -- Complete the Mine Diamond advancement:
    { "type": "advancement", "target": "minecraft:story/mine_diamond", "required": 1 }

  -----------------------------------------------------------------------
  TYPE: item_acquired
  -----------------------------------------------------------------------
  Unlock by obtaining items over time (loot, pickup, crafting results, etc.).
  "target" must be a full item registry ID.

  Example -- Obtain 64 ender pearls:
    { "type": "item_acquired", "target": "minecraft:ender_pearl", "required": 64 }

  -----------------------------------------------------------------------
  TYPE: item_crafted
  -----------------------------------------------------------------------
  Unlock by crafting specific items.
  "target" must be a full item registry ID.

  Example -- Craft 3 enchanting tables:
    { "type": "item_crafted", "target": "minecraft:enchanting_table", "required": 3 }

  -----------------------------------------------------------------------
  TYPE: damage_dealt
  -----------------------------------------------------------------------
  Unlock by total outgoing damage dealt.
  Damage uses Minecraft damage points (2 damage = 1 heart).
  No "target" needed.

  Example -- Deal 5000 total damage:
    { "type": "damage_dealt", "required": 5000 }

  -----------------------------------------------------------------------
  TYPE: damage_taken
  -----------------------------------------------------------------------
  Unlock by total incoming damage taken. Useful for tank/survivor titles.
  Damage uses Minecraft damage points (2 damage = 1 heart).
  No "target" needed.

  Example -- Absorb 4000 total damage:
    { "type": "damage_taken", "required": 4000 }

  -----------------------------------------------------------------------
  TYPE: highest_hit
  -----------------------------------------------------------------------
  Unlock by landing a single high-damage hit.
  Damage uses Minecraft damage points (2 damage = 1 heart).
  No "target" needed.

  Example -- Land a 40-damage hit:
    { "type": "highest_hit", "required": 40 }

  -----------------------------------------------------------------------
  MULTIPLE CONDITIONS (require more than one thing)
  -----------------------------------------------------------------------
  You can require multiple conditions. ALL of them must be completed.

    "conditions": [
      { "type": "advancement", "target": "minecraft:story/mine_diamond", "required": 1 },
      { "type": "item_crafted", "target": "minecraft:enchanting_table", "required": 2 },
      { "type": "damage_dealt", "required": 3000 }
    ]

  This means: complete the advancement AND craft 2 enchanting tables AND deal 3000 damage.

================================================================================
  BUFFS (stat bonuses while title is equipped)
================================================================================

Buffs are the stat bonuses players get while their title is active.
Swapping or removing a title instantly removes its buffs.

  -----------------------------------------------------------------------
  attack_damage     Adds flat attack damage.
  -----------------------------------------------------------------------
    1.0 = half a heart of extra damage.
    Example: { "type": "attack_damage", "value": 2.0 }

  -----------------------------------------------------------------------
  max_health        Adds extra maximum health.
  -----------------------------------------------------------------------
    2.0 = 1 extra heart.  10.0 = 5 extra hearts.
    Example: { "type": "max_health", "value": 4.0 }  (2 extra hearts)

  -----------------------------------------------------------------------
  armor             Adds armor points.
  -----------------------------------------------------------------------
    Full diamond armor = 20 armor for reference.
    Example: { "type": "armor", "value": 3.0 }

  -----------------------------------------------------------------------
  armor_toughness   Reduces damage from strong hits.
  -----------------------------------------------------------------------
    Full diamond armor = 8 toughness for reference.
    Example: { "type": "armor_toughness", "value": 2.0 }

  -----------------------------------------------------------------------
  speed             Increases movement speed.
  -----------------------------------------------------------------------
    This is a percentage multiplier. 0.03 = 3% faster.
    WARNING: Keep this small! 0.05 (5%) is already very fast.
    Example: { "type": "speed", "value": 0.03 }

  -----------------------------------------------------------------------
  luck              Improves loot tables and fishing.
  -----------------------------------------------------------------------
    Example: { "type": "luck", "value": 2.0 }

  -----------------------------------------------------------------------
  damage_multiplier   Multiplies damage dealt to mobs.
  -----------------------------------------------------------------------
    value = 1.3 means 30% more damage.  value = 2.0 means double damage.
    Optional "target" filters which mob is affected:

      No target  = applies to ALL mobs:
        { "type": "damage_multiplier", "value": 1.2 }

      All non-player entities (PvE only):
        { "type": "damage_multiplier", "value": 1.5, "target": "!player" }

      Specific mob:
        { "type": "damage_multiplier", "value": 1.3, "target": "minecraft:zombie" }

      All mobs from a mod (use the mod's ID without a colon):
        { "type": "damage_multiplier", "value": 1.2, "target": "twilightforest" }

      Specific NPC by UUID:
        { "type": "damage_multiplier", "value": 1.3, "target": "550e8400-e29b-..." }

  -----------------------------------------------------------------------
  COSMETIC TITLES (no buffs)
  -----------------------------------------------------------------------
  Want a title that's just for bragging rights? Leave buffs empty:
    "buffs": []

  -----------------------------------------------------------------------
  MULTIPLE BUFFS
  -----------------------------------------------------------------------
  Give a title several buffs at once:
    "buffs": [
      { "type": "attack_damage", "value": 3.0 },
      { "type": "max_health", "value": 4.0 },
      { "type": "armor", "value": 2.0 }
    ]

================================================================================
  STEP-BY-STEP: Creating Your First Custom Title
================================================================================

Let's create a title called "Lava Walker" that requires killing 50 blazes
and surviving 30 minutes, and gives +2 attack damage and +2 armor.

  1. Open custom_titles.json with any text editor (Notepad works fine).

  2. Inside the "titles": [ ... ] section, add this block:

     {
       "id": 200,
       "name": "Lava Walker",
       "rarity": "rare",
       "description": "Kill 50 blazes and survive 30 min. The Nether bows to you.",
       "conditions": [
         { "type": "kill_mob", "target": "minecraft:blaze", "required": 50 },
         { "type": "survival_time", "required": 30 }
       ],
       "buffs": [
         { "type": "attack_damage", "value": 2.0 },
         { "type": "armor", "value": 2.0 }
       ]
     }

  3. Make sure there's a comma between titles (after the } of the previous
     title, before the { of the next one).

  4. Save the file and type /sol titlesystem reload in-game. Done!

================================================================================
  COMMON VANILLA MOB NAMES (for kill_mob conditions)
================================================================================

  Overworld Hostiles:
    minecraft:zombie            minecraft:skeleton
    minecraft:creeper            minecraft:spider
    minecraft:witch              minecraft:phantom
    minecraft:pillager           minecraft:ravager
    minecraft:vindicator         minecraft:evoker
    minecraft:drowned            minecraft:husk
    minecraft:stray              minecraft:slime
    minecraft:cave_spider        minecraft:silverfish

  Nether Hostiles:
    minecraft:blaze              minecraft:wither_skeleton
    minecraft:ghast              minecraft:magma_cube
    minecraft:piglin_brute       minecraft:hoglin

  End:
    minecraft:enderman           minecraft:shulker

  Bosses:
    minecraft:ender_dragon       minecraft:wither
    minecraft:elder_guardian

  Popular Modded Mobs (examples):
    twilightforest:naga          twilightforest:lich
    twilightforest:hydra         twilightforest:ur_ghast
    iceandfire:fire_dragon       iceandfire:ice_dragon

  To find any mob's registry name: look at it with F3 debug screen enabled,
  or check the mod's wiki/documentation.

================================================================================
  ADMIN COMMANDS
================================================================================

  /sol titlesystem reload                    Reload configs (no restart needed)
  /sol titlesystem grant <player> <titleId>  Give a title to a player
  /sol titlesystem grantall <player>         Give ALL titles to a player
  /sol titlesystem revoke <player> <titleId> Take a title from a player
  /sol titlesystem revokeall <player>        Revoke ALL titles from a player
  /sol titlesystem list                      Show all loaded titles
  /sol titlesystem check <player>            Check a player's progress
  /sol titlesystem info                      Show mod version info
  /sol titlesystem debug                     Toggle damage debug messages
  All commands require OP (permission level 2).

================================================================================
  BALANCE GUIDELINES (recommended buff ranges)
================================================================================

  These are the ranges used by the built-in titles. You can use them as
  a reference when creating your own titles:

  Tier          Attack  Armor   Health    Speed   Other
  ----------    ------  ------  --------  ------  ------
  Common        +0-1    +0-1    none      +0.01   luck +1
  Uncommon      +1-2    +1-2    +0-2      +0.02   toughness +2
  Rare          +2      +1-2    +0-2      +0.03   luck +2
  Epic          +2.5-3  +2-3    +4-6      none    toughness +2
  Legendary     +3      +3-4    +4-8      +0.03-4 luck +3
  Mythical      +3-4    +3-4    +8-10     +0.04   toughness +3
  Supreme       +5-6    +5-6    +10-14    +0.05   all stats

  Speed guide:  0.01 = barely noticeable,  0.03 = good,  0.05 = very fast
  Health guide: 2.0 = 1 heart,  10.0 = 5 hearts,  20.0 = 10 hearts
  Damage mult:  1.2 = 20% more,  1.5 = 50% more,  2.0 = double

================================================================================
  IMPORTANT NOTES
================================================================================

  - Players can only have ONE title equipped at a time.
  - Buffs are ONLY active while the title is equipped.
  - Swapping or removing a title instantly removes its buffs.
  - Players cannot swap titles during combat (configurable timer).
  - Survival time resets to 0 when the player dies.
  - Kill counts are permanent and never reset.
  - IDs 1-99 are reserved for built-in titles. Use 100+ for your own.
  - Don't use the same ID for two different titles!
  - Combat timer is configurable in solstitlesystem-common.toml.
  - Server settings (combat lock, display, broadcasts) are in the .toml file.
  - OP players can bypass combat lock (configurable in .toml).
  - Title unlock broadcasts (to all players) can be enabled/disabled in .toml.

================================================================================
  WHAT HAPPENS WHEN THE MOD UPDATES?
================================================================================

  When you update this mod, your existing configs are SAFE. Here's what
  happens automatically:

    1. New built-in titles are added (if their IDs don't already exist).
    2. Untouched built-in title descriptions may be improved.
    3. Your custom titles in custom_titles.json are NEVER touched.
    4. The config_version number is updated.

  No backup files are created -- changes are applied in-place.
  You NEVER need to delete your config after updating.
  Your custom titles and edits are always preserved.

  Vanilla descriptions edited by a server owner are preserved. Only the
  previously shipped description text is refreshed automatically.

================================================================================
  Questions? Contact solmochi or check the mod's CurseForge page.
================================================================================
