Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

19.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    api.ts
 * @brief   Normalized mini-game host surface + per-vendor profile descriptor.
 *
 * WeChat (`wx`) and Douyin (`tt`) are two vendors of the same "mini-game
 * platform" family: their global objects expose a near-identical API. This file
 * models only the subset the engine actually uses; each vendor's global
 * satisfies `MiniGameGlobal` structurally and is bound at the profile boundary
 * (`sdk/src/platform/<vendor>/profile.ts`) with a single cast.
 *
 * The family logic (canvas / fs / fetch / image / input / storage) is written
 * ONCE against `MiniGameGlobal` in `adapter.ts`. Genuinely divergent operations
 * — WASM instantiation (WeChat's WXWebAssembly vs a standard loader), audio,
 * video, sockets — are methods on `MiniGameProfile`, not derived from the global.
 */

import type { MiniGameDeviceHost } from '../../device/minigame';
import type { PlatformAudioBackend } from '../../audio/PlatformAudioBackend';
import type { PlatformVideoBackend, VideoBackendContext } from '../../video/PlatformVideoBackend';
import type {
    PlatformPaymentRequest, PlatformSocket, PlatformSocketOptions, WasmInstantiateResult,
} from '../types';

// =============================================================================
// Normalized host primitives
// =============================================================================

export interface MiniGameCanvas {
    width: number;
    height: number;
    getContext(type: string, attributes?: unknown): unknown;
}

export interface MiniGameImage {
    width: number;
    height: number;
    src: string;
    onload: (() => void) | null;
    onerror: ((err: unknown) => void) | null;
}

export interface MiniGameFileSystemManager {
    readdir?(opts: { dirPath: string; success?: (res: { files: string[] }) => void; fail?: (err: { errMsg: string }) => void }): void;
    stat?(opts: { path: string; recursive?: boolean; success?: (res: { stats: { size: number; lastAccessedTime: number; isFile(): boolean } }) => void; fail?: (err: { errMsg: string }) => void }): void;
    unlink?(opts: { filePath: string; success?: () => void; fail?: (err: { errMsg: string }) => void }): void;
    rename?(opts: { oldPath: string; newPath: string; success?: () => void; fail?: (err: { errMsg: string }) => void }): void;
    readFileSync(path: string, encoding?: string): ArrayBuffer | string;
    readFile(opts: {
        filePath: string;
        encoding?: string;
        success?: (res: { data: ArrayBuffer | string }) => void;
        fail?: (err: { errMsg: string }) => void;
    }): void;
    access(opts: { path: string; success?: () => void; fail?: (err: { errMsg: string }) => void }): void;
    accessSync(path: string): void;
    writeFile(opts: {
        filePath: string;
        data: string | ArrayBuffer;
        encoding?: string;
        success?: () => void;
        fail?: (err: { errMsg: string }) => void;
    }): void;
}

export interface MiniGameRequestOptions {
    url: string;
    method?: string;
    data?: string | ArrayBuffer;
    header?: Record<string, string>;
    responseType?: 'text' | 'arraybuffer';
    timeout?: number;
    success?: (res: { statusCode: number; header?: Record<string, string>; data: string | ArrayBuffer }) => void;
    fail?: (err: { errMsg: string }) => void;
}

export interface MiniGameSystemInfo {
    pixelRatio?: number;
    language?: string;
    windowWidth?: number;
    windowHeight?: number;
    /** Where the host itself is running — `ios`, `android`, `devtools`, … Not
     *  cosmetic: in-game purchase is permitted on some of these and forbidden
     *  on others, so a capability has to read it. */
    platform?: string;
    model?: string;
    memorySize?: number | string;
}

export interface MiniGameTouch {
    identifier: number;
    clientX: number;
    clientY: number;
}
export interface MiniGameTouchEvent {
    changedTouches: MiniGameTouch[];
}
export interface MiniGameKeyEvent {
    code: string;
}
export interface MiniGameStorageInfo {
    keys: string[];
}

/**
 * A one-shot audio player. Every mini-game host exposes this shape under
 * `createInnerAudioContext()`; WeChat's `InnerAudioContext` is structurally
 * assignable. Modelling it here is what makes audio a FAMILY capability instead
 * of a per-vendor backend.
 */
export interface MiniGameInnerAudioContext {
    src: string;
    loop: boolean;
    volume: number;
    playbackRate: number;
    startTime: number;
    obeyMuteSwitch: boolean;
    readonly paused: boolean;
    readonly currentTime: number;
    readonly duration: number;
    play(): void;
    pause(): void;
    stop(): void;
    destroy(): void;
    onEnded(cb: () => void): void;
    // The host passes an error record; typed as the bottom-ish `{ errMsg: string }`
    // supertype-by-contravariance so a vendor's richer callback stays assignable.
    onError(cb: (res: { errMsg: string }) => void): void;
}

/**
 * A rewarded video ad, as every mini-game host shapes it: WeChat's
 * `RewardedVideoAd` and Douyin's are structurally identical, which is what
 * makes ads a FAMILY capability rather than a per-vendor override. `onClose`
 * reports whether the video was watched to the end (`isEnded`); some hosts
 * omit the record entirely on older runtimes, which callers must treat as
 * "completed" — the platform granted the reward and simply didn't say so.
 */
export interface MiniGameRewardedVideoAd {
    load(): Promise<void>;
    show(): Promise<void>;
    onLoad(cb: () => void): void;
    offLoad(cb: () => void): void;
    onError(cb: (err: { errMsg: string; errCode?: number }) => void): void;
    offError(cb: (err: { errMsg: string; errCode?: number }) => void): void;
    onClose(cb: (res?: { isEnded: boolean }) => void): void;
    offClose(cb: (res?: { isEnded: boolean }) => void): void;
}

/** An interstitial ad. Same family shape as rewarded, plus `destroy` (the
 *  hosts document interstitials as destroyable; rewarded ads are singletons). */
export interface MiniGameInterstitialAd {
    load(): Promise<void>;
    show(): Promise<void>;
    destroy(): void;
    onLoad(cb: () => void): void;
    offLoad(cb: () => void): void;
    onError(cb: (err: { errMsg: string; errCode?: number }) => void): void;
    offError(cb: (err: { errMsg: string; errCode?: number }) => void): void;
    onClose(cb: () => void): void;
    offClose(cb: () => void): void;
}

/** WeChat's GameRecorder. Control calls return promises; outcomes arrive as
 *  events — `stop` carries `{ duration }` in ms and no file, because WeChat
 *  keeps the video. */
export interface MiniGameWxRecorder {
    start(opts: { duration?: number }): void;
    pause(): Promise<unknown>;
    resume(): Promise<unknown>;
    stop(): Promise<unknown>;
    abort(): Promise<unknown>;
    isFrameSupported?(): boolean;
    /** Kuaishou's share for the last recording; the callback gets an error only on failure. */
    publishVideo?(opts: { query?: string; callback?: (error?: unknown) => void }): void;
    on(event: 'start' | 'stop' | 'pause' | 'resume' | 'abort' | 'error', cb: (res?: unknown) => void): void;
    off(event: 'start' | 'stop' | 'pause' | 'resume' | 'abort' | 'error', cb: (res?: unknown) => void): void;
}

/** Douyin's GameRecorderManager. Calls are synchronous; each outcome has its own
 *  listener, and `onStop` hands over the temp file. */
export interface MiniGameTtRecorder {
    start(opts: { duration?: number }): void;
    pause(): void;
    resume(): void;
    stop(): void;
    recordClip(opts: {
        timeRange: [number, number];
        success?: (res: { index: number }) => void;
        fail?: (err: { errMsg?: string }) => void;
    }): void;
    clipVideo(opts: {
        path: string;
        success?: (res: { videoPath: string }) => void;
        fail?: (err: { errMsg?: string }) => void;
    }): void;
    onStart(cb: () => void): void;
    onPause(cb: () => void): void;
    onResume(cb: () => void): void;
    onStop(cb: (res: { videoPath: string }) => void): void;
    onError(cb: (res: { errMsg?: string }) => void): void;
    /** Base library 1.6.1+. */
    onInterruptionBegin?(cb: () => void): void;
    onInterruptionEnd?(cb: () => void): void;
}

/** The share card a host shows for an active or passive share. */
export interface MiniGameShareOptions {
    title?: string;
    imageUrl?: string;
    query?: string;
}

/**
 * The open data context, seen from the MAIN domain.
 *
 * It is a second JS runtime with no WebGL, no wasm and almost none of the host
 * API — and the only place a player's FRIENDS can be read at all. It draws on
 * `canvas`, which the main domain samples as a texture; `postMessage` is how it
 * is told what to draw. There is no channel back: no host offers sub→main
 * messaging, which is why nothing in this engine's leaderboard asks the context
 * a question.
 */
export interface MiniGameOpenDataContext {
    postMessage(message: Record<string, unknown>): void;
    /** The shared canvas. The context draws here; the main domain samples it. */
    readonly canvas: MiniGameCanvas;
}

/** One entry of the host's per-player cloud store — the rows a leaderboard is
 *  assembled from. Writable only for the player themselves. */
export interface MiniGameKVData {
    key: string;
    value: string;
}

/** The socket task `connectSocket()` returns. WeChat's `SocketTask` fits. */
export interface MiniGameSocketTask {
    send(opts: { data: string | ArrayBuffer }): void;
    close(opts: { code?: number; reason?: string }): void;
    onOpen(cb: (res?: unknown) => void): void;
    onMessage(cb: (res: { data: string | ArrayBuffer }) => void): void;
    onClose(cb: (res: { code: number; reason: string }) => void): void;
    onError(cb: (err: unknown) => void): void;
}

// =============================================================================
// The normalized mini-game global
// =============================================================================

/**
 * The subset of the mini-game host global (`wx` / `tt`) the engine consumes.
 * Optional members are capabilities a vendor may lack (keyboard, subpackages,
 * memory-pressure signal, app show/hide). The adapter probes for them at use
 * time, so a vendor missing one degrades gracefully rather than throwing.
 */
export interface MiniGameGlobal extends MiniGameDeviceHost {
    /** The writable directory a game may keep files in (`wx.env.USER_DATA_PATH`). */
    env?: { USER_DATA_PATH?: string };
    createCanvas(): MiniGameCanvas;
    createImage(): MiniGameImage;
    getFileSystemManager(): MiniGameFileSystemManager;
    request(opts: MiniGameRequestOptions): void;
    createInnerAudioContext(): MiniGameInnerAudioContext;
    connectSocket(opts: { url: string; protocols?: string[] }): MiniGameSocketTask;
    getSystemInfoSync(): MiniGameSystemInfo;
    getDeviceInfo?(): MiniGameSystemInfo;

    onTouchStart(cb: (res: MiniGameTouchEvent) => void): void;
    onTouchMove(cb: (res: MiniGameTouchEvent) => void): void;
    onTouchEnd(cb: (res: MiniGameTouchEvent) => void): void;
    offTouchStart(cb: (res: MiniGameTouchEvent) => void): void;
    offTouchMove(cb: (res: MiniGameTouchEvent) => void): void;
    offTouchEnd(cb: (res: MiniGameTouchEvent) => void): void;
    // Optional: a cancelled gesture (system interruption). Present on WeChat/Douyin;
    // guarded so a host without it still binds start/move/end.
    onTouchCancel?(cb: (res: MiniGameTouchEvent) => void): void;
    offTouchCancel?(cb: (res: MiniGameTouchEvent) => void): void;

    onKeyDown?(cb: (res: MiniGameKeyEvent) => void): void;
    onKeyUp?(cb: (res: MiniGameKeyEvent) => void): void;
    offKeyDown?(cb: (res: MiniGameKeyEvent) => void): void;
    offKeyUp?(cb: (res: MiniGameKeyEvent) => void): void;

    // Optional: the host's own loading indicator. WeChat and Douyin both have it,
    // and it is the only progress surface a mini-game has — the display canvas is
    // already the GL surface, so a 2D overlay cannot be drawn on it.
    showLoading?(opts: { title: string; mask?: boolean }): void;
    hideLoading?(): void;

    loadSubpackage?(opts: {
        name: string;
        success?: () => void;
        fail?: (err: unknown) => void;
        complete?: () => void;
    }): void;
    onMemoryWarning?(cb: () => void): void;
    offMemoryWarning?(cb: () => void): void;

    /** Errors that reached the host uncaught. WeChat reports the script error as
     *  a string (plus a structured second argument on newer bases, which this
     *  does not rely on); an unhandled rejection arrives separately, and only on
     *  bases new enough to have it — hence both optional. */
    onError?(cb: (error: string | { message?: string; stack?: string }) => void): void;
    offError?(cb: (error: string | { message?: string; stack?: string }) => void): void;
    onUnhandledRejection?(cb: (res: { reason?: unknown }) => void): void;
    offUnhandledRejection?(cb: (res: { reason?: unknown }) => void): void;

    onShow?(cb: () => void): void;
    onHide?(cb: () => void): void;
    offShow?(cb: () => void): void;
    offHide?(cb: () => void): void;
    /** The window changed size — a rotation, a foldable, split screen. Carries
     *  the new size, which is authoritative: a `getSystemInfoSync` beside it can
     *  still answer with the old one. */
    onWindowResize?(cb: (res: { windowWidth: number; windowHeight: number }) => void): void;

    /** Monetization + share — optional like every capability a vendor may lack
     *  (or a game may not have configured): the adapter probes at use time. */
    createRewardedVideoAd?(opts: { adUnitId: string }): MiniGameRewardedVideoAd;
    createInterstitialAd?(opts: { adUnitId: string }): MiniGameInterstitialAd;
    shareAppMessage?(opts: MiniGameShareOptions & {
        channel?: 'video';
        desc?: string;
        extra?: { videoPath: string };
        success?: () => void;
        fail?: (err: { errMsg?: string }) => void;
    }): void;
    /** Passive share: what the card says when the player shares from the host's
     *  own menu. The host calls `cb` at share time, not at registration. */
    onShareAppMessage?(cb: () => MiniGameShareOptions): void;

    /** WeChat's recorder (base 2.8.0), a singleton. Kuaishou copies the shape. */
    getGameRecorder?(): MiniGameWxRecorder;
    /** Shares WeChat's last recording; must run inside a tap (base 2.26.1). */
    operateGameRecorderVideo?(opts: {
        title?: string;
        desc?: string;
        query?: string;
        timeRange?: number[][];
        success?: () => void;
        fail?: (err: { errMsg?: string; errCode?: number }) => void;
    }): void;
    /** Douyin's recorder (base 1.6.1), a singleton. */
    getGameRecorderManager?(): MiniGameTtRecorder;

    /** Begin a sign-in. The result is a one-time code the game's own server
     *  exchanges — see the note on `PlatformAdapter.login`. */
    login?(opts: {
        success?: (res: { code: string }) => void;
        fail?: (err: unknown) => void;
        timeout?: number;
    }): void;
    /** Whether the host still regards the last sign-in as current. Reports the
     *  answer by WHICH callback it calls, not by a value. */
    checkSession?(opts: { success?: () => void; fail?: (err: unknown) => void }): void;

    /** In-game purchase of the host's currency. Present on the global whatever
     *  device it is running on — whether it may actually be CALLED is a
     *  platform rule, not an API-shape question. See `MiniGamePlatformAdapter.canPay`. */
    requestMidasPayment?(opts: {
        mode: string;
        offerId: string;
        buyQuantity: number;
        zoneId?: string;
        currencyType?: string;
        platform?: string;
        env?: number;
        success?: () => void;
        fail?: (err: { errMsg?: string; errCode?: number }) => void;
    }): void;

    /** The open data context, if this host has one. Absent on a host without
     *  friend data, and on a game whose package declares no context directory. */
    getOpenDataContext?(): MiniGameOpenDataContext;
    /** Write THIS player's rows into the host's cloud store. Writing is the main
     *  domain's half of a leaderboard; reading — anyone's, including the
     *  player's own — belongs to the open data context alone. */
    setUserCloudStorage?(opts: {
        KVDataList: MiniGameKVData[];
        success?: () => void;
        fail?: (err: unknown) => void;
        complete?: () => void;
    }): void;

    getStorageSync(key: string): unknown;
    setStorageSync(key: string, value: string): void;
    removeStorageSync(key: string): void;
    getStorageInfoSync(): MiniGameStorageInfo;
}

// =============================================================================
// Per-vendor profile
// =============================================================================

/**
 * A mini-game vendor's id. The vendors the engine ships are named for
 * completion, but the type is OPEN: a game can describe a host the engine has
 * never heard of and get the whole family for it. Nothing in the SDK branches on
 * this value — it is identity (adapter name, diagnostics, logs), not behavior.
 */
export type MiniGameVendor = 'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | 'alipay' | 'huawei' | 'openpaas' | (string & {});

/**
 * A vendor described as DATA — three facts and, at most, one method.
 *
 * The family adapter reads `global` for every capability the hosts share, and
 * that is nearly all of them: audio (`createInnerAudioContext`), sockets
 * (`connectSocket`), video (the engine's own wasm decoder) and the whole
 * fs/fetch/canvas/input/storage surface all come from the normalized global. So
 * the overrides below are OPTIONAL — a vendor supplies one only where it truly
 * differs from the family. WeChat overrides exactly one (`instantiateWasm`, for
 * WXWebAssembly); a host with standard `WebAssembly` overrides none.
 */
export interface MiniGameProfile {
    /** Vendor identity — used for the adapter `name`, diagnostics, and logs. */
    readonly id: MiniGameVendor;
    /** Human label woven into filesystem error guidance ("WeChat" / "抖音"). */
    readonly hostLabel: string;
    /** The host global (`wx` / `tt`), bound with a cast at the profile boundary. */
    readonly global: MiniGameGlobal;

    /** WASM instantiation, when the host does not use the standard
     *  `WebAssembly.instantiate` (WeChat routes it through WXWebAssembly, which
     *  takes a package path and is not a member of the host global). Omit and
     *  the family reads the file through the adapter and instantiates it. */
    instantiateWasm?(pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports): Promise<WasmInstantiateResult>;

    /** Omit for the family backend over `global.createInnerAudioContext()`. */
    createAudioBackend?(): PlatformAudioBackend;
    /** Omit for the engine's own wasm video decoder (portable to every vendor). */
    createVideoBackend?(ctx: VideoBackendContext): PlatformVideoBackend;
    /** Omit for the family socket over `global.connectSocket()`. */
    createSocket?(options: PlatformSocketOptions): PlatformSocket;

    /**
     * Buying in-game currency, when the vendor's call is not WeChat's
     * `requestMidasPayment`. That one carries WeChat's own rules (Android only,
     * Midas field names), and applying them everywhere makes the engine say
     * "this host sells nothing" about a host that sells things.
     */
    pay?: {
        /** Asked before a game offers a purchase at all. */
        can(): boolean;
        request(request: PlatformPaymentRequest): Promise<void>;
    };

    /** The host reports `windowWidth`/`windowHeight` and touch positions in physical
     *  pixels rather than WeChat's logical ones (vivo: 2340 wide beside a pixelRatio
     *  of 2.75), so multiplying by pixelRatio again would size the screen past the
     *  GPU's limit and put every tap off it. */
    windowInPhysicalPixels?: boolean;

    /** The recording length this vendor accepts, when its recorder's shape is
     *  another vendor's but its limits are not. */
    recordingLimits?: { readonly minSeconds: number; readonly maxSeconds: number };
}