PlatformAdapter

Defined in: platform/types.ts:374

Properties

family?

readonly optional family?: "minigame"

Defined in: platform/types.ts:385

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:378

Methods

bindInputEvents()

bindInputEvents(callbacks, target?): void

Defined in: platform/types.ts:442

Parameters

callbacks

InputEventCallbacks

target?

unknown

Returns

void

---

canManageCache()?

optional canManageCache(): boolean

Defined in: platform/types.ts:528

Cache management is separate from byte storage. Entries are opaque safe names, never arbitrary paths; hosts must exclude application saves.

Returns

boolean

---

canPay()?

optional canPay(): boolean

Defined in: platform/types.ts:654

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:643

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:660

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:682

Parameters

prefix

string

Returns

void

---

createAudioBackend()?

optional createAudioBackend(): PlatformAudioBackend

Defined in: platform/types.ts:496

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:402

Parameters

width

number

height

number

Returns

PlatformCanvas

---

createImage()

createImage(): PlatformImage

Defined in: platform/types.ts:440

Returns

PlatformImage

---

createInterstitialAd()?

optional createInterstitialAd(adUnitId): PlatformInterstitialAd | null

Defined in: platform/types.ts:608

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:606

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:536

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:436

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:503

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

---

device()?

optional device(): DeviceBackend

Defined in: platform/types.ts:376

Lazy device services, so unused games bind no sensor/lifecycle listeners.

Returns

DeviceBackend

---

deviceName()?

optional deviceName(): string

Defined in: platform/types.ts:598

What a person would call this device when picking it from a list: a phone’s model, or a browser and its system. Optional.

Returns

string

---

devicePixelRatio()

devicePixelRatio(): number

Defined in: platform/types.ts:667

Returns

number

---

deviceQualityInfo()?

optional deviceQualityInfo(): DeviceQualityInfo

Defined in: platform/types.ts:377

Returns

DeviceQualityInfo

---

fetch()

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

Defined in: platform/types.ts:387

Parameters

url

string

options?

PlatformRequestOptions

Returns

Promise<PlatformResponse>

---

fileExists()

fileExists(path): Promise<boolean>

Defined in: platform/types.ts:393

Parameters

path

string

Returns

Promise<boolean>

---

flushStorage()?

optional flushStorage(): Promise<void>

Defined in: platform/types.ts:684

Await pending asynchronous storage writes. Absence implies synchronous storage only.

Returns

Promise<void>

---

getStorageItem()

getStorageItem(key): string | null

Defined in: platform/types.ts:679

Parameters

key

string

Returns

string | null

---

hasCacheStorage()?

optional hasCacheStorage(): boolean

Defined in: platform/types.ts:529

Returns

boolean

---

hasTouch()?

optional hasTouch(): boolean

Defined in: platform/types.ts:450

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:397

Parameters

pathOrBuffer

string | ArrayBuffer

imports

WebAssembly.Imports

Returns

Promise<WasmInstantiateResult>

---

language()?

optional language(): string

Defined in: platform/types.ts:595

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

---

listCacheFiles()?

optional listCacheFiles(): Promise<object[]>

Defined in: platform/types.ts:530

Returns

Promise<object[]>

---

loadImagePixels()

loadImagePixels(path): Promise<ImageLoadResult>

Defined in: platform/types.ts:395

Parameters

path

string

Returns

Promise<ImageLoadResult>

---

loadSubpackage()?

optional loadSubpackage(name): Promise<void>

Defined in: platform/types.ts:510

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:634

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:438

Returns

number

---

onAppHide()?

optional onAppHide(callback): () => void

Defined in: platform/types.ts:590

Parameters

callback

() => void

Returns

() => void

---

onAppShow()?

optional onAppShow(callback): () => void

Defined in: platform/types.ts:589

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

---

onAudioMute()?

optional onAudioMute(handler): () => void

Defined in: platform/types.ts:674

Host audio policy; game volume/resume controls cannot override it.

Parameters

handler

(muted) => void

Returns

() => void

---

onContextLost()?

optional onContextLost(callback): () => void

Defined in: platform/types.ts:583

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:541

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:614

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:490

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:554

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:627

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:623

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:459

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:415

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:524

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:389

Parameters

path

string

Returns

Promise<ArrayBuffer>

---

readTextFile()

readTextFile(path): Promise<string>

Defined in: platform/types.ts:391

Parameters

path

string

Returns

Promise<string>

---

registerFont()?

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

Defined in: platform/types.ts:429

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>

---

removeCacheFile()?

optional removeCacheFile(name): Promise<void>

Defined in: platform/types.ts:531

Parameters

name

string

Returns

Promise<void>

---

removeStorageItem()

removeStorageItem(key): void

Defined in: platform/types.ts:681

Parameters

key

string

Returns

void

---

requestPayment()?

optional requestPayment(request): Promise<void>

Defined in: platform/types.ts:657

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>

---

safeAreaInsets()?

optional safeAreaInsets(): object

Defined in: platform/types.ts:671

Live native content insets in framebuffer pixels, independent of DPR. Absent on hosts without a safe-area source.

Returns

object

bottom

bottom: number

left

left: number

right

right: number

top

top: number

---

screenRecorder()?

optional screenRecorder(): PlatformScreenRecorder | null

Defined in: platform/types.ts:618

The host’s screen recorder, or null where this particular host has none. Absent on platforms that cannot record at all (native, playable).

Returns

PlatformScreenRecorder | null

---

setCloudKeyValues()?

optional setCloudKeyValues(entries): boolean

Defined in: platform/types.ts:665

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:680

Parameters

key

string

value

string

Returns

void

---

setWindowSize()?

optional setWindowSize(width, height): void

Defined in: platform/types.ts:481

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:611

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:468

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:472

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

---

submitScore()?

optional submitScore(score): Promise<void>

Defined in: platform/types.ts:677

Send one score to the host. Completion does not certify ranking acceptance.

Parameters

score

number

Returns

Promise<void>

---

unbindInputEvents()?

optional unbindInputEvents(): void

Defined in: platform/types.ts:454

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:525

Parameters

key

string

bytes

ArrayBuffer

Returns

Promise<void>