damageoverhaul

================================================================
  Damage Overhaul Mod Usage Tutorial
  For Minecraft 1.20.1 Forge
================================================================

[Table of Contents]
  I. Mod Introduction
  II. Installation and Startup
  III. Explanation of the Eight Damage Types
  IV. Tooltip Explanation
  V. Command Overview
  VI. Config File Overview and Common Modification Examples
  VII. Enchantment System
  VIII. Projectile System and Entity Replacement
  IX. Gun Mod Compatibility (Scorched Guns / TACZ, etc.)
  X. Block-Source Damage Configuration
  XI. Charm System (Built-in Gems + Third-Party Charm Bonuses)
  XII. Equipment Scaling System (requires more_attributes attribute points)
  XIII. Potion Effect System (Resistance Up/Down + Damage Amplification/Weakening)
  XIV. Toughness and Impact Force System
  XV. Mana Repair (requires Botania)
  XVI. Display Toggles and Server Sync
  XVII. Automatic Migration and Backup Mechanism
  XVIII. Patchouli Manual Explanation
  XIX. Frequently Asked Questions (FAQ)

================================================================
I. Mod Introduction
================================================================

Damage Overhaul is a damage system overhaul mod. It splits the vanilla
single damage value into 8 damage types (slashing/blunt/piercing/magic/
fire/lightning/dark/holy), and allows you to freely control through JSON
config files:

  - The damage composition dealt by each weapon (e.g., iron sword = 60% slashing + 30% piercing + 10% blunt)
  - Each mob's resistance to different damage types
  - Each piece of armor's resistance to different damage types
  - The damage distribution of each projectile (arrow, trident, snowball, fireball, ...)
  - The environmental damage distribution caused by each block (magma block, campfire, cactus, ...)
  - Weapon damage distributions for gun-type mods (Scorched Guns, TACZ, etc.)
  - Charm system: 8 built-in damage gems, plus configuring damage bonuses
    and type resistances for any other mod's Curios charms (automatic scan,
    no need to manually enter item IDs)
  - Potion effect system: each damage type registers 4 potion effects
    (resistance up / resistance down / damage amplification / damage weakening),
    with per-level values configured through mob_effects_config.json
  - Equipment scaling system (soft dependency on more_attributes): based on
    the player's 9 invested base ability points, configure multipliers per
    weapon/armor by damage type. Weapons increase dealt damage, armor reduces
    received damage piece by piece multiplicatively. Tooltip shows SABCDE letter grades.
  - Enchantment level decoupling: enchantment caps are relaxed from vanilla
    level 4 to a configurable value (default 255). Ultra-high-level enchantments
    work normally according to linear formulas.

All configs can be hot-reloaded in-game with commands, no game restart needed.
(Note: adding new damage types / adding new built-in charm entries / adding new
potion effects requires a restart, because enchantments, items, and effects are
registered frozen at startup. Values for already registered entries hot-reload.)

================================================================
II. Installation and Startup
================================================================

1. Environment requirements: Minecraft 1.20.1 + Forge (47.x).
2. Prerequisite mod: Curios API (charm slots). The mod cannot load without Curios.
3. Put damageoverhaul-1.0.0.jar into the mods folder.
4. (Optional) Install Patchouli to get this mod's in-game illustrated manual.
   Without Patchouli, the mod still runs normally.
5. On first startup, all config files (with default values) are automatically
   generated under config/damageoverhaul/; at the same time, a Curios charm
   slot (charm) is automatically added to players.

[How to get the in-game manual]
- When Patchouli is installed, the "Tools & Utilities" creative tab contains
  "Damage Overhaul Guide" (purple book model). It can also be obtained by command:
    /give @s patchouli:guide_book{patchouli:book:"damageoverhaul:guide"}
- In survival mode, you can add an acquisition method through a datapack recipe.

================================================================
III. Explanation of the Eight Damage Types
================================================================

  Slashing  -- sword slashing/cleaving damage
  Blunt     -- hammer strikes, explosions, falling, crushing
  Piercing  -- arrows, spikes, cactus, berry bushes
  Magic     -- potions, enchantment damage, phantoms, etc.
  Fire      -- burning, lava, campfire
  Lightning -- lightning strikes
  Dark      -- wither, shadow-type damage
  Holy      -- light-type damage (reserved for expansion)

How are damage types determined?
Every vanilla damage instance carries a "damage source identifier" (damage type),
for example minecraft:arrow (arrow), minecraft:explosion (explosion).
The mod translates these identifiers into the 8 types through
damage_type_mappings.json, and supports "splitting one source into multiple
types as a mixed distribution", for example:

  "minecraft:explosion": { "blunt": 0.7, "fire": 0.3 }

means explosion damage is 70% settled as blunt and 30% as fire.

The mod also automatically scans all damage types registered in the game
(including those added by other mods), infers mappings by tags, and writes
them into the config. Those with the is_fire tag are inferred as fire, those
without tags default to blunt. Everything can be modified in the config.

================================================================
IV. Tooltip Explanation
================================================================

Hover the mouse over an item:

  Weapon   -> Shows "Damage Distribution": each line = damage type + value
              (base attack × ratio) + percentage, sorted descending by ratio
  Armor    -> Shows "Armor Resistance": non-zero resistances sorted descending,
              red = vulnerability, green = resistance
  Projectile -> Shows "Projectile Damage Distribution": percentage only
              (damage is determined by the bow)
  Enchantment -> Enchanted item titles append "(Enchanted)", and each line ends
              with green text listing the values/percentages added by enchantments
  Gun      -> Guns have no attack damage attribute; tooltip automatically parses
              the damage number labeled by the gun mod itself as the base
              (e.g., "Damage: 10.0"). If parsing fails, only percentages are shown.
  Mana Repair -> Shows enabled status and mana cost per durability point
  Built-in Charm -> Shows associated damage type, attack bonus, and damage resistance
  Third-Party Charm -> Other-mod charms with configured non-0 factors show
              "External Charm Bonus": red = damage amplification, green = type
              resistance. Types with 0 effect are not displayed.
  Equipment Scaling -> After installing more_attributes, weapons/armor show an
              "Ability Scaling" section: each line = damage type + letter grade
              (SABCDE) + percentage,
              e.g. Fire S (+150%) (weapon damage bonus, red) /
                   Fire S (-150%) (armor damage mitigation, green),
              calculated in real time based on the current viewing player's
              attribute points, only showing positive scaling.

Displayed content can be controlled by the 8 toggles in display_config.json
(see Section XVI).

================================================================
V. Command Overview
================================================================

All commands require OP level 2.

  /damageoverhaul reload
      Reload all config files, and automatically fill in missing
      resistance/weapon/mapping entries for new damage types.

  /damageoverhaul migrate
      Force a migration check (equivalent to reload, semantically emphasizes migration).

  /damageoverhaul migrations
      Show the detailed migration log from the most recent load: which files
      were changed, which entries were added, and backup locations.

  /damageoverhaul status
      Show the mod's current status: damage type count, three enchantment
      counts (and level cap), potion effect status (type rows), deflection
      mechanics, default ranged source, projectile config stats, dual-use list,
      mana repair, block distribution entry count, built-in charm count and
      third-party charm bonus status (indexed entry count, startup scan toggle),
      equipment scaling status (weapon/armor indexed counts, ability column
      count, more_attributes loaded status).

================================================================
VI. Config File Overview and Common Modification Examples
================================================================

All configs are located in config/damageoverhaul/:

  damage_types.json              Damage type definitions (core; other files auto-sync)
  damage_type_mappings.json      Damage source -> type mappings (supports mixed distributions)
  weapon_distributions/          Weapon distributions + gun auto-learning (folder, split by mod)
  unarmed_distributions.json     Unarmed/mob bare-hand distributions
  entity_resistances/            Entity resistances + mob base toughness/impact resistance (folder, split by mod)
  armor_resistances.json         Armor resistances
  ranged_config/                 Ranged sources and projectile distributions (folder, split by mod)
  projectile_item_mappings.json  Projectile mappings and entity replacement
  block_distributions.json       Block-source damage
  special_mechanics.json         Special mechanics such as damage deflection
  mana_repair_config.json        Mana repair
  display_config.json            Tooltip display toggles
  projectile_strike_config.json  Projectile enchantment bonuses
  charms.json                    Built-in charms (8 damage gems, including toughness)
  external_charms.json           Third-party charm factor table (auto-scan generated, including toughness)
  mob_effects_config.json        Potion effect value table (4 effects per type)
  weapon_scaling/                Weapon scaling multiplier tables (folder, requires more_attributes)
  armor_scaling/                 Armor scaling multiplier tables (folder, requires more_attributes)
  weapon_guard_break.json        Weapon guard break values + associated impact effects
  armor_toughness.json           Armor toughness table
  player_config.json             Player base toughness + impact resistance (immunity/remap)
  impact_effects.json            Impact effect presets (displacement/stun)

Note: Paths ending with "/" are folder structures, internally split into
multiple small JSON files by mod name (namespace), avoiding oversized single
files in large modpacks. On first load, old single files are automatically
migrated to folders and backed up.

[Example 1: Modify the iron sword distribution]
Open minecraft.json in the weapon_distributions/ folder, find "minecraft:iron_sword":
  "damage_distribution": {
    "slashing": 0.6, "piercing": 0.3, "blunt": 0.1, ... all others 0
  }
Save after editing, then run /damageoverhaul reload in-game.

[Example 2: Make skeletons immune to fire]
Open minecraft.json in the entity_resistances/ folder, find "minecraft:skeleton",
and change "fire" to -1.0 (-100% immunity).

[Example 3: Change explosion to 70% blunt + 30% fire]
Open damage_type_mappings.json:
  "minecraft:explosion": { "blunt": 0.7, "fire": 0.3 }

[Example 4: Adjust a certain gun's distribution]
First shoot once with that gun (auto-learning will generate an entry), then
modify the corresponding entry and reload.

[Example 5: Add fire damage bonus to another mod's charm]
After starting the world, external_charms.json has already automatically indexed
all Curios charms. Find the corresponding item row, and change "fire" in
attack_bonuses to 0.15 (see Section XI for details).

[Example 6: Make an iron sword gain fire scaling from strength]
Open the corresponding mod's json in the weapon_scaling/ folder, find
"minecraft:iron_sword", and in the "fire" row change "strength" to 0.02
(see Section XII for details):
When strength is invested to level 30 (effective 20 points), fire scaling =
0.02×20 = +40%.

Standard process: edit -> save -> /damageoverhaul reload -> done.
Missing fields/entries in all files are automatically filled and written back;
manual adjustments will not be overwritten.

================================================================
VII. Enchantment System
================================================================

At startup, the mod automatically registers three enchantment sets per damage
type (8 types × 3 categories = 24):

  protect_<type>   Armor resistance enchantment, 5%/level
                   (settled after armor resistance and before armor value)
  strike_<type>    Weapon damage bonus enchantment, 10%/level
                   (only increases the corresponding type's share, does not
                   squeeze out other types)
  projectile_strike_<type>  Projectile damage bonus enchantment
                   (only applicable to pure projectile items, such as arrows;
                   values same as strike)

[Level Cap Decoupling]
The level caps of the three enchantment sets are controlled by the
max_enchant_level field in damage_types.json, default 255 (vanilla is 4).
The value formula remains linear:
  Level N = N × per-level value (e.g., protect 5%/level × level 10 = 50% resistance)
After modifying max_enchant_level, a game restart is required. The enchanting
table still produces at most level 4 (limited by vanilla enchantment logic),
but any level granted by anvil stacking/commands works normally according to
the formula.

Acquisition method: protect/strike can be used in enchanting tables and anvils.
Vanilla arrows cannot be normally enchanted. The mod takes over the anvil merge
process to implement projectile enchantment:
  Put a weapon on the left (with the corresponding strike enchanted book),
  put arrows on the right -> merge to get enchanted arrows.

Note: Enchantment registration is frozen at game startup. After adding a new
damage type, the game must be restarted to generate the corresponding
enchantment; value configs for existing enchantments can hot-reload.

================================================================
VIII. Projectile System and Entity Replacement
================================================================

[Projectile Distribution] ranged_config/
  - ranged_damage_source: global ranged determination method
      "projectile" = by projectile distribution (default)
      "weapon"     = by weapon distribution
  - Each projectile entry has a follow_default field:
      true  = follow global default
      false = use that entry's own distribution
  - Dual-use items (such as tridents, which are both weapons and projectiles)
    refuse to follow the default by default.

[Projectile Item and Entity Mapping]
The same entity can correspond to multiple items (enchanted arrow/spectral
arrow/normal arrow are all minecraft:arrow). The mod uses a three-layer mechanism:
  1) Same-name matching: entity ID is the same as item ID
  2) Tag scan: members of minecraft:arrows / forge:arrows tags are
     automatically mapped to minecraft:arrow
  3) Manual extension: add custom mappings in projectile_item_mappings.json

[Entity Replacement] projectile_item_mappings.json
  Want arrows to shoot TNT? In the mapping write:
    "minecraft:arrow": {
      "entity": "minecraft:tnt",
      "replace_entity": true
    }
  And set the global toggle allow_dangerous_replace to true.

  Explanation:
  - Replacement occurs at the moment the projectile is created; the original
    entity is cancelled, and the new entity inherits position/velocity/rotation/owner
  - The replaced entity's damage is settled according to the distribution of the
    entity mapped from the original projectile item. If not configured, it falls
    back to damage type mapping (TNT explosion -> blunt)
  - Risk warning: mapping to large entities such as the Ender Dragon may cause
    abnormal behavior

================================================================
IX. Gun Mod Compatibility (Scorched Guns / TACZ, etc.)
================================================================

Characteristics of gun-type mods: damage values are stored in the gun JSON,
settled by projectile entities, and are completely different from the vanilla
weapon system (guns have no attack damage attribute, projectile entity IDs are
not the same as gun item IDs, and ammunition does not carry damage).

This mod's general compatibility solution (does not hardcode any mod):
  1. Source weapon fallback: after a gun projectile hits, if no projectile
     distribution is found, automatically check the distribution of the gun in
     the shooter's hand in weapon_distributions/ and split damage according to it
  2. Auto-learning: when auto_learn_ranged_weapons = true (default), the first
     time a gun deals damage it automatically generates an entry (default
     piercing 100%) and writes it to the config
  3. Tooltip base: automatically parses the damage number labeled by the gun mod
     as the display base

Usage steps (using Scorched Guns as an example):
  1. Enter the game, take any gun and shoot once
  2. Open weapon_distributions/, and you can see the scguns:xxx entry
  3. Modify its damage_distribution (e.g., change a flamethrower's fire ratio)
  4. /damageoverhaul reload to apply

Ammunition does not need configuration -- damage is determined entirely by the gun.
TACZ and other "gun JSON + projectile" type mods are equally applicable.

================================================================
X. Block-Source Damage Configuration
================================================================

block_distributions.json configures environmental damage by block ID
(magma block, campfire, cactus, powder snow, wither rose, etc.).

Format:
  "minecraft:magma_block": {
    "use_default": true,                  <- true=use default mapping chain
    "damage_distribution": { ... }        <- this distribution applies when false
  }

Determination condition: the damage source has no entity (such as hot_floor
damage from standing on a magma block). The mod checks the block your body is
in (campfire/fire/cactus, etc.) and the block under your feet (magma block).

Auto-learning: when auto_learn_block_damage = true (default), the first time
an entity takes damage from a block, that block is automatically registered in
the config (use_default=true, behavior unchanged). Afterward, change
use_default to false and fill in the distribution to take over that block.

Campfires and magma blocks can use completely different distributions -- this
is fine-grained control that damage_type_mappings cannot achieve.

================================================================
XI. Charm System (Built-in Gems + Third-Party Charm Bonuses)
================================================================

The charm feature depends on Curios API. Players have a charm Curios slot
(automatically added by the mod, coexisting with rings/necklaces from other
mods in modpacks without conflict).

[11.1 Built-in Charms: 8 Damage Gems]

The mod includes 8 charms (found in the creative inventory):
  Slashing Gem / Blunt Gem / Piercing Gem / Magic Gem / Flame Gem /
  Thunder Gem / Shadow Gem / Holy Gem
Default: +15% attack damage of the corresponding type, -10% damage taken of
the corresponding type.

Stacking rule: multiple charms of the same type (including third-party charms)
only take the highest value, no stacking.
Settlement position:
  - Attack: that type's damage ×(1+bonus)
  - Defense: after mob resistance, armor resistance, and enchantment resistance,
    independently reduce by type ×(1-resistance) (only for configured types;
    each part of mixed damage is reduced separately)

charms.json can adjust each gem's values and texture frame animation; note that
adding/removing built-in charm entries is an item registration change and
requires a game restart. Values for already registered entries hot-reload.

[11.2 Third-Party Charm Bonuses: external_charms.json (Important)]

No need to manually look up item IDs, no need to hand-write entries in a format
-- the mod automatically traverses:

  1) Startup/reload full scan: all other-mod charms in the item registry that
     have the curios tag and can fit into Curios slots are automatically indexed
     into the table
  2) Equip-time supplementary scan: when a player actually equips a charm into
     a slot (checked at login and every 10 seconds afterward), if a missed item
     is found (such as mods whose tags are dynamically generated by in-memory
     datapacks), it is automatically added to the table

Each charm has one row in the table, listing factors for all damage types, for example:

  {
    "item_id": "botania:sojourner_sash",
    "attack_bonuses": {
      "slashing": 0, "blunt": 0, "piercing": 0, "magic": 0,
      "fire": 0.15, "lightning": 0, "dark": 0, "holy": 0
    },
    "defense_resistances": {
      ...same as above, "fire": 0.1 means fire damage reduced by 10%...
    }
  }

Value meanings:
  attack_bonuses       Damage amplification, 0.15 = that type's damage +15%
  defense_resistances  Type resistance, 0.10 = that type's damage -10%
  0 = no effect (produces no effect, and tooltip does not show that line)

Usage process:
  1. Start a world once (table is automatically generated)
  2. Open config/damageoverhaul/external_charms.json
  3. Find the target charm's row, change the corresponding type's 0 to the desired factor
  4. /damageoverhaul reload (servers require reconnect to sync client display)

Two master switches (at the top of the file):
  enable_external_charms   Master switch, false = third-party charm feature fully stopped
  auto_scan_curios_items   Startup scan switch, false = only keep existing entries,
                           no longer automatically index new charms (equip
                           supplementary scan also stops)

Features and rules:
  - When adding a damage type, automatically add a 0 column for that type to
    all charms in the table
  - All-zero entries do not participate in network sync, so any number of
    modpack charms will not affect login speed
  - For the same damage type: when built-in gems and third-party charms are
    worn together, merge and take the highest
  - Old hand-filled entries automatically migrate and retain values; old files
    are automatically backed up
  - Must be truly equipped in a Curios slot to take effect (placing in backpack
    has no effect)

================================================================
XII. Equipment Scaling System (requires more_attributes attribute points)
================================================================

[Soft Dependency]
After installing more_attributes (org.mantodea.more_attributes), this system
automatically enables; when not installed, equipment scaling does not take
effect, and all other mod features work as usual.
That mod provides 9 allocatable base abilities:
  strength / health / focus / stamina / endurance / intelligence / agility /
  skill / luck

[How Scaling Is Calculated]
Each piece of equipment has multipliers filled per "damage type × base ability":
  Scaling = Σ(multiplier × effective attribute points)
  Effective attribute points = invested level − that ability's baseLevel
(strength baseLevel=10, others are 0; negative values are allowed, fully
consistent with more_attributes' own scaling semantics)

[Two Config Files]
  weapon_scaling/   Weapon scaling table
  armor_scaling/    Armor scaling table
On first entering the world, a full registry scan automatically generates:
  - Weapons: swords/axes/bows/crossbows/tridents, any item with an attack
    damage attribute, guns already in weapon_distributions/
  - Armor: all ArmorItem
Each piece of equipment has one row, default all 0 (pure indexing: no effect,
no display, no sync traffic).

File structure (weapon table as example):
  {
    "enable_weapon_scaling": true,
    "base_attributes": ["strength","health",...9 total],
    "grade_thresholds": {"S":1.5,"A":1.0,"B":0.75,
                         "C":0.5,"D":0.25,"E":0.0},
    "items": {
      "minecraft:iron_sword": {
        "fire":      { "strength": 0.02, "other abilities": 0 },
        "slashing":  { "strength": 0.01, ... }
      }
    }
  }
The armor table has the same structure; the switch name is enable_armor_scaling.

Multiplier meaning: 0.02 = each effective attribute point brings 2% scaling.
Example: strength invested to level 30 -> effective 20 points -> a certain type
multiplier 0.02
      -> that type's scaling = 0.02 × 20 = +40%.
Filling 0 = that ability has no scaling for that damage type.

[Weapon Settlement] Only takes effect for players (mobs have no attribute
points), independent by damage type, additively merged into the existing attack
multiplier:
  Type damage × (1 + charm bonus + potion bonus + weapon scaling)
The attacking weapon uses the player's held item (if the main hand has a scaling
entry, use main hand; otherwise check offhand).

[Armor Settlement] Only takes effect for players, head/chest/legs/feet 4 pieces
multiply sequentially, independent by type, located "after enchantment + potion
resistance, before charm type resistance":
  Damage × (1−helmet scaling) × (1−chestplate scaling) × (1−leggings scaling) × (1−boots scaling)
Note this is multiplicative, not additive: 4 pieces each 10% fire scaling ->
  0.9×0.9×0.9×0.9 ≈ 0.656, i.e. fire damage taken is about -34% (not -40%).

[Letter Grade Display]
The tooltip's "Ability Scaling (Damage Bonus/Mitigation)" section is calculated
in real time based on the current viewing player's attribute points. Each line =
type + letter grade + percentage, sorted descending by scaling:
  Weapon: Fire S (+150%) (red percentage)
  Armor: Fire S (-150%) (green percentage, indicating reduced damage taken of
         that type)
Types with scaling ≤ 0 are not displayed (but negative scaling still
participates in actual settlement).
Letter thresholds can be customized in each file's grade_thresholds, default:
  S≥150%  A≥100%  B≥75%  C≥50%  D≥25%  E≥0%

[Display Toggle] display_config.json:
  show_equipment_scaling   Equipment scaling section master toggle (default true)

[Automatic Maintenance]
  - New damage type -> all equipment automatically gets that type row added
  - more_attributes new ability (datapack extension) -> automatically add ability column
  - Install a mod with new weapons/armor -> startup scan automatically indexes all-0 rows
  - Old files automatically migrate and back up to backups/, hand-filled values
    are not lost
  - All-0 rows do not participate in network sync

================================================================
XIII. Potion Effect System (Resistance Up/Down + Damage Amplification/Weakening)
================================================================

At startup, the mod automatically registers potion effects per damage type
(8 types × 4 effects = 32):

  resist_<type>        Resistance up (beneficial): when hit, that type's
                       resistance +X%/level
                       Additively merged into the enchantment resistance pool
                       (same settlement stage as protect enchantment)
  vulnerable_<type>    Resistance down (harmful): when hit, that type's
                       resistance -X%/level
  amplify_<type>       Damage amplification (beneficial): when attacking, that
                       type's damage +X/level
                       Additively merged into the charm damage bonus multiplier
  weaken_<type>        Damage weakening (harmful): when attacking, that type's
                       damage -X/level

Effect name examples: resist_fire (fire resistance up), amplify_slashing
(slashing damage amplification), vulnerable_dark (dark resistance down), etc.

[Value Config] mob_effects_config.json:

  enable_mob_effects    Master switch (default true)
  defaults              Default per-level values (used when adding rows for new
                        damage types):
                          resist_up_per_level    5.0  (+5% resistance per level)
                          resist_down_per_level  5.0  (-5% resistance per level)
                          damage_up_per_level    0.10 (+10% damage per level)
                          damage_down_per_level  0.10 (-10% damage per level)
  per_type              Per-type overrides (can set values individually for each
                        damage type)

When adding a damage type, effect value rows are automatically filled according
to defaults; when deleting a damage type, corresponding rows are automatically
removed. Effect registration requires a game restart; values hot-reload.

[How to Grant Effects]
Effects are granted by command (there is no brewable potion form):
  /effect give @s damageoverhaul:resist_fire 60 1
  (effect ID, 60 seconds, level 1 -> +5% fire resistance)
  /effect give @s damageoverhaul:amplify_slashing 60 2
  (60 seconds, level 2 -> +20% slashing damage)

Other mods/datapacks can also grant these effects through /effect or effect pools.
Effects also work on mobs (e.g., give a mob vulnerable_fire to lower its fire
resistance).

[Settlement Position]
Complete settlement chain (potion effects in bold):
  Adjusted damage = original damage ×(1+charm bonus+potion bonus+weapon scaling)
              ×(1-mob resistance)×(1-armor resistance)
              ×(1-enchantment resistance-potion resistance)
              ×armor scaling 4 pieces ∏(1−single piece scaling)
              ×(1-charm type resistance)

Potion resistance and enchantment resistance share the same additive pool
(percentages are added and then reduced together). Potion damage bonus and charm
damage bonus share the same multiplier (ratios are added and then multiplied
together).

[Effect Icons]
Effect icons are located at assets/damageoverhaul/textures/mob_effect/,
named resist_fire.png, amplify_slashing.png, etc. You can replace them with
hand-drawn textures (recommended 18×18 pixels).

================================================================
XIV. Toughness and Impact Force System
================================================================

The mod implements a dynamic toughness system. A weapon's guard break value
deducts the target's toughness. When toughness reaches zero, an impact effect
is triggered.

[Core Concepts]
  guard_break     Weapon attribute; each attack deducts target toughness
  toughness       Dynamic value resisting guard break; broken when it reaches zero
  impact_effect   Effect associated with the weapon (displacement/stun),
                  triggered when toughness is broken

[Toughness Formula]
  maxToughness = base toughness + Σ armor toughness + Σ charm toughness
    Player base: player_config.json's base_toughness
    Mob base: entity_resistances/ corresponding entity's base_toughness
  When hit: currentToughness -= weapon guard_break
  Trigger condition: currentToughness <= 0 -> toughness broken -> trigger impact effect

[Toughness Recovery]
  Player: linear recovery per tick (maxToughness - currentToughness) / 40
          (about 2 seconds to full), no delay, no need to stop taking damage.
  Mob: after stopping taking damage for 1 second, recovers at the same speed.
  After toughness is broken and affected by an impact effect, reset to max
  (not reset when immune/not triggered).
  When equipment changes cause maxToughness to change, currentToughness scales
  proportionally.

[Impact Resistance] (only player base + mob base, does not affect guard_break)
  1. Immunity: impact effect IDs listed in immune_impact_effects are completely ignored
  2. Remap: in impact_effect_remap, {"D": "C"} means impact D is treated as impact C

[Config Files]
  weapon_guard_break.json    Weapon guard break values + associated impact effect IDs
  unarmed_distributions.json Mob/player unarmed guard break values + associated impact effect IDs
  armor_toughness.json       Armor toughness (4 pieces stack)
  player_config.json         Player base toughness + immunity list + remap
  impact_effects.json        Impact effect presets (direction/distance/stun duration/AI pause)
  charms.json / external_charms.json  Charm toughness field

[Impact Effect Presets] impact_effects.json
  Each effect contains:
    up_down           Up/down direction: + up, - down, 0 none
    left_right        Left/right direction: + right, - left, 0 none
    forward_backward  Forward/backward direction: + forward, - backward, 0 none
                      (all three axes are relative to the victim's facing; can
                      be combined arbitrarily, e.g., diagonal knockback)
    distance          Displacement distance (blocks)
    duration_tick     Stun duration (ticks). Mob=completely disables AI
                      (no movement, no targeting, no attacking);
                      Player=completely disables all input (movement/attack/
                      jump/use item/interact/hotkeys).
                      Implemented via NBT marker + network packet sync, not a
                      potion effect.
    ai_pause_tick     Mob AI extra pause ticks (optional, reserved field)

  [Interrupt Behavior During Stun] When stun is active, besides pausing AI, it
  also cancels the target's ongoing behavior and returns it to base state
  (continuously cancels every tick during the stun to prevent re-triggering):
    - Bow drawing/crossbow charging/drinking potion/using item, etc.: immediately
      stopUsingItem
      (also applies to players: the server directly interrupts channeling;
      channeling is wasted, and releasing will not shoot)
    - Targeting and pathfinding: clear current target, stop pathfinding
    - Creeper explosion charge: swell reset to zero, charge direction reset,
      clear ignited (otherwise the charge restarts)
    - Warden sonic boom: abort ongoing sonic boom behavior and return to base
      state (enter cooldown).
      Note: does not clear the Warden's targeting/anger memory; after the stun
      ends it will continue chasing the original target.
    - Better Combat swing: interrupt ongoing swing and prevent attack settlement
      when channeling ends;
      during stun also release attack/use keys to avoid holding left click being
      continuously re-triggered.
      When Better Combat is not installed, this logic automatically skips, does
      not affect vanilla behavior, and adds no dependency.

[Example: Add guard break and knockback effect to an iron sword]
1. Open impact_effects.json, confirm or add an effect:
     "light_knockback": {
       "up_down": 0.0, "left_right": 0.0, "forward_backward": -1.0,
       "distance": 2.0, "duration_tick": 20, "ai_pause_tick": 10
     }
2. Open weapon_guard_break.json, find "minecraft:iron_sword":
     "guard_break": 15.0,
     "impact_effect": "light_knockback"
3. After reload, each iron sword attack deducts 15 toughness from the target.
   When toughness reaches zero, the target is knocked backward 2 blocks and
   stunned for 20 ticks.

[Example: Diagonal launch (forward and upward)]
     "launch_forward_up": {
       "up_down": 1.0, "left_right": 0.0, "forward_backward": 1.0,
       "distance": 3.0, "duration_tick": 30, "ai_pause_tick": 15
     }

[Example: Add guard break and knockback to unarmed attacks]
Open unarmed_distributions.json, find the corresponding mob (e.g., "minecraft:zombie"):
  "guard_break": 8.0,
  "impact_effect": "light_knockback"
After reload, that mob's unarmed attack deducts 8 toughness per hit. When
toughness reaches zero, it triggers knockback.
The same applies to player unarmed attacks; the corresponding entry is
"minecraft:player".

[Example: Make the player immune to a certain impact effect]
Open player_config.json:
  "immune_impact_effects": ["heavy_knockback"]
This effect is completely invalid for the player (guard break still deducts
toughness, but the effect is not triggered).

[Example: Remap impact A to impact B]
Open player_config.json (or the corresponding mob in entity_resistances):
  "impact_effect_remap": { "light_knockback": "launch_up" }
When receiving light_knockback, launch_up is actually triggered (upward launch).

================================================================
XV. Mana Repair (requires Botania)
================================================================

When Botania is installed, mana_repair_config.json allows durability items to
consume mana to automatically repair:

  - Each item entry must be enabled individually
  - Can configure "mana consumed per durability point" (ratio freely adjustable)
  - When Botania is not installed, this feature is automatically disabled and
    the mod runs normally

Tooltip displays enabled status and mana consumption ratio.

================================================================
XVI. Display Toggles and Server Sync
================================================================

display_config.json controls eight types of tooltip display:

  show_weapon_distribution      Weapon damage distribution
  show_armor_resistance         Armor resistance
  show_projectile_distribution  Projectile damage distribution
  show_mana_repair              Mana repair status
  show_external_charm_bonus     Third-party charm bonus
  show_equipment_scaling        Equipment ability scaling (requires more_attributes)
  show_weapon_guard_break       Weapon guard break value and impact effect
  show_armor_toughness          Armor toughness

Server-side priority: in multiplayer, the server's display config prevails and
is automatically synced to the client on login, ensuring consistent display
across the server. Singleplayer directly uses the local config.

================================================================
XVII. Automatic Migration and Backup Mechanism
================================================================

Each time configs are loaded (startup/reload/migrate):

  1. Validate each file's _schema_version; old formats are automatically
     migrated to the new format
  2. Missing damage types/entries are automatically filled and written back
     to the file
  3. Before modification, the original file is automatically backed up to:
       config/damageoverhaul/backups/<timestamp>/
  4. All automatic changes are recorded in the migration log (view with
     /damageoverhaul migrations)

Manual adjustments will never be overwritten.

================================================================
XVIII. Patchouli Manual Explanation
================================================================

The mod includes a complete Patchouli manual, "Damage Overhaul Guide" (the
in-game version of this tutorial), with contents and table of contents:

  - Mod Introduction: Welcome / Eight Damage Types / Quick Start
  - System Details: Weapon Distribution / Resistances / Enchantments /
    Projectiles / Entity Replacement / Gun Compatibility / Block Damage /
    Charm System / Equipment Scaling / Potion Effects / Mana Repair /
    Special Mechanics and Display
  - Config Files: Overview / Modification and Reload Process
  - Commands: Detailed Explanation of the Four Commands
  - FAQ

The manual supports Chinese and English (automatically follows game language).
Manual entries can hot-reload: in-game, Shift+click the pencil icon at the
bottom left of the manual to refresh the content.

================================================================
XIX. Frequently Asked Questions (FAQ)
================================================================

Q1: The client cannot see the server's distribution config?
A: No manual sync is needed -- the server automatically pushes all configs when
   the player logs in. If you just changed server configs, reconnect.

Q2: After adding a damage type, the enchantment does not appear?
A: Enchantments and potion effects are registered frozen at startup. Restart
   the game to generate new enchantments and new potion effects. Value configs
   for already registered entries can hot-reload.

Q3: Config changes do not take effect?
A: Run /damageoverhaul reload. If the JSON format is incorrect, check the error
   messages in the startup log.

Q4: Want to customize the distribution of a gun mod's gun?
A: First shoot once with that gun (auto-learning will register an entry), then
   edit the corresponding entry in weapon_distributions/ and reload.

Q5: If I change arrows to shoot TNT, how is damage calculated?
A: See Sections IX/X. TNT explosions default to the blunt mapping, and can be
   refined in the mapping table or block/projectile config.

Q6: Want to hide certain tooltips?
A: display_config.json has eight toggles; server-side prevails.

Q7: Can vanilla arrows be enchanted?
A: Yes. Through an anvil: left weapon + strike enchanted book, right arrows,
   merge to get enchanted arrows. projectile_strike enchantment only applies to
   pure projectile items.

Q8: Will configs be lost after upgrading the mod version?
A: No. Automatic migration preserves your manual adjustments, and old files are
   backed up to the backups directory first.

Q9: How do I add damage bonus or resistance to other mods' rings/charms?
A: No need to hand-write config. After starting the world, the mod has already
   automatically indexed all Curios charms into external_charms.json. Find the
   corresponding item row, change the desired damage type factor from 0 to a
   value (e.g., 0.15), and reload. See Section XI for details.

Q10: Third-party charm values were changed but there is no effect/display?
A: Check in order: ① whether the charm is truly equipped in a Curios slot
   (placing in backpack has no effect); ② whether the factor is non-zero
   (0 has no effect and is not displayed); ③ whether reload was executed
   (multiplayer servers also require reconnect to sync display);
   ④ whether enable_external_charms is true.

Q11: The modpack has too many charms and external_charms.json is too long?
A: File length does not affect performance (all-0 rows are not synced and do
   not participate in settlement). If you do not want to automatically index
   new charms, set auto_scan_curios_items to false; you can also directly
   delete unneeded rows (they will be re-indexed on the next scan).

Q12: How do I temporarily add/subtract damage/resistance for players or mobs?
A: Use the /effect command. Each damage type has 4 effects:
   resist_<type> (resistance up), vulnerable_<type> (resistance down),
   amplify_<type> (damage amplification), weaken_<type> (damage weakening).
   For example, /effect give @s damageoverhaul:amplify_fire 60 2 gives
   60 seconds of +20% fire damage. Effects also work on mobs. See Section XIII.

Q13: Can the enchantment level cap exceed level 4?
A: Yes. The max_enchant_level field in damage_types.json controls the whole
   series' enchantment level cap, default 255. Any level granted by anvil
   stacking and commands works normally according to the linear formula
   (e.g., level 10 protect = 50% resistance). The enchanting table still
   produces at most level 4 (vanilla limit). Modifying the cap requires a restart.

Q14: How do I configure equipment scaling? How are attribute points calculated?
A: You need more_attributes installed. After first entering the world,
   weapon_scaling/ and armor_scaling/ automatically index all weapons/armor
   (all-0 rows).
   Scaling = Σ(multiplier × effective attribute points), effective attribute
   points = invested level − baseLevel (strength baseLevel=10, others 0, can be
   negative). A 0.02 multiplier = +2% per point.
   Weapon scaling is additively merged into the attack multiplier; armor's 4
   pieces multiply sequentially for mitigation. See Section XII.

Q15: I installed more_attributes but the tooltip has no "Ability Scaling" section?
A: Check in order: ① whether that equipment's multipliers are all 0 (all 0 is
   not displayed; first fill in a non-0 multiplier in the json and reload);
   ② whether the player has allocated points in more_attributes (when effective
   attribute points are all 0, it is not displayed); ③ whether
   show_equipment_scaling and enable_weapon_scaling / enable_armor_scaling are
   true; ④ multiplayer servers require reconnect to sync the scaling table.

Q16: What is the difference between guard break and impact force?
A: guard_break is a weapon attribute used to deduct target toughness;
   impact_effect is the effect triggered when toughness is broken
   (displacement/stun). A weapon can have only guard break (only deducts
   toughness and triggers no effect), or both. Impact resistance
   (immunity/remap) only affects impact effects, not guard break deduction.

Q17: Why did I set guard_break for a weapon but there is no impact effect?
A: Check whether the impact_effect field for that weapon in
   weapon_guard_break.json is filled with a valid effect ID (it must be defined
   in impact_effects.json). If impact_effect is empty, after toughness is broken
   it only deducts toughness and triggers no effect.

Q18: How do I make a certain mob completely immune to impact force?
A: In entity_resistances/, find that mob, and add the corresponding impact
   effect ID to the immune_impact_effects list. Note that guard break still
   deducts toughness; it simply does not trigger that impact effect when
   toughness is broken.

Q19: Toughness recovery is too slow/too fast. How do I adjust it?
A: The recovery speed is a fixed linear rate (about 2 seconds from 0 to full),
   currently not configurable. You can increase total toughness by raising base
   toughness/armor toughness/charm toughness, or raise weapon guard break to
   break toughness faster. See Section XIV.

================================================================
  End of tutorial. Have fun!
================================================================