ISS Punchy Handoff

Fixes the clash between Punchy's first-person hand animations and Iron's Spellbooks' cast animations.

Casting instant spells back to back makes Iron's animation and Punchy's animation play on top of each other, or snap between the two. Long casts hand control back to Punchy with a stutter: its right-click motion starts from the middle, or the vanilla "raise item" pose flashes in between. This mod decides, every tick, which one owns the screen, so only one of them is ever drawn.

What it does

• No more overlap on instant spells – Punchy stays hidden for as long as Iron's cast animation is actually playing (not only while the spell counts as "casting"), including between back-to-back casts.
• Clean hand-over to Punchy – when Iron's animation ends, Punchy's animation state is reset first, so it starts from the beginning instead of resuming a stale right-click motion from the middle.
• No vanilla item-raise flash – the short gap where vanilla's hold pose showed through between the two animations is closed.
• Epic Fight third person – with Epic Fight and efiscompat, Epic Fight keeps drawing the player for the whole time Iron's cast animation plays. Previously the picture flipped between Epic Fight's cast animation and Iron's own animation, which looked like mixed animations and head jitter.
• Respects Iron's own settings – if Iron's first-person cast animation is switched off in its config, Punchy stays visible and plays its own animation.
• Nothing to set up – works out of the box. Every part can be switched off in the config.

Requirements

• Minecraft 1.20.1, Forge 47+
• Punchy 2.7 or newer (tested with 3.0)
• Iron's Spellbooks 3.0.0 or newer
• Optional: Epic Fight + efiscompat (for the third-person fix)

Punchy and Iron's Spellbooks are soft dependencies: if one is missing, the mod does nothing and logs a single line saying so. It never crashes the game.

Configuration

config/iss_punchy_handoff-client.toml

• enabled (default true) – master switch for the first-person hand-over.
• ironsAnimationForInstantSpells (default true) – instant spells play Iron's animation and Punchy waits until it has finished. Set to false to let Punchy's own interact motion play instead and suppress Iron's first-person animation.
• instantGraceMillis (default 0) – extra time in ms Punchy stays hidden after Iron's animation ends.
• graceMillis (default 0) – extra time in ms Punchy stays hidden after a long cast ends or is cancelled.
• keepEpicFightRenderDuringCast (default true) – the Epic Fight third-person fix.
• advancedHandoff (default false) – experimental extras: long casts hand over to Punchy at once, and Iron's first-person animation is gated per cast type.
• logging (default false) – writes state changes to latest.log ([iss_punchy] lines). Only needed when reporting a bug. The one-time startup lines are always written.

Notes

• Client-side only. Do not install it on a server.
• Hooks are applied with Mixin and verified at startup: latest.log contains an [iss_punchy] mixin hooks: ...=APPLIED line, so you can see whether it is active.
• Not tested with other first-person animation mods besides Punchy.