Skip to content

t1k:cocos:base:platform-integrate

FieldValue
Modulebase
Version4.51.9
Effortmedium
Tools—

Keywords: adapter, capability, ci-targets, cloud save, composeAuto, composeStatic, conformance, cpm registry, cross-platform game, IAdServices, IIapServices, leaderboard, multi-platform, platform sdk, platform-core, playablelabs, portal, publish, rewardTrust

/t1k:cocos:base:platform-integrate
[game or portal to integrate]

Platform Integration (Cocos → many portals)

Section titled “Platform Integration (Cocos → many portals)”

One game, one integration, many portals. The game calls domain ports; one adapter per portal supplies them at build time. A game written against a portal’s own SDK is a game somebody has to port.

Not this skill: playable-ad network SDKs, postMessage parameters, CTA routing → t1k:cocos:playable:sdk-core. Plane/Jenkins tracking for a playable → t1k:cocos:playable:pipeline.

IntentPath
“Add the SDK to my game for the first time”1. Install then 2. Write against ports
“Ship to one more portal”3. Compose per target
“Feature X is missing on portal Y”4. Capabilities
“Grant currency for a rewarded ad”5. Reward trust
“Is my adapter correct?”6. Verify

Packages live on the studio’s private registry, not npmjs.org. Scope @playablelabs must point at it:

.npmrc
@playablelabs:registry=https://cpm.playablelabs.ai/

Then core plus one adapter per portal you ship to:

bun add @playablelabs/platform-core @playablelabs/platform-poki @playablelabs/platform-yandex

21 adapter packages exist. Add @playablelabs/platform-loader when you want the composition helpers in §3, and @playablelabs/platform-conformance as a devDependency (§6).

2. Write against ports, never a vendor SDK

Section titled “2. Write against ports, never a vendor SDK”

platform-core exports 10 domain ports. Your game imports these and nothing portal-specific:

PortFor
IAdServicesRewarded and non-rewarded ads
IIapServicesProducts, receipts, settlement
IAnalyticServicesEvents
IAuthServicesIdentity claims, proofs, sessions
ISocialServicesShare, invite, social context
ILeaderboardServicesScores and entries
ICloudSaveServicesKey-value save backends
IHostServicesThe host page or shell
INetworkServicesNetwork policy
ISystemServicesDevice and environment facts

The load-bearing rule: the game must not know which portal it is running on. If a call site names Poki, that code has to be rewritten for every other row. platform-core itself imports neither cc nor any Node builtin, and CI enforces both, which is what lets your game logic be unit-tested with no Creator and no browser.

Composition happens at build time, one named adapter per target. Two entry points, from @playablelabs/platform-loader:

  • composeStatic(...) — the default. The generated build entry names exactly one adapter module. One bundle per portal, and no second adapter is ever imported into it.
  • composeAuto(...) — opt-in runtime detect plus a dynamic import of exactly one adapter chunk, with a local fallback. Never for a strict-portal or mini-game row (decision D43): those hosts refuse the extra fetch or forbid the dynamic chunk outright.

Prefer composeStatic unless you can state why the target tolerates runtime detection.

One adapter can serve several targets. platform-quickgame covers four Chinese OEM stores (OPPO, vivo, Huawei, Honor), which is why the SDK’s 21 adapters map to 25 build-target rows. Do not assume one adapter equals one store.

4. Capabilities are four states, not a boolean

Section titled “4. Capabilities are four states, not a boolean”

Every adapter publishes a capability table. A capability is one of:

StateMeaningWhat the game does
supportedAvailable hereUse it
unsupportedThis portal cannot do itHide the affordance
prohibitedPolicy forbids it, and it will never be enabledHide it, and never retry
unresolvedNot known until runtime asksAsk, then branch

Do not collapse these into a boolean. unsupported and prohibited differ because a dashboard toggle can turn one on and policy will never turn the other on: Zalo bans ads by policy, while another portal’s ads are merely switched off in a console. unresolved is not “false” — treating it as false silently disables working features.

Capability tables are per-adapter data, never branching logic in the game. If you find yourself writing if (platform === 'poki'), the answer belongs in a capability row instead.

5. Reward trust is not the adapter’s to decide

Section titled “5. Reward trust is not the adapter’s to decide”

Four tiers, strongest first: server-verified, client-first-party, client-third-party, client-only.

An adapter never declares its own rewardTrust. That row lives in platform-core’s CODEOWNED registry, and CI fails a build where an adapter manifest sets it. The reason is economic, not stylistic: trust decides whether a rewarded ad may mint currency the player keeps.

client-only is the conservative floor and the one tier that must never mint persisted currency. On a client-only portal, grant a session-scoped reward, or gate the grant behind your own server.

Save, currency, IAP-grant and rewarded-ad result rules (one currency authority, merge a late save, branch on the ad result, thunk for hydrated deps): references/save-and-economy.md.

CheckWhat it catches
bun conformance (platform-conformance)An adapter that does not honour the port contract
Manifest two-way checkDeclaring a capability you do not deliver, and delivering one you never declared
bash scripts/ci-gates.sh (in the SDK repo)Engine or Node imports, and Node globals, in runtime source

The two-way manifest check matters more than it sounds: an undeclared capability that works today is a capability the next adapter author will break without knowing.

  • bun typecheck cannot see Node globals. Tests import vitest, vitest’s pnpm copy carries a peer @types/node, and TypeScript pulls that globals.d.ts into the whole program, so process.env typechecks clean and then throws ReferenceError in the player’s browser. The SDK’s scripts/node-globals-gate.mjs is what actually catches it. Never reach for process, Buffer, __dirname or require in game or adapter runtime code.
  • Never bundle a vendor SDK. Several ship with no licence at all (all rights reserved), so redistributing a copy inside your build is not cleared. Load them from the vendor’s own CDN at run time, which is what the SDK’s vendor injection already does.
  • Third-party ads and analytics can void payment. CrazyGames pays nothing where a game contains ads not integrated via its SDK; GameDistribution prohibits non-GD ads and Google Analytics; Poki states Google products including Analytics cannot be approved. Ship no extra ad or analytics SDK.
  • composeAuto on a strict-portal or mini-game row is a build that fails late, at submission rather than at compile. Use composeStatic there (D43).
  • The private registry is not npmjs.org. Without the @playablelabs:registry line, install resolves against the public registry and fails with 404 on every package.
  • One adapter is not one store. platform-quickgame fans out to four OEMs; a per-adapter loop over “portals” will under-count your build matrix by three rows.

Integrating a Cocos game with the @playablelabs platform SDK and shipping it to portals. Not ad network SDKs or CTA wiring (t1k:cocos:playable:sdk-core), not portal business terms or revenue splits, and not the SDK’s own internal development.