Skip to content

t1k:cocos:playable:gameflow

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: boot cover fade, CTA, end card, game flow, gameflow, loading, UI views

/t1k:cocos:playable:gameflow

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).

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.

Terminal window
ls -d assets/PLAGameFoundation assets/H5GameFoundation assets/packages/@playablelabs 2>/dev/null # framework root
ls -d assets/PlayableParamterTool assets/scripts/parameter 2>/dev/null # parameter layer
grep -rl "CTAService\|STORE_LINK" assets/scripts 2>/dev/null | head # CTA layer
ls assets/scripts/**/GameConfig.ts 2>/dev/null # tuning location
grep -rl "class GameFlow\b" assets/scripts 2>/dev/null | head # 🅗 H5 registered-state architecture
grep -rl "class ScreenManager\|class PopupService\|class ViewRegistry" assets/scripts 2>/dev/null | head
grep -rl "class GameView\b" assets/scripts 2>/dev/null | head # 🅛 legacy view-stack architecture
Playable-ad profileGameplay-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 cardfull end card with CTA buttonresult view, no CTA button
Loadingwaits on AllAsyncParametersReadySignalno parameter gate — drive from asset/bundle load only
Framework rootdb://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 ownerGameView 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 .activeScreenManager (full-screen states) + PopupService (overlays) + ViewRegistry (view-id → prefab resolution), runtime-spawned rather than scene-wired
Win / loseWinView / 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 classn/a (concrete Component subclasses)BaseScreen — the abstract base every registered full-screen state extends
GameView.instancepresentgone — 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.

LOADING -> FTUE -> GAMEPLAY -> WIN / LOSE
export 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 / LOSE

Route 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.

  • GameView (singleton) — State machine. onWin(), onLose(), onTutorialComplete()
  • LoadingView — Progress bar. 🅟 waits for AllAsyncParametersReadySignal and is bound via LoadingScreenParameter (replaces old scattered LoadingBackgroundColor + LoadingIcon + LoadingGameName params). 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, subtitleLabel for ParameterBinder.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 old EndCardWinCTA / EndCardLoseCTA params).
  • 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.
  • 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 is GameRoot, not GameFlow (see below).
  • State classes (typically Loading / Ftue / Gameplay / ChapterResult / Win / Lose) — one class per GameState value, registered with GameFlow rather 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 PopupView never destroys the screen beneath it.
  • ViewRegistry — resolves a view id to its prefab/class for ScreenManager/PopupService to 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; GameRoot then asks PopupService to show the win/lose popup. Gameplay code never imports PopupService or ViewRegistry directly — it only ever calls through GameRoot.

🅟 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.

Steps per profile (🅛 six steps, 🅗 five steps): references/adding-views-and-states.md.

ParametersReadySignal 🅟 sync params ready
AllAsyncParametersReadySignal 🅟 async params loaded (LoadingView waits for this)
FirstInteractionSignal -- user first touch (InputService)
TapSignal / SwipeSignal -- user input events

The 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.

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.

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.

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.

See references/gameflow-code-examples.md for complete implementation patterns.

  • 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, because LoadingView is waiting on AllAsyncParametersReadySignal in a project that has no parameters to load.
  • 🅛 NEVER extend EndCardView for an interstitial (between-rounds) view. EndCardView.onEnable() calls setupCTA() unconditionally, and when fullScreenCTA is true it binds TOUCH_END on the whole node → CTAService.handleCTAClick(). A card shown mid-gameplay would redirect the player to the store on any tap. Write a plain Component (~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 a cc.BlockInputEvents: Cocos dispatches a touch to the topmost node that registers a listener, so a bare dimming Sprite overlay does NOT stop taps from reaching the live board underneath. (On 🅗 H5, the equivalent is: don’t route an interstitial through PopupService’s win/lose popup path — give it its own PopupView subclass 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); scheduleOnce callbacks 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 in onLoad(), and call unscheduleAllCallbacks() 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.instance is gone on the H5 profile — never import or reference it, even defensively. A null-guarded GameView.instance?.onWin() still imports a class the project’s tsc build doesn’t have; the H5 gameplay boundary is GameRoot.instance.onWin() / .onLose(). Porting legacy gameplay code that calls GameView.instance directly onto an H5 project is the most common way this mismatch surfaces — grep for GameView before assuming the legacy path.
  • 🅗 Popup-over-gameplay is an invariant, not a style choice. Win/lose results are PopupViews shown by PopupService over 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 when closeOnBackdrop is off; on a non-stretched Panel root when it is on. Verify by runtime tap-through and scripts/check-popup-blockers.cjs <popup-prefab-dir>. references/popup-input-and-stack.md § 1.
  • 🅗 Entrance stagger: never scale a cc.Button from zero — the hit box follows scale; fade at rest scale. references/popup-input-and-stack.md § 2.
  • 🅗 ScreenManager.show closes 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; every cc.Button ships SCALE ~0.94. references/screen-states-and-lists.md.
  • 🅗 Gameplay code calls through GameRoot, never PopupService/ViewRegistry directly. GameRoot.instance.onWin()/.onLose() is the one boundary gameplay crosses; if you find gameplay code importing PopupService to 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, not undefined — onComplete?.() or if (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 before startLoading() resolves, so an entrance fade on the cover itself exposes the live unconfigured world underneath for the fade’s duration. See t1k-cocos-playable-juice’s Gotchas for the full rule (snap covers opaque on show, fade only their exit) and the feedback-waiver: boot cover must be opaque on frame 1 convention.
  • Audio clips resolve ONLY from the in-scene AudioContainer.audioList — no resources/audio fallback. A clip must be in audioList and its AUDIO_NAME must 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’s GameRoot sits at /UICanvas/GameRoot. A guarded release script then skips onTutorialComplete() with no error, the gate never releases, and the flow stays parked on the template TransitionPopup cover: a preview showing only a logo is that cover, not a splash screen. Call cc.find('UICanvas/GameRoot').getComponent('GameRoot').onTutorialComplete() from the console, reading the path off the open scene rather than assuming one.

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.