Disclosure: This draft was generated with AI and checked against the cited primary sources, with a separate AI editorial review. It was prepared for the FrameSprite team, which has a commercial interest in FrameSprite. Proposed examples are not executed tests unless explicitly identified as recorded fixture results.
Use frameNumber when your rule refers to a position inside the current HaxeFlixel animation. Use frameIndex only when the rule deliberately refers to an image's position in the shared sheet. They can differ, especially when an animation reorders or repeats source frames. The controller signal contract names both values.
Key Takeaways
- An action's third playback position need not be atlas frame two.
- Guard gameplay events by action identity and action-instance state.
- Do not use a repeated art frame as the only identifier for a damage event.
Trace a noncontiguous sequence
Consider the constructed animation list [8, 9, 9, 12]. At animation position two, counting from zero, the sheet image is still nine. A rule testing frameIndex == 2 never identifies that position. A rule testing frameIndex == 9 matches more than one position.
The FlxAnimation reference distinguishes its current animation position from the underlying sheet index. Write both numbers in a log while diagnosing an attack. This makes the difference visible without changing the artwork.
The existing hitbox timing guide explains why gameplay windows require a deliberate timeline. This article identifies the HaxeFlixel signal values used to observe that timeline.
Subscribe once and filter the action
The following fragment illustrates an animation-position diagnostic:
// HaxeFlixel signals require 5.9.0 or later.
// Fragment only; not compiled or executed here.
sprite.animation.onFrameChange.add(function(name, frameNumber, frameIndex) {
trace(name + ":" + frameNumber + " -> " + frameIndex);
});
Register the listener during setup, not each time the attack starts. The FlxTypedSignal reference describes adding and removing listeners. Keep the listener reference if your component needs to remove it later.
For an actual hit, also require the intended action name and a valid action-instance state. A frame-change callback does not know whether a swing was interrupted, whether its target is still valid, or whether damage has already been applied.
Decide between an event and a window
A one-time sound at a frame boundary can use an event. A hit region active over several simulation steps needs state representing an interval. Opening a window and closing it only when another visual callback arrives is fragile if an animation is interrupted.
Define explicit interruption cleanup. When switching from attack to hurt or death, close the old attack window even if the expected recovery frame never appeared. Do not add more duplicate callbacks to compensate for an unclear action lifecycle.
| Intended rule | Suitable reference |
|---|---|
| Trigger at the third pose in this action | Animation position |
| Identify a particular atlas image | Sheet index |
| Apply one hit per swing | Action instance plus hit policy |
| Keep a region active during contact | Gameplay interval with interruption cleanup |
The one-shot death guide is useful when terminal poses and transitions need separate ownership.
Acceptance with repeated artwork
Test a sequence containing a repeated source frame, then reorder its atlas images without changing the intended action. Confirm gameplay still occurs at the intended animation position.
Interrupt before contact, during contact and after recovery. Verify stale callbacks cannot apply another hit. Save the signal interpretation and interruption policy in the animation handoff checklist.
The sample list is explanatory, not a measured test. This guide uses the current documented HaxeFlixel signal API, with the explicit 5.9.0 minimum for onFrameChange; older callback-based projects need their own migration review.
Keep events stable during art revisions
Name gameplay events by their role, such as contact-start or recovery-end, and map them to reviewed animation positions. A later art revision may insert an anticipation drawing or move the same sheet image elsewhere. Review that mapping with the changed action instead of assuming the previous numeric position still expresses the same moment. Keep the old and new sequence beside each other during acceptance. This protects the meaning of the event while allowing artwork changes; it does not remove the need to test interruption and one-hit rules.
Sources and editorial ownership
Primary references checked on October 20, 2026:
Editorial owner: FrameSprite Workflow Team. Editorial and verification policy. Report a documentation correction.
Top comments (0)