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.

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.mdx
index 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 the
gameplay-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)`) publishes
the **`Lifecycle`** resource — a `LifecycleManager` that tracks page
visibility/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 (see
creation (shader compilation, device injection) — they cannot be toggled on a
live 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 pause
it made itself.
- **Route "is X loaded?" through `app.subsystems`.** It distinguishes
diff --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.mdx
index 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.md
index 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): LifecycleManager
static 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 — function
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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): LifecycleManager
static 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 — function
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 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.ts
index 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 Platform
diff --git a/sdk/src/webAppFactory.ts b/sdk/src/webAppFactory.ts
index 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,
];