t1k:cocos:base:platform-integrate
| Field | Value |
|---|---|
| Module | base |
| Version | 4.51.9 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/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.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “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 |
1. Install
Section titled “1. Install”Packages live on the studio’s private registry, not npmjs.org. Scope @playablelabs must point at it:
@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-yandex21 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:
| Port | For |
|---|---|
IAdServices | Rewarded and non-rewarded ads |
IIapServices | Products, receipts, settlement |
IAnalyticServices | Events |
IAuthServices | Identity claims, proofs, sessions |
ISocialServices | Share, invite, social context |
ILeaderboardServices | Scores and entries |
ICloudSaveServices | Key-value save backends |
IHostServices | The host page or shell |
INetworkServices | Network policy |
ISystemServices | Device 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.
3. Compose one adapter per build target
Section titled “3. Compose one adapter per build target”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:
| State | Meaning | What the game does |
|---|---|---|
supported | Available here | Use it |
unsupported | This portal cannot do it | Hide the affordance |
prohibited | Policy forbids it, and it will never be enabled | Hide it, and never retry |
unresolved | Not known until runtime asks | Ask, 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.
6. Verify before you ship
Section titled “6. Verify before you ship”| Check | What it catches |
|---|---|
bun conformance (platform-conformance) | An adapter that does not honour the port contract |
| Manifest two-way check | Declaring 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.
Hard rules
Section titled “Hard rules”bun typecheckcannot see Node globals. Tests import vitest, vitest’s pnpm copy carries a peer@types/node, and TypeScript pulls thatglobals.d.tsinto the whole program, soprocess.envtypechecks clean and then throwsReferenceErrorin the player’s browser. The SDK’sscripts/node-globals-gate.mjsis what actually catches it. Never reach forprocess,Buffer,__dirnameorrequirein 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.
composeAutoon a strict-portal or mini-game row is a build that fails late, at submission rather than at compile. UsecomposeStaticthere (D43).- The private registry is not npmjs.org. Without the
@playablelabs:registryline, install resolves against the public registry and fails with 404 on every package. - One adapter is not one store.
platform-quickgamefans 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.