t1k:cocos:playable:animation-core

Field	Value
Module	`playable`
Version	`2.14.4`
Effort	`high`
Tools	—

Keywords: animation, flying, object pool, tween

How to invoke

/t1k:cocos:playable:animation-core

FlyingAnimation & FlyingAnimationController

Pooled particle-like animation system built on Cocos tween(). FlyingAnimation is the per-node Component; FlyingAnimationController is the scene singleton that manages spawning and pooling. See also: t1k-cocos-playable-signalbus.

Not available in the vendored CPM packages. FlyingAnimation and FlyingAnimationController shipped from the old assets/PLAGameFoundation/animations/ folder. Neither symbol exists in @playablelabs/game-foundation, @playablelabs/parameter-tool, or @playablelabs/motion (checked against 1.1.4 / 1.0.7 / 0.1.3), and there is no drop-in successor. Everything below describes legacy embedded source — it applies only to a project that still carries its own animations/ folder.

For new work, drive flying/reward motion with @playablelabs/motion (db://assets/packages/@playablelabs/motion) and pool the spawned nodes through t1k-cocos-playable-object-pool.

Details

Common Mistakes

Not calling Tween.stopAllByTarget(node) before replaying on a pooled node — old tweens persist after recycle.
Setting autoDestroy = true when using the controller — controller handles pooling; autoDestroy must stay false.
Passing targetNode for a non-target animation type — ignored silently; check enum group.
Forgetting UIOpacity component on prefab — FlyingAnimation.onLoad auto-adds it, but only after the node is active in the scene.

Gotchas

Animation clip references hold scene assets — they don’t unload until the component is destroyed — disable doesn’t free.
Skeletal animation events fire on the animation thread; UI mutation must marshal to main.
Inspector-wired callback params must guard with typeof param === 'function', never bare ?.() or a truthy check. Any public method whose callback param may also be fired from a Cocos Inspector EventHandler (animation FINISHED handlers, button clicks, custom [EventHandler] arrays) receives the EventHandler’s CustomEventData string as its FIRST argument — it is NOT undefined. So onComplete?.() (guards only null/undefined) AND if (onComplete) onComplete() (a non-empty string is truthy) both throw onComplete is not a function. Guard with if (typeof onComplete === 'function') onComplete(); so the SAME method is safe called from code (anim.PlayReverse(() => {...})) OR from the Inspector (string arg ignored, no crash). This bug recurs because devs assume the only “absent” case is undefined; Inspector EventHandlers violate that.