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
refactor(sdk): one plugin-construction shape — lowercase exports are values
esengine2e6132e0bdfc
diff --git a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdxindex bc6cc26aa..455db72a7 100644--- a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx+++ b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx@@ -64,7 +64,7 @@ content stack, in this order:`RenderPipeline`.2. **UI**: `uiPlugins` — the composed UI pipeline (layout, text, text input,masks, render order, interaction, drag, focus, safe area).-3. **Base content**: `timerPlugin`, `lifecyclePlugin()`, `animationPlugin`,+3. **Base content**: `timerPlugin`, `lifecyclePlugin`, `animationPlugin`,`audioPlugin`, `videoPlugin`, `particlePlugin`, `trailPlugin`,`mesh2dPlugin`, `tilemapPlugin`, `postProcessPlugin`, `timelinePlugin`,`perceptionPlugin`, `fsmPlugin`, `btPlugin`, `navPlugin`,@@ -104,7 +104,7 @@ stop();| `sideModules` | `SideModuleHost` | Optional-native-module acquirer (physics on the server). |Included: `assetPlugin`, `prefabsPlugin`, `sceneManagerPlugin`, `timerPlugin`,-`lifecyclePlugin()`, `audioPlugin` (silent on hosts without a device), and the+`lifecyclePlugin`, `audioPlugin` (silent on hosts without a device), and thegameplay-AI/replication set (`perceptionPlugin`, `fsmPlugin`, `btPlugin`,`navPlugin`, `replicationPlugin`).@@ -231,7 +231,7 @@ systems are flushed before the first frame.## Lifecycle events-`lifecyclePlugin(options?)` (installed by default in both factories) publishes+`lifecyclePlugin` (installed by default in both factories; configure with `new LifecyclePlugin(options)`) publishesthe **`Lifecycle`** resource — a `LifecycleManager` that tracks pagevisibility/focus and can auto-pause the game:@@ -248,7 +248,7 @@ const off = lifecycle.on((event) => {|---|---|---|| `visible` | `boolean` | Current page/app visibility. || `focused` | `boolean` | Window focus (tracked; changing it emits no event). |-| `autoPause` | `boolean` | Whether hiding the page pauses the app. Default `true`; writable at runtime, seeded from `lifecyclePlugin({ autoPause })`. |+| `autoPause` | `boolean` | Whether hiding the page pauses the app. Default `true`; writable at runtime, seeded from `new LifecyclePlugin({ autoPause })`. || `on(listener)` / `off(listener)` | — | Subscribe to events; `on` returns an unsubscribe function. |`LifecycleEvent` is `'show' | 'hide' | 'pause' | 'resume'`, and a@@ -376,7 +376,7 @@ after a reload — write them as idempotent setup (seecreation (shader compilation, device injection) — they cannot be toggled on alive app.- **Don't fight the lifecycle auto-pause.** Turn it off with- `lifecyclePlugin({ autoPause: false })` (or `lifecycle.autoPause = false`)+ `new LifecyclePlugin({ autoPause: false })` (or `lifecycle.autoPause = false`)rather than un-pausing in a listener; the manager only ever resumes a pauseit made itself.- **Route "is X loaded?" through `app.subsystems`.** It distinguishesdiff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdxindex 224aeeb05..f05703eda 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx@@ -59,7 +59,7 @@ await app.run();`RenderPipeline`。2. **UI**:`uiPlugins`——组合好的 UI 管线(布局、文本、文本输入、遮罩、渲染排序、交互、拖拽、焦点、安全区)。-3. **基础内容**:`timerPlugin`、`lifecyclePlugin()`、`animationPlugin`、+3. **基础内容**:`timerPlugin`、`lifecyclePlugin`、`animationPlugin`、`audioPlugin`、`videoPlugin`、`particlePlugin`、`trailPlugin`、`mesh2dPlugin`、`tilemapPlugin`、`postProcessPlugin`、`timelinePlugin`、`perceptionPlugin`、`fsmPlugin`、`btPlugin`、`navPlugin`、@@ -96,7 +96,7 @@ stop();| `sideModules` | `SideModuleHost` | 可选原生模块获取器(服务器上的物理)。 |包含:`assetPlugin`、`prefabsPlugin`、`sceneManagerPlugin`、`timerPlugin`、-`lifecyclePlugin()`、`audioPlugin`(无音频设备的宿主上静音),以及游戏 AI /+`lifecyclePlugin`、`audioPlugin`(无音频设备的宿主上静音),以及游戏 AI /复制集合(`perceptionPlugin`、`fsmPlugin`、`btPlugin`、`navPlugin`、`replicationPlugin`)。@@ -217,7 +217,7 @@ export const scorePlugin: Plugin = {## 生命周期事件-`lifecyclePlugin(options?)`(两个工厂都默认安装)发布 **`Lifecycle`** 资源——+`lifecyclePlugin`(两个工厂都默认安装;用 `new LifecyclePlugin(options)` 配置)发布 **`Lifecycle`** 资源——一个跟踪页面可见性/焦点、并能自动暂停游戏的 `LifecycleManager`:```typescript@@ -233,7 +233,7 @@ const off = lifecycle.on((event) => {|---|---|---|| `visible` | `boolean` | 当前页面/应用可见性。 || `focused` | `boolean` | 窗口焦点(会跟踪;变化不发事件)。 |-| `autoPause` | `boolean` | 页面隐藏时是否暂停应用。默认 `true`;运行时可写,初值来自 `lifecyclePlugin({ autoPause })`。 |+| `autoPause` | `boolean` | 页面隐藏时是否暂停应用。默认 `true`;运行时可写,初值来自 `new LifecyclePlugin({ autoPause })`。 || `on(listener)` / `off(listener)` | — | 订阅事件;`on` 返回退订函数。 |`LifecycleEvent` 是 `'show' | 'hide' | 'pause' | 'resume'`,`LifecycleListener`@@ -336,7 +336,7 @@ import 你的 bundle,返回一个 `ProbedRegistrations`:的存活性归因、可用的依赖报错。- **前置声明 `colorSpace` 和 `backend`。**两者都在创建时固化(着色器编译、设备注入)——不能在存活应用上切换。-- **别和生命周期自动暂停较劲。**用 `lifecyclePlugin({ autoPause: false })`(或+- **别和生命周期自动暂停较劲。**用 `new LifecyclePlugin({ autoPause: false })`(或`lifecycle.autoPause = false`)关掉它,而不是在监听器里解除暂停;manager 只会解除它自己造成的暂停。- **"X 加载了吗?"走 `app.subsystems`。**它区分*已加载*与*在运行*(`phase` 与diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex fcb2489b7..64bba445b 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1244 stable · 17 beta · 0 deprecated+Symbols: 1245 stable · 17 beta · 0 deprecated## ABI_LAYOUT_HASH — const```@@ -3241,6 +3241,15 @@ static new (autoPause?: boolean): LifecycleManagerstatic prototype: LifecycleManager```+## LifecyclePlugin — class+```+build: (app: App) => void+cleanup: () => void+name: string+static new (options_?: LifecyclePluginOptions | undefined): LifecyclePlugin+static prototype: LifecyclePlugin+```+## LifecyclePluginOptions — interface```autoPause: boolean | undefined@@ -8631,7 +8640,7 @@ InputRouter## lifecyclePlugin — const```-(options?: LifecyclePluginOptions) => Plugin+LifecyclePlugin```## loadComponent — functiondiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 38e482cea..1a19ed8e5 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1243 stable · 19 beta · 0 deprecated+Symbols: 1244 stable · 19 beta · 0 deprecated## ANCHOR_AXES — const```@@ -3236,6 +3236,15 @@ static new (autoPause?: boolean): LifecycleManagerstatic prototype: LifecycleManager```+## LifecyclePlugin — class+```+build: (app: App) => void+cleanup: () => void+name: string+static new (options_?: LifecyclePluginOptions | undefined): LifecyclePlugin+static prototype: LifecyclePlugin+```+## LifecyclePluginOptions — interface```autoPause: boolean | undefined@@ -8626,7 +8635,7 @@ InputRouter## lifecyclePlugin — const```-(options?: LifecyclePluginOptions) => Plugin+LifecyclePlugin```## loadComponent — functiondiff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex c288fef12..76bbae668 100644--- a/sdk/src/core-sys.ts+++ b/sdk/src/core-sys.ts@@ -191,6 +191,7 @@ export {LifecycleManager,Lifecycle,lifecyclePlugin,+ LifecyclePlugin,type LifecycleEvent,type LifecycleListener,type LifecyclePluginOptions,diff --git a/sdk/src/lifecycle.ts b/sdk/src/lifecycle.tsindex fa69476c7..d6afdf309 100644--- a/sdk/src/lifecycle.ts+++ b/sdk/src/lifecycle.ts@@ -6,7 +6,7 @@*/import { defineResource } from './resource';-import type { Plugin } from './app';+import type { App, Plugin } from './app';import { getPlatformType } from './platform';import { log } from './logger';@@ -97,32 +97,36 @@ export interface LifecyclePluginOptions {autoPause?: boolean;}-export const lifecyclePlugin = (options?: LifecyclePluginOptions): Plugin => {- let cleanupFn_: (() => void) | null = null;+export class LifecyclePlugin implements Plugin {+ name = 'Lifecycle';+ private cleanupFn_: (() => void) | null = null;- return {- name: 'Lifecycle',- build(app) {- const autoPause = options?.autoPause ?? true;- const manager = new LifecycleManager(autoPause);- app.insertResource(Lifecycle, manager);+ constructor(private readonly options_?: LifecyclePluginOptions) {}- const platformType = getPlatformType();+ build(app: App): void {+ const autoPause = this.options_?.autoPause ?? true;+ const manager = new LifecycleManager(autoPause);+ app.insertResource(Lifecycle, manager);- if (platformType === 'wechat') {- setupWeChatLifecycle_(manager, app);- } else if (typeof document !== 'undefined' && typeof window !== 'undefined') {- cleanupFn_ = setupWebLifecycle_(manager, app);- }- // Headless hosts (node server, workers) have no visibility/focus- // signal — the Lifecycle resource still exists, always visible.- },- cleanup() {- cleanupFn_?.();- cleanupFn_ = null;- },- };-};+ const platformType = getPlatformType();++ if (platformType === 'wechat') {+ setupWeChatLifecycle_(manager, app);+ } else if (typeof document !== 'undefined' && typeof window !== 'undefined') {+ this.cleanupFn_ = setupWebLifecycle_(manager, app);+ }+ // Headless hosts (node server, workers) have no visibility/focus+ // signal — the Lifecycle resource still exists, always visible.+ }++ cleanup(): void {+ this.cleanupFn_?.();+ this.cleanupFn_ = null;+ }+}++/** Default-config instance; `new LifecyclePlugin({ autoPause })` to configure. */+export const lifecyclePlugin = new LifecyclePlugin();// =============================================================================// Web Platformdiff --git a/sdk/src/webAppFactory.ts b/sdk/src/webAppFactory.tsindex ed49ca645..5ee6db609 100644--- a/sdk/src/webAppFactory.ts+++ b/sdk/src/webAppFactory.ts@@ -35,7 +35,7 @@ export interface CreateWebAppOptions extends WebAppOptions {wasmBaseUrl?: string;}-const basePlugins = [timerPlugin, lifecyclePlugin(), animationPlugin, audioPlugin, videoPlugin, particlePlugin, trailPlugin, mesh2dPlugin, tilemapPlugin, postProcessPlugin, timelinePlugin, perceptionPlugin, fsmPlugin, btPlugin, navPlugin, replicationPlugin];+const basePlugins = [timerPlugin, lifecyclePlugin, animationPlugin, audioPlugin, videoPlugin, particlePlugin, trailPlugin, mesh2dPlugin, tilemapPlugin, postProcessPlugin, timelinePlugin, perceptionPlugin, fsmPlugin, btPlugin, navPlugin, replicationPlugin];export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptions): App {const sideModules: SideModuleHost | undefined = options?.sideModules@@ -57,7 +57,7 @@ export interface HeadlessAppOptions {// (particles, tilemap render, post-process, timeline, UI, spine) stay out —// they exist to be seen.const headlessBasePlugins = (): Plugin[] => [- timerPlugin, lifecyclePlugin(), audioPlugin,+ timerPlugin, lifecyclePlugin, audioPlugin,perceptionPlugin, fsmPlugin, btPlugin, navPlugin, replicationPlugin,];