Skip to content

t1k:cocos:playable:sdk-core

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
Tools—

Keywords: ad network, applovin, audio, AudioBufferSourceNode, CTA, mute, postMessage, sdk, SdkFactory

/t1k:cocos:playable:sdk-core

This skill handles SDK integration, adapter creation, and CTA routing for playable ads. Does NOT handle parameter definitions (use t1k-cocos-playable-parameter) or game flow (use t1k-cocos-playable-gameflow).

Ad Dashboard -> postMessage -> window.mainPlayable.onParameterUpdated()
-> BaseSdkAdapter hooks intercept -> fireParameterUpdate() to listeners
-> PlayableParameterUpdates syncs to PlayableConfig -> onUpdate callbacks

SDK selection: CURRENT_SDK constant in PlayableConfig.ts — set at build time.

assets/PlayableParamterTool/GameConfig.ts
export enum SdkType { VOODOO = 'voodoo', THE_ONE = 'theone' }
  • BaseSdkAdapter (abstract) — Window object hooks, parameter listener pub/sub, polling init
  • SdkFactory — Creates adapter + registers window objects by SDK type
  • CTAService — Routes CTA clicks: THE_ONE -> gameEndHandler, VOODOO -> ParameterManager.redirect()
  1. Add enum value in GameConfig.ts -> SdkType
  2. Create adapter class extending BaseSdkAdapter (singleton pattern)
  3. Implement getWindowPlayableName() and getWindowSdkName()
  4. Register in SdkFactory.createSdk() and getSdkInstance() switch cases
  5. Update CTAService with SDK-specific redirect logic
  6. Set CURRENT_SDK in PlayableConfig.ts
  1. Dashboard edits param -> sends postMessage
  2. SDK sets window.mainPlayable.onParameterUpdated(params)
  3. BaseSdkAdapter hook intercepts, calls original + fires to listeners
  4. PlayableParameterUpdates (listener) syncs values to PlayableConfig
  5. Each parameter’s onUpdate callback fires
  6. ParameterUtils applies changes to scene nodes
  7. Sync done: ParametersReadySignal
  8. Async done (sprites, audio): AllAsyncParametersReadySignal

Playable (from dashboard): create(), init(), start(), pause(), resume(), onResize(), onParameterUpdated(params), onAudioVolumeChanged(), onParameterHighlighted(params)

PlayableMainSdk (our API): getAudioVolume(), getParameterValue(key), getScreenSize(), win(), lose(), getUserLanguage(), redirectToInstallPage()

See references/sdk-code-examples.md for adapter implementation patterns.

  • Per-network SDK quirks — AppLovin auto-resizes the canvas; AdMob doesn’t; Meta freezes mid-frame on init. Pin per-network behavior in a network-specific build flag.
  • The hosting iframe rules — window.top is unreachable; storage is per-iframe; user gesture requirements differ per network.
  • Orion SDK input — installCocosAdapter starts its own RafClock, and that clock silently eats taps. The Orion SDK’s default clock ticks on its own requestAnimationFrame chain, independent of Cocos’s frame loop; each tick commits Begin-phase touches to Hold. Cocos’s own pacer runs a separate rAF chain — it skips vsyncs above game.frameRate, and after any pause/resume (tab hide/show) it re-registers behind the SDK’s chain. Once that happens, the SDK’s clock ticks (and commits Begin -> Hold) before Cocos’s update() gets to read the frame’s taps, so a game reading Begin-phase touches from update() silently loses them. Measured in headless Chrome preview: 19/30 taps seen normally, 0/30 after one pause/resume, 0/30 at game.frameRate = 30. Fix: replace the SDK’s clock via configureProviders({ clock }) with a clock that only ticks when told to, driven from Director.EVENT_AFTER_UPDATE (so the SDK commits touch phases strictly after every component’s update()/lateUpdate() has read this frame’s taps) and reset its baseline on Game.EVENT_SHOW (so a hidden-tab span doesn’t count as one giant delta). installCocosAdapter still starts its own RafClock regardless — it can’t be skipped, since the same call also wires the touch source, mouse fallback, and transport — but once nothing subscribes to it, it just idles. Reference pattern: a small IClock-shaped class (deltaSeconds, now(), onTick(), advance(), resetBaseline(), dispose()) injected with a nowMs/clampDelta pair so it stays Cocos- and SDK-free, wired from the one sim/infrastructure file that is allowed to import the SDK.
  • AppLovin iOS host silently mutes ALL WebAudio buffer playback (BGM + SFX) when the ad opens at device volume 0 — it replaces AudioBufferSourceNode.prototype.start with a no-op before any game script runs, and never restores it once the user raises the volume. AudioContext.state stays "running", gain nodes read correctly, getAudioVolume()/onAudioVolumeChanged() report volume 1, and decoded buffers are intact — every SDK-facing signal says audio should work. Android is unaffected; an OscillatorNode and an HTML <audio> element both keep playing because neither goes through the stubbed method. Detect and fix per references/applovin-ios-volume0-audio-mute.md — a drop-in module restores a native start() at boot and on first touch.