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.
A recycled HaxeFlixel sprite can still be controlled by a tween created during its previous use. Resetting alpha or position once does not cancel later tween updates. Cancel the owned tween before reuse and invalidate stale completion work. The FlxTween API provides cancellation by object and fields.
Key Takeaways
- Pool reuse is a lifecycle transition, not just a new position assignment.
- Cancel an obsolete effect before writing the reused object's new state.
- A completion callback must belong to the current logical use of the sprite.
Trace the delayed writer
Suppose an enemy starts a fade-out and returns to a pool before that fade ends. The pool restores alpha to one for a new enemy. If the old tween still writes alpha on the same object, the new enemy begins fading unexpectedly.
Log a monotonically increasing spawn generation next to each tween creation and reuse. This distinguishes the object reference, which persists, from the logical enemy instance, which changes. The FlxBasic API documents the alive, exists and visibility lifecycle controls; those flags alone do not describe every external effect.
The sprite hit-flash guide helps decide whether a transient effect should touch alpha, tint or a separate visual layer.
Cancel before applying new state
For tweens managed by the ordinary FlxTween path, a reset fragment is:
// Current HaxeFlixel 6.x API; cancelTweensOf exists since 4.9.0.
// Not compiled or executed here.
FlxTween.cancelTweensOf(enemy, ["alpha", "x", "y"]);
enemy.alpha = 1;
enemy.setPosition(spawnX, spawnY);
The API notes that matching a field cancels the entire matching tween, including its other properties. Keep unrelated effects on separate owned tweens if selective cancellation matters.
If the project uses a custom tween manager, cancel through the owner that actually manages the effect. A convenient global call cannot be assumed to cover every custom manager. Retain explicit handles where ownership is otherwise unclear.
Guard stale completion callbacks
A completion handler may award a reward, kill an object or start another effect. Associate that handler with the logical spawn generation and reject work for an obsolete generation. Clearing an old visual value does not make a delayed gameplay callback safe.
Do not use a completion operation as a substitute for cancellation when you want to abandon an effect. Completing a tween can deliberately invoke completion behavior. Choose the operation according to whether the old action should finish or be discarded.
| Transition | Required question |
|---|---|
| Return to pool | Which tweens and listeners still own this object? |
| Reuse | Which fields need a fresh baseline? |
| Old completion arrives | Does its generation still match? |
| Permanent destruction | Who releases remaining owned effects? |
The typed group reference describes recycling-related group behavior. Treat that as the container lifecycle, then account for effect ownership separately.
Acceptance with a shortened reuse interval
Start a long fade, recycle the sprite before it ends, and immediately reuse it. Wait longer than the old effect duration. Confirm the new enemy remains at its intended position and alpha and receives no stale reward or kill action.
Repeat with a position tween and a combined position/alpha tween. Record the lifecycle policy in the animation handoff checklist, and keep the source-art reset separate from palette variants.
No tween or pool was executed here. This guide describes the linked API and a proposed adversarial acceptance sequence.
Account for effects outside the sprite itself
An effect can own a child object or a nested property rather than the sprite reference passed to a cancellation helper. Inventory those targets during reset. A weapon trail, shadow or separate flash overlay may continue its old effect even after the body's tween is canceled. Give the actor reset path a list of owned effect handles or owners, and release them together. Avoid broad cancellation of unrelated UI or gameplay tweens merely because they happen to share a manager.
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)