Skip to content

t1k:cocos:playable:animation-core

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: animation, flying, object pool, tween

/t1k:cocos:playable:animation-core

FlyingAnimation & FlyingAnimationController

Section titled “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.

  • API reference: animation types, config interface, controller API, tween patterns (references/api-reference.md)
  • Usage examples: collect effect, explosion, float-up text (references/usage-examples.md)
  • tween(target).stop() is a silent no-op — it never stops a running tween. tween(target) builds a NEW, empty tween on the target and .stop() stops that one, so every already-running tween keeps going (symptom: a toast or popup outlives its intended duration and never fades, because the fade tween was “stopped” but kept running). Stop running tweens with Tween.stopAllByTarget(target) (import { Tween } from 'cc'), or keep the handle returned by .start() and call .stop() on that. Grep new code for tween( followed by .stop().
  • 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.
  • 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.