damageoverhaul

================================================================
Damage Overhaul Mod Usage Guide
For Minecraft 1.20.1 Forge Version
================================================================

[Table of Contents]

1. Mod Introduction

2. Installation and Startup

3. Explanation of the Eight Damage Types

4. Tooltip Explanation

5. Command List

6. Configuration File List 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. Charm System (Own Gems + Third-Party Charm Bonuses)

12. Mana Repair (Requires Botania)

13. Display Toggles and Server-Side Sync

14. Automatic Migration and Backup Mechanism

15. Patchouli Manual Explanation

16. Frequently Asked Questions (FAQ)

================================================================

1. 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 configuration files:

• The damage composition dealt by each weapon (e.g., Iron Sword = 60% Slashing + 30% Piercing + 10% Blunt)

• Each creature's resistance to different damage types

• Each piece of armor's resistance to different damage types

• The damage distribution of each projectile (arrows, tridents, snowballs, fireballs...)

• The environmental damage distribution caused by each block (magma blocks, campfires, cacti...)

• The weapon damage distribution of gun mods (Scorched Guns, TACZ, etc.)

• Charm system: 8 built-in damage gems, plus configuring damage bonuses
  and type resistances for any Curios charm from other mods (automatic
  scanning, no need to manually enter item IDs)

All configurations can be hot-reloaded in-game via commands, with no game
restart required throughout.
(Note: Adding new damage types / adding new built-in charm entries requires
a restart, because enchantments and items are frozen at startup.)

================================================================

1. Installation and Startup
   ================================================================

2. Requirements: Minecraft 1.20.1 + Forge (47.x).

3. Prerequisite mod: Curios API (charm slots). The mod cannot load without Curios.

4. Place damageoverhaul-1.0.0.jar into the mods folder.

5. (Optional) Install Patchouli to get the mod's in-game illustrated
   manual. The mod runs normally without Patchouli.

6. On first startup, all configuration files (with default values) are
   automatically generated in the config/damageoverhaul/ directory;
   simultaneously, Curios charm slots (charm) are automatically added to players.

[How to Obtain the In-Game Manual]

• When Patchouli is installed, the "Damage Overhaul Guide" (purple book
  model) is in the creative inventory "Tools & Utilities" category. It can
  also be obtained via command:
  /give @s patchouli:guide_book{patchouli:book:"damageoverhaul:guide"}

• In survival mode, you can add acquisition methods yourself via data pack recipes.

================================================================

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

Slashing —— Sword-slashing type damage
Blunt —— Hammer strikes, explosions, falls, crushing
Piercing —— Arrows, spikes, cacti, berry bushes
Magic —— Potions, enchantment damage, phantoms, etc.
Fire —— Burning, lava, campfires
Lightning —— Lightning strikes
Dark —— Wither, shadow-type damage
Holy —— Light-type damage (reserved for expansion)

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

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

This means explosion damage is settled as 70% Blunt and 30% Fire.

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

================================================================

1. Tooltip Explanation
   ================================================================

Hover the mouse over an item:

Weapon → Displays "Damage Distribution": each line = damage type + value
(base attack × proportion) + percentage, sorted in descending
order by proportion
Armor → Displays "Armor Resistance": non-zero resistances sorted in
descending order, red = vulnerability, green = resistance
Projectile → Displays "Projectile Damage Distribution": percentage only
(damage is determined by the bow)
Enchantment → Enchanted item titles have "(Enchanted)" appended, and each
line ends with the values/percentages added by the enchantment
listed in green
Gun → Guns have no attack power attribute; the tooltip automatically
parses the damage number annotated by the gun mod itself as the
base (e.g., "Damage: 10.0"). If parsing fails, only percentages
are displayed
Mana Repair → Displays enabled status and mana cost per point of durability
Own Charm → Displays associated damage type, attack bonus, and damage resistance
Third-Party Charm → Other mod charms with configured non-zero factors
display "External Charm Bonus": red = damage bonus, green = type
resistance, types with 0 effect are not displayed

Display content can be controlled via the 5 toggles in display_config.json
(see Section 13).

================================================================

1. Command List
   ================================================================

All commands require OP level 2.

/damageoverhaul reload
Reloads all configuration files, and automatically fills in
resistance/weapon/mapping entries for newly added damage types.

/damageoverhaul migrate
Forces a migration check (equivalent to reload, semantically
emphasizing migration).

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

/damageoverhaul status
Displays the mod's current status: number of damage types, number of
the three enchantment categories, deflection mechanics, default ranged
source, projectile configuration statistics, dual-use list, mana repair,
block distribution entry count, own charm count, and third-party charm
bonus status (number of recorded entries, startup scan toggle).

================================================================

1. Configuration File List and Common Modification Examples
   ================================================================

All configurations 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 distribution)
weapon_distributions.json Weapon distributions + gun auto-learning
unarmed_distributions.json Unarmed/creature bare-handed distributions
entity_resistances.json Entity resistances
armor_resistances.json Armor resistances
ranged_config.json Ranged sources and projectile distributions
projectile_item_mappings.json Projectile mappings and entity replacement
block_distributions.json Block-sourced 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 Own charms (8 damage gems)
external_charms.json Third-party charm factor table (auto-scan generated)

[Example 1: Modify the Iron Sword's distribution]
Open weapon_distributions.json and find "minecraft:iron_sword":
"damage_distribution": {
"slashing": 0.6, "piercing": 0.3, "blunt": 0.1, ... the rest 0
}
Save after editing, then run /damageoverhaul reload in-game.

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

[Example 3: Change explosions 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 fire that gun once (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
recorded all Curios charms. Find the corresponding item line and change
"fire" in attack_bonuses to 0.15 (see Section 11 for details).

Standard procedure: Edit → Save → /damageoverhaul reload → Done.
Missing fields/entries in all files will be automatically filled in and
written back; manual adjustments will not be overwritten.

================================================================

1. Enchantment System
   ================================================================

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

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

How to obtain: protect/strike can be used at enchanting tables and anvils.
Vanilla arrows cannot be enchanted normally; the mod implements projectile
enchanting by taking over the anvil combining process:
Place the weapon on the left (with the corresponding strike enchanted book),
place arrows on the right → combine to get enchanted arrows.

Note: Enchantment registration is frozen at game startup. After adding new
damage types, you need to restart the game to generate the corresponding
enchantments; the value configurations of existing enchantments can be
hot-reloaded.

================================================================

1. Projectile System and Entity Replacement
   ================================================================

[Projectile Distribution] ranged_config.json

• ranged_damage_source: Global ranged determination method
  "projectile" = Use projectile distribution (default)
  "weapon" = Use weapon distribution

• Each projectile entry has a follow_default field:
  true = Follow the 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 corresponds to multiple items (enchanted arrows / spectral
arrows / normal arrows are all minecraft:arrow). The mod resolves this using
a three-layer mechanism:

1. Same-name matching: Entity ID is the same as item ID

2. Tag scanning: Members of the 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? Write in the mapping:
"minecraft:arrow": {
"entity": "minecraft:tnt",
"replace_entity": true
}
And change the global toggle allow_dangerous_replace to true.

Explanation:

• Replacement occurs at the moment the projectile is spawned; the original
  entity is cancelled, and the new entity inherits position/velocity/
  rotation/owner

• The replaced entity's damage is settled according to the original
  projectile item's mapped entity distribution; if unconfigured, it falls
  back to the damage type mapping (TNT explosion → Blunt)

• Risk warning: Mapping to large entities such as the Ender Dragon may
  cause abnormal behavior

================================================================

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

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

This mod's universal compatibility solution (does not hardcode any mod):

1. Source weapon fallback: When a gun projectile hits and no projectile
   distribution is found, it automatically checks the distribution of the
   gun in the shooter's hand in weapon_distributions.json and splits
   according to it

2. Auto-learning: When auto_learn_ranged_weapons = true (default), the
   first time a gun deals damage, an entry is automatically generated
   (default Piercing 100%) and written to the configuration

3. Tooltip base: Automatically parses the damage number annotated 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.json, and you will see the scguns:xxx entry

3. Modify its damage_distribution (e.g., change a flamethrower to fire
   proportion)

4. /damageoverhaul reload to take effect

Ammunition does not need configuration — damage is entirely determined by
the gun. The same applies to "gun JSON + projectile" type mods such as TACZ.

================================================================

1. Block-Sourced Damage Configuration
   ================================================================

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

Format:
"minecraft:magma_block": {
"use_default": true, ← true=use default mapping chain
"damage_distribution": { ... } ← this distribution takes effect 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 below your feet (magma
block).

Auto-learning: When auto_learn_block_damage = true (default), the first time
an entity takes damage from a certain block, that block is automatically
registered into the configuration (use_default=true, behavior unchanged).
Afterwards, 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 the fine granularity that damage_type_mappings cannot achieve.

================================================================

1. Charm System (Own Gems + Third-Party Charm Bonuses)
   ================================================================

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

[11.1 Own Charms: 8 Damage Gems]

The mod comes with 8 charms (findable in the creative inventory):
Slashing Gem / Blunt Gem / Piercing Gem / Magic Gem / Flame Gem /
Thunder Gem / Shadow Gem / Holy Light Gem
Default: +15% damage of the corresponding type on attack, -10% damage of
the corresponding type when hit.

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 creature resistance, armor resistance, and enchantment
  resistance, independently reduced by type ×(1-resistance) (only applies
  to 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/deleting own charm entries is an item registration change and
requires a game restart to take effect.

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

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 be equipped in Curios slots are
   automatically recorded into the table

2. Equipment-time supplementary scan: When a player actually equips a
   charm into a slot (checked at login and every 10 seconds thereafter),
   if any missed items are found (such as mods whose tags are dynamically
   generated by in-memory data packs), they are automatically added to
   the table

Each charm has one row in the table, listing two types of 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 10% fire damage reduction...
}
}

Value meanings:
attack_bonuses Damage bonus, 0.15 = +15% damage of that type
defense_resistances Type resistance, 0.10 = -10% damage of that type
0 = no effect (produces no effect, and the tooltip does not display that line)

Usage procedure:

1. Start the world once (the table is automatically generated)

2. Open config/damageoverhaul/external_charms.json

3. Find the target charm's row, and change the corresponding type's 0 to
   the desired factor

4. /damageoverhaul reload (servers require reconnection to sync client
   display)

Two master toggles (at the top of the file):
enable_external_charms Master toggle, false = all third-party charm
features stopped
auto_scan_curios_items Startup scan toggle, false = only keep existing
entries, no longer automatically record new charms
(equipment supplementary scan also stops)

Features and rules:

• When new damage types are added, a 0 column for that type is
  automatically added to all charms in the table

• All-zero entries do not participate in network sync; no matter how many
  charms are in the modpack, login speed is unaffected

• Same damage type: When own gems and third-party charms are worn together,
  the highest is taken

• Old manually filled entries are automatically migrated and their values
  preserved; old files are automatically backed up

• Must be actually equipped in a Curios slot to take effect (putting it in
  the backpack has no effect)

================================================================

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

When Botania is installed, mana_repair_config.json allows durable items to
automatically repair by consuming mana:

• Each item entry needs to be enabled individually

• The "mana consumed per point of durability" can be configured (the ratio
  can be adjusted arbitrarily)

• When Botania is not installed, this feature is automatically disabled,
  and the mod runs normally

The tooltip displays the enabled status and mana consumption ratio.

================================================================

1. Display Toggles and Server-Side Sync
   ================================================================

display_config.json controls five categories 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 bonuses

Server-side priority: In multiplayer, the server's display configuration
takes precedence, and is automatically synced to the client when the player
logs in, ensuring consistent display across the server. Single-player
directly uses the local configuration.

================================================================

1. Automatic Migration and Backup Mechanism
   ================================================================

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

1. Verify each file's _schema_version; old formats are automatically
   migrated to the new format

2. Missing damage types/entries are automatically filled in 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 you have made will never be overwritten.

================================================================

1. Patchouli Manual Explanation
   ================================================================

The mod includes a complete Patchouli manual "Damage Overhaul Guide" (the
in-game version of this tutorial), with the following content 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 / Mana Repair / Special Mechanics and Display

• Configuration Files: Overview / Modification and Reload Process

• Commands: Detailed Explanation of the Four Commands

• FAQ

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

================================================================

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

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

Q2: Enchantments did not appear after adding new damage types?
A: Enchantments are frozen at startup registration and require a game
restart to generate new enchantments. Configuration values can be
hot-reloaded.

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

Q4: How to customize the distribution of a gun mod's gun?
A: First fire that gun once (auto-learning will register an entry), then
modify the corresponding entry in weapon_distributions.json and reload.

Q5: If arrows are changed to shoot TNT, how is damage calculated?
A: See Sections 9/10. TNT explosions default to the Blunt mapping, and can
be refined in the mapping table or block/projectile configurations.

Q6: Want to hide certain tooltips?
A: Five toggles in display_config.json, server-side takes precedence.

Q7: Can vanilla arrows be enchanted?
A: Yes. Via anvil: weapon on the left + strike enchanted book, arrows on
the right, combine to get enchanted arrows. projectile_strike
enchantments only apply to pure projectile items.

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

Q9: How to add damage bonuses or resistances to other mods' rings/charms?
A: No need to hand-write configuration. After starting the world, the mod
has already automatically recorded all Curios charms into
external_charms.json. Find the corresponding item row and change the
needed damage type factor from 0 to a value (such as 0.15), then reload.
See Section 11 for details.

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

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

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