Skip to content

t1k:cocos:playable:juice

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: @playablelabs/motion, animation, binding, boot cover, disable, enable, enhance, game feel, hide, juice, loading screen fade, motion, MotionBindingPlayer, MotionPresetPlayer, params not ready overlay, preset, show, tween

/t1k:cocos:playable:juice

Scan the project’s visual code and make it feel better with @playablelabs/motion: improve existing animations and add motion to bare visual state-changes (enable/disable, show/hide). Apply effects by attaching a config-driven Player component to the node through Cocos MCP — never by hand-tweening or editing raw properties in the editor.

Prefer @playablelabs/motion for new game-feel work. Drive effects through the config-driven Player components rather than introducing hand-rolled JuiceKit / ScreenEffects static tweens (db://assets/.../game-foundation/juice/*). When you touch an existing JuiceKit call-site, migrate it to a motion preset/binding; leave untouched call-sites alone.

Before hand-tweening or attaching a preset for any of the six effects below, use PolishKit from @playablelabs/cc-polish-kit (peer @playablelabs/core-polish-profile). The kit composes @playablelabs/motion and ScreenEffects; it adds no tween code of its own, so this does not conflict with the motion guidance below. Only when none of the six calls fits do you fall through to the Players and presets.

Getting it into a project. A pla-generator scaffold already has both packages in playableSync and on disk (they are baseline packages, src/lib/baseline-packages.json). An existing project does not: add @playablelabs/core-polish-profile and then @playablelabs/cc-polish-kit to the project’s package.json playableSync array (CPM does not read peerDependencies, so the profile must be listed by hand, before the kit) and sync. Either way the host still assigns the prefab and layer refs and calls bind() (package README “Wiring” and “Smoke”). Signatures: packages/cc-polish-kit/src/PolishKit.ts on cocos-stdlib main.

CallReplaces a hand-writtenFeedback Matrix classChannels the kit coversGame still owes (REQUIRED, not covered)refId argument
confettiBurst(refId?)confetti / particle burstmilestonevisual, vfxsfx, uione string
win(refIds?)win confetti + vignetteterminalvisual, vfxsfx, uiobject { confetti?, vignette? }
lose(refIds?)lose vignetteterminalvisualvfx, sfx, uiobject { vignette? }
showEndCard(refIds?)end-card entrance + CTA pulseterminal (ui leg)uivisual, vfx, sfxobject { card?, cta? }
ctaPulse(refId?) / stopCtaPulse()looping CTA scale pulseterminal (ui leg)uivisual, vfx, sfxone string
tapFeedback(x, y, refId?)tap ripple / puffinput-ackvisualhapticone string

The “owes” column is every cell theonekit-designer/.claude/modules/base/rules/game-feedback-mandate.md marks REQUIRED for the class, minus what the kit covers: haptic is REQUIRED only for input-ack and invalid-action, so it is owed on tapFeedback and on no other row. For the two ui leg rows the visual, vfx and sfx cells come from the win() / lose() call of the same moment and the game’s own cue. The kit ships no sound and no haptic: an sfx cell is met by a cue in the profile plus the audio bind option, a haptic cell by the game’s own input handler. Wire each owed cell or record feedback-waiver: <reason> (haptic: see references/feedback-channel-mechanisms.md). Pass a refId (or the object form above) when the effect copies a reference so the QA polishEvents stream can be matched to it; an effect without one still plays and is reported unmapped.

IntentPath
“Add juice / suggest motion for this project”Full Workflow — scan → classify → vibe-gate → apply
“This element just appears/disappears, give it life”Goal 2 (bare show/hide → preset)
“This tween is flat, make it punchier”Goal 1 (improve existing)
“Apply preset X to node Y”Skip to Apply via MCP
“Shatter/break this sprite into pieces at runtime”references/runtime-2d-mesh-shatter.md (custom IAssembler, not a Motion preset)
“Fill a Feedback Matrix row / which API implements the visual–ui channels”references/feedback-channel-mechanisms.md (the two Cocos prohibitions, the haptic waiver, channel → Cocos mechanism, engine hazards, perf budget)
“Camera shake decays wrong / damage numbers unreadable on bright backgrounds”references/camera-shake-decay-and-number-contrast.md (frame-rate-independent shake decay, floating-number contrast)
  1. Improve existing animation — a hand-rolled tween() / flat scale / linear fade gets a tuned @playablelabs/motion preset or binding with better easing, overshoot, or stagger.
  2. Add new motion to bare visual updates — a node that only flips active/enabled or sets opacity (no animation) gets an Entrance/Exit (one-shot) or Attention/Tutorial (looping) preset.

Both decisions consider the game vibe. When the element’s intent is unclear, you MUST ask (see the gate in the Workflow).

Working examples ship with the @playablelabs/motion package: API in assets/packages/@playablelabs/motion/README.md; demo Players (MotionDemo.ts, MotionPresetPlayer.ts, MotionBindingPlayer.ts) under the package’s demo directory. A project may also vendor the demo Players as example components elsewhere under assets/ — attach whichever copy the editor has compiled.

Barrel import (registers built-in adapters + bindToX helpers):

import { Motion, Ease, LoopType, LSequence, MotionPresets } from "db://assets/packages/@playablelabs/motion/index";

Two Player components (config-object driven)

Section titled “Two Player components (config-object driven)”

Both assemble their effect from inspector fields via buildConfig() — you set config, never raw transform. Attach the one that fits:

ComponentUse whenConfig surface
MotionPresetPlayerA named, designed effect fits (entrance, attention loop, reward, celebration, label)preset enum + tuning fields (duration, scale, offsetY, arcHeight, turns, colorA/B, …). Leave a numeric field at 0 to use the preset’s own default. playOnStart, replayInterval.
MotionBindingPlayerYou need ONE raw property animated (Position/Scale/Angle/Color/Opacity/ContentSize) with custom from→to + ease + looptarget enum, from*/to*, ease, loopType, loops (-1 = forever; note: this is the @playablelabs/motion dispatcher convention, separate from Cocos’s native tween().repeatForever which has no loops count), delay. Stack several on one node for concurrent multi-property motion.

Preset catalog (MotionPresetPlayer.preset)

Section titled “Preset catalog (MotionPresetPlayer.preset)”

Grouped here by category and ordered for READING. Neither the grouping nor the row order is the enum — resolve the numeric preset index as “Apply via MCP” describes, from the compiled Player.

One-shot (fire once; set replayInterval to re-fire):

CategoryPresets
EntrancepopIn fadeIn scaleIn slideIn dropIn flyIn zoomIn spinIn
ExitpopOut fadeOut scaleOut slideOut flyOut
Feedbackpunch shake squashStretch punchRotation flash nudge
Rewardcollect arcCollect coinPop countUp scorePop
CelebrationvictoryBounce starPop confettiRise trophyRaise
Label (per-char)popInChars fadeInChars slideInChars popOutChars fadeOutChars slideOutChars

Looping (play forever; replayInterval ignored):

CategoryPresets
Attentionpulse breathe heartbeat float swing wobble tilt glow jiggle
TutorialtapHint dragHint ripple pointBob tapPulse
Label loopwaveChars

This skill runs in the caller’s session (no context: fork)

Section titled “This skill runs in the caller’s session (no context: fork)”

effort: high with no context:, deliberately (#1582). The workflow below ends in an apply — step 5 attaches Player components and sets their config through the editor MCP — and the agents that load this skill (t1k-cocos-playable-feel-developer, t1k-cocos-base-developer, and the rest) are themselves the implementers of the same view files. A forked body runs in a fresh subagent with its own tool pool, so invoking it from an implementer starts a second writer on the same files: the run behind #1582 had the fork write seven files and rewrite BoardView, GoalPanelView and GoalCardView while the agent was editing them. Step 1’s delegate to Explore is the second reason — a fork strips Agent, so that line cannot run in a forked body either.

Invoked with Skill, the body loads into the caller’s session and this skill is guidance the caller applies itself, which is what every calling agent wants. Do not add context: fork here for prompt-cache savings; if a future edit genuinely needs a separate context, the apply step has to move to the caller first.

  1. Scan CocosPlayableAdsTemplate/assets/scripts (delegate to Explore for breadth) for visual-update sites on a label / sprite / node / UI view / node-with-UI-children:
    • existing animation: tween(, Tween, JuiceKit., .to(, setScale, UIOpacity, manual easing.
    • bare state-change: node.active =, .enabled =, .opacity =, setSiblingIndex, removeFromParent with no animation.
  2. Classify each site → Goal 1 (improve) or Goal 2 (add). Note the element’s role (CTA, score, tutorial hand, reward, panel, end-card title…).
  3. Game-vibe gate (MANDATORY when intent is unclear). Use AskUserQuestion — never guess silently. The core question per ambiguous element: should it be catchy all the time (a loop) or show/move quickly then settle (one-shot)? Map answers: “catchy/persistent/draw-the-eye” → Attention/Tutorial looping preset; “quick info/appears then done” → Entrance (+Exit) one-shot. Batch up to 4 elements per call.
  4. Map vibe → component + preset using the catalog. CTA/idle-prompt → looping pulse/breathe/tapHint. Reward/score → coinPop/scorePop/countUp. End-card title → popIn/victoryBounce. Bare panel show → scaleIn/fadeIn; hide → fadeOut/scaleOut.
  5. Apply via MCP (config object only — see below).
  6. Verify — re-get_info the component, confirm preset/config fields landed; report each node + chosen preset + vibe rationale.

t1k-gamedev-playable-visual-director (advisory — never edits): feel targets as numbers (ms, easing, overshoot) briefed before presets are applied, and a screenshot review before done. Max 2 rounds — then the remainder is the caller’s call. Its fixes land through t1k-cocos-base-developer / t1k-cocos-base-editor-operator.

Cocos MCP server cocos-creator. The port is per project (settings/mcp-server.json; 3000 is only the shipped default) — resolve it per t1k-cocos-playable-parameter-mcp/references/mcp-endpoint.md rather than assuming. Everything goes through the config object — set component properties, never raw node transform in the editor.

manage_node { action: "find_by_name", name: "<NodeName>" } → nodeUuid
manage_component { action: "attach_script", nodeUuid,
scriptPath: "db://assets/<motion-demo-path>/MotionPresetPlayer.ts" }
manage_component { action: "set_property", nodeUuid, componentType: "MotionPresetPlayer",
property: "preset", propertyType: "number", value: <enum index> }
manage_component { action: "set_property", nodeUuid, componentType: "MotionPresetPlayer",
property: "duration", propertyType: "number", value: 0.5 }
manage_component { action: "set_property", nodeUuid, componentType: "MotionPresetPlayer",
property: "playOnStart", propertyType: "boolean", value: true }
  • scriptPath points at wherever the demo Players are compiled in the project (package demo dir or a vendored assets/ copy).
  • Resolve the index from the compiled Player, never from the tables above: preset is a numeric index into the PRESET_NAMES literal declared inside the compiled MotionPresetPlayer.ts — read that literal directly, or read the applied value back with manage_component get_info; the catalog’s row order is a reading aid and a project’s vendored fork may differ, so translating a catalog position silently selects a different effect (#1432).
  • Numeric tuning fields left at 0 fall back to the preset’s built-in default — only set the ones you intend to override.
  • For MotionBindingPlayer: set target (enum: Position=0, PositionX=1, PositionY=2, PositionZ=3, Scale=4, Angle=5, EulerAngles=6, Color=7, Opacity=8, ContentSize=9), fromScalar/toScalar or fromVec/toVec, ease, loopType (enum: Restart=0, Yoyo=1, Flip=2, Incremental=3 — the demo player’s default is Yoyo), loops.

The Player components exist so animation is data, not code: every effect is the MotionPresetConfig / MotionBindingConfig assembled from inspector fields. Always drive motion by setting those config properties through MCP. Do NOT: hand-write Motion.create(...).bindToX() at call-sites for these nodes, tween raw worldPosition in editor scripts, or set node.scale/position/opacity directly to fake an animation.

The probe is a deterministic stand-in for a game-feel check; applying motion is judgment. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run probe-bare-state-change.cjs and report the bare .active toggles it listst1k-list-classifier
Pick presets, apply Player components through MCP, review feelt1k-cocos-base-developer applies (operator for editor-only/repair); t1k-gamedev-playable-visual-director reviews — reasoning tier
  • Duplicate demo-Player copies collide. If the demo Players exist in more than one place (e.g. the package under assets/packages/@playablelabs/motion/ plus a project-vendored copy elsewhere under assets/), both register the same @ccclass('MotionPresetPlayer') name. A duplicate-ccclass error or “missing or invalid” component means only ONE copy compiled — attach the Player from the copy Cocos actually loaded (confirm with manage_component get_available). Import the library API from the package barrel.
  • Demo Players are example components excluded from the package’s shipped files manifest. They are the intended attach targets for this pass; if the project later needs its own, copy the pattern into assets/scripts (keep the config-driven buildConfig shape).
  • Inspector Enum() must be a LOCAL static literal — the demo Players build their dropdowns from local literals (PRESET_NAMES, BindingTargetEnum), NOT Enum(importedLibEnum). A barrel value can be undefined during bundle module-eval; the load-order throw de-registers every @ccclass in the package. Preserve this if you fork a Player.
  • Call Motion.cancelAll() on scene teardown/reload — the dispatcher is director-level and survives scene loads; leaked handles to destroyed nodes are avoided by node bindings (they guard isValid per tick), but cancelAll() is the teardown safety valve.
  • Looping vs one-shot is a vibe decision, not a default — never silently pick a loop for a CTA or a one-shot for an idle prompt. If unsure, the gate (AskUserQuestion) is mandatory.
  • Accessibility: screen shake amplifies motion-sickness (gate behind a toggle); hit-stop > 100ms reads as a freeze; ~50 particles is the 60fps mid-tier Android ceiling.
  • No CLI build/test — verification is manual in the Cocos Editor; confirm the component + config landed via MCP get_info.
  • Shard/mesh-based shatter effects are out of scope for the Player components above. See references/runtime-2d-mesh-shatter.md for the custom-IAssembler technique (engine-private surface, quarantine required) and the radial-tessellation coverage gotcha.
  • Feedback-mandate work reads its own reference. When the task is a Feedback Matrix row rather than a juice pass, references/feedback-channel-mechanisms.md carries the two Cocos prohibitions, the haptic waiver, the channel → Cocos mechanism table, the pooling/teardown and H5-autoplay hazards, and the mobile-web performance budget.
  • Never read renderer.material to inspect or copy a tint — it allocates a MaterialInstance as a getter side effect. setMaterialInstance(plainMaterial, i) also replaces the slot’s material with a plain copied Material. The self-erasing pattern is using a material asset as a “which slot do I paint” marker: calling setMaterialInstance with a plain Material replaces the marker it just matched, so a pooled node reused for another colour never matches again. When you only need to inspect or copy the current material, read renderer.sharedMaterial / sharedMaterials instead (the shared material asset; no MaterialInstance is created). Prefer per-node material instances set via getMaterialInstance(i) / setMaterialInstance(instance, i) for node-local tinting, and always reset the tint to the shared material when the node returns to the pool.
  • Never stage an entrance by setting a Widget-bearing node to scale 0 in onEnable. Widget.AlignMode is ONCE=0/ALWAYS=1/ON_WINDOW_RESIZE=2 — a serialized _alignMode: 2 is ON_WINDOW_RESIZE, not ALWAYS. ON_WINDOW_RESIZE aligns exactly once, at the end of the frame the widget first enables (_dirty defaults true), and again only on canvas resize; _setDirtyByMode() re-dirties on transform/size change for ALWAYS only. align() sizes the box as uiTrans.width * scale.x / height * scale.y, so a node held at scale 0 during that one alignment is aligned as a zero-size box — TOP lands half its height too high, RIGHT half its width off-edge — and is never re-aligned. Hide staged elements with UIOpacity (author it in the prefab) instead, keep scale at rest until the widget has aligned, and animate a widget-less child if something must move; Widget.updateAlignment() is the manual re-align escape hatch. Verified against Cocos Creator 3.8.7 engine source (cocos/ui/widget.ts, widget-manager.ts).
  • Never fade a boot cover (loading screen, “params not ready” overlay) in from opacity 0 — snap it opaque on show, fade only its exit. A boot cover’s whole job is to hide the world until it is safe to look at; gameplay can start (world scrolling, spawns ticking) before that cover’s own show animation finishes, so a fadeIn/popIn on the cover itself exposes the live, unconfigured world underneath for the fade’s duration. This is Goal 2’s “bare show/hide → preset” guidance applied wrong: converting a boot cover’s bare active = true into a 0→255 opacity tween is exactly the improvement this skill recommends for an ordinary panel, and exactly the case where it is wrong. Snap the cover to full opacity the instant it shows (no entrance animation), and reserve motion for its dismiss (fadeOut/scaleOut) once the game underneath is actually ready. Record feedback-waiver: boot cover must be opaque on frame 1 on the element so a later game-feel sweep doesn’t re-flag the snap as unjuiced. Confirmed in TimelineUpPLA: GameView.startGameFlow() calls startRun() (world scrolling) before startLoading(), so LoadingView fading in from 0 for 0.25s showed the live unconfigured board for a quarter second on every load.
  • Every @playablelabs/motion preset (Entrance, Feedback, and the looping Attention/Tutorial presets alike) captures the node’s CURRENT scale/transform as its own rest pose the instant it is registered — the dispatcher evaluates t=0 synchronously when the preset has no delay, so “rest” is whatever the node looks like at that exact call, not some later authored default. Two consequences: (1) never pre-zero a node’s scale before playing an Entrance preset like popIn — it captures rest = 0 and animates 0→0, so the node stays invisible the whole time; (2) never start a looping Attention/Tutorial preset (pulse, breathe, …) on the same tick an Entrance preset finishes — the loop captures the entrance’s zeroed off-state as ITS rest pose and pins the node at scale 0 forever. Sequence them — entrance → onComplete → THEN start the loop — never fire both in the same frame. EndCardView in the template does this correctly inside the pop’s withOnComplete.

Rule visual-change-discord-notice: adding motion or feedback is a visible change. Capture OLD before the first edit and NEW after the last (preview-verify shot steps, or the image file itself for a 2D asset), return the paths and a draft Discord post (what changed, undo = revert the PR) to the orchestrator, who posts; never post from here. Logic-only: no visible change. No capture possible: screenshots pending: <reason>, never a mock image. The PR needs the Discord link or visual-notice-waiver: <reason>; the owning agent’s Visual change notice section has the full steps.