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.

feat(export): a project can be packaged for Kuaishou

esenginee6102f68f917
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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/desktop
index bb9bb1a05..2632e8d6f 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit bb9bb1a0561be6c6992879f80d71b3ae63d731f9
+Subproject commit 2632e8d6f44db9b340896a2a1ee5f034412b6ed7
diff --git a/pipeline/src/bundle/engineSubpaths.ts b/pipeline/src/bundle/engineSubpaths.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 chosen
diff --git a/pipeline/src/project/serviceSupport.ts b/pipeline/src/project/serviceSupport.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.md
index cd7cddcc9..272214032 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -5135,6 +5135,7 @@ hostLabel: string
id: MiniGameVendor
instantiateWasm: ((pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>) | undefined
pay: { 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 @experimental
diff --git a/sdk/package.json b/sdk/package.json
index 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.js
index 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 fail
diff --git a/sdk/rollup.config.js b/sdk/rollup.config.js
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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): Platfor
rec.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.ts
index 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.mjs
index 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.js
index 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.mjs
index 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." },
};