EnchanterLetter

# Enchanter Letter

[](https://opensource.org/licenses/MPL-2.0)

**Enchanter Letter** is a Minecraft mod supporting **Minecraft 1.21.1 / 1.20.1** with four branches for **NeoForge / Forge / Fabric**. It adds a set of growable, customizable **Enchanter Letters** and **Letter Binders**: simply keep them in your inventory, accessory slots, or a binder to gain damage bonuses and defensive attributes — no need to hold them.

- All four branches are feature-synchronized; only the underlying implementations differ.
- No mandatory mod dependencies. `UsefulMagic`, `Curios`, `Accessories`, `Terra Curio`, etc. are all optional, reflection-based integrations.
- The mod works on `usefulmagic:magic` damage by default, and can be extended to any registered damage type through configuration and commands.

---

## Feature Overview

### 1. Letter Types & Progression

Each letter has a level (Lv). Higher levels grant stronger bonuses, and levels are automatically gained by performing the corresponding activity:

| Letter | Level-Up Condition (default) | Damage Bonus per Level |
| --- | --- | --- |
| Experience Letter | Gain 1,000 XP | +10% |
| Kill Letter | Kill 50 monsters | +10% |
| Fishing Letter | Catch 100 fish | +10% |
| Travel Letter | Walk 5,000 blocks / fly 20,000 blocks | +10% |
| Treasure Letter | Open 20 naturally-generated chests | +10% |
| Time Letter | 3,600 seconds of world uptime | +10% |
| Tenacity Letter | Take 10,000 damage | +10% |
| Hero Letter | Win 1 raid | +10% at low levels, +20% from level 4 |
| Stage Letter | Fixed multiplier, no progression | 100% – 1000% (configurable) |
| Custom Letter | Always level 0 | Reads item data directly; no progression/config participation |

All values above are configuration defaults and are adjustable, except for the Custom Letter.

### 2. Damage Bonus Rules

- A letter in your **inventory, accessory slots, or a Letter Binder** counts as carried — you do not need to hold it.
- By default, it boosts `usefulmagic:magic` damage. You can add any registered damage type through `default_bonus_damage_types`.
- Actual multiplier = letter level × bonus per level. The item tooltip and HUD show the current real multiplier.
- Stacking rules are supported: `allow_multiple_letters` (whether multiple letters sum together) and `allow_same_letters` (whether identical letters each count).

### 3. Binding System

- **Sneak + long-press right-click for about 2 seconds** while holding a letter (or an empty Letter Binder) to bind/unbind it.
- A bound letter only works while held by its bound player. If someone else picks it up, it will be automatically "ejected" as an item entity.
- Inventory, accessory slots, and Letter Binder contents are all continuously checked.

### 4. Item Entity Protection

Dropped letters and binders:

- Are immune to all damage, including explosions and cacti;
- Have no gravity, are not pushed by water, and always have zero velocity;
- Cannot be sucked up by hoppers / hopper minecarts.

### 5. Letter Binder

- Works like the vanilla Bundle: right-click to store/retrieve, inventory interactions, and hover to preview contents.
- Letters are not stackable and occupy one slot each; the binder natively holds up to 64 letters.
- Letters inside a binder count as "carried" and participate in damage bonuses and ejection checks.
- An empty binder can be bound; a non-empty binder ejects all contents at once when sneak-right-clicked.

### 6. Magic Conversion Enchantment (`magic_conversion`)

- Once enchanted, the letter no longer uses the default damage type; instead it resolves against a specified damage type.
- Use `/letterdamage <damage_type>` to set the conversion type.
- In Creative mode, you can right-click an enchanted book to open a client-side screen and directly type a damage type ID.
- Converted damage of the same type is merged and resolved with a delayed tick; different conversion types do not interfere with each other.

### 7. Accessory Slot Compatibility

- **NeoForge**: Compatible with Curios API, including third-party slots such as Terra Curio.
- **Fabric**: Compatible with Accessories and Curios (Fabric).
- All integrations are reflection-based and have no effect when the corresponding mod is not installed.

### 8. HUD Display

- Shows the currently active letters in the top-left corner: item name, level, and actual multiplier; converted letters also show their damage type.
- Press `N` (default) to cycle through displays: damage bonus → armor → armor toughness → resistance → off.
- Gray text means "currently inactive" (suppressed by a higher multiplier); white text means active.

### 9. Defensive Attributes

All letters provide three defensive attributes while carried:

- **Armor**: Directly adds armor as a vanilla attribute modifier, visible in the armor bar.
- **Armor Toughness**: Directly adds armor toughness.
- **Resistance**: Reduces incoming damage by a percentage (before armor calculation). Disabled by default; the server cap is 80% by default and can be changed with `/letterresistance limit`.
- When `allow_multiple_letters` is disabled, each attribute independently uses the highest value among all letters; when enabled, they add together.
- Defensive attributes are not affected by the `magic_conversion` enchantment.

### 10. Enchantment System

- **Glowing**: Can be applied to letters/binders to make the carrier glow. The glow color is controlled by `/lettercolor`; mobs are also supported.
- **Magic Binding (`magic_binding`)**: Keeps the item on death and returns it after respawn; accessory slot items are restored to their original slot where possible.
- **Vanishing Curse (`vanishing_curse`)**: The mod's items can receive the vanilla Curse of Vanishing and are destroyed on death. Use `/lettervanish` to enable forced vanishing.

### 11. Mob Wielding & Admin Commands

- When a mob carries letters in its main hand, off hand, armor, or accessory slots, **all damage it deals** is boosted (players still strictly follow the configured damage types).
- `/letterstorage` lets you capture an entity, swap items with its main hand/off hand/armor slots, and export its NBT.
- Management commands such as `/letterback` (retrieve dropped items), `/letterclean` (scheduled cleanup), and `/letterbinding` (ejection whitelist) are also provided.

---

## Versions & Branches

| Directory | Minecraft | Loader / Runtime | Java | Item Data Storage | Damage Modification |
| --- | --- | --- | --- | --- | --- |
| `neoforge-1.21.1` | 1.21.1 | NeoForge 21.1.x | Java 21 | Data Components | Events (`LivingIncomingDamageEvent` + `LivingDamageEvent.Pre`) |
| `fabric-1.21.1` | 1.21.1 | Fabric Loader 0.16.10 + Fabric API 0.110.0+1.21.1 | Java 21 | Data Components | Mixin modifies damage parameter in `LivingEntity.hurt()` |
| `forge-1.20.1` | 1.20.1 | Forge 47.1.x | Java 17 (can build `release 17` with JDK 21) | NBT | Event (`LivingHurtEvent`) |
| `fabric-1.20.1` | 1.20.1 | Fabric Loader 0.15.11 + Fabric API 0.92.2+1.20.1 | Java 17 (can build `release 17` with JDK 21) | NBT | Mixin modifies damage parameter in `LivingEntity.hurt()` |

The **items, mechanics, configuration, commands, HUD, binding/ejection, item entity protection, magic conversion, and enchantments** are identical across all four branches. Pick the directory matching your loader and Minecraft version.

---

## 1.20.1 vs 1.21.1 Differences

Both versions are feature-complete and synchronized; the main differences are in the underlying implementation:

| Aspect | 1.21.1 (NeoForge / Fabric) | 1.20.1 (Forge / Fabric) |
| --- | --- | --- |
| Data storage | **Data Components** | **NBT** |
| Damage calculation | NeoForge uses events; Fabric uses Mixin | Forge uses `LivingHurtEvent`; Fabric uses Mixin |
| Curios item tag path | `data/curios/tags/item/` (singular) | `data/curios/tags/items/` (plural) |
| Binder capacity implementation | `BundleContents.getWeight` returns `Fraction`; Mixin changes it to `1/64` | `BundleItem.getWeight` returns `int`; Mixin changes it to `1` |
| Forge port adaptation | Not needed | Automatically compatible with MesdagPortLib, syncing amplified damage into its `PortDamageContainer` |
| Fabric third-party compatibility | Normal Accessories integration | Extra handling for Accessories beta.48's unconditional Sodium dependency crash (registers an empty renderer) |

> For developer-focused API differences (attribute registration, `ResourceLocation`, `AttributeModifier`, Mixin mappings, etc.), refer to the source comments and development documentation in each branch.

---

## Command Reference

All mod commands require permission level 2/3/4:

| Command | Description |
| --- | --- |
| `/lettermulti [true false]` | Toggle multiple letters being active at once |
| `/lettersame [true false]` | Toggle identical letters each counting |
| `/letterset <type> <param> <value>` | Modify letter growth / multiplier / defensive attributes |
| `/lettertype [add delete] <damage_type>` | Add / remove default bonus damage types |
| `/letterentity [add delete] <entity_type>` | Add / remove magic conversion blacklist entities |
| `/letterdamage <damage_type>` | Set the damage type of the held conversion letter |
| `/letterback [player]` | Retrieve a player's bound letter/binder item entities |
| `/lettercolor [red green blue]` | Query / set the glowing color |
| `/letterenchanted [true\|false\|glowing <p>\|binding <p>\|conversion <p>]` | Query / toggle the enchanted book injection and adjust the three enchantment probabilities |
| `/letterclean ...` | Query / toggle / configure scheduled cleanup (including `allbinding` / `allnormal` bulk cleanup) |
| `/letterdelay [tick]` | Query / set the respawn restore delay |
| `/letterresistance ...` | Query / toggle / set the resistance cap |
| `/lettervanish ...` | Query / toggle the forced vanishing mechanic |
| `/letterbinding ...` | Manage binding whitelist and modify bound UUID |
| `/letterstorage ...` | Capture an entity, swap items, export NBT |