t1k:cocos:playable:juice
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| 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
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:juiceMotion — Game-Feel Enhancement Pass
Section titled “Motion — Game-Feel Enhancement Pass”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/motionfor new game-feel work. Drive effects through the config-driven Player components rather than introducing hand-rolledJuiceKit/ScreenEffectsstatic 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.
PolishKit first
Section titled “PolishKit first”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.
| Call | Replaces a hand-written | Feedback Matrix class | Channels the kit covers | Game still owes (REQUIRED, not covered) | refId argument |
|---|---|---|---|---|---|
confettiBurst(refId?) | confetti / particle burst | milestone | visual, vfx | sfx, ui | one string |
win(refIds?) | win confetti + vignette | terminal | visual, vfx | sfx, ui | object { confetti?, vignette? } |
lose(refIds?) | lose vignette | terminal | visual | vfx, sfx, ui | object { vignette? } |
showEndCard(refIds?) | end-card entrance + CTA pulse | terminal (ui leg) | ui | visual, vfx, sfx | object { card?, cta? } |
ctaPulse(refId?) / stopCtaPulse() | looping CTA scale pulse | terminal (ui leg) | ui | visual, vfx, sfx | one string |
tapFeedback(x, y, refId?) | tap ripple / puff | input-ack | visual | haptic | one 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.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “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) |
Two goals
Section titled “Two goals”- Improve existing animation — a hand-rolled
tween()/ flat scale / linear fade gets a tuned@playablelabs/motionpreset or binding with better easing, overshoot, or stagger. - Add new motion to bare visual updates — a node that only flips
active/enabledor 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).
Reference
Section titled “Reference”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:
| Component | Use when | Config surface |
|---|---|---|
MotionPresetPlayer | A 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. |
MotionBindingPlayer | You need ONE raw property animated (Position/Scale/Angle/Color/Opacity/ContentSize) with custom from→to + ease + loop | target 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):
| Category | Presets |
|---|---|
| Entrance | popIn fadeIn scaleIn slideIn dropIn flyIn zoomIn spinIn |
| Exit | popOut fadeOut scaleOut slideOut flyOut |
| Feedback | punch shake squashStretch punchRotation flash nudge |
| Reward | collect arcCollect coinPop countUp scorePop |
| Celebration | victoryBounce starPop confettiRise trophyRaise |
| Label (per-char) | popInChars fadeInChars slideInChars popOutChars fadeOutChars slideOutChars |
Looping (play forever; replayInterval ignored):
| Category | Presets |
|---|---|
| Attention | pulse breathe heartbeat float swing wobble tilt glow jiggle |
| Tutorial | tapHint dragHint ripple pointBob tapPulse |
| Label loop | waveChars |
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.
Workflow
Section titled “Workflow”- Scan
CocosPlayableAdsTemplate/assets/scripts(delegate toExplorefor 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,removeFromParentwith no animation.
- existing animation:
- Classify each site → Goal 1 (improve) or Goal 2 (add). Note the element’s role (CTA, score, tutorial hand, reward, panel, end-card title…).
- 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. - 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. - Apply via MCP (config object only — see below).
- Verify — re-
get_infothe component, confirmpreset/config fields landed; report each node + chosen preset + vibe rationale.
Visual director loop
Section titled “Visual director loop”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.
Apply via MCP
Section titled “Apply via MCP”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>" } → nodeUuidmanage_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 }scriptPathpoints at wherever the demo Players are compiled in the project (package demo dir or a vendoredassets/copy).- Resolve the index from the compiled Player, never from the tables above:
presetis a numeric index into thePRESET_NAMESliteral declared inside the compiledMotionPresetPlayer.ts— read that literal directly, or read the applied value back withmanage_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
0fall back to the preset’s built-in default — only set the ones you intend to override. - For
MotionBindingPlayer: settarget(enum: Position=0, PositionX=1, PositionY=2, PositionZ=3, Scale=4, Angle=5, EulerAngles=6, Color=7, Opacity=8, ContentSize=9),fromScalar/toScalarorfromVec/toVec,ease,loopType(enum: Restart=0, Yoyo=1, Flip=2, Incremental=3 — the demo player’s default isYoyo),loops.
Config-object thumb rule
Section titled “Config-object thumb rule”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.
Executed by
Section titled “Executed by”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”.
| Step | Agent |
|---|---|
Run probe-bare-state-change.cjs and report the bare .active toggles it lists | t1k-list-classifier |
| Pick presets, apply Player components through MCP, review feel | t1k-cocos-base-developer applies (operator for editor-only/repair); t1k-gamedev-playable-visual-director reviews — reasoning tier |
Hard rules
Section titled “Hard rules”- 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 underassets/), 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 withmanage_component get_available). Import the library API from the package barrel. - Demo Players are example components excluded from the package’s shipped
filesmanifest. They are the intended attach targets for this pass; if the project later needs its own, copy the pattern intoassets/scripts(keep the config-drivenbuildConfigshape). - Inspector
Enum()must be a LOCAL static literal — the demo Players build their dropdowns from local literals (PRESET_NAMES,BindingTargetEnum), NOTEnum(importedLibEnum). A barrel value can beundefinedduring bundle module-eval; the load-order throw de-registers every@ccclassin 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 guardisValidper tick), butcancelAll()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.mdfor the custom-IAssemblertechnique (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.mdcarries 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.materialto inspect or copy a tint — it allocates aMaterialInstanceas a getter side effect.setMaterialInstance(plainMaterial, i)also replaces the slot’s material with a plain copiedMaterial. The self-erasing pattern is using a material asset as a “which slot do I paint” marker: callingsetMaterialInstancewith a plainMaterialreplaces 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, readrenderer.sharedMaterial/sharedMaterialsinstead (the shared material asset; noMaterialInstanceis created). Prefer per-node material instances set viagetMaterialInstance(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.AlignModeisONCE=0/ALWAYS=1/ON_WINDOW_RESIZE=2— a serialized_alignMode: 2isON_WINDOW_RESIZE, notALWAYS.ON_WINDOW_RESIZEaligns exactly once, at the end of the frame the widget first enables (_dirtydefaultstrue), and again only on canvas resize;_setDirtyByMode()re-dirties on transform/size change forALWAYSonly.align()sizes the box asuiTrans.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 withUIOpacity(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/popInon 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 bareactive = trueinto 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. Recordfeedback-waiver: boot cover must be opaque on frame 1on the element so a later game-feel sweep doesn’t re-flag the snap as unjuiced. Confirmed in TimelineUpPLA:GameView.startGameFlow()callsstartRun()(world scrolling) beforestartLoading(), soLoadingViewfading in from 0 for 0.25s showed the live unconfigured board for a quarter second on every load. - Every
@playablelabs/motionpreset (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 evaluatest=0synchronously when the preset has nodelay, 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 likepopIn— 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.EndCardViewin the template does this correctly inside the pop’swithOnComplete.
Visual change notice
Section titled “Visual change notice”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.