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.
addByPrefix selects frames by names stored in a HaxeFlixel atlas. A broad prefix can select more than the intended action, while a mismatched name selects nothing useful. Inspect actual frame names and use addByNames when selection order must be explicit. The animation-controller API documents these separate selection methods.
Key Takeaways
- The atlas frame name, file name and animation name are different identifiers.
- Inspect the imported collection before inventing a prefix.
- Make exceptional ordering explicit rather than depending on accidental export names.
Read the imported names
Suppose an atlas contains attack_01, attack_02 and attack_heavy_01. The prefix attack_ is broader than the light attack you intended. Renaming the controller's animation to light does not narrow the atlas selection: that name identifies the animation object, not the source frames.
Use a small diagnostic that prints the imported frame names. The FlxFramesCollection reference describes the frame collection, and FlxAtlasFrames describes supported atlas importers. Select the importer that matches your metadata format instead of treating an XML or JSON filename as interchangeable.
If the names were changed during export, fix or document that upstream mapping. The Aseprite tag and filename guide covers a related export boundary.
Define an exact action
For a short action whose names you have inspected, explicit selection makes the contract easy to review:
// HaxeFlixel 6.x API fragment; assumes these atlas names exist.
// Not compiled or executed here.
sprite.animation.addByNames(
"lightAttack",
["attack_light_01", "attack_light_02", "attack_light_03"],
12,
false
);
Do not copy these hypothetical names into a real pack without checking them. When a frame is missing, fail the import or show a clear diagnostic rather than silently accepting a shorter attack.
A repeated frame may be intentional. For example, repeating a hold pose can extend its visual presence. Document that decision so a later cleanup does not remove a duplicate that carries timing.
Keep naming, order and duration separate
A successful lookup does not prove the order is correct. Export a temporary contact sheet with each frame's name beside its number, then compare it with the intended animation. Inspect anticipation, contact and recovery as separate phases.
| Failure | Inspect first |
|---|---|
| No usable frames | Imported names and importer format |
| Two actions mixed | Prefix breadth |
| Correct images, wrong sequence | Explicit order and exported name conventions |
| Correct order, unexpected pacing | Frame durations and controller timing |
Do not force a frame rate to hide a selection error. If the imported format carries per-frame timing, inspect that information as well. The animation frame-count guide helps distinguish drawing count from playback timing.
Acceptance before adding gameplay
Play the action alone, label each displayed frame and stop on the final recovery pose. Confirm the imported count matches the explicit list and that an unrelated heavy-attack frame never appears.
Then attach gameplay events using animation positions rather than assumptions about the atlas's global order. Record the exact names and intended timing in the delivery checklist.
This is a source-based workflow for the linked HaxeFlixel 6.x API snapshot checked October 20, 2026. No atlas was imported or played here, and the sample sequence is constructed.
Validate a replacement atlas before publishing it
When replacing artwork, compare the required animation names with the new atlas before swapping it onto a live actor. A visually similar pack can rename or omit one recovery frame. Keep the previous valid animation set available until the required names resolve, then report any missing names together rather than one failed pose at a time. Preserve intentional duplicates and ordering in the contract. This is a recommended validation step for an importer, not a claim that prefix selection alone enforces the completeness of your action set.
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)