Perfect Utils

A library mod for Hytale that exposes reusable gameplay primitives to other mods. The current build ships one primitive: a mob stun.

This is part of narwhals' "Perfect" mod family (Perfect Parries, Perfect Dodges, Perfect Utils). Other narwhals mods may move shared utilities here over time.

Features

Mob stun primitive

StunMobAPI lets any plugin freeze a mob's movement, suppress its combat AI, and lock its interactions for a duration. Internally:

• Stun state lives on a per-entity ECS component (StunComponent).
• A ticking system (StunSystem) drains the duration each frame and re-applies the entity effect.
• Wake-up restores combat AI after a short buffer (250 ms full stun, 100 ms stagger) so the mob doesn't re-engage mid-recovery.
• Apply requests are queued and drained on the next world tick (StunQueueDrainSystem), so callers don't need a CommandBuffer of their own — pass a Store and a Ref, that's it. Worst-case latency is one tick (~50 ms at 20 TPS).

Two flavors:

• applyStun — full stun (STUN_WAKE_DELAY_MS = 250).
• applyStagger — lighter stagger (STAGGER_WAKE_DELAY_MS = 100); reapplications only refresh duration if the existing component is also a stagger, so a stagger never downgrades a full stun.