t1k:cocos:playable:gameflow
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: boot cover fade, CTA, end card, game flow, gameflow, loading, UI views
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:gameflowCocos Playable Game Flow
Section titled “Cocos Playable Game Flow”This skill handles game states, views, loading screens, end cards, and CTA integration. Does NOT handle parameter definitions (use t1k-cocos-playable-parameter) or SDK adapters (use t1k-cocos-playable-sdk-core).
⛔ Detect the project profile FIRST
Section titled “⛔ Detect the project profile FIRST”The state machine concept is universal; which classes implement it is not. Probe the filesystem before writing any code — never assume a layer or an architecture exists because this skill documents it. There are two independent axes: the tunable-layer axis (dashboard parameters / ad-network CTA) and the view architecture axis (which classes own state + screen/popup lifecycle). Probe both.
ls -d assets/PLAGameFoundation assets/H5GameFoundation assets/packages/@playablelabs 2>/dev/null # framework rootls -d assets/PlayableParamterTool assets/scripts/parameter 2>/dev/null # parameter layergrep -rl "CTAService\|STORE_LINK" assets/scripts 2>/dev/null | head # CTA layerls assets/scripts/**/GameConfig.ts 2>/dev/null # tuning locationgrep -rl "class GameFlow\b" assets/scripts 2>/dev/null | head # 🅗 H5 registered-state architecturegrep -rl "class ScreenManager\|class PopupService\|class ViewRegistry" assets/scripts 2>/dev/null | headgrep -rl "class GameView\b" assets/scripts 2>/dev/null | head # 🅛 legacy view-stack architecture| Playable-ad profile | Gameplay-only profile (e.g. H5 template) | |
|---|---|---|
| Dashboard parameters | ✅ PlayableConfig / ParameterBinder / AllAsyncParametersReadySignal | ❌ removed — tune in GameConfig.ts |
| Ad-network CTA | ✅ CTAService + STORE_LINK | ❌ no CTA service; store routing is an optional host integration, not wired by default |
| End card | full end card with CTA button | result view, no CTA button |
| Loading | waits on AllAsyncParametersReadySignal | no parameter gate — drive from asset/bundle load only |
| Framework root | db://assets/packages/@playablelabs/game-foundation/… | whatever the probe found (H5GameFoundation, @playablelabs/*, …) |
Sections below marked 🅟 apply to the playable-ad profile only (dashboard-parameter / CTA axis). On
a gameplay-only project, skip them — do not reintroduce PlayableConfig, ParameterBinder,
CTAService, STORE_LINK, or a parameter-gated loading screen into a project that deliberately
removed them.
View architecture is a SEPARATE axis — probe it independently of the tunable-layer axis above:
| 🅛 Legacy view-stack | 🅗 H5 registered-state | |
|---|---|---|
| State owner | GameView singleton (GameView.instance) | GameFlow + registered state classes (typically Loading / Ftue / Gameplay / ChapterResult / Win / Lose — six states, one per GameState value) |
| Screen/popup lifecycle | @property(Node) refs on GameView, toggled .active | ScreenManager (full-screen states) + PopupService (overlays) + ViewRegistry (view-id → prefab resolution), runtime-spawned rather than scene-wired |
| Win / lose | WinView / LoseView extend EndCardView, toggled by GameView.onWin()/.onLose() | ordinary popups shown via PopupService; GameRoot.instance.onWin() / .onLose() is the gameplay boundary that triggers them — popup-over-gameplay is an invariant, gameplay never destroys or replaces itself for a win/lose result |
| Base screen class | n/a (concrete Component subclasses) | BaseScreen — the abstract base every registered full-screen state extends |
GameView.instance | present | gone — do not import or reference GameView on this profile |
Sections below marked 🅛 apply to the legacy view-stack profile only; sections marked 🅗 apply to the
H5 registered-state profile only. Writing 🅛 code (a GameView property, hideAllViews(), extending
EndCardView) into an 🅗 project reintroduces a class the project doesn’t have and the compiler will
catch — but writing 🅗-shaped guidance (registering a new GameFlow state) into a 🅛 project invents
classes that were never there either. If the probe is ambiguous — neither GameFlow nor GameView is
found — ask rather than guess; both architectures are expensive to unwind once code assumes the wrong
one.
Game State Machine
Section titled “Game State Machine”LOADING -> FTUE -> GAMEPLAY -> WIN / LOSEexport enum GameState { LOADING, FTUE, GAMEPLAY, WIN, LOSE }Ads that chain several rounds add one interstitial state between rounds:
LOADING -> FTUE -> GAMEPLAY -> [CHAPTER_RESULT -> GAMEPLAY]* -> WIN / LOSERoute every round outcome — win, lose, and timeout alike — through a single handler that decides
“interstitial vs end/result”. A secondary path that calls the win/lose entry point directly (a
countdown timer is the usual culprit) skips the chain entirely and ends the round on the first loss.
🅛 that handler is onLevelFinished(won) on GameView. 🅗 it is whatever calls
GameRoot.instance.onWin() / .onLose() — route through one place, not scattered call sites.
The six GameState values above map 1:1 to the 🅗 profile’s six registered GameFlow states
(Loading / Ftue / Gameplay / ChapterResult / Win / Lose) — same state machine, different owner class.
Confirm the exact registered set in the project’s own GameFlow registration code before assuming
names; this skill documents the shape, not a byte-exact API for every consumer.
Core Components
Section titled “Core Components”🅛 Legacy view-stack profile
Section titled “🅛 Legacy view-stack profile”- GameView (singleton) — State machine.
onWin(),onLose(),onTutorialComplete() - LoadingView — Progress bar. 🅟 waits for
AllAsyncParametersReadySignaland is bound viaLoadingScreenParameter(replaces old scatteredLoadingBackgroundColor+LoadingIcon+LoadingGameNameparams). Without the parameter layer, resolve the loading promise from asset/bundle load alone — a project with no parameters will otherwise wait forever on a signal that never fires. - EndCardView (abstract) — Base for end cards, plays audio. 🅟 triggers CTA and exposes
backgroundSprite,titleLabel,subtitleLabelforParameterBinder.bindEndCard(). Without the CTA layer this is a plain result view — keep the audio, drop the CTA button. - WinView / LoseView — Extend EndCardView, provide audio name. 🅟 bound via
EndCardParameter(replaces oldEndCardWinCTA/EndCardLoseCTAparams). - CTAService 🅟 — Routes CTA click to correct store per SDK
- PlayableHelper 🅟 — First touch -> BGM, optional redirect-after-N-clicks. The first-touch-starts-BGM half is generally useful; the redirect half is ad-only.
🅗 H5 registered-state profile
Section titled “🅗 H5 registered-state profile”- GameFlow (singleton) — Owns the state machine. Registers the project’s state classes at boot;
drives transitions between them. There is no
GameFlow.instance.onWin()— the gameplay boundary isGameRoot, notGameFlow(see below). - State classes (typically Loading / Ftue / Gameplay / ChapterResult / Win / Lose) — one class per
GameStatevalue, registered withGameFlowrather than scene-wired as@property(Node)refs. - ScreenManager — owns full-screen state transitions (loading → ftue → gameplay). Each managed
screen extends
BaseScreen. - PopupService — owns overlay lifecycle (win/lose results, confirmation dialogs, anything shown
over the current screen rather than replacing it). A
PopupViewnever destroys the screen beneath it. - ViewRegistry — resolves a view id to its prefab/class for
ScreenManager/PopupServiceto runtime-spawn. There is no scene-wired@property(Node)per view on this profile — views are instantiated on demand, not pre-placed and toggled. - BaseScreen / PopupView — the abstract bases every registered full-screen state / popup extends.
- GameRoot (singleton) — the gameplay boundary.
GameRoot.instance.onWin()/GameRoot.instance.onLose()is what gameplay code calls;GameRootthen asksPopupServiceto show the win/lose popup. Gameplay code never importsPopupServiceorViewRegistrydirectly — it only ever calls throughGameRoot.
🅟 Composite Parameter Binding for Views
Section titled “🅟 Composite Parameter Binding for Views”Playable-ad profile only. Skip this section entirely if the profile probe found no parameter layer — tune in GameConfig.ts instead.
EndCardParameter and LoadingScreenParameter are composite types that bundle all view fields into one dashboard group. Use ParameterBinder to apply them:
// In ParameterController.SetUpOnUpdate():PlayableConfig.EndCardWin.onUpdate = (config) => { const p = ParameterBinder.bindEndCard(this.winView, config); if (p) this._spriteUpdatePromises.push(p);};
PlayableConfig.LoadingScreen.onUpdate = (config) => { const p = ParameterBinder.bindLoadingScreen(this.loadingView, config); if (p) this._spriteUpdatePromises.push(p);};See t1k-cocos-playable-parameter skill for composite type definitions and migration guide.
Workflow: Adding a New View/State
Section titled “Workflow: Adding a New View/State”Steps per profile (🅛 six steps, 🅗 five steps): references/adding-views-and-states.md.
Signal Flow
Section titled “Signal Flow”ParametersReadySignal 🅟 sync params readyAllAsyncParametersReadySignal 🅟 async params loaded (LoadingView waits for this)FirstInteractionSignal -- user first touch (InputService)TapSignal / SwipeSignal -- user input eventsThe two parameter signals exist only where the parameter layer does. On a gameplay-only project the input signals remain; nothing should await a parameters-ready signal.
Import Convention
Section titled “Import Convention”Always use the db:// protocol for cross-package imports — but resolve the framework root from the project, don’t hardcode one. At least three roots are in circulation: assets/PLAGameFoundation/ (classic playable), assets/H5GameFoundation/ (H5 template), and assets/packages/@playablelabs/* (CPM packages, which prefer the barrel import @playablelabs/game-foundation). Use whichever the profile probe found, and match the import style already used by the files around you.
// <FOUNDATION> = the root your probe found: PLAGameFoundation | H5GameFoundation | …import { SignalBus } from "db://assets/<FOUNDATION>/signalBus/SignalBus";import { AudioService } from "db://assets/<FOUNDATION>/gameControl/utilities/AudioSystem/AudioService";
// 🅛 legacy view-stack profile only — GameView does not exist on the 🅗 H5 profile:import { GameView } from "db://assets/scripts/UI/GameView";
// 🅗 H5 registered-state profile only:import { GameRoot } from "db://assets/scripts/GameRoot";
// 🅟 parameter-layer imports — only where PlayableParamterTool exists:import { SdkType } from "db://assets/packages/@playablelabs/parameter-tool/GameConfig";⚠️ db://assets/packages/@playablelabs/parameter-tool/GameConfig is the parameter tool’s GameConfig, and is unrelated to the gameplay-tuning GameConfig.ts a gameplay-only project keeps under assets/scripts/. Same filename, different file — don’t import the former to reach the latter.
Audio Integration
Section titled “Audio Integration”AudioService.instance.playMusic(Constant.AUDIO_NAME.BGM);AudioService.instance.playSFX(Constant.AUDIO_NAME.WIN);Audio files in resources/audio/. Register names in constant.ts -> AUDIO_NAME.
⚠️ Naming a clip is not the same as shipping it. A clip is audible in an unmodified build only if it is also referenced from the scene’s AudioLoader → AudioContainer.audioList; a clip missing from that list returns null from getAudioClip (both playSfx and playMusic then bail silently) and is stripped from the build by the removal scanner. See t1k-cocos-playable-parameter → skills/t1k-cocos-playable-parameter/references/audio-wiring.md.
⚠️ Gating audio until first interaction is not simply “call playMusic in the first-touch handler” — AudioService mute-state and one-shot handling make that a trap. See the audio-gate bullet in Gotchas below.
🅟 Store Links & CTA
Section titled “🅟 Store Links & CTA”Playable-ad profile only.
// constant.ts: STORE_LINK = { ANDROID_LINK, IOS_LINK }// CTAService routes per SDK: THE_ONE -> gameEndHandler, VOODOO -> ParameterManager.redirect()On a gameplay-only project there is no CTAService and no STORE_LINK, and the host redirect is typically not wired at all. Treat store routing as an optional integration the host owns: leave the result view without a CTA button and surface the gap, rather than authoring a redirect the project deliberately dropped.
Code Examples
Section titled “Code Examples”See references/gameflow-code-examples.md for complete implementation patterns.
Hard rules
Section titled “Hard rules”- A missing layer is a project decision, not a gap to fill. When porting gameplay into a project whose parameter/dashboard or ad-network SDK layer was deliberately removed, following this skill’s playable-ad sections reintroduces
PlayableConfig,ParameterBinder,CTAService,STORE_LINK, and dead framework imports — all of which the target excluded on purpose. Run the profile probe first and keep tuning where the project keeps it (GameConfig.ts). The sharpest symptom of getting this wrong is a loading screen that never completes, becauseLoadingViewis waiting onAllAsyncParametersReadySignalin a project that has no parameters to load. - 🅛 NEVER extend
EndCardViewfor an interstitial (between-rounds) view.EndCardView.onEnable()callssetupCTA()unconditionally, and whenfullScreenCTAis true it bindsTOUCH_ENDon the whole node →CTAService.handleCTAClick(). A card shown mid-gameplay would redirect the player to the store on any tap. Write a plainComponent(~80 lines) instead; carving a “disable CTA” hole into the base class breaks the two real end cards that depend on it. Also give the interstitial acc.BlockInputEvents: Cocos dispatches a touch to the topmost node that registers a listener, so a bare dimmingSpriteoverlay does NOT stop taps from reaching the live board underneath. (On 🅗 H5, the equivalent is: don’t route an interstitial throughPopupService’s win/lose popup path — give it its ownPopupViewsubclass so it never inherits win/lose-specific input handling.) - A restartable level breaks everything written for a one-shot level. The moment a round can rebuild in place (chapter chains, retry-on-lose), audit for: state armed by a once-per-playthrough signal (a level-selected signal fires once, but per-round freezes fire every round);
scheduleOncecallbacks that outlive teardown and land on the next round; pooled visual state left dirty by the previous round; and values captured lazily on first use, which then inherit round N−1 instead of the editor default. Capture such defaults exactly once inonLoad(), and callunscheduleAllCallbacks()in teardown. - 🅛 GameView lifecycle owns the FSM, not vice versa — destroying GameView while FSM holds a reference dangles the state’s
this. - Scene transitions during state.enter() are a footgun — the next state runs onLoad against an unmounted parent.
- 🅗
GameView.instanceis gone on the H5 profile — never import or reference it, even defensively. A null-guardedGameView.instance?.onWin()still imports a class the project’stscbuild doesn’t have; the H5 gameplay boundary isGameRoot.instance.onWin()/.onLose(). Porting legacy gameplay code that callsGameView.instancedirectly onto an H5 project is the most common way this mismatch surfaces — grep forGameViewbefore assuming the legacy path. - 🅗 Popup-over-gameplay is an invariant, not a style choice. Win/lose results are
PopupViews shown byPopupServiceover the still-live gameplay screen — gameplay is never destroyed, unloaded, or replaced to show a result. Code that tears down the gameplay screen before showing win/lose breaks any “peek behind the popup” or retry-in-place flow the popup depends on. - 🅗 A popup blocks input in BOTH directions, and the blocker must BE
cc.BlockInputEvents(a bare dimmer claims no touch): on the Backdrop whencloseOnBackdropis off; on a non-stretched Panel root when it is on. Verify by runtime tap-through andscripts/check-popup-blockers.cjs <popup-prefab-dir>.references/popup-input-and-stack.md§ 1. - 🅗 Entrance stagger: never scale a
cc.Buttonfrom zero — the hit box follows scale; fade at rest scale.references/popup-input-and-stack.md§ 2. - 🅗
ScreenManager.showcloses ALL popups after activating the new screen — wait for the screen to be current,PopupService.closeAll(), then open.references/popup-input-and-stack.md§ 3. - 🅗 Android hardware back is unbound by default: bind it once at boot to a pure precedence rule.
references/popup-input-and-stack.md§ 5. - 🅗 Panel content budget is
panelWidth − 2×frame ring, not the container’s.references/popup-input-and-stack.md§ 4. - 🅗 A popup/list has three states (empty, locked-and-visible, populated); pooled lists bind every slot; clip with
SPRITE_STENCIL; everycc.Buttonships SCALE ~0.94.references/screen-states-and-lists.md. - 🅗 Gameplay code calls through
GameRoot, neverPopupService/ViewRegistrydirectly.GameRoot.instance.onWin()/.onLose()is the one boundary gameplay crosses; if you find gameplay code importingPopupServiceto show its own popup, that is coupling gameplay to the presentation layer the H5 architecture was built to separate out. - Inspector-wired callback params must guard with
typeof param === 'function', never bare?.()or a truthy check. Cocos invokes an Inspector-wired handler with the EventHandler’s CustomEventData string as its FIRST argument, notundefined—onComplete?.()orif (onComplete)then throws.references/inspector-and-audio-traps.md§ 1. LoadingView(and any “params not ready” boot cover) must render opaque on frame 1, never fade in from 0.startRun()/gameplay can begin beforestartLoading()resolves, so an entrance fade on the cover itself exposes the live unconfigured world underneath for the fade’s duration. Seet1k-cocos-playable-juice’s Gotchas for the full rule (snap covers opaque on show, fade only their exit) and thefeedback-waiver: boot cover must be opaque on frame 1convention.- Audio clips resolve ONLY from the in-scene
AudioContainer.audioList— noresources/audiofallback. A clip must be inaudioListand itsAUDIO_NAMEmust match the asset basename exactly; anything else resolves null and logs only a warning.references/inspector-and-audio-traps.md§ 2. - Gating audio on first interaction has two traps: unlock order (
stopMusic→ unmute →playMusic, all in the gesture handler) and muted one-shots staying silent after unlock — by design, do not “fix”.references/inspector-and-audio-traps.md§ 3. - 🅗 Releasing the FTUE gate in the editor preview:
cc.find('GameRoot')is null — the template’sGameRootsits at/UICanvas/GameRoot. A guarded release script then skipsonTutorialComplete()with no error, the gate never releases, and the flow stays parked on the templateTransitionPopupcover: a preview showing only a logo is that cover, not a splash screen. Callcc.find('UICanvas/GameRoot').getComponent('GameRoot').onTutorialComplete()from the console, reading the path off the open scene rather than assuming one.
Executed by
Section titled “Executed by”check-popup-blockers.cjs is scripted: t1k-data-verifier runs it; wiring stays on t1k-cocos-base-developer. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md.