PlatformAdapter

Defined in: platform/types.ts:367

Properties

family?

readonly optional family?: "minigame"

Defined in: platform/types.ts:375

The capability family this platform belongs to, if any. Absent means the platform stands alone (web, node, native). Set by the mini-game family adapter — the single reason isMiniGame() needs no vendor list.

---

name

readonly name: PlatformName

Defined in: platform/types.ts:368

Methods

bindInputEvents()

bindInputEvents(callbacks, target?): void

Defined in: platform/types.ts:432

Parameters

callbacks

InputEventCallbacks

target?

unknown

Returns

void

---

canPay()?

optional canPay(): boolean

Defined in: platform/types.ts:631

Whether in-game purchase is permitted HERE.

A separate question from whether the host exposes the call, and the reason this is a capability rather than a try-and-see: on WeChat, paying inside a mini-game is an Android-only permission — the API is present on an iPhone and refusing it is the platform’s rule, not a fault. A game has to be able to ask before it shows a shop.

Returns

boolean

---

canSignIn()?

optional canSignIn(): boolean

Defined in: platform/types.ts:620

Whether login would reach a real sign-in.

Method presence is not a capability probe for a FAMILY adapter — one class serves every mini-game vendor, so it defines login whether or not the host behind it has one. An adapter that is one platform can omit this and presence stands; a family answers for the host it actually wraps.

Returns

boolean

---

checkSession()?

optional checkSession(): Promise<boolean>

Defined in: platform/types.ts:637

Whether the host still regards the last sign-in as current, so a game can skip re-exchanging a code it does not need.

Returns

Promise<boolean>

---

clearStorage()

clearStorage(prefix): void

Defined in: platform/types.ts:649

Parameters

prefix

string

Returns

void

---

createAudioBackend()?

optional createAudioBackend(): PlatformAudioBackend

Defined in: platform/types.ts:486

Create the platform audio backend (WebAudio on web, the mini-game audio API on WeChat). Optional — a host with no audio device (headless node, the unshipped native shell) omits it and the audio system falls back to the silent Null backend, exactly like createVideoBackend.

Returns

PlatformAudioBackend

---

createCanvas()

createCanvas(width, height): PlatformCanvas

Defined in: platform/types.ts:392

Parameters

width

number

height

number

Returns

PlatformCanvas

---

createImage()

createImage(): PlatformImage

Defined in: platform/types.ts:430

Returns

PlatformImage

---

createInterstitialAd()?

optional createInterstitialAd(adUnitId): PlatformInterstitialAd | null

Defined in: platform/types.ts:589

One interstitial ad unit — same availability story as rewarded.

Parameters

adUnitId

string

Returns

PlatformInterstitialAd | null

---

createRewardedAd()?

optional createRewardedAd(adUnitId): PlatformRewardedAd | null

Defined in: platform/types.ts:587

One rewarded ad unit. Mini-game hosts implement it over their RewardedVideoAd; platforms without an ad system (web, native until a mediation SDK is wired, playable — networks forbid nested ads) omit the method, and a family adapter whose PARTICULAR host lacks the capability returns null. Both answers mean the same thing to the services layer: substitute the mock provider or fail loud with the reason.

Parameters

adUnitId

string

Returns

PlatformRewardedAd | null

---

createSocket()?

optional createSocket(options): PlatformSocket

Defined in: platform/types.ts:520

Open a socket connection. Web → WebSocket, WeChat → wx.connectSocket, Node → a ws wrapper. Optional — platforms without networking (playable ads) omit it and createSocket() fails loud.

Parameters

options

PlatformSocketOptions

Returns

PlatformSocket

---

createTextEditor()?

optional createTextEditor(): PlatformTextEditor | null

Defined in: platform/types.ts:426

The OS text-editing surface for editable fields (see PlatformTextEditor). Optional — a host without one (a headless realm, the editor’s edit mode) renders fields but cannot type into them.

Returns

PlatformTextEditor | null

---

createVideoBackend()?

optional createVideoBackend(ctx): PlatformVideoBackend

Defined in: platform/types.ts:493

Create the platform video backend: HTMLVideoElement on web, the wasm software decoder (videodec side module) on WeChat. The choice is a static per-platform matrix — no runtime fallback chain. Optional — a platform without video (headless server) omits it and the video system uses the silent Null backend.

Parameters

ctx

VideoBackendContext

Returns

PlatformVideoBackend

---

devicePixelRatio()

devicePixelRatio(): number

Defined in: platform/types.ts:644

Returns

number

---

fetch()

fetch(url, options?): Promise<PlatformResponse>

Defined in: platform/types.ts:377

Parameters

url

string

options?

PlatformRequestOptions

Returns

Promise<PlatformResponse>

---

fileExists()

fileExists(path): Promise<boolean>

Defined in: platform/types.ts:383

Parameters

path

string

Returns

Promise<boolean>

---

getStorageItem()

getStorageItem(key): string | null

Defined in: platform/types.ts:646

Parameters

key

string

Returns

string | null

---

hasTouch()?

optional hasTouch(): boolean

Defined in: platform/types.ts:440

Whether this device can be touched at all. A game that only shows its on-screen controls after the first touch asks its player to touch the screen twice, the first time at nothing — so the question has to be answerable before anyone has touched anything. Absent means no.

Returns

boolean

---

instantiateWasm()

instantiateWasm(pathOrBuffer, imports): Promise<WasmInstantiateResult>

Defined in: platform/types.ts:387

Parameters

pathOrBuffer

string | ArrayBuffer

imports

WebAssembly.Imports

Returns

Promise<WasmInstantiateResult>

---

language()?

optional language(): string

Defined in: platform/types.ts:579

The host’s UI language tag (‘zh-CN’, ‘en-US’, …). WeChat reports ‘zh_CN’-style tags — platformLanguage() normalizes underscores. Optional; web falls through to navigator.language.

Returns

string

---

loadImagePixels()

loadImagePixels(path): Promise<ImageLoadResult>

Defined in: platform/types.ts:385

Parameters

path

string

Returns

Promise<ImageLoadResult>

---

loadSubpackage()?

optional loadSubpackage(name): Promise<void>

Defined in: platform/types.ts:500

Download an on-demand asset subpackage by name and resolve when its files are available. WeChat → wx.loadSubpackage; platforms with no subpackage concept (web) omit it and lazy groups load directly from their URLs.

Parameters

name

string

Returns

Promise<void>

---

login()?

optional login(): Promise<string>

Defined in: platform/types.ts:611

Begin a host sign-in. Resolves with the one-time CODE, never a session: turning a code into an identity needs the app secret, which must not be in anything a player can open, so the exchange is the game’s own server’s to make. A platform with no sign-in omits this.

Returns

Promise<string>

---

now()

now(): number

Defined in: platform/types.ts:428

Returns

number

---

onAppHide()?

optional onAppHide(callback): () => void

Defined in: platform/types.ts:574

Parameters

callback

() => void

Returns

() => void

---

onAppShow()?

optional onAppShow(callback): () => void

Defined in: platform/types.ts:573

App foreground/background signals, for platforms with no DOM visibility event. The native shell pushes them through its bridge; the Lifecycle plugin subscribes and auto-pauses on hide. Web/WeChat read visibility from their own globals (document/wx) and omit these. Each returns an unsubscribe.

Parameters

callback

() => void

Returns

() => void

---

onContextLost()?

optional onContextLost(callback): () => void

Defined in: platform/types.ts:567

Subscribe to the GPU taking the rendering context away — backgrounding, a driver reset, too many live contexts on the page. Returns an unsubscribe.

Worth its own channel because it is invisible from everywhere else: no error is thrown and no log is written, the frames simply stop containing anything. A game whose players report “it went black” has no other way to find out that this is what happened.

Who can answer this, and who cannot:

web — yes. webglcontextlost does not bubble, but a non-bubbling event still travels the capture phase, so one window-level listener sees every canvas.

native — yes, IF the shell wired it (NativeBridge.onContextLost). The surface belongs to the host binary and is not visible from JS at all, so it has to be pushed in, like memory pressure and foreground/background.

mini-game — NO, and this is a platform limit rather than a gap here. A mini-game canvas is not a DOM element: MiniGameCanvas is width, height and getContext, with no listener registration and no vendor API for context loss. Nothing to duck-type for. Left unimplemented rather than approximated, because a hook that silently never fires reads as “this never happens” — which on a phone is the opposite of true.

Parameters

callback

() => void

Returns

() => void

---

onMemoryWarning()?

optional onMemoryWarning(callback): () => void

Defined in: platform/types.ts:525

Subscribe to OS memory-pressure warnings; returns an unsubscribe. WeChat → wx.onMemoryWarning; platforms without a pressure signal (web) omit it. Residency caches subscribe to drop their evictable entries.

Parameters

callback

() => void

Returns

() => void

---

onShareRequest()?

optional onShareRequest(provide): void

Defined in: platform/types.ts:595

Provide the card for PASSIVE shares (the host’s own share menu). The host asks at share time, so the provider can answer with live state.

Parameters

provide

() => PlatformShareOptions

Returns

void

---

onStoreOverlay()?

optional onStoreOverlay(listener): () => void

Defined in: platform/types.ts:480

Tell me when the store’s overlay covers the game, and when it stops.

A takeover the game did not ask for: the player pressed Shift+Tab and can no longer act, so it pauses exactly as a fullscreen ad does. Returns an unsubscribe. Absent where no overlay exists, and nothing is missed there.

Parameters

listener

(covered) => void

Returns

() => void

---

onUnhandledError()?

optional onUnhandledError(callback): () => void

Defined in: platform/types.ts:538

Subscribe to errors that reached the host with nobody catching them — window.onerror + unhandledrejection on the web, wx.onError + wx.onUnhandledRejection on a mini-game. Returns an unsubscribe.

This is the only channel for the failures that happen OUTSIDE a system: a throw in a setTimeout, a promise nobody awaited, a callback from the host. The engine’s own errors go through the logger and need no platform. Optional — a platform without the signal simply never fires, and the diagnostics plugin still collects everything else.

Parameters

callback

(error) => void

Returns

() => void

---

openDataCanvas()?

optional openDataCanvas(): PlatformCanvas | null

Defined in: platform/types.ts:604

The canvas the open data context draws on, for the main domain to sample as a texture. Null when the host has the capability but this game’s package declares no context to draw with.

Returns

PlatformCanvas | null

---

openDataPostMessage()?

optional openDataPostMessage(message): void

Defined in: platform/types.ts:600

Send a message into the open data context — the second JS runtime that is the only place friend data can be read. ONE WAY by nature: no host offers a channel back, so this returns nothing and nothing awaits it.

Parameters

message

Record<string, unknown>

Returns

void

---

pollGamepads()?

optional pollGamepads(): GamepadSnapshot[]

Defined in: platform/types.ts:449

Poll connected gamepads for this frame. Optional — platforms without gamepad support (WeChat, headless) omit it and the input plugin skips gamepad polling entirely.

Returns

GamepadSnapshot[]

---

rasterizeGlyph()?

optional rasterizeGlyph(request): PlatformGlyph | null

Defined in: platform/types.ts:405

Rasterize one glyph through the OS text stack, for a platform with no 2D canvas to draw it on. Synchronous: the dynamic glyph atlas fills cells during the frame it needs them.

Optional — a platform that has createCanvas omits it and the atlas uses the Canvas2D rasterizer (web, WeChat). Native implements it (the embedded-Dawn host has no DOM), and null means the font or the glyph was unavailable, which the atlas treats as “no cell” exactly as it does a canvas miss.

Parameters

request

PlatformGlyphRequest

Returns

PlatformGlyph | null

---

readCacheFile()?

optional readCacheFile(key): Promise<ArrayBuffer | null>

Defined in: platform/types.ts:514

Persistent content-addressed byte cache — the offline/disk primitive behind hot-update. key is an immutable content-addressed url (the asset’s <hash>.<ext> CDN url), so an entry NEVER goes stale and needs no invalidation. Hot-update writes each verified downloaded asset here; the http backend reads it first so updated assets stay available offline and skip the CDN roundtrip.

Optional — a platform with no local storage (web relies on the browser HTTP cache) omits BOTH; then platformReadCacheFile returns null (a miss → normal fetch) and platformWriteCacheFile is a no-op. Node (fs) and native (the shell’s on-disk store) implement them; WeChat may later back them with wx user storage.

Parameters

key

string

Returns

Promise<ArrayBuffer | null>

---

readFile()

readFile(path): Promise<ArrayBuffer>

Defined in: platform/types.ts:379

Parameters

path

string

Returns

Promise<ArrayBuffer>

---

readTextFile()

readTextFile(path): Promise<string>

Defined in: platform/types.ts:381

Parameters

path

string

Returns

Promise<string>

---

registerFont()?

optional registerFont(family, bytes): Promise<void>

Defined in: platform/types.ts:419

Make a font file the app SHIPS usable under family, so Text can name it the same way it names a system font. Every platform resolves a family through its own text stack — Canvas2D on the web, the OS matcher on native — and none of them can see a file inside the project, so a shipped font has to be handed to that stack explicitly. This is that hand-off; the font asset loader calls it once per font.

Optional: a host without it simply has no project fonts, and Text falls back to fontFamily (documented behaviour, not a silent failure). Resolves when the family is ready to rasterize with.

Parameters

family

string

bytes

ArrayBuffer

Returns

Promise<void>

---

removeStorageItem()

removeStorageItem(key): void

Defined in: platform/types.ts:648

Parameters

key

string

Returns

void

---

requestPayment()?

optional requestPayment(request): Promise<void>

Defined in: platform/types.ts:634

Buy quantity units of the host’s in-game currency. Resolves when the host reports the purchase done; rejects with the host’s own reason.

Parameters

request

PlatformPaymentRequest

Returns

Promise<void>

---

setCloudKeyValues()?

optional setCloudKeyValues(entries): boolean

Defined in: platform/types.ts:642

Write this player’s own rows to the host’s per-player cloud store — the writable half of a leaderboard. Reading is the open data context’s alone, which is the whole reason that context exists. Returns whether there was a store to write to; the write itself is fire-and-forget.

Parameters

entries

Readonly<Record<string, string>>

Returns

boolean

---

setStorageItem()

setStorageItem(key, value): void

Defined in: platform/types.ts:647

Parameters

key

string

value

string

Returns

void

---

setWindowSize()?

optional setWindowSize(width, height): void

Defined in: platform/types.ts:471

Ask for a window this big, in design pixels.

Only a platform that OWNS a window has one to size — a phone is given a screen and a browser a canvas. Best-effort: the host clamps it to the display, and only the first ask counts.

Parameters

width

number

height

number

Returns

void

---

share()?

optional share(options): void

Defined in: platform/types.ts:592

Actively open the host’s share sheet. Fire-and-forget: since 2021 no mini-game host reports whether the player actually shared.

Parameters

options

PlatformShareOptions

Returns

void

---

steamAchievements()?

optional steamAchievements(appId): AchievementProvider | null

Defined in: platform/types.ts:458

Bring a store’s achievement service up for

Parameters

appId

number

Returns

AchievementProvider | null

P

appId, or null.

A platform with no store omits it; a desktop build with no client running answers null. The service then keeps its local provider, so a game’s code never branches on any of this.

---

steamIdentity()?

optional steamIdentity(): { id: string; name: string; } | null

Defined in: platform/types.ts:462

The signed-in store account, or null. id is a STRING — 64 bits of account id do not survive a double.

Returns

{ id: string; name: string; } | null

---

unbindInputEvents()?

optional unbindInputEvents(): void

Defined in: platform/types.ts:444

Tear down the listeners bindInputEvents registered. Optional — a headless host that never binds input (node) omits it.

Returns

void

---

writeCacheFile()?

optional writeCacheFile(key, bytes): Promise<void>

Defined in: platform/types.ts:515

Parameters

key

string

bytes

ArrayBuffer

Returns

Promise<void>