Magic NPCs

[0.5.0] — aimed casting fix, spell discovery, weighted gear, cooldown clarity

Quality-of-life for pack authors driving Iron's casters: projectile spells now fire at the target (not in a stale direction), a new command lists every valid spell id, loadouts can grant weighted starting gear, and the cooldown rules are documented in one place. Every new field is optional and backward compatible — existing datapacks, configs, and shipped loadouts are unchanged, and the offline bootSanity GameTest still passes with neither Iron's nor Recruits installed.

Added

• /magicnpcs spells [filter] — list the valid Iron's spell registry ids with school, rarity, default cooldown, cast type, and a mob-friendly hint (filter by substring). Read-only; available whenever Iron's is present. Backed by the new generated reference docs/irons_spell_ids.md.
• Weighted starting equipment — an optional per-loadout equipment block grants gear on spawn: mainhand/offhand weighted item lists (bare "id" or { "item", "weight" }), plus chance (default 1.0) and only_if_empty (default true). Omit the block to keep the existing global equipment.spawnWithGearChance behaviour. Useful with requireSpellFocus to arm casters with a Pyrium Staff or other focus.
• Mob-friendly spell guide (docs/mob-friendly-spells.md): curated projectile / self-support / melee / AoE / not-recommended categories, with example projectile- and melee-mob loadouts.
• Cooldown documentation in the README: explicit cooldown (ticks) vs cooldown_multiplier (scales the Iron's default — bigger = slower), the minCooldownTicks floor, 20 ticks = 1 s, and a worked Phantom echoing_strikes 5-second example.

Fixed

• Aimed casting / stale projectile direction. The casting goal relied on LookControl, whose rotation is applied after the goal runs — so on the instant (windup = 0) path a projectile spell fired in the caster's previous facing. The goal now snaps the caster's yaw/pitch (head and body) onto the target immediately before onCast, so spells launch on-aim regardless of wind-up.
• Silent unknown spell ids. A loadout referencing an unresolved spell id used to fail invisibly. It now logs a clear warning naming the file, entity, field, and bad id, and a bare id (no namespace) is auto-retried under irons_spellbooks: (so devour resolves to irons_spellbooks:devour).

Changed

• NpcSpellAttackGoal.resolveCooldown now delegates to a pure, unit-tested CooldownResolver (no behaviour change): explicit ticks > per-spell multiplier > global multiplier, always floored.

Tests

• New JUnit tests: CooldownResolverTest (precedence, multiplier direction, floor) and WeightedItemPickTest (weighted equipment selection). New runtime GameTests: windupAimsAtTarget (projectile flies toward the target on windup=0), focusGateRequiresHeldFocus, bareSpellIdAutoNamespaces, and perSpellCastChanceZeroNeverCasts.

Notes

• Fully backward compatible. Migration: none required — every new field is optional and omitting it preserves current behaviour. If you were confused by cooldowns on an older build: raising cooldown_multiplier increases cooldown; use a value below 1.0 to speed a spell up, or just set an explicit "cooldown" in ticks (100 = 5 s).
• Spell ids and item ids are version-specific to your installed Iron's build; /magicnpcs spells and /give are the authoritative sources.