Fiw Custom Items

[1.2.0] - New abilities and deeper customization

Added

• teleport_behind — a standalone blink to a safe spot behind your target (behindDistance), with optional armor-piercing damage (ignoreArmor true/false/percent), particles, sound and a message. Works from on_attack (the struck target) or on_right_click (the entity under the crosshair within targetRange).
• lightning_rain — mark a circle at the crosshair (targetRange, radius), telegraph it, then rain bolts down on a fully custom schedule. Give a groups array of {count, delayTicks} to place bolts exactly (one, then one 10t later, then three together), or omit it for count bolts spread over waves waveInterval apart. Each bolt is cosmetic by default and damages everything within aoeRadius of its strike. Example: examples/items/stormcaller_staff.json
• lightning_ray — a straight line of bolts that march forward from your look direction, one every boltInterval ticks up to range, each landing on the ground and damaging within aoeRadius. A "run or get fried" lane.
• repair — a repair kit: hold it and right-click while a damaged item is in your other hand (or armor) to restore its durability by repairAmount (+ optional repairPercent) or fullRepair. The kit is spent per use (shrinks by one, or burns its own durability with useKitDurability). An optional targets filter (items/bases/tags) limits what it mends.
• homing_bolt — a projectile that curves toward the nearest enemy as it flies, turning at most turnRate degrees per tick and re-aiming within trackRange; deals damage in aoeRadius on contact or at range.
• aegis_shield — raise an on-demand barrier that swallows incoming hits for duration ticks. A pool of damage is absorbed; each hit is eaten whole while the pool lasts and the hit that drains it shatters the barrier. A real damage gate, not extra hearts. Damage that bypasses invulnerability (/kill, the void) and the curse system's drain are never absorbed.
• stun_strike — true hard crowd-control: on hit the target is locked for duration ticks (a per-tick sweep zeroes its movement while stacked Slowness / Weakness / Mining Fatigue stop it attacking or mining). A full freeze on mobs; a hard root and near-total disable on players.
• apply_effect — the general-purpose potion-effect tool: name any vanilla effect and drop it on the caster or the target, for any trigger, with duration / amplifier / ambient / particles.
• Skill-based ritual/mystical abilities — abilities that reward execution over spam: blood_debt (pay HP to bank charges, spend them on hits before the debt collects and backlashes), void_rift (a telegraphed rift that drags enemies in, then detonates — you cast it before they arrive), phase_shade (blink forward leaving a shade, re-cast to snap back in the window), gravity_singularity (a hold-to-charge pull scaled by charge time, with an optional self-cost), and a set of channelled abilities — hold sneak and stand still while a progress bar fills, broken by moving or taking a hit: exsanguinate (bleed into a blood nova), blood_circle (channel a ritual: AoE damage + party buffs), and marionette (grab and puppet a mob while you're rooted). Plus a timing/positioning set: riposte (parry a hit just before it lands to negate + reflect it, then land an empowered strike), sanguine_tether (mark and bind a target to split your incoming damage onto it), ley_line (two anchors + a damaging/healing line between them), and altar_sacrifice (execute a low-HP target for a boon). Finally two execution-heavy casts: runic_sequence (draw a spell by clicking in a look-pitch pattern — up/down/level — in order) and heartbeat_cast (click on the beat of a steady pulse to empower the burst). See Item Config Docs.
• Multi-block mining (mining root field) — turn a tool into a vein-miner, 3×3 hammer, or forward tunnel-borer. vein flood-fills connected matching blocks (ores, or logs for a tree-feller), area breaks a plane facing you, tunnel extends it forward. Extra blocks break through your own game mode so drops, XP, Fortune/Silk Touch and durability all behave normally; filter by whitelist/tags, cap with maxBlocks, and hold sneak to mine one block. The tool never snaps mid-vein (unbreakable/infinite tools mine whole veins free). See Multi-block Mining.

Changed

• Attribute lock — a Fiw item's configured attributes are now re-stamped after any anvil or smithing-table operation, so a rename, repair, book-enchant, netherite upgrade or trim can never leave it with attributes other than the ones its config declares. Imbued attribute bonuses are replayed on top, so player-earned imbuements survive the station.
• enchanting.allowEnchant — new per-item flag. false blocks adding enchantments at the anvil (books, combining enchanted copies) while still allowing rename and repair — the inverse of allowRename. Also blocks the item acting as an enchant donor from the sacrifice slot. See Enchanting Control.
• Imbue self-targeting — a catalyst can now imbue the item in your main hand: hold the target in the main hand and the catalyst in the off hand. The catalyst never imbues itself.
• Tiered resonance — resonance abilities take a per-ability minPieces (default = the set's resonanceRequires), so one set can grant a 2-piece bonus and a stronger 4-piece bonus.
• Proc groups — abilities sharing a procGroup on the same trigger are mutually exclusive: one weighted roll (by each ability's chance) fires at most one of them, instead of every eligible ability firing. Abilities whose cost can't be paid never enter the roll. Sibling to cooldownGroup. Works on imbued (addAbilities) abilities too.
• Ability scaling — any ability can carry a scaling block whose entries add perPoint × stat to a numeric param at fire time, where stat is streak_tier, imbue_count, charges, or max_health. Static abilities become build-defined curves. The scaled param must have an explicit base value in params (configs without one fail to load). Works on imbued abilities too.

Fixed

Update immediately — a run_command ability using the {target} placeholder could be abused for privilege escalation: a mob renamed to @a (or a selector) made the command run on everyone at full permission. All placeholders are now stripped to safe characters before use.

• State survives everything now — player- and admin-set state is never wiped when an item is rebuilt. A /fiwtools reload, an artifact awakening, or a crafting upgrade recipe now carries the item's imbuements, binding owner, souls, killstreak, stance, charges, and any enchantments / attribute modifiers / armor trim / dye that a player, command, datapack or other mod added — instead of returning a stripped-down copy. Awakening progress is intentionally reset when an item transforms so it can't instantly trigger the next stage.
• Player enchant upgrades stick — upgrading a config enchantment at an anvil (e.g. Sharpness 3 → 4) is no longer snapped back to the configured level on the next reload.
• Imbue lore stays — appendLore lines added by an imbuement are no longer erased a second later on items that also use dynamicLore.
• Unbreakable items keep their abilities — an item that earns unbreakable (via rechargeOnKill) no longer loses access to its own durability-cost abilities; the cost is simply free when there is no durability to spend.
• repair on infinite items — repairing an infinite: damage item now sticks immediately instead of possibly reverting on the next use.
• stun_strike no longer air-freezes bosses — targets immune to the stun's effects (the Ender Dragon, and anything that can't be affected) are skipped rather than frozen in place.
• imbue requires a single item — imbuing a stack is refused (message key stacked), closing a dupe where splitting the stack yielded one imbued item per unit for a single catalyst charge.
• Anvils and smithing tables keep foreign attributes — attribute modifiers added by admin commands, datapacks or other mods are no longer wiped when a Fiw item passes through an anvil or smithing-table operation (they were previously rebuilt from config + imbuements only).
• Resonance counts distinct set pieces — a set bonus can no longer be triggered by holding two copies of the same piece (e.g. one weapon in each hand); only distinct pieces count toward resonanceRequires / minPieces.