Item attributes and changer

# Item Attributes

**Version:** 1.4.1-legacy · **Minecraft:** 1.20.1 · **Loader:** Forge

## What this mod does

Item Attributes lets players (and admins) customize *any* item — vanilla or modded — using XP
levels as currency. Everything is stored in the item's own NBT, so no new items, blocks, or
recipes are added; a plain diamond sword or leather boots can become a build-defining piece of gear.

The system has four layers, roughly in order of power:

1. **Attributes** — set attack damage, attack speed, attack range, or armor to an exact value.
2. **Effects** — attach vanilla or modded potion effects that trigger while held, while worn as
   armor, or on a melee hit.
3. **Rank** — every attribute and effect on an item counts as one "modification." Enough of them
   pushes the item's rank from E all the way to **SSS**.
4. **Flux Cores** — once an item hits SSS rank, it can be assigned one of 12 rare cores (7 for
   weapons, 5 for armor), each with its own passive kit, and in several cases, unique abilities.

Everything is priced in XP **levels**, and almost every number in the system — costs, drop rates,
cooldowns, damage, terrain destruction — is server-configurable.

---

## Progression

### Rank

`RankUtil` counts how many real modifications are on an item (Damage/Speed/Range/Armor each count
as one if set, plus one per Hold/Armor/Hit effect):

| Modifications | Rank |
|---|---|
| 0 | E |
| 1–2 | D |
| 3–4 | C |
| 5–6 | A |
| 7–9 | S |
| 10+ | **SSS** |

Reaching SSS for the first time on an item automatically rolls it a random Flux Core (from the
correct pool for that item's type — weapon cores for weapons/tools, armor cores for armor pieces)
and grants the **God Forge** advancement.

### Cost

Every modification costs XP levels, computed per-attribute and multiplied by a global cost
multiplier (default 2x):

- Damage/Speed/Range/Armor: cost scales with the requested value (per-point cost, configurable).
- Hold/Armor/Hit effects: base cost per tier-1 vanilla effect (default 30), doubled for modded
  effects, and multiplied per amplifier tier above 1 (default 3x per tier).
- Setting a specific Flux Core costs a flat amount (default 500); rolling a random one costs less
  (default 50).
- An optional **max level cost cap** can clamp any single modification's cost down to a ceiling,
  regardless of how expensive the raw calculation would otherwise be.

---

## Weapon Flux Cores

Rolled or set on whatever is in the **mainhand or offhand** slot. Only one weapon core is active
per item; Godfather can only exist once server-wide (see below).

| Core | Default roll weight | Passive kit |
|---|---|---|
| Everchosen | 35% | Regeneration II while held. On hit: true damage (bypasses armor/resistance/invulnerability). |
| Juggernaut | 25% | Resistance II, Health Boost II, Absorption II while held. On hit: weaker true-damage explosion. |
| Angelic | 15% | Regeneration II + a 37-block "godly pressure" aura (Slowness/Wither on nearby hostiles). Hits deal true damage. |
| Reaper | 14.79% | Strength V, Speed V + godly pressure aura. Hits deal 1.5x true damage and cap the victim's HP below their max. |
| Celestial | 0.1% | Regeneration + Resistance, slower flight, 25% chance incoming damage phases through. **Shift+attack**: freeze time for 15s (cooldown). **Alt+attack**: Divide — a long-range true-damage slash that clears a line of terrain. |
| Primordial | 0.1% | Same passives as Celestial, plus a "Primordial Rage" kill-counter that scales true-damage bonus over time (up to +50%), plus the same godly pressure aura Celestial/Godfather get. **Shift+attack**: Demonic Claw slash. **Alt+attack**: Draconic Shockwave — a huge terrain-clearing AoE that costs the caster 95% of their own HP. |
| Godfather | 0.01% (singleton — only one can exist at a time server-wide) | Every passive at once (Resistance, Absorption, Speed, Strength, Regeneration, Haste), golden wings, halo, divine-day aura, homing Truth Seeking Orbs, 3x true-damage hits. **Shift+attack**: Almighty Slash. **Alt+attack**: Almighty Push — the most destructive ability in the mod. |

**True damage** in all cases bypasses armor, resistance, and invulnerability frames. Ultimate
abilities (Divide, Demonic Claw, Draconic Shockwave, Almighty Slash, Almighty Push) each have their
own independently configurable cooldown and damage value, and Almighty Slash/Push broadcast a big
bold title to every player's screen when triggered.

Terrain-clearing abilities respect a global destruction toggle and percentage scale (see Config).

### Godfather's singleton rule

Only one Godfather-cored item can exist at any time across the whole server. Setting Godfather on a
new item clears the claim from wherever it previously was. If the item is ever lost/destroyed
without going through the mod's own clear logic, an admin can force-reset the claim with
`/itemattr forcerest godfather`.

---

## Armor Flux Cores

A completely separate pool from weapon cores, rolled/set on **helmet/chestplate/leggings/boots**.
Stat bonuses are applied as real attribute modifiers tied to what's currently equipped — take a
piece off and the bonus disappears that same tick, no lingering potion effect.

| Core | Default roll weight | Highlights |
|---|---|---|
| Flux | 55% | More armor + toughness, periodic durability self-repair, Speed I while worn. |
| Nexus | 25% | Purple particles. Bigger attack/defense/mobility boost. Immune to fall, fire, and drowning damage. |
| Astralis | 15% | Red particles. Toxic + environmental immune. Big stat boost. 5% chance of 1 second of invincibility after being hit. |
| Zenith | 4.9% | Black particles. Toxic + environmental immune. Superhuman stats. 25% damage reduction per piece worn, capped at 55%. |
| Omniframe | 0.1% | Golden particles + a 25-block golden ground aura. Unbreakable armor piece. God-like stats. 75% damage reduction per piece, capped at 75%. Toxic + environmental immune. Grants the **Chosen by Fate** advancement. |

Weapon cores never work on armor pieces and armor cores never work on weapons/tools — enforced
both in the GUI (buttons gray out) and server-side (can't be bypassed by a modified client).

### Omniframe extras

- **Repel** (keybind, default **R**): a sonic-boom knockback burst. Requires at least one
  Omniframe piece. Scales with how many pieces you're wearing (1–4):
  - Radius: 8 → 32 blocks.
  - Knockback strength increases.
  - Cooldown: 45s at 1 piece down to 5s at a full 4-piece set (both ends configurable).
  - Anything launched takes **true damage** in a small explosion when it lands back on the ground
    (catches anything else standing nearby too).
  - The caster gets 5 seconds of invincibility.
- **Bonus XP**: wearing Omniframe multiplies all XP gains — 1 piece = 2x, scaling linearly to a
  full 4-piece set = 5x.

---

## Global Item Templates

Server-wide default attributes/cores for **every instance** of an item type — e.g. "all diamond
swords start with 15 attack damage." Configured with `/itemattr global` or directly in the config.

- Applies without ever touching an item's NBT, so it never counts as a "modification" and never
  affects rank.
- The moment a player explicitly sets their own value for that same attribute/core on their
  specific item (via command or menu), their value takes priority for that item from then on — the
  global default keeps applying to every other untouched instance of that item type.
- Supports Damage, Speed, Range, Armor, a default weapon core, or a default armor core.
  Godfather can't be set as a global default since only one can ever exist.
- The mod automatically validates item/attribute compatibility (e.g. you can't set `armor` on a
  sword, or a weapon `core` on a helmet).

---

## Commands

All commands are under `/itemattr`. Commands marked **(op)** require permission level 2+.

| Command | Description |
|---|---|
| `/itemattr menu` | Opens the Item Forge GUI for the held item. Blocked for non-ops if `allowSurvivalMenu` is disabled. |
| `/itemattr info` **(op)** | Shows every modification on the held item: rank, attributes, cores, and effect lists. |
| `/itemattr clear` **(op)** | Clears every modification (attributes, effects, both cores) from the held item. |
| `/itemattr damage <value>` **(op)** | Sets the held item's attack damage. |
| `/itemattr speed <value>` **(op)** | Sets the held item's attack speed. |
| `/itemattr range <value>` **(op)** | Sets the held item's attack range. |
| `/itemattr armor <value>` **(op)** | Sets the held item's armor value. |
| `/itemattr effect add/remove/clear <effect> [level] [seconds]` **(op)** | Manage Hold Effects (apply while holding/wearing). |
| `/itemattr armoreffect add/remove/clear <effect> [level]` **(op)** | Manage Armor Effects (apply while worn in an armor slot). |
| `/itemattr hiteffect add/remove/clear <effect> [level] [seconds]` **(op)** | Manage Hit Effects (apply to whatever you melee). |
| `/itemattr fluxcore set/clear <core>` **(op)** | Force-set or clear the held item's weapon Flux Core (bypasses SSS/cost checks; rejects armor items). |
| `/itemattr armorfluxcore set/clear <core>` **(op)** | Force-set or clear the held item's armor Flux Core (rejects non-armor items). |
| `/itemattr block fluxcore/armorcore <core>` **(op)** | Adds a core to the runtime ban list (on top of the config ban list). |
| `/itemattr unblock fluxcore/armorcore <core>` **(op)** | Removes a core from the runtime ban list. |
| `/itemattr forcerest godfather` **(op)** | Deletes every loaded Godfather item (inventories, ender chests, dropped items) and unlocks a new claim. |
| `/itemattr destruction <percent>` **(op)** | Live-adjusts the terrain-destruction scale for ultimate abilities (also updates the config). |
| `/itemattr global set damage/speed/range/armor <item> <value>` **(op)** | Sets a global default attribute for every instance of an item type. |
| `/itemattr global set core <item> <core>` **(op)** | Sets a global default weapon core for an item type (Godfather rejected). |
| `/itemattr global set armorcore <item> <core>` **(op)** | Sets a global default armor core for an item type. |
| `/itemattr global clear <item>` **(op)** | Removes all global template overrides for an item type. |
| `/itemattr global list` **(op)** | Lists every configured global item template. |
| `/itemattr particles wing/sparks/goldypressure/halo/truthorbs/armorcore <true\|false>` | Per-player toggle for that core's particle effect (only usable while holding/wearing a core that has it). |
| `/itemattr truthorbs attack <true\|false>` | Toggles Godfather's homing Truth Seeking Orb auto-attack. |
| `/itemattr godlypressure effects <true\|false>` | Toggles the held item's godly-pressure aura on/off without removing the core. |

---

## Keybinds

Both are registered under an "Item Attributes" category in Controls:

| Action | Default key | Notes |
|---|---|---|
| Open Item Forge Menu | **M** | Instantly opens `/itemattr menu`. Actually sends a request to the server, which applies the same `allowSurvivalMenu` gate as the command — the keybind can't bypass an op-only lockdown. |
| Omniframe Repel | **R** | Only usable with at least one Omniframe armor piece equipped. |

Ultimate weapon-core abilities aren't separate keybinds — they piggyback on vanilla's attack/use
keys: **Shift+Attack**, **Shift+Use**, and **Alt+Attack** (see the Weapon Flux Cores table above
for what each core does with them).

---

## Configuration

Generated at `config/itemattributes-common.toml` on first launch. All values below are defaults.

### `[costs]`
| Key | Default | Meaning |
|---|---|---|
| `costMultiplier` | 2.0 | Global multiplier applied to every computed cost. |
| `moddedEffectMultiplier` | 2.0 | Multiplier for effects from a non-vanilla namespace. |
| `effectTierMultiplier` | 3.0 | Multiplier per amplifier tier above 1. |
| `vanillaEffectBaseCost` | 30 | Base cost for tier-1 of a vanilla effect. |
| `damageCostPerPoint` | 10.0 | Cost per point of requested attack damage. |
| `speedCostPerPoint` | 15.0 | Cost per point of requested attack speed. |
| `rangeCostPerPoint` | 50.0 | Cost per point of requested attack range. |
| `armorCostPerPoint` | 10.0 | Cost per point of requested armor. |
| `weaponFluxCoreCost` | 500 | Base cost to set a specific weapon core. |
| `armorFluxCoreCost` | 500 | Base cost to set a specific armor core. |
| `randomFluxCoreCost` | 50 | Base cost to roll a random core (either pool). |
| `maxLevelCostCap` | -1 | Clamps any single modification's cost to this ceiling. -1 disables the cap. |

### `[survival]`
| Key | Default | Meaning |
|---|---|---|
| `allowSurvivalMenu` | true | If false, only ops can open the menu or have modification packets processed. |

### `[weaponFluxCores]` / `[armorFluxCores]`
| Key | Default | Meaning |
|---|---|---|
| `bannedCores` | [] | Cores that can't be rolled/set by survival players (admins can still force-set). |
| `weights.*` | see tables above | Per-core roll weight. |

### `[abilities]`
| Key | Default | Meaning |
|---|---|---|
| `reaperDamageMultiplier` | 1.5 | Reaper's true-damage multiplier. |
| `godfatherDamageMultiplier` | 3.0 | Godfather's true-damage multiplier. |
| `primordialRagePercentPerKill` | 1.25 | % true-damage bonus per Primordial Rage kill. |
| `primordialRageMaxPercent` | 5000.0 | Cap on Primordial Rage's bonus %. |
| `juggernautExplosionDamage` | 4.0 | Juggernaut's on-hit explosion damage. |
| `juggernautExplosionRadius` | 2.0 | Juggernaut's on-hit explosion radius. |
| `celestialDivideDamage` | 50.0 | Celestial's Divide ability damage. |
| `primordialClawDamage` | 50.0 | Primordial's Demonic Claw damage. |
| `primordialShockwaveDamage` | 250.0 | Primordial's Draconic Shockwave damage. |
| `godfatherSlashDamage` | 150.0 | Godfather's Almighty Slash damage. |
| `godfatherPushDamage` | 500.0 | Godfather's Almighty Push damage. |
| `godfatherOrbDamage` | 25.0 | Godfather's Truth Seeking Orb damage. |
| `omniframeRepelImpactDamage` | 30.0 | True damage dealt when a Repel-launched entity lands. |

### `[destruction]`
| Key | Default | Meaning |
|---|---|---|
| `terrainDestructionEnabled` | true | Master on/off switch for ultimate abilities clearing terrain. |
| `destructionScalePercent` | 100.0 | Scales terrain-clearing radius/length/depth (0–200%). Live-adjustable with `/itemattr destruction`. |

### `[cooldowns]` (all in seconds)
| Key | Default |
|---|---|
| `celestialFreezeCooldownSeconds` | 120 |
| `celestialDivideCooldownSeconds` | 30 |
| `primordialClawCooldownSeconds` | 30 |
| `primordialShockwaveCooldownSeconds` | 300 |
| `godfatherSlashCooldownSeconds` | 20 |
| `godfatherPushCooldownSeconds` | 300 |
| `omniframeRepelCooldownSeconds` | 45 (at 1 Omniframe piece) |
| `omniframeRepelCooldownMinSeconds` | 5 (at a full 4-piece Omniframe set) |

### `[materialRequirements]`
A list of strings, one per rule: `"ACTION:modid:itemid:count"`, e.g.
`"SET_FLUX_CORE:minecraft:nether_star:1"` requires 1 Nether Star (in addition to XP) to set a
weapon core. Valid `ACTION` values: `SET_DAMAGE`, `SET_SPEED`, `SET_RANGE`, `SET_ARMOR`,
`ADD_HOLD_EFFECT`, `ADD_ARMOR_EFFECT`, `ADD_HIT_EFFECT`, `SET_FLUX_CORE`, `SET_ARMOR_FLUX_CORE`,
`RANDOM_FLUX_CORE`, `RANDOM_ARMOR_FLUX_CORE`.

### `[globalItemTemplates]`
A list of strings, one per item: `"itemid;Key=Value;Key=Value..."`, e.g.
`"minecraft:diamond_sword;Damage=15;Core=reaper"`. Valid keys: `Damage`, `Speed`, `Range`, `Armor`
(numbers), `Core` (weapon flux core, Godfather rejected), `ArmorCore` (armor flux core). Easier to
manage with `/itemattr global` in-game than by hand-editing this list.

---

## Notes for admins

- Every number in this mod is tunable without recompiling — see the Configuration section above.
- The rank/SSS system and Flux Core gacha are the only things gated by cost and progress; global
  item templates and admin force-set commands bypass that entirely by design (they're
  admin/server decisions, not player grinding).
- Terrain-clearing ultimate abilities don't check land claims or world protection plugins — if
  griefing is a concern, use `terrainDestructionEnabled=false` or a low `destructionScalePercent`.
- Cooldowns, roll weights, and ban lists reload from the config file; runtime `/itemattr block`
  and `/itemattr destruction` changes are written back into the config automatically.