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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(export): a project can be packaged for Kuaishou
esenginee6102f68f917
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ad1179064..94568309f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,12 +16,14 @@ published separately; it ships inside the editor.### Added+- **A project can be packaged for Kuaishou (快手).** The third mini-game vendor rides the same pipeline and runtime as WeChat and Douyin: a package of `game.js` + `game.json` (the appid is entered in Kuaishou's developer tool, not written into the package), judged against Kuaishou's 6 MB main package and 30 MB total. The recorder shares through Kuaishou's own `publishVideo`, whole — the host takes no ranges. Ads, share and sign-in are forwarded to `ks` and marked unverified; purchase is not offered, since `ks.requestGamePayment` needs an order signed by your server. It renders only where the host offers WebGL2, which Kuaishou still calls beta.- **The `record-share` example.** Record a run, mark a highlight every few seconds, stop, and share the clip; the share button hides where the host cannot share, which is what a real game wants too.- **`tsc` and an outside editor type-check the official packages too.** Opening a project mirrors the packages the editor ships into `.esengine/packages/`, beside the SDK's types, and a tsconfig maps them with `"estella-plugin-*": ["./.esengine/packages/*"]` — the `wechat-minigame` template and the examples that use one already do.- **A game can record a run and share the clip.** `Recorder` in `estella-plugin-minigame-services` starts, pauses, resumes and stops the host's screen recorder, and `highlight(before, after)` keeps the moment that just happened; `share()` then publishes the highlights, or the whole recording without any. WeChat keeps the video and shares it through its own call (at most 60 s of highlights); Douyin hands over a temp file and cuts the highlights on its side. `available` and `canShare` are separate answers, so a record button and a share button can each hide where the host lacks one. Every call resolves when the host says the thing happened, and a host that never answers is reported after 5 s rather than awaited forever. In the editor's play mode the recording is real — the canvas as WebM — and `canShare` is false there.### Fixed+- A mini-game host that offers only WebGL1 is told the game cannot start there, instead of booting to shader failures and a black screen — the engine renders on WebGL2.- **Sharing, in-game purchase, the friends leaderboard and the recorder can be used at all.** They live in `estella-plugin-minigame-services`, which every doc page said to `npm install` — and it is on no registry, so the command failed and a project that imported it failed to build, in play and in every export. The editor already carried the package; now every bundle of a project's scripts resolves `estella-plugin-*` to that copy (play, web, desktop, native, WeChat, Douyin, playable, the open data context and component extraction), and the editor's script checking and the built-in agent see its types. A copy the project installs into its own `node_modules` still takes precedence, and an unknown `estella-plugin-*` names the ones that do ship.- The agent drawer's History button shows it is open with a grey press again, not the accent colour 0.71 gave it.diff --git a/desktop b/desktopindex bb9bb1a05..2632e8d6f 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit bb9bb1a0561be6c6992879f80d71b3ae63d731f9+Subproject commit 2632e8d6f44db9b340896a2a1ee5f034412b6ed7diff --git a/pipeline/src/bundle/engineSubpaths.ts b/pipeline/src/bundle/engineSubpaths.tsindex 24ce4d913..d5512bdd7 100644--- a/pipeline/src/bundle/engineSubpaths.ts+++ b/pipeline/src/bundle/engineSubpaths.ts@@ -20,6 +20,7 @@ export const ESENGINE_SUBPATHS: Readonly<Record<string, string>> = {'esengine/physics': 'physics/index.js','esengine/physics3d': 'physics3d/index.js','esengine/douyin': 'douyin/index.js',+ 'esengine/kuaishou': 'kuaishou/index.js','esengine/wasm': 'wasm.js',};@@ -28,7 +29,7 @@ export const ESENGINE_SUBPATHS: Readonly<Record<string, string>> = {* loads, and a platform adapter an entry chooses rather than content asking for* it. Named here so the pickable set is derived rather than written twice.*/-const NOT_A_MODULE = new Set(['esengine/wasm', 'esengine/douyin']);+export const NOT_A_MODULE: ReadonlySet<string> = new Set(['esengine/wasm', 'esengine/douyin', 'esengine/kuaishou']);/** The modules a project can force in or refuse, as `features.modules` keys it. */export const ENGINE_MODULES: readonly string[] =diff --git a/pipeline/src/bundle/runtimeHosts.ts b/pipeline/src/bundle/runtimeHosts.tsindex c0323aeac..375eaf658 100644--- a/pipeline/src/bundle/runtimeHosts.ts+++ b/pipeline/src/bundle/runtimeHosts.ts@@ -16,7 +16,7 @@ import { ESENGINE_EXTERNAL } from './esengineResolve';// vendor's runtime profile is a module the generated entry imports, so the// editor has to ship it for the same reason it ships the hosts.export const RUNTIME_HOSTS = [- 'gameHost', 'playableHost', 'playableLoader', 'douyinPlatformProfile',+ 'gameHost', 'playableHost', 'playableLoader', 'douyinPlatformProfile', 'kuaishouPlatformProfile',] as const;export type RuntimeHost = (typeof RUNTIME_HOSTS)[number];diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex aebc50ba7..b7e86d220 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -36,13 +36,14 @@ import {import { engineImportMap, FULL_IMPORT_MAP, LEAN_ENTRY_FILE, FULL_ENTRY_FILE, type EngineImportMap } from '../bundle/importMap';import { engineInstalls, forcedSideModules, moduleChoices, type EngineInstallPlan } from '../bundle/engineInstalls';import { exportMiniGame } from './exportMiniGame';-import { wechatExportProfile, douyinExportProfile } from './miniGameExportProfile';+import { wechatExportProfile, douyinExportProfile, kuaishouExportProfile } from './miniGameExportProfile';import type { MiniGameExportProfile } from './miniGameExportProfile';/** The mini-game vendors the editor ships, by platform id. */const BUILTIN_MINIGAME_PROFILES: Readonly<Record<string, MiniGameExportProfile>> = {wechat: wechatExportProfile,douyin: douyinExportProfile,+ kuaishou: kuaishouExportProfile,};import { exportPlayable } from './exportPlayable';import { genericPlayableProfile, type PlayableAdProfile } from './playableAdProfile';diff --git a/pipeline/src/export/miniGameExportProfile.ts b/pipeline/src/export/miniGameExportProfile.tsindex 2d435ad23..0ef8d6718 100644--- a/pipeline/src/export/miniGameExportProfile.ts+++ b/pipeline/src/export/miniGameExportProfile.ts@@ -22,7 +22,7 @@ import type { SizeBudget } from '../project/sizeBudget';* ship can still be exported by handing {@link exportMiniGame} a profile.* Mirrors the SDK's `MiniGameVendor` (sdk/src/platform/minigame/api.ts).*/-export type MiniGameVendor = 'wechat' | 'douyin' | (string & {});+export type MiniGameVendor = 'wechat' | 'douyin' | 'kuaishou' | (string & {});/** Vendor-neutral facts the pipeline computes, handed to the config emitter. */export interface MiniGameConfigContext {@@ -394,3 +394,47 @@ export const douyinExportProfile: MiniGameExportProfile = {emitEntry: defaultMiniGameEntry,};++// =============================================================================+// Kuaishou profile+// =============================================================================++/**+ * Kuaishou (快手), from open.kuaishou.com/miniGameDocs: `game.js` + `game.json`+ * and nothing else (the appid is entered in the developer tool), and `game.json`+ * spells `subpackages` lower-case. The host has no open data context.+ */+export const kuaishouExportProfile: MiniGameExportProfile = {+ id: 'kuaishou',+ sdkEntryFile: 'index.minigame.js',+ runtimeInit: 'initMiniGameRuntime',+ runtimeProfileHost: 'kuaishouPlatformProfile',+ engineGlueCandidates: MINIGAME_ENGINE_GLUE,+ // WeChat's floor, unconfirmed here: down-levelling costs nothing and a syntax+ // error on a phone costs a release.+ esTarget: 'es2017',+ wasmBuildHint: MINIGAME_ENGINE_BUILD,+ hostGlobal: 'ks',+ sideModuleBuildTargets: {},+ // Assumed to match WeChat and Douyin, not read from a Kuaishou doc; a wrong+ // guess is a staged file the runtime cannot read, on a device.+ nativeSuffixes: new Set(['.js', '.json']),+ // No published upload whitelist, so nothing is restaged — see Douyin's note.+ packerSuffixes: null,+ // The docs show `.wasm.br` only as the Unity converter's output; not claimed+ // for an engine that loads its own binary.+ wasmBrotli: false,+ subpackageDir: 'subpackages',+ // 「ks.loadSubpackage … 会自动 require 分包目录下的 game.js」+ subpackageEntry: 'game.js',++ emitConfigFiles(ctx) {+ const gameCfg: Record<string, unknown> = { deviceOrientation: ctx.orientation };+ if (ctx.subPackages.length > 0) {+ gameCfg.subpackages = ctx.subPackages.map((s) => ({ name: s.name, root: s.root }));+ }+ return [{ file: 'game.json', content: JSON.stringify(gameCfg, null, 2) + '\n' }];+ },++ emitEntry: defaultMiniGameEntry,+};diff --git a/pipeline/src/export/platformCatalog.ts b/pipeline/src/export/platformCatalog.tsindex e88e8d913..6e927e079 100644--- a/pipeline/src/export/platformCatalog.ts+++ b/pipeline/src/export/platformCatalog.ts@@ -120,6 +120,7 @@ function builtinReadiness(case 'wechat':case 'douyin':+ case 'kuaishou':// One probe for the family: they run the same engine build, so a machine// ready for one is ready for the other — and answering otherwise offers a// build command that produces a file the target already has.diff --git a/pipeline/src/project/platforms.ts b/pipeline/src/project/platforms.tsindex e710766b3..37118cb20 100644--- a/pipeline/src/project/platforms.ts+++ b/pipeline/src/project/platforms.ts@@ -21,11 +21,11 @@* Xcode), so a single row could not tell you what to run, whether this machine* can run it, or where the package comes out.*/-export type BuiltinPlatform = 'web' | 'desktop' | 'wechat' | 'douyin' | 'playable' | 'android' | 'ios';+export type BuiltinPlatform = 'web' | 'desktop' | 'wechat' | 'douyin' | 'kuaishou' | 'playable' | 'android' | 'ios';/** Built-ins, in the order they are offered. */export const BUILTIN_PLATFORMS: readonly BuiltinPlatform[] = [- 'web', 'desktop', 'wechat', 'douyin', 'playable', 'android', 'ios',+ 'web', 'desktop', 'wechat', 'douyin', 'kuaishou', 'playable', 'android', 'ios',];/**@@ -63,7 +63,7 @@ export function isNativePlatform(platform: ExportPlatform): platform is NativePl* project's own vendor is one of these without appearing here, so that build* lives in the family's export defaults rather than behind this list.*/-export const MINIGAME_PLATFORMS = ['wechat', 'douyin'] as const;+export const MINIGAME_PLATFORMS = ['wechat', 'douyin', 'kuaishou'] as const;export type MiniGamePlatform = (typeof MINIGAME_PLATFORMS)[number];export function isMiniGamePlatform(platform: ExportPlatform): platform is MiniGamePlatform {@@ -176,7 +176,7 @@ export type ToolchainPiece = 'xcode' | 'macos' | 'emsdk' | 'hostcc';* playable has nowhere to put a module; iOS and Android need a cross-compiler.*/export function compileTargetFor(platform: ExportPlatform): 'wasm' | 'native' | null {- if (platform === 'web' || platform === 'wechat' || platform === 'douyin') return 'wasm';+ if (platform === 'web' || isMiniGamePlatform(platform)) return 'wasm';if (platform === 'desktop') return 'native';if (platform === 'playable' || platform === 'android' || platform === 'ios') return null;// A project platform is a mini-game platform: the playable ones are chosendiff --git a/pipeline/src/project/serviceSupport.ts b/pipeline/src/project/serviceSupport.tsindex 6405e6161..f11c24d54 100644--- a/pipeline/src/project/serviceSupport.ts+++ b/pipeline/src/project/serviceSupport.ts@@ -146,6 +146,35 @@ const DOUYIN_SERVICES: readonly ServiceStatus[] = [{ service: 'achievements', support: 'no', note: ACHIEVEMENTS_LOCAL_ONLY },];+/** From open.kuaishou.com/miniGameDocs; nothing here has run on a device yet. */+const KUAISHOU_SERVICES: readonly ServiceStatus[] = [+ {+ service: 'ads',+ support: 'unknown',+ note: 'The engine forwards to ks.createRewardedVideoAd / ks.createInterstitialAd, which Kuaishou documents'+ + ' (onClose carries isEnded, as WeChat\'s does); unverified on a device.',+ },+ {+ service: 'share',+ support: 'unknown',+ note: 'ks.shareAppMessage is documented as an active share only, keyed by a templateId from the console;'+ + ' there is no passive share menu to answer, so setShareCard reaches nothing here.',+ },+ {+ service: 'signIn',+ support: 'unknown',+ note: 'The engine forwards to ks.login, which yields a code your server exchanges; unverified on a device.',+ },+ {+ service: 'purchase',+ support: 'no',+ note: 'Kuaishou sells through ks.requestGamePayment, whose order is signed by the game\'s server'+ + ' (sign, goods_name, third_party_trade_no) and needs an ISBN to enable — a shape the engine\'s'+ + ' purchase request does not carry, so the profile leaves the slot empty.',+ },+ { service: 'achievements', support: 'no', note: ACHIEVEMENTS_LOCAL_ONLY },+];+const DESKTOP_SERVICES: readonly ServiceStatus[] = noHostServices().map((s) => (s.service === 'achievements'? {@@ -167,6 +196,7 @@ const DESKTOP_SERVICES: readonly ServiceStatus[] = noHostServices().map((s) => (export function builtinServiceSupport(platform: ExportPlatform): readonly ServiceStatus[] {if (platform === 'wechat') return WECHAT_SERVICES;if (platform === 'douyin') return DOUYIN_SERVICES;+ if (platform === 'kuaishou') return KUAISHOU_SERVICES;if (platform === 'desktop') return DESKTOP_SERVICES;if (platform === 'web' || platform === 'playable' || platform === 'android' || platform === 'ios') {return noHostServices();diff --git a/pipeline/src/project/sizeBudget.ts b/pipeline/src/project/sizeBudget.tsindex 91715f9ed..b32ab81ef 100644--- a/pipeline/src/project/sizeBudget.ts+++ b/pipeline/src/project/sizeBudget.ts@@ -75,6 +75,7 @@ const MB = 1024 * 1024;export function builtinSizeBudgets(platform: ExportPlatform): readonly SizeBudget[] {if (platform === 'wechat') return WECHAT_BUDGETS;if (platform === 'douyin') return DOUYIN_BUDGETS;+ if (platform === 'kuaishou') return KUAISHOU_BUDGETS;return NO_BUDGETS;}@@ -95,6 +96,15 @@ const DOUYIN_BUDGETS: readonly SizeBudget[] = [},];+/**+ * 「代码包总大小不能超过 30M,单个分包不限制大小,主包不超过 6M。」+ * https://open.kuaishou.com/miniGameDocs/gameDev/framework/code-package.html+ */+const KUAISHOU_BUDGETS: readonly SizeBudget[] = [+ { scope: 'initial', maxBytes: 6 * MB, note: "Kuaishou caps a mini-game's main package at 6MB (主包不超过 6M)" },+ { scope: 'total', maxBytes: 30 * MB, note: 'Kuaishou caps a mini-game at 30MB across the main package and all subpackages' },+];+const NO_BUDGETS: readonly SizeBudget[] = [];/**diff --git a/pipeline/src/runtime/kuaishouPlatformProfile.ts b/pipeline/src/runtime/kuaishouPlatformProfile.tsnew file mode 100644index 000000000..106357be2--- /dev/null+++ b/pipeline/src/runtime/kuaishouPlatformProfile.ts@@ -0,0 +1,9 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file kuaishouPlatformProfile.ts — the module a Kuaishou package installs its+ * platform from, as the export profile's `runtimeProfileModule`.+ */+import { kuaishouProfile } from 'esengine/kuaishou';++export default kuaishouProfile;diff --git a/pipeline/tests/engine-installs.test.ts b/pipeline/tests/engine-installs.test.tsindex db78aa522..041121d0e 100644--- a/pipeline/tests/engine-installs.test.ts+++ b/pipeline/tests/engine-installs.test.ts@@ -10,7 +10,7 @@*/import { describe, it, expect } from 'vitest';import { engineInstalls, forcedSideModules, moduleChoices, moduleForAsset } from '../src/bundle/engineInstalls';-import { ENGINE_MODULES, ESENGINE_SUBPATHS } from '../src/bundle/engineSubpaths';+import { ENGINE_MODULES, ESENGINE_SUBPATHS, NOT_A_MODULE } from '../src/bundle/engineSubpaths';import { SUBSYSTEM_COMPONENTS, SUBSYSTEM_INSTALL, type Subsystem } from '../src/project/targetSupport';describe('the engine modules a package installs', () => {@@ -67,7 +67,7 @@ describe('the engine modules a package installs', () => {describe('every subpath the SDK publishes', () => {/** Not subsystems: the engine module every target loads, and a platform* adapter an entry picks rather than content asking for it. */- const NOT_A_SUBSYSTEM = new Set(['esengine/wasm', 'esengine/douyin']);+ const NOT_A_SUBSYSTEM = NOT_A_MODULE;it('is named by something a project can be evidence of', () => {const installable = new Set<string>();diff --git a/pipeline/tests/export-kuaishou.test.ts b/pipeline/tests/export-kuaishou.test.tsnew file mode 100644index 000000000..2586fb1f6--- /dev/null+++ b/pipeline/tests/export-kuaishou.test.ts@@ -0,0 +1,91 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Kuaishou MiniGame export — a third vendor through the same pipeline.+ * What is Kuaishou's own: a package of `game.js` + `game.json` with no+ * project config and no appid in it, `subpackages` spelled lower-case,+ * the `ks` host named by the entry, and caps of 6MB / 30MB.+ */+import { describe, it, expect, beforeAll, afterAll } from 'vitest';+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { exportGame } from '../src/export/exportGame';+import { kuaishouExportProfile } from '../src/export/miniGameExportProfile';+import { builtinSizeBudgets } from '../src/project/sizeBudget';+import { builtinServiceSupport } from '../src/project/serviceSupport';+import { runtimeConfigOf } from '../src/project/runtimeConfig';+import { OFFICIAL_PACKAGES } from './officialPackagesDir';++let root: string;+let out: string;+const SCN = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';++beforeAll(() => {+ root = mkdtempSync(path.join(tmpdir(), 'estella-export-kuaishou-'));+ mkdirSync(path.join(root, 'scenes'), { recursive: true });+ writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify({ version: '1.0', name: 'Main', entities: [] }));+ writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'),+ JSON.stringify({ uuid: SCN, version: '2.0', type: 'scene', importer: {} }));+ mkdirSync(path.join(root, '_sdk', 'kuaishou'), { recursive: true });+ writeFileSync(path.join(root, '_sdk', 'index.minigame.js'),+ 'export function initMiniGameRuntime(){return Promise.resolve();}\n'+ + 'export function installMiniGamePlatform(){}\n');+ writeFileSync(path.join(root, '_sdk', 'kuaishou', 'index.js'),+ 'export const kuaishouProfile = { id: "kuaishou", hostLabel: "\\u5feb\\u624b" };\n');+ mkdirSync(path.join(root, '_wasm'), { recursive: true });+ writeFileSync(path.join(root, '_wasm', 'esengine.wxgame.js'), 'module.exports = () => Promise.resolve({});');+ writeFileSync(path.join(root, '_wasm', 'esengine.wxgame.wasm'), 'wasmbytes');+ out = path.join(root, 'dist-kuaishou');+}, 60_000);++afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));++describe('exportGame (kuaishou)', () => {+ it('writes game.json and nothing a Kuaishou package does not carry', async () => {+ const res = await exportGame({+ root,+ entryScene: 'scenes/main.esscene',+ hostsDir: path.resolve(__dirname, '../src/runtime'), packagesDir: OFFICIAL_PACKAGES,+ sdkDistDir: path.join(root, '_sdk'),+ wasmDir: path.join(root, '_wasm'),+ outDir: out,+ title: 'My Game',+ platform: 'kuaishou',+ orientation: 'portrait',+ runtime: runtimeConfigOf({ designResolution: { width: 720, height: 1280 } }),+ miniGameAppid: 'should-not-appear',+ });+ expect(res.ok, res.errors.join('\n')).toBe(true);+ expect(res.platform).toBe('kuaishou');++ expect(JSON.parse(readFileSync(path.join(out, 'game.json'), 'utf8'))).toEqual({ deviceOrientation: 'portrait' });+ // The appid is entered in the developer tool; the package has no file for it.+ expect(existsSync(path.join(out, 'project.config.json'))).toBe(false);+ expect(existsSync(path.join(out, 'game.js'))).toBe(true);+ }, 180_000);++ it('installs the ks profile before booting', () => {+ const bundle = readFileSync(path.join(out, 'game-bundle.js'), 'utf8');+ expect(bundle).toContain('installMiniGamePlatform');+ expect(bundle).toContain('kuaishou');+ expect(readFileSync(path.join(out, 'game.js'), 'utf8')).toContain("require('./wasm/esengine.wxgame.js')");+ });++ it('declares subpackages under the key Kuaishou reads', () => {+ const [cfg] = kuaishouExportProfile.emitConfigFiles({+ title: 't', appid: '', orientation: 'landscape',+ subPackages: [{ name: 'level2', root: 'subpackages/level2/' }],+ includeSuffixes: [], hasOpenData: false, openDataRoot: 'open-data',+ });+ const json = JSON.parse(cfg.content);+ expect(json.subpackages).toEqual([{ name: 'level2', root: 'subpackages/level2/' }]);+ expect(json).not.toHaveProperty('subPackages');+ });++ it('is judged against 6MB and 30MB, and claims no purchase', () => {+ expect(builtinSizeBudgets('kuaishou').map((b) => [b.scope, b.maxBytes / (1024 * 1024)]))+ .toEqual([['initial', 6], ['total', 30]]);+ expect(builtinServiceSupport('kuaishou').find((s) => s.service === 'purchase')?.support).toBe('no');+ });+});diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex cd7cddcc9..272214032 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -5135,6 +5135,7 @@ hostLabel: stringid: MiniGameVendorinstantiateWasm: ((pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>) | undefinedpay: { can(): boolean; request(request: PlatformPaymentRequest): Promise<void>; } | undefined+recordingLimits: { readonly minSeconds: number; readonly maxSeconds: number; } | undefined```## MiniGameRequestOptions — interface @experimental@@ -5226,7 +5227,7 @@ changedTouches: MiniGameTouch[]## MiniGameVendor — type @experimental```-'wechat' | 'douyin' | (string & {})+'wechat' | 'douyin' | 'kuaishou' | (string & {})```## MissingAssetCallback — type @experimentaldiff --git a/sdk/package.json b/sdk/package.jsonindex 4c0c134d5..a3229699b 100644--- a/sdk/package.json+++ b/sdk/package.json@@ -23,6 +23,7 @@"./dist/physics/index.js","./dist/physics3d/index.js","./dist/douyin/index.js",+ "./dist/kuaishou/index.js","./dist/index.wechat.cjs.js"],"main": "./dist/index.js",@@ -90,6 +91,10 @@"./douyin": {"import": "./dist/douyin/index.js","types": "./dist/douyin/index.d.ts"+ },+ "./kuaishou": {+ "import": "./dist/kuaishou/index.js",+ "types": "./dist/kuaishou/index.d.ts"}},"files": [diff --git a/sdk/rolldown.config.js b/sdk/rolldown.config.jsindex d3ca403a3..eaf8379e9 100644--- a/sdk/rolldown.config.js+++ b/sdk/rolldown.config.js@@ -102,6 +102,7 @@ export default defineConfig(['gameplay/index': 'src/gameplay/index.ts','dragonbones/index': 'src/dragonbones/index.ts','douyin/index': 'src/platform/douyin/index.ts',+ 'kuaishou/index': 'src/platform/kuaishou/index.ts','wasm': 'src/wasm.ts',},// Only the node entry reaches these; a browser entry that did would faildiff --git a/sdk/rollup.config.js b/sdk/rollup.config.jsindex 92695b505..ece2637b8 100644--- a/sdk/rollup.config.js+++ b/sdk/rollup.config.js@@ -17,6 +17,7 @@ export default ['physics/index': 'src/physics/index.ts','physics3d/index': 'src/physics3d/index.ts','douyin/index': 'src/platform/douyin/index.ts',+ 'kuaishou/index': 'src/platform/kuaishou/index.ts','spine/index': 'src/spine/index.ts','tilemap/index': 'src/tilemap/index.ts','logic/index': 'src/logic/index.ts',diff --git a/sdk/src/platform/kuaishou/index.ts b/sdk/src/platform/kuaishou/index.tsnew file mode 100644index 000000000..45b689ffa--- /dev/null+++ b/sdk/src/platform/kuaishou/index.ts@@ -0,0 +1,24 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file index.ts+ * @brief Kuaishou MiniGame platform (a profile of the mini-game family).+ *+ * Adapter, polyfills and install are the family's; Kuaishou adds nothing, which is+ * the point of the family existing.+ */+import { MiniGamePlatformAdapter, installMiniGamePlatform } from '../minigame';+import { kuaishouProfile } from './profile';++export const kuaishouAdapter = new MiniGamePlatformAdapter(kuaishouProfile);++let initialized = false;++/** Initialize the Kuaishou platform. */+export function initKuaishouPlatform(): void {+ if (initialized) return;+ initialized = true;+ installMiniGamePlatform(kuaishouProfile, kuaishouAdapter);+}++export { kuaishouProfile };diff --git a/sdk/src/platform/kuaishou/profile.ts b/sdk/src/platform/kuaishou/profile.tsnew file mode 100644index 000000000..c7f5ac4b3--- /dev/null+++ b/sdk/src/platform/kuaishou/profile.ts@@ -0,0 +1,35 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file profile.ts+ * @brief Kuaishou as a profile of the mini-game platform family.+ *+ * `ks` answers the family's shape — fs, canvas, subpackages, ads, login and a+ * WeChat-shaped recorder (open.kuaishou.com/miniGameDocs). Two facts differ:+ * a recording is 3–300 s (「录制时间太短(>=3s)」「录制时间太长(<=300s)」), and+ * the recorder publishes through its own `publishVideo`, which the family+ * recorder reads off the host.+ *+ * UNVERIFIED on a device: that `WebAssembly` is the standard global here (the+ * docs name no host loader), and that WebGL2 is available — the docs call it+ * beta, and the engine renders on nothing less.+ *+ * NOT CLAIMED: `pay`. Kuaishou's `ks.requestGamePayment` takes an order signed+ * by the game's server (`sign`, `goods_name`, `third_party_trade_no`), a shape+ * PlatformPaymentRequest does not carry, so purchase reports itself unavailable.+ */+import type { MiniGameGlobal, MiniGameProfile } from '../minigame';++/** Kuaishou's host global, read lazily — importing this outside Kuaishou must not touch it. */+declare const ks: unknown;++export const kuaishouProfile: MiniGameProfile = {+ id: 'kuaishou',+ hostLabel: '快手',++ get global(): MiniGameGlobal {+ return ks as MiniGameGlobal;+ },++ recordingLimits: { minSeconds: 3, maxSeconds: 300 },+};diff --git a/sdk/src/platform/minigame/adapter.ts b/sdk/src/platform/minigame/adapter.tsindex ed118737f..6b50b819e 100644--- a/sdk/src/platform/minigame/adapter.ts+++ b/sdk/src/platform/minigame/adapter.ts@@ -202,7 +202,9 @@ export class MiniGamePlatformAdapter implements PlatformAdapter {/** The host hands out one recorder, so this does too. */screenRecorder(): PlatformScreenRecorder | null {- if (this.recorder_ === undefined) this.recorder_ = createMiniGameRecorder(this.g_);+ if (this.recorder_ === undefined) {+ this.recorder_ = createMiniGameRecorder(this.g_, this.profile_.recordingLimits);+ }return this.recorder_;}diff --git a/sdk/src/platform/minigame/api.ts b/sdk/src/platform/minigame/api.tsindex 5cefadd90..110a49ef6 100644--- a/sdk/src/platform/minigame/api.ts+++ b/sdk/src/platform/minigame/api.ts@@ -165,6 +165,8 @@ export interface MiniGameWxRecorder {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;}@@ -383,7 +385,7 @@ export interface MiniGameGlobal {* 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' | (string & {});+export type MiniGameVendor = 'wechat' | 'douyin' | 'kuaishou' | (string & {});/*** A vendor described as DATA — three facts and, at most, one method.@@ -428,4 +430,8 @@ export interface MiniGameProfile {can(): boolean;request(request: PlatformPaymentRequest): Promise<void>;};++ /** 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 };}diff --git a/sdk/src/platform/minigame/recorder.ts b/sdk/src/platform/minigame/recorder.tsindex 8dc7bfb4d..e1b7a6cb9 100644--- a/sdk/src/platform/minigame/recorder.ts+++ b/sdk/src/platform/minigame/recorder.ts@@ -135,7 +135,11 @@ class Session {}}-export function createWxRecorder(g: MiniGameGlobal, now?: () => number): PlatformScreenRecorder | null {+export function createWxRecorder(+ g: MiniGameGlobal,+ now?: () => number,+ limits: PlatformScreenRecorder['limits'] = { minSeconds: 5, maxSeconds: 7200 },+): PlatformScreenRecorder | null {const rec: MiniGameWxRecorder | undefined = g.getGameRecorder?.call(g);if (!rec) return null;if (rec.isFrameSupported && !rec.isFrameSupported.call(rec)) return null;@@ -145,11 +149,12 @@ export function createWxRecorder(g: MiniGameGlobal, now?: () => number): Platforrec.on(event, (res) => gate.fire(event, res));}rec.on('error', (res) => gate.fail(toError(res)));- const limits = { minSeconds: 5, maxSeconds: 7200 };return {limits,- get canShare() { return typeof g.operateGameRecorderVideo === 'function'; },+ get canShare() {+ return typeof g.operateGameRecorderVideo === 'function' || typeof rec.publishVideo === 'function';+ },async start(maxSeconds, onFailure) {session.begin(onFailure);await gate.wait('start', () => rec.start({ duration: clampSeconds(maxSeconds, limits) }));@@ -178,7 +183,7 @@ export function createWxRecorder(g: MiniGameGlobal, now?: () => number): Platfor},share(recording, options) {const operate = g.operateGameRecorderVideo;- if (!operate) return Promise.reject(new Error('this host cannot share a recording'));+ if (!operate) return publish(rec, options);const timeRange = wxTimeRange(recording.highlights);if (timeRange && spanOf(timeRange) < WX_SHARE_MIN_MS) {return Promise.reject(new Error(@@ -196,6 +201,22 @@ export function createWxRecorder(g: MiniGameGlobal, now?: () => number): Platfor};}+/**+ * Kuaishou's share: the host publishes the last recording whole. It takes no+ * ranges, so highlights cannot narrow what is shared here — the recording+ * keeps them, and the host ignores them.+ */+function publish(rec: MiniGameWxRecorder, options: PlatformRecordingShareOptions): Promise<void> {+ const publishVideo = rec.publishVideo;+ if (!publishVideo) return Promise.reject(new Error('this host cannot share a recording'));+ return new Promise<void>((resolve, reject) => {+ publishVideo.call(rec, {+ ...(options.query !== undefined ? { query: options.query } : {}),+ callback: (error) => (error ? reject(toError(error)) : resolve()),+ });+ });+}+function spanOf(ranges: readonly (readonly number[])[]): number {return ranges.reduce((sum, [a, b]) => sum + (b - a), 0);}@@ -312,8 +333,11 @@ export function createTtRecorder(g: MiniGameGlobal, now?: () => number): Platfor/** Whichever recorder this host has. Chosen by what the global offers, not by* vendor id: a vendor copying WeChat's shape gets WeChat's recorder. */-export function createMiniGameRecorder(g: MiniGameGlobal): PlatformScreenRecorder | null {+export function createMiniGameRecorder(+ g: MiniGameGlobal,+ limits?: PlatformScreenRecorder['limits'],+): PlatformScreenRecorder | null {if (g.getGameRecorderManager) return createTtRecorder(g);- if (g.getGameRecorder) return createWxRecorder(g);+ if (g.getGameRecorder) return createWxRecorder(g, undefined, limits);return null;}diff --git a/sdk/tests/minigame-recorder.test.ts b/sdk/tests/minigame-recorder.test.tsindex 61f91ad7a..c453707ae 100644--- a/sdk/tests/minigame-recorder.test.ts+++ b/sdk/tests/minigame-recorder.test.ts@@ -11,7 +11,8 @@*/import { describe, it, expect, vi, afterEach } from 'vitest';import { createMiniGameRecorder, createTtRecorder, createWxRecorder, wxTimeRange } from '../src/platform/minigame/recorder';-import type { MiniGameGlobal } from '../src/platform/minigame/api';+import type { MiniGameGlobal, MiniGameProfile } from '../src/platform/minigame/api';+import { MiniGamePlatformAdapter } from '../src/platform/minigame/adapter';type Listener = (res?: unknown) => void;@@ -152,6 +153,43 @@ describe('WeChat', () => {});});+describe('Kuaishou, which is WeChat-shaped and publishes its own way', () => {+ const ksHost = (fail?: unknown) => {+ const host = fakeWx({ share: false });+ const published: unknown[] = [];+ const rec = (host.g as unknown as { getGameRecorder(): Record<string, unknown> }).getGameRecorder();+ rec.publishVideo = (o: { query?: string; callback?: (e?: unknown) => void }) => {+ published.push(o.query);+ o.callback?.(fail);+ };+ return { ...host, published };+ };++ it('shares through publishVideo, carrying the query', async () => {+ const host = ksHost();+ const r = createWxRecorder(host.g)!;+ expect(r.canShare).toBe(true);+ await r.share({ durationMs: 8000, highlights: [[0, 3000]] }, { query: 'from=clip', title: 'ignored here' });+ expect(host.published).toEqual(['from=clip']);+ });++ it('carries the host refusal', async () => {+ const r = createWxRecorder(ksHost({ errMsg: 'publishVideo:fail too short' }).g)!;+ await expect(r.share({ durationMs: 1000, highlights: [] }, {})).rejects.toThrow('too short');+ });++ it('asks for a length inside the limits the profile declares', async () => {+ const host = ksHost();+ const adapter = new MiniGamePlatformAdapter({+ id: 'kuaishou', hostLabel: '快手', global: host.g, recordingLimits: { minSeconds: 3, maxSeconds: 300 },+ } as MiniGameProfile);+ const r = adapter.screenRecorder()!;+ expect(r.limits).toEqual({ minSeconds: 3, maxSeconds: 300 });+ await r.start(1, () => {});+ expect(host.calls.start).toEqual([{ duration: 3 }]);+ });+});+describe('the newest highlights that fit WeChat\'s 60s', () => {it('keeps the latest and trims the oldest one that straddles the ceiling', () => {expect(wxTimeRange([[0, 30_000], [40_000, 70_000], [80_000, 90_000]]))diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjsindex 1dfb83263..af22b7593 100644--- a/tools/goldenProjects.mjs+++ b/tools/goldenProjects.mjs@@ -26,7 +26,7 @@ const EXAMPLES = path.join(ROOT, 'examples');export const TIERS = ['pr', 'nightly', 'release'];/** Export targets a golden project can be asked to package + launch for. */-export const TARGETS = ['web', 'playable', 'desktop', 'wechat', 'douyin', 'android', 'ios'];+export const TARGETS = ['web', 'playable', 'desktop', 'wechat', 'douyin', 'kuaishou', 'android', 'ios'];/*** How far a packaged frame may sit from the editor's frame of the same game.diff --git a/tools/nativeScriptModules.js b/tools/nativeScriptModules.jsindex 141c39a14..2f48316ef 100644--- a/tools/nativeScriptModules.js+++ b/tools/nativeScriptModules.js@@ -94,6 +94,10 @@ export const MODULES = {disposition: 'forbidden-native-script',why: "Douyin's platform profile — it names a host global (`tt`) that a native build does not have",},+ 'esengine/kuaishou': {+ disposition: 'forbidden-native-script',+ why: "Kuaishou's platform profile — it names a host global (`ks`) that a native build does not have",+ },};/** The `exports` subpath ("." / "./physics3d") a specifier corresponds to. */diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 731f87d15..91aa004c4 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -978,6 +978,12 @@ export const NOTED = {{ note: '`tsc` and an outside editor type-check the official packages too.' },'feat(tooling): the examples type-check the official packages the way a project does':{ note: '`tsc` and an outside editor type-check the official packages too.' },+ 'feat(export): a project can be packaged for Kuaishou':+ { note: 'A project can be packaged for Kuaishou (快手).' },+ 'feat(editor): Kuaishou is a build target':+ { note: 'A project can be packaged for Kuaishou (快手).' },+ 'fix(runtime): a mini-game host with only WebGL1 is told the game cannot start':+ { note: 'A mini-game host that offers only WebGL1 is told the game cannot start there' },'fix(agent): the history toggle presses grey again, not the accent':{ note: "The agent drawer's History button shows it is open with a grey press again, not the accent colour 0.71 gave it." },};