Enchanter Letter

================================================================
Enchanter Letter
Minecraft 1.21.1 / 1.20.1 Mod Introduction
Supported Loaders: NeoForge / Forge / Fabric (multiversion sync)
Current Version: 3.1.0
================================================================

Open source: https://github.com/chiyouhuaji/Enchanterletter

----------------------------------------------------------------

I. Mod Overview
----------------------------------------------------------------
This mod adds a series of "Enchanter Letters" and "Letter Binders".
Letters are beneficial items carried in the inventory or accessory
slots: when the holder deals a specified type of damage, the letter
provides damage amplification based on its level (by default it works
on UsefulMagic's usefulmagic:magic damage, but any registered damage
type can be added via config files and commands). Letters can also be
bound to a player and enchanted with "Magic Conversion" to change the
damage type, and they support integration with other accessory mods
(Curios / Accessories).

Letters are non-stackable items (each occupies one slot) and can be
placed in a Letter Binder for unified management.

II. Types of Letters and Growth Methods
----------------------------------------------------------------
Each letter has a "Level (Lv)"; higher levels give higher damage
amplification. Levels are earned by performing the corresponding
actions:

  - Experience Letter (experience): gain 1,000 experience points to
    level up; each level adds +10% damage.
  - Kill Letter (kill): kill 50 mobs to level up; each level adds +10%.
  - Fishing Letter (fishing): catch 100 fish to level up; each level
    adds +10%.
  - Travel Letter (travel): walk 5,000 blocks / fly 20,000 blocks to
    level up; each level adds +10%.
  - Treasure Letter (treasure): open 20 natural chests to level up;
    each level adds +10%.
  - Time Letter (time): based on server world time (level up every
    3,600 seconds, +10% per level); unrelated to player playtime.
  - Tenacity Letter (tenacity): take 10,000 damage to level up; each
    level adds +10%.
  - Hero Letter (hero): win 1 raid to level up; low levels give +10%
    per level, from level 4 onward +20% per level; item progress is
    split into "Low-Tier Raids / High-Tier Raids" (sum = total raid
    victories; low-tier = victories before reaching the high-tier
    threshold, high-tier = victories after the threshold).
  - Stage Letters (stage_1 ~ stage_10): fixed-multiplier letters,
    ranging from 100%, 200%, 300% … up to 1,000%; multipliers can be
    modified in the config.
  - Custom Letter (custom): level is always 0 and does not grow;
    damage multiplier, armor value, armor toughness, and resistance
    boost all default to 0 and can be manually set.

(The values above are the default config file values and are fully
adjustable, except for custom letters. The default values for the
eight growth-type letters are only used as initial values when a new
letter is created (creative inventory / /give); the actual values for
each letter are stored independently in that letter's own data.)

[Damage Amplification Application Rules]
  - Placing a letter in the inventory (or accessory slot / binder)
    counts as being carried; no need to hold it.
  - Amplification targets: damage types listed in the config entry
    default_bonus_damage_types (default usefulmagic:magic); any
    registered damage type can be added.
  - Effective multiplier = Letter Level x Increment per level (the
    item tooltip and HUD display the current actual multiplier).
  - Unenchanted letters apply directly to the default damage type;
    letters enchanted with "Magic Conversion" calculate based on the
    converted damage type.

III. Stacking Rules (stacking_rules)
----------------------------------------------------------------
  - allow_multiple_letters (default false):
      false - regardless of how many letters are carried, only the
              highest-multiplier letter takes effect;
      true  - the multipliers of all letters are summed.
  - allow_same_letters (default false): two letters that are identical
    in every respect except conversion state (same item, same
    multiplier, same damage type, same enchantment state); false means
    only one applies, true means each applies.

IV. Binding System
----------------------------------------------------------------
While holding a letter (or an empty Letter Binder), sneak + hold
right-click for ~2 seconds to bind/unbind: after binding the item
tooltip shows "Bound: <player name>".

When the bound player holds the letter it works normally; if someone
else picks up / holds your bound letter, it will not work and will be
automatically "ejected" as a dropped item (checked every second in
inventory, Curios / Accessories slots, and binder contents).

V. Dropped Item Protection
----------------------------------------------------------------
All letters and binders dropped as items are protected:
  - Immune to explosions, cactus, and all other damage;
  - No gravity, velocity constantly zero, remain stationary (not
    pushed by water);
  - Cannot be sucked into hoppers / hopper mines.

VI. Letter Binder
----------------------------------------------------------------
  - Usage is identical to the vanilla shulker box (right-click to
    store/retrieve, inventory interaction, hover to view contents);
  - Letters are non-stackable; each letter occupies one slot, vanilla
    box holds up to 64 letters;
  - Hover correctly shows letter count / capacity progress;
  - When empty, sneak + hold right-click to bind/unbind the binder
    itself;
  - When not empty, sneak right-click to release all contents at once;
  - Letters inside the binder are considered "carried" and participate
    normally in damage amplification and ejection checks.

VII. Magic Conversion Enchantment
----------------------------------------------------------------
After enchanting a letter with "Magic Conversion" (magic_conversion):
  - The letter's amplification no longer binds to the default damage
    type but is calculated based on the specified damage type;
  - Use /letterdamage <damage_type> to set the conversion damage type;
  - In creative mode, right-clicking an enchanted book with this
    enchantment opens a client UI to input the damage type ID directly;
  - Conversion calculation groups by damage type: letters of the same
    type have their multipliers combined and are resolved together with
    a delay; different conversion types do not interfere with each
    other.

[Special Conversion / Special Resistance (NBT Damage Filtering)]
Letters can, via /letterfilter, write two kinds of "filtered damage
types" into their own data; the two are independent and enabled by
default (not affected by the magic conversion enchantment toggle):

  - Special Conversion (data key letter_filter_damage): assigns a
    specific "triggerable damage type" to that letter. When the holder
    deals that type of damage, the letter works as usual: unenchanted
    letters give direct damage boost for that type; enchanted "Magic
    Conversion" letters convert that damage into the letter's
    designated conversion target (shown in the description and HUD to
    the right of the arrow). If the NBT is present, the letter only
    works for that damage type (overriding the config whitelist);
    without the NBT it follows the config whitelist.
  - Special Resistance (data key letter_filter_resistance): assigns a
    whitelist of "damage types reduced" for that letter's resistance
    boost. With the NBT present, the letter's resistance only applies
    to those damage types; without it, it applies to all damage. The
    overall resistance boost feature is still controlled by the global
    config switch letter_resistance.enabled.

Use /letterfilter (permission 2/3/4, operates on the letter in the
main hand):
  - /letterfilter damage <damage_type>       Set special conversion
                                             damage type
  - /letterfilter damage clean               Clear special conversion
  - /letterfilter resistance <damage_type>   Set special resistance
                                             damage type
  - /letterfilter resistance clean           Clear special resistance
<damage_type> is auto-completed from the registry of registered damage
types. When carrying multiple different letters, each NBT filter works
independently.

Display: in the letter's description, special conversion is marked in
purple as "Special Conversion" (showing the NBT damage type; enchanted
conversion also shows the conversion target); special resistance is
marked in purple as "Special Resistance" (showing its damage type).
HUD damage-gain mode shows: <Letter Name Lv.x (Multiplier) Special Conversion Damage Type -> Conversion Target> (left of arrow = actual
multiplier, right of arrow = conversion target; empty if no conversion
enchantment). Resistance-boost mode shows the damage type for special
resistance.

VIII. Accessory Slot Compatibility
----------------------------------------------------------------
  - NeoForge / Forge: Curios accessory slots (including slots added by
    other Curios-compatible mods; this mod allows letters / binders in
    those slots);
  - Fabric: Accessories and Curios (Fabric);
  - All are optional: if the corresponding mod is not installed, there
    is no impact; letters placed in accessory slots work the same and
    also participate in binding/ejection checks.

IX. HUD Display
----------------------------------------------------------------
The top-left corner of the screen continuously shows the list of
currently active letters (item name, level, actual multiplier;
conversion-enchanted letters also show the conversion damage type).
Grey text indicates letters not currently active (only the highest
multiplier is active, others are overridden); white text indicates
active letters. Default key N toggles the HUD (key can be changed in
client config).

X. Configuration Files
----------------------------------------------------------------
Generated in the config/ folder on first launch.

[1. config/enchanter_letter.json] (server / main config)
{
  "experience_letter":  { "exp_per_level": 1000.0, "growth_per_level": 0.1 },
  "kill_letter":        { "kills_per_level": 50,   "growth_per_level": 0.1 },
  "fishing_letter":     { "fish_per_level": 100,   "growth_per_level": 0.1 },
  "travel_letter": {
    "walk_distance_per_level": 5000.0,
    "fly_distance_per_level":  20000.0,
    "walk_growth_per_level":   0.1,
    "fly_growth_per_level":    0.1
  },
  "treasure_letter":    { "opens_per_level": 20,    "growth_per_level": 0.1 },
  "time_letter":        { "seconds_per_level": 3600.0, "growth_per_level": 0.1 },
  "tenacity_letter":    { "damage_per_level": 10000.0, "growth_per_level": 0.1 },
  "hero_letter": {
    "victories_per_level": 1,
    "growth_low_levels": 0.1,
    "growth_high_levels": 0.2,
    "high_level_start": 4
  },
  "stage_letters": { "multipliers": [1,2,3,4,5,6,7,8,9,10] },
  "stacking_rules": {
    "allow_multiple_letters": false,
    "allow_same_letters": false
  },
  "magic_conversion": {
    "interval_seconds": 0.5,
    "blacklist_entity_names": ""
  },
  "letter_bonus": {
    "default_bonus_damage_types": "usefulmagic:magic"
  },
  "letter_glowing": {
    "default_red": 0,
    "default_green": 0,
    "default_blue": 0
  },
  "letter_cleanup": {
    "enabled": true,
    "interval_seconds": 600.0,
    "target_uuids": ["00000000-0000-0000-0000-000000000000"],
    "clean_all_binding": false,
    "clean_all_normal": false
  },
  "letter_respawn": {
    "restore_delay_ticks": 20
  },
  "letter_enchanted": {
    "enabled": true,
    "glowing_chance": 0.1,
    "magic_binding_chance": 0.08,
    "magic_conversion_chance": 0.0
  }
}

Note:
  - After modifying the config file, restart the game/server for
    changes to take effect;
  - Command-based changes (/lettermulti, /lettertype, /letterentity,
    etc.) apply instantly and are written back to the file; see section
    X for /letterset write-back rules (when the main hand is empty the
    command writes to the config, otherwise it writes directly to the
    letter's data). The default values for the eight growth-type
    letters are now only used as the "initial default values" when a
    new letter is created; once a letter is obtained via creative
    inventory or /give, its own data stores its values, which are then
    read and calculated independently per item. The config defaults no
    longer affect existing letters, and in-game commands cannot modify
    those defaults anymore.

[2. config/enchanter_letter_client.json] (client config)
{
  "hud_visible": true,
  "hud_toggle_key_code": 78
}

XI. Commands (all require permission level >= 2, i.e., usable by ranks 2/3/4)
----------------------------------------------------------------
  /lettermulti [true|false]
       Toggle "multiple letters active simultaneously" (no argument
       flips current value).

  /lettersame [true|false]
       Toggle "identical letters each apply" (no argument flips).

  /letterset <type> <value>
       Modify growth values of a letter; <type> supports
       (tab-completable):
         experience|kill|fishing|travel|treasure|time|tenacity|hero
         custom
         stage_1 ~ stage_10
        supports (tab-completable):
         time / time2 / damage / damage2
         armor / armor2 / toughness / toughness2 / resistance / resistance2
       The per-level parameters for the eight growth-type letters are
       stored in the letter item's own data: when the command is run,
       three cases are handled based on the main hand - if the main
       hand is empty (or the executor isn't a player), the parameters
       are written to the config file and saved (restoring the old
       behavior); if the main hand holds a letter of the specified
       type, the parameters are written directly to that letter's data,
       and the letter's level, multiplier, armor, toughness, and
       resistance boost are recalculated immediately, with the item
       tooltip and HUD reflecting the new values; if the main hand
       holds something else, the command does nothing. Config defaults
       are only used for newly created letters (creative inventory /
       /give) and no longer participate in subsequent calculations.
       Examples:
         /letterset time damage 0.05        (time letter damage to 5%)
         /letterset stage_4 damage 2.5      (stage 4 multiplier to 250%)
         /letterset stage_4 armor 5.5       (stage 4 armor value 5.5)
         /letterset stage_2 resistance 0.3  (stage 2 resistance 30%)
         /letterset custom damage 1.5       (custom damage multiplier 150%)
         /letterset custom armor 4.0        (custom armor value 4.0)
         /letterset custom resistance 0.2   (custom resistance 20%)
       Stage letters are fixed-value items: each stage is configured
       independently (stage_N directly specified), not using a numeric
       sequence; armor/toughness are raw values, resistance is a
       reduction ratio; modifications to stage letters are still
       written back to the config.
       Custom letters do not grow by count/level: values are written
       directly to the item's data and not to the config; they must be
       held in the main hand to apply.

  /lettertype add|delete <damage_type>
       Add or remove a damage type from default_bonus_damage_types.
       The add tab-completion lists all registered damage types not
       already added; delete lists the currently configured ones.
       Example: /lettertype add minecraft:magic

  /letterentity add|delete <entity_type>
       Add or remove an entity type from
       magic_conversion.blacklist_entity_names (entities on the
       blacklist are excluded from magic conversion).
       Add tab-completion lists all registered entity types not
       already added; delete lists the current blacklist.
       Example: /letterentity add minecraft:warden

  /letterdamage <damage_type>
       Set the conversion damage type for the held letter enchanted
       with "Magic Conversion".

  /letterfilter damage|resistance <damage_type>|clean
       Set or clear "Special Conversion / Special Resistance" NBT
       filter damage types for the held letter:
         /letterfilter damage <damage_type>
         /letterfilter damage clean
         /letterfilter resistance <damage_type>
         /letterfilter resistance clean
       <damage_type> auto-completes from the registry; works even
       without the enchantment (see section VII).

  /letterback [player]
       Search all loaded dimensions for dropped items and teleport the
       bound letters/binders of the command executor (no argument) or
       the specified online player (argument, tab-complete) to that
       player's location, zero velocity, instantly collectible.
       Example:
         /letterback                  (recall your own letters)
         /letterback Steve            (recall Steve's letters)

  /lettercolor <red> <green> <blue>
       Set the "glowing" RGB color of the held letter or binder (each
       channel 0-255, e.g., /lettercolor 255 0 0 = red; 0 0 0 = white).
       When multiple glowing items are carried, the displayed color is
       the average of all item colors.

  /letterenchanted
       Query the enchantment book addition logic switch and three
       enchantment chances.
  /letterenchanted true|false
       Enable/disable the enchantment book addition logic.
  /letterenchanted glowing <0.0~1.0>
       Set the chance for the glowing enchantment to appear on books.
  /letterenchanted binding <0.0~1.0>
       Set the chance for the magic binding enchantment to appear on
       books.
  /letterenchanted conversion <0.0~1.0>
       Set the chance for the magic conversion enchantment to appear on
       books.
       (The three chances are independent; one book may contain
       multiple enchantments.)

  /letterclean
       Query the cleanup feature status (toggle/interval/list).
  /letterclean on|off
       Toggle timed cleanup.
  /letterclean time <seconds>
       Set cleanup interval (minimum 1 second).
  /letterclean add <UUID>
       Add a UUID to the cleanup list.
  /letterclean delete <UUID>
       Remove a UUID from the cleanup list.
  /letterclean add allbinding
       Enable "clean all bound letters/binders drops".
  /letterclean delete allbinding
       Disable "clean all bound letters/binders drops".
  /letterclean add allnormal
       Enable "clean all unbound letters/binders drops".
  /letterclean delete allnormal
       Disable "clean all unbound letters/binders drops".
  /letterclean all
       Clean all letters/binders drops.
  /letterclean all confirm
       Execute cleanup after a second confirmation.
  /letterclean uuid <UUID>
       Clean drops bound to the specified UUID.
  /letterclean uuid <UUID> confirm
       Execute cleanup after a second confirmation.

  /letterdelay
       Query the current respawn return delay (game ticks).
  /letterdelay <tick>
       Set the respawn return delay (game ticks, 0-6000, default 20):
       After a player respawns, wait this duration before executing
       (1) magic-bound item "force re-equip original slot and
       overwrite" (prevents failure if the slot isn't loaded yet) and
       (2) disappearance-curse item scan-delete (immediately delete on
       detection). Config key: letter_respawn.restore_delay_ticks.

  /letterstorage nbt [<uuid|player>]
       Without a target argument: output all data of the currently
       captured entity (see section XIV for the no-argument form);
       With a target argument: resolve the target (UUID or online
       player name, tab-complete), lock it as the captured entity, and
       output its full data - the target must exist and be loaded,
       otherwise an error is thrown.

  /lettereffect add <slot> <effect> <seconds> <amplifier> <hideParticles> <loopMode> <looptime> [<looptime2> …]
  /lettereffect delete <slot>
  /lettereffect ls
       Manage potion-effect entries of the "main-hand magic letter"
       (entries are stored in the letter's own data, default empty, no
       config file needed; must be executed while holding a magic
       letter in the main hand, permission 2/3/4):
         add     Write/overwrite an effect entry in the specified slot
                 (slot >= 1): if the slot already has an effect,
                 overwrite its contents (keeping the slot number),
                 otherwise create a new entry in that slot.
                 Parameters: slot, effect (registered potion effect id,
                 tab-complete, e.g. minecraft:speed), seconds (effect
                 duration), amplifier (0 = level I), hideParticles
                 (true/false), loopMode (daytime | gametime), and one
                 or more trigger times (looptime… up to 8).
         delete  Delete the effect entry at the given slot (that slot
                 number can then be reused by add).
         ls      List all current effect entries:
                 #<slot> <effect> <sec> <level> <hideParticles>
                 <mode> <times>.

Note: apart from /letterset, the config changes made by the commands
above apply instantly and are written back to the config file;
/letterset writes growth-type letters to the config when the main hand
is empty (or the executor isn't a player), writes to the held letter's
data when holding a matching letter, and does nothing otherwise;
custom letters write directly to the held item's data; stage_1 ~
stage_10 still write back to the config; /letterset, /lettertype, and
/letterentity all support tab-completion.