damageoverhaul

This mod adds config to implement a Dark Souls‑style damage. It automatically generates five configuration files that cover: damage types, weapon damage types and their distribution, entity resistances, armor resistances, mob damage typesThese settings also apply to entities and weapons from other mods. I can't speak English. If you find bugs, tell me.
This is how to use it

================================================================
  Damage Overhaul Mod User Guide
  For Minecraft 1.20.1 Forge
================================================================

【Table of Contents】
  1. Mod Overview
  2. Installation and Startup
  3. Description of Eight Damage Types
  4. Tooltip Explanation
  5. Command List
  6. Configuration Files Overview and Common Modification Examples
  7. Enchantment System
  8. Projectile System and Entity Replacement
  9. Gun Mod Compatibility (Scorched Guns / TACZ, etc.)
  10. Block‑Sourced Damage Configuration
  11. Mana Repair (Requires Botania)
  12. Display Toggles and Server‑Client Sync
  13. Automatic Migration and Backup Mechanism
  14. Patchouli Guidebook
  15. Frequently Asked Questions (FAQ)

================================================================
1. Mod Overview
================================================================

Damage Overhaul is a mod that completely reworks the damage system.
It splits the single vanilla damage value into 8 distinct damage types
(Slashing/Blunt/Piercing/Magic/Fire/Lightning/Dark/Holy), and allows
you to freely control via JSON configuration files:

  - The damage composition of each weapon (e.g., iron sword = 60% slashing + 30% piercing + 10% blunt)
  - The resistance of each mob to each damage type
  - The resistance of each armour piece to each damage type
  - The damage distribution of each projectile (arrow, trident, snowball, fireball, …)
  - The environmental damage distribution from each block (magma block, campfire, cactus, …)
  - The damage distribution of weapons from gun mods (Scorched Guns, TACZ, etc.)

All configurations can be hot‑reloaded in‑game with commands – no restart required.

================================================================
2. Installation and Startup
================================================================

1. Requirements: Minecraft 1.20.1 + Forge (47.x).
2. Place damageoverhaul-1.0.0.jar into the mods folder.
3. (Optional) Install Patchouli to obtain an illustrated in‑game guidebook.
   The mod works fine without Patchouli.
4. On first launch, all configuration files (with default values) are automatically generated in config/damageoverhaul/.

【How to get the in‑game guidebook】
- With Patchouli installed, find "Damage Overhaul Guide" (purple book model) in the Creative inventory under "Tools & Utilities",
  or obtain it with the command:
    /give @s patchouli:guide_book{patchouli:book:"damageoverhaul:guide"}
- Survival players can add a recipe via datapack.

================================================================
3. Description of Eight Damage Types
================================================================

  Slashing   – sword and blade cuts
  Blunt      – hammering, explosions, falling, crushing
  Piercing   – arrows, spikes, cactus, berry bushes
  Magic      – potions, enchantment damage, phantoms, etc.
  Fire       – burning, lava, campfires
  Lightning  – lightning strikes
  Dark       – withering, shadow‑like damage
  Holy       – light‑based damage (reserved for expansion)

How are damage types determined?
Each vanilla damage instance carries a "damage type" identifier,
e.g. minecraft:arrow (arrow), minecraft:explosion (explosion).
The mod translates these identifiers into the 8 types via damage_type_mappings.json,
and supports mixed distributions for a single source, e.g.:

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

means 70% of explosion damage is dealt as blunt, 30% as fire.

The mod also automatically scans all registered damage types (including those added by other mods),
infers mappings based on tags and writes them into the config. Types with the is_fire tag are inferred as Fire,
un‑tagged ones default to Blunt – all can be edited.

================================================================
4. Tooltip Explanation
================================================================

Hover over an item:

  Weapons   → shows "Damage Distribution": each line = damage type + value (base attack × share)
              + percentage, sorted descending by share
  Armour    → shows "Armour Resistances": non‑zero resistances sorted descending,
              red = vulnerability, green = resistance
  Projectiles → shows "Projectile Damage Distribution": percentages only (base damage determined by the bow)
  Enchanted items → the title gets "(Enchanted)" appended; each line shows green‑coloured
              additions from enchantments (values/percentages)
  Guns      → guns have no attack attribute; tooltip automatically parses the damage number
              shown by the gun mod itself (e.g., "Damage: 10.0") as the base; if parsing fails,
              only percentages are shown
  Mana Repair → shows enabled status and mana cost per durability point

Display can be toggled via the 4 switches in display_config.json (see section 12).

================================================================
5. Command List
================================================================

All commands require OP level 2.

  /damageoverhaul reload
      Reloads all configuration files and automatically adds missing resistance /
      weapon / mapping entries for any newly added damage types.

  /damageoverhaul migrate
      Forces a migration check (functionally identical to reload; emphasises migration).

  /damageoverhaul migrations
      Shows the detailed migration log from the latest load: which files were changed,
      which entries were added, backup location.

  /damageoverhaul status
      Shows the mod's current status: number of damage types, counts of three enchantment
      categories, deflection mechanics, ranged default source, projectile config statistics,
      dual‑purpose list, mana repair, block distribution entry count.

================================================================
6. Configuration Files Overview and Common Modification Examples
================================================================

All configs are located in config/damageoverhaul/:

  damage_types.json              Damage type definitions (core; other files sync automatically)
  damage_type_mappings.json      Damage source → type mapping (supports mixed distributions)
  weapon_distributions.json      Weapon distributions + automatic gun learning
  unarmed_distributions.json     Empty‑handed / mob bare‑handed distributions
  entity_resistances.json        Entity resistances
  armor_resistances.json         Armour resistances
  ranged_config.json             Ranged source and projectile distributions
  projectile_item_mappings.json  Projectile mapping and entity replacement
  block_distributions.json       Block‑sourced damage
  special_mechanics.json         Special mechanics like deflection
  mana_repair_config.json        Mana repair
  display_config.json            Tooltip display toggles
  projectile_strike_config.json  Projectile enchantment bonuses

【Example 1: Change the distribution of an iron sword】
Open weapon_distributions.json, find "minecraft:iron_sword":
  "damage_distribution": {
    "slashing": 0.6, "piercing": 0.3, "blunt": 0.1, ... all others 0
  }
Save and run /damageoverhaul reload in‑game.

【Example 2: Make skeletons immune to fire】
Open entity_resistances.json, find "minecraft:skeleton",
change "fire" to -1.0 (-100% immunity).

【Example 3: Make explosions 70% blunt + 30% fire】
Open damage_type_mappings.json:
  "minecraft:explosion": { "blunt": 0.7, "fire": 0.3 }

【Example 4: Adjust the distribution of a specific gun】
Shoot with that gun once (auto‑learning creates an entry), then edit that entry and reload.

Standard workflow: edit → save → /damageoverhaul reload → done.
Missing fields/entries are automatically completed and written back; manual edits are never overwritten.

================================================================
7. Enchantment System
================================================================

On startup, the mod automatically registers three sets of enchantments per damage type (8 types × 3 = 24):

  protect_<type>   Armour resistance enchantment, 5%/level, max level 4
                   (applied after armour resistances but before armour value)
  strike_<type>    Weapon damage enchantment, 10%/level, max level 4
                   (only increases the share of that type without crowding out others)
  projectile_strike_<type>   Projectile damage enchantment
                   (only applicable to pure projectile items like arrows; values same as strike)

Obtaining: protect/strike can be obtained via enchanting table and anvil.
Vanilla arrows cannot normally be enchanted – the mod intercepts the anvil merge process:
  Place a weapon (with the corresponding strike book) on the left, arrow on the right → merge to get an enchanted arrow.

Note: Enchantments are frozen at game startup. Adding a new damage type requires a game restart
to generate the corresponding enchantments; values for existing enchantments can be hot‑reloaded.

================================================================
8. Projectile System and Entity Replacement
================================================================

【Projectile Distributions】ranged_config.json
  - ranged_damage_source: global ranged damage determination method
      "projectile" = use projectile distribution (default)
      "weapon"     = use weapon distribution
  - Each projectile entry has a follow_default field:
      true  = follow global default
      false = use its own distribution
  - Dual‑purpose items (e.g., tridents, which are both weapons and projectiles) default to NOT follow the global default.

【Projectile Item ↔ Entity Mapping】
The same entity can correspond to multiple items (enchanted arrows, spectral arrows, normal arrows are all minecraft:arrow).
The mod uses a three‑layer mechanism:
  1) Name matching: entity ID equals item ID
  2) Tag scanning: members of minecraft:arrows / forge:arrows tags
     automatically map 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 switch allow_dangerous_replace to true.

  Explanation:
  - Replacement happens at projectile spawn; the original entity is cancelled,
    the new entity inherits position/velocity/rotation/owner
  - Damage from the replaced entity is calculated using the distribution of the original projectile item's mapped entity;
    if not configured, the damage type mapping is used as a fallback (TNT explosion → blunt)
  - Caution: mapping to large entities like the Ender Dragon may cause abnormal behaviour

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

Gun mods have a distinct mechanic: damage values are stored in the gun's JSON,
dealt by projectile entities, and are completely separate from the vanilla weapon system
(guns have no attack attribute, projectile entity IDs differ from the gun item ID, ammunition does not carry damage).

This mod's universal compatibility approach (no hard‑coding for any specific mod):
  1. Weapon fallback: when a gun projectile hits and no projectile distribution is found,
     the mod checks the gun in the shooter's hand and splits damage according to its
     weapon_distributions.json entry.
  2. Auto‑learning: with auto_learn_ranged_weapons = true (default),
     the first time a gun deals damage, an entry is automatically created (default 100% piercing)
     and written to config.
  3. Tooltip base: automatically parses the damage number displayed by the gun mod as the base for tooltips.

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

Ammunition does not need configuration – damage is entirely determined by the gun.
TACZ and similar "gun JSON + projectile" mods work the same way.

================================================================
10. Block‑Sourced Damage Configuration
================================================================

block_distributions.json configures environmental damage by block ID
(magma blocks, campfires, cacti, powdered snow, wither roses, etc.).

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

Detection condition: damage source has no entity (e.g., hot_floor damage from standing on a magma block).
The mod checks the block you are inside (campfire/fire/cactus, etc.) and the block below your feet (magma block).

Auto‑learning: with auto_learn_block_damage = true (default), the first time an entity takes damage
from a block, that block is automatically registered (use_default=true, behaviour unchanged).
Then set use_default to false and fill in the distribution to take over that block.

Campfires and magma blocks can have entirely different distributions – something impossible with damage_type_mappings alone.

================================================================
11. Mana Repair (Requires Botania)
================================================================

With Botania installed, mana_repair_config.json allows durability items to consume mana for automatic repair:

  - Each item entry must be enabled individually
  - Configurable "mana cost per durability point" (any ratio)
  - When Botania is not installed, the feature is automatically disabled and the mod runs normally

Tooltips show the enabled status and mana cost ratio.

================================================================
12. Display Toggles and Server‑Client Sync
================================================================

display_config.json controls four categories of tooltip display:

  show_weapon_distribution    weapon damage distribution
  show_armor_resistance       armour resistance
  show_projectile_distribution projectile damage distribution
  show_mana_repair            mana repair status

Server‑side priority: in multiplayer, the server's display config takes precedence.
When players log in, it is automatically synced to the client, ensuring consistency across the server.
In single‑player, the local config is used directly.

================================================================
13. Automatic Migration and Backup Mechanism
================================================================

Every time configurations are loaded (startup/reload/migrate):

  1. The _schema_version of each file is validated; old formats are automatically migrated to the new format.
  2. Missing damage types / entries are automatically completed 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 (viewable with /damageoverhaul migrations).

Manual adjustments are never overwritten.

================================================================
14. Patchouli Guidebook
================================================================

The mod includes a complete Patchouli guidebook "Damage Overhaul Guide" (the in‑game version of this tutorial)
with the following contents:

  - Mod Overview: Welcome / Eight Damage Types / Quick Start
  - System Details: Weapon Distributions / Resistances / Enchantments / Projectiles /
    Entity Replacement / Gun Compatibility / Block Damage / Mana Repair /
    Special Mechanics and Display
  - Configuration Files: Overview / Modification and Reload Workflow
  - Commands: Detailed explanation of the four commands
  - Frequently Asked Questions

The guidebook supports both Chinese and English (follows the game language automatically).
Guidebook entries can be hot‑reloaded: Shift+click the pencil icon at the bottom‑left of the book in‑game.

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

Q1: I can't see the server's distribution config on the client?
A: No manual sync needed – the server automatically pushes all configs when a player logs in.
   After changing the server config, simply reconnect.

Q2: Enchantments don't appear after adding a new damage type?
A: Enchantments are frozen at startup – a game restart is required to generate new enchantments.
   Numerical values can be hot‑reloaded.

Q3: Modifications to config don't take effect?
A: Run /damageoverhaul reload. If the JSON has syntax errors, check the startup log for error messages.

Q4: I want to customise the distribution of a gun from a gun mod?
A: Shoot with that gun once (auto‑learning creates an entry), then edit the corresponding
   entry in weapon_distributions.json and reload.

Q5: If I make arrows shoot TNT, how is the damage calculated?
A: See sections 9/10. TNT explosion damage defaults to the blunt mapping;
   you can fine‑tune it in the mapping table or block/projectile configs.

Q6: How can I hide certain tooltips?
A: Use the four switches in display_config.json – the server's setting takes priority.

Q7: Can vanilla arrows be enchanted?
A: Yes. Use an anvil: place a weapon with the strike book on the left, arrow on the right,
   merge to get an enchanted arrow. projectile_strike enchantments only apply to pure projectile items.

Q8: Will my configs be lost when updating the mod?
A: No. Automatic migration preserves your manual edits,
   and old files are always backed up to the backups directory.

================================================================
  End of Guide. Enjoy!
================================================================

================================================================
  伤害改革（Damage Overhaul）模组使用教程
  适用于 Minecraft 1.20.1 Forge 版本
================================================================

【目录】
  一、模组简介
  二、安装与启动
  三、八种伤害类型说明
  四、悬浮提示（tooltip）说明
  五、指令一览
  六、配置文件一览与常用修改示例
  七、附魔系统
  八、射弹系统与实体替换
  九、枪械模组兼容（焦火枪械 / TACZ 等）
  十、方块源性伤害配置
  十一、魔力修复（需要植物魔法）
  十二、显示开关与服务端同步
  十三、自动迁移与备份机制
  十四、帕秋莉手册说明
  十五、常见问题（FAQ）

================================================================
一、模组简介
================================================================

伤害改革是一款伤害系统重构模组。它把原版单一的伤害数值拆分为
8 种伤害类型（斩击/钝击/穿刺/魔法/火焰/闪电/黑暗/神圣），并且
允许你通过 JSON 配置文件自由控制：

  - 每一件武器打出来的伤害构成（如铁剑 = 60%斩击 + 30%穿刺 + 10%钝击）
  - 每一个生物对不同伤害类型的抗性
  - 每一件护甲对不同伤害类型的抗性
  - 每一种射弹（箭、三叉戟、雪球、火球……）的伤害分布
  - 每一个方块造成的环境伤害分布（岩浆块、篝火、仙人掌……）
  - 枪械类模组（焦火枪械、TACZ 等）的武器伤害分布

所有配置都可以在游戏中用指令热重载，全程无需重启游戏。

================================================================
二、安装与启动
================================================================

1. 环境要求：Minecraft 1.20.1 + Forge（47.x）。
2. 把 damageoverhaul-1.0.0.jar 放入 mods 文件夹。
3. （可选）安装帕秋莉手册（Patchouli），即可在游戏内获得本模组
   的图文手册。没有帕秋莉手册时模组照常运行。
4. 首次启动会自动在 config/damageoverhaul/ 目录下生成全部配置
   文件（带默认值）。

【如何拿到游戏内手册】
- 装有帕秋莉手册时，创造物品栏"工具与实用"分类中有
  《伤害改革指南》（紫色书本模型），也可用指令获取：
    /give @s patchouli:guide_book{patchouli:book:"damageoverhaul:guide"}
- 生存模式可通过数据包配方自行添加获取途径。

================================================================
三、八种伤害类型说明
================================================================

  斩击（slashing）  —— 刀剑劈砍类伤害
  钝击（blunt）     —— 锤击、爆炸、坠落、挤压
  穿刺（piercing）  —— 箭矢、尖刺、仙人掌、浆果丛
  魔法（magic）     —— 药水、附魔伤害、幻翼等
  火焰（fire）      —— 烧灼、岩浆、篝火
  闪电（lightning） —— 雷击
  黑暗（dark）      —— 凋零、暗影类伤害
  神圣（holy）      —— 光明系伤害（预留扩展）

伤害类型如何判定？
原版每段伤害都带有一个"伤害来源标识"（damage type），
例如 minecraft:arrow（箭）、minecraft:explosion（爆炸）。
模组通过 damage_type_mappings.json 把这些标识翻译成 8 种类型，
并且支持"一种来源拆成多种类型的混合分布"，例如：

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

表示爆炸伤害 70% 按钝击、30% 按火焰结算。

模组还会自动扫描游戏内注册的全部伤害类型（包括其他模组新增
的），按标签自动推断映射并写入配置。带 is_fire 标签的推断为
火焰，无标签的默认钝击，全部可在配置中修改。

================================================================
四、悬浮提示（tooltip）说明
================================================================

把鼠标悬停在物品上：

  武器   → 显示"伤害分布"：每行 = 伤害类型 + 数值（基础攻击×占比）
           + 百分比，按占比降序排列
  护甲   → 显示"护甲抗性"：非零抗性降序排列，红色=易伤，
           绿色=抗性
  射弹   → 显示"射弹伤害分布"：仅百分比（伤害由弓决定）
  附魔   → 带附魔的物品标题会追加"(含附魔)"，每行末尾用绿色
           列出附魔增加的数值/百分比
  枪械   → 枪械没有攻击力属性，tooltip 会自动解析枪械模组自己
           标注的伤害数字作为基数（如"伤害: 10.0"），解析失败则
           只显示百分比
  魔力修复 → 显示启用状态与每点耐久魔力消耗

显示内容可通过 display_config.json 的 4 个开关控制（见第十二节）。

================================================================
五、指令一览
================================================================

所有指令需要 OP 等级 2。

  /damageoverhaul reload
      重载全部配置文件，并自动补齐新增伤害类型对应的
      抗性/武器/映射条目。

  /damageoverhaul migrate
      强制执行一次迁移检查（与 reload 等价，语义强调迁移）。

  /damageoverhaul migrations
      显示最近一次加载的详细迁移日志：改了哪些文件、
      新增了哪些条目、备份位置。

  /damageoverhaul status
      显示模组当前状态：伤害类型数、三类附魔数量、偏转机制、
      远程默认来源、射弹配置统计、两用清单、魔力修复、
      方块分布条目数。

================================================================
六、配置文件一览与常用修改示例
================================================================

全部配置位于 config/damageoverhaul/：

  damage_types.json              伤害类型定义（核心，其他文件自动同步）
  damage_type_mappings.json      伤害来源→类型映射（支持混合分布）
  weapon_distributions.json      武器分布 + 枪械自动学习
  unarmed_distributions.json     空手/生物裸击分布
  entity_resistances.json        实体抗性
  armor_resistances.json         护甲抗性
  ranged_config.json             远程来源与射弹分布
  projectile_item_mappings.json  射弹映射与实体替换
  block_distributions.json       方块源性伤害
  special_mechanics.json         伤害偏转等特殊机制
  mana_repair_config.json        魔力修复
  display_config.json            tooltip 显示开关
  projectile_strike_config.json  射弹附魔加成

【示例 1：修改铁剑的分布】
打开 weapon_distributions.json，找到 "minecraft:iron_sword"：
  "damage_distribution": {
    "slashing": 0.6, "piercing": 0.3, "blunt": 0.1, ... 其余 0
  }
改完保存，游戏内执行 /damageoverhaul reload。

【示例 2：让骷髅免疫火焰】
打开 entity_resistances.json，找到 "minecraft:skeleton"，
把 "fire" 改为 -1.0（-100% 免疫）。

【示例 3：把爆炸改为 70% 钝击 + 30% 火焰】
打开 damage_type_mappings.json：
  "minecraft:explosion": { "blunt": 0.7, "fire": 0.3 }

【示例 4：调整某把枪的分布】
先拿那把枪射一次（自动学习会生成条目），再修改对应条目并 reload。

标准流程：编辑 → 保存 → /damageoverhaul reload → 完成。
所有文件缺少的字段/条目会自动补齐回写，手动调整不会被覆盖。

================================================================
七、附魔系统
================================================================

模组在启动时按伤害类型自动注册三套附魔（8 类型 × 3 类 = 24 个）：

  protect_<类型>   护甲抗性附魔，5%/级，最高 4 级
                   （在护甲抗性之后、护甲值之前结算）
  strike_<类型>    武器增伤附魔，10%/级，最高 4 级
                   （只增加对应类型占比，不挤占其他类型）
  projectile_strike_<类型>  射弹增伤附魔
                   （仅纯射弹物品可附，如箭类；数值同 strike）

获取方式：protect/strike 可在附魔台与铁砧使用。原版箭无法被
正常附魔，模组通过接管铁砧合并流程实现射弹附魔：
  左侧放武器（用对应 strike 附魔书），右侧放箭 → 合并得附魔箭。

注意：附魔注册在游戏启动时冻结。新增伤害类型后需要重启游戏
才会生成对应附魔；已有附魔的数值配置可以热重载。

================================================================
八、射弹系统与实体替换
================================================================

【射弹分布】ranged_config.json
  - ranged_damage_source：全局远程判定方式
      "projectile" = 按射弹分布（默认）
      "weapon"     = 按武器分布
  - 每个射弹条目有 follow_default 字段：
      true  = 跟随全局默认
      false = 使用该条目自己的分布
  - 两用物品（如三叉戟既是武器又是射弹）默认拒绝跟随默认。

【射弹物品与实体的映射】
同种实体对应多种物品（附魔箭/光灵箭/普通箭都是 minecraft:arrow）。
模组用三层机制解析：
  1) 同名匹配：实体 ID 与物品 ID 相同
  2) 标签扫描：minecraft:arrows / forge:arrows 标签成员
     自动映射到 minecraft:arrow
  3) 手动扩展：projectile_item_mappings.json 添加自定义映射

【实体替换】projectile_item_mappings.json
  想让箭射出 TNT？在映射中写：
    "minecraft:arrow": {
      "entity": "minecraft:tnt",
      "replace_entity": true
    }
  并把全局开关 allow_dangerous_replace 改为 true。

  说明：
  - 替换发生在射弹生成瞬间，原实体被取消，新实体继承
    位置/速度/旋转/所有者
  - 被替换实体的伤害按原弹药物品映射实体的分布结算，
    未配置时按伤害类型映射兜底（TNT 爆炸 → 钝击）
  - 风险提示：映射到末影龙等大型实体可能产生异常行为

================================================================
九、枪械模组兼容（焦火枪械 / TACZ 等）
================================================================

枪械类模组的特点：伤害数值存储在枪械 JSON 中，由射弹实体结算，
与原版武器体系完全不同（枪械没有攻击力属性、射弹实体 ID 与
枪物品 ID 不同名、弹药不携带伤害）。

本模组的通用兼容方案（不硬编码任何模组）：
  1. 来源武器回退：枪械射弹命中后查不到射弹分布时，自动检查
     射手手中的枪在 weapon_distributions.json 中的分布并按其拆分
  2. 自动学习：auto_learn_ranged_weapons = true（默认）时，
     某把枪首次造成伤害会自动生成条目（默认穿刺 100%）写入配置
  3. tooltip 基数：自动解析枪械模组标注的伤害数字作为显示基数

使用步骤（以焦火枪械为例）：
  1. 进游戏，拿任意枪射击一次
  2. 打开 weapon_distributions.json，能看到 scguns:xxx 条目
  3. 修改它的 damage_distribution（如火焰枪改 fire 占比）
  4. /damageoverhaul reload 生效

弹药不需要配置——伤害完全由枪决定。TACZ 等"枪 JSON + 射弹"
型模组同样适用。

================================================================
十、方块源性伤害配置
================================================================

block_distributions.json 按方块 ID 配置环境伤害
（岩浆块、篝火、仙人掌、细雪、凋零玫瑰等）。

格式：
  "minecraft:magma_block": {
    "use_default": true,                  ← true=使用默认映射链路
    "damage_distribution": { ... }        ← false 时此分布生效
  }

判定条件：伤害来源没有实体（如站在岩浆块上的 hot_floor 伤害）。
模组检查你身体所在的方块（篝火/火/仙人掌等）与脚下方块（岩浆块）。

自动学习：auto_learn_block_damage = true（默认）时，实体首次受到
某方块的伤害，该方块自动登记进配置（use_default=true，行为不变）。
之后把 use_default 改为 false 并填写分布，即可接管该方块。

篝火和岩浆块可以使用完全不同的分布——这是 damage_type_mappings
做不到的细粒度。

================================================================
十一、魔力修复（需要植物魔法）
================================================================

安装了植物魔法（Botania）时，mana_repair_config.json 可以让耐久
物品消耗魔力自动修复：

  - 每个物品条目需单独启用
  - 可配置"每点耐久消耗的魔力值"（比例任意调整）
  - 未安装植物魔法时该功能自动禁用，模组照常运行

tooltip 会显示启用状态与魔力消耗比例。

================================================================
十二、显示开关与服务端同步
================================================================

display_config.json 控制四类 tooltip 显示：

  show_weapon_distribution    武器伤害分布
  show_armor_resistance       护甲抗性
  show_projectile_distribution 射弹伤害分布
  show_mana_repair            魔力修复状态

服务端优先：多人游戏中以服务端的显示配置为准，玩家登录时自动
同步到客户端，保证全服显示一致。单人游戏直接使用本地配置。

================================================================
十三、自动迁移与备份机制
================================================================

每次加载配置时（启动/reload/migrate）：

  1. 校验每个文件的 _schema_version，旧格式自动迁移为新格式
  2. 缺失的伤害类型/条目自动补齐并回写文件
  3. 修改前原文件自动备份到：
       config/damageoverhaul/backups/<时间戳>/
  4. 全部自动变更记录在迁移日志中（/damageoverhaul migrations 查看）

手动做过的调整永远不会被覆盖。

================================================================
十四、帕秋莉手册说明
================================================================

模组内置一本完整的帕秋莉手册《伤害改革指南》（本教程的游戏内
版本），内容与目录：

  - 模组简介：欢迎阅读 / 八种伤害类型 / 快速上手
  - 系统详解：武器分布 / 抗性 / 附魔 / 射弹 / 实体替换 /
    枪械兼容 / 方块伤害 / 魔力修复 / 特殊机制与显示
  - 配置文件：总览 / 修改与重载流程
  - 指令：四大指令详解
  - 常见问题

手册支持中英双语（自动跟随游戏语言）。手册条目可热重载：
游戏内 Shift+点击手册左下角的铅笔图标即可刷新内容。

================================================================
十五、常见问题（FAQ）
================================================================

Q1：客户端看不到服务器的分布配置？
A：无需手动同步——玩家登录时服务端自动推送全部配置。
   刚改完服务端配置的话，重连即可。

Q2：新增伤害类型后附魔没出现？
A：附魔在启动时注册冻结，需要重启游戏生成新附魔。
   配置数值可以热重载。

Q3：修改配置后不生效？
A：执行 /damageoverhaul reload。若 JSON 格式错误，
   查看启动日志中的报错信息。

Q4：枪械模组的枪想自定义分布？
A：先拿那把枪射一次（自动学习会登记条目），再改
   weapon_distributions.json 中对应条目并 reload。

Q5：把箭改成射 TNT，伤害怎么算？
A：见第九/十节。TNT 爆炸默认走钝击映射，
   可在映射表或方块/射弹配置中细化。

Q6：想隐藏某些 tooltip？
A：display_config.json 四个开关，服务端为准。

Q7：原版箭能附魔吗？
A：可以。通过铁砧：左侧武器+strike 附魔书，右侧箭，
   合并得附魔箭。projectile_strike 附魔只附在纯射弹物品上。

Q8：升级模组版本后配置会丢吗？
A：不会。自动迁移会保留你的手动调整，
   旧文件都会先备份到 backups 目录。

================================================================
  教程结束。祝你玩得愉快！
================================================================