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
perf(app): a single system can sit out the frames it has nothing to do in
yhhdde7b34ed01e
diff --git a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdxindex 8bf29e583..d34fb83ac 100644--- a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx+++ b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx@@ -162,7 +162,7 @@ subsystem publishes its API. See| `dependencies` | `PluginDependency[]?` | Prerequisites, each either a plugin **name** (`string`) or a **resource definition**. `addPlugin` throws if one is missing; `addPlugins` also uses the name edges to sort the batch. || `before` / `after` | `string[]?` | Soft ordering hints against other plugin names, honored when installing a batch via `addPlugins`. || `build(app)` | required | Register systems, resources, and events. Runs immediately on `addPlugin`. |-| `activeWhen` | `ComponentDef[]?` | The components the plugin's work is about. While no entity has any of them, the systems registered in its `build()` are skipped, so a game that never places water pays nothing for the water plugin each frame. They still run for one frame after the last one goes, so the plugin can release what it held. Absent: always run. The engine's water, terrain, planet, foliage, tilemap, navigation, behaviour tree, state machine, perception and velocity plugins declare it. |+| `activeWhen` | `ComponentDef[]?` | The components the plugin's work is about. While no entity has any of them, the systems registered in its `build()` are skipped, so a game that never places water pays nothing for the water plugin each frame. They still run for one frame after the last one goes, so the plugin can release what it held. Absent: always run. The engine's water, terrain, planet, foliage, tilemap, navigation, behaviour tree, state machine, perception and velocity plugins declare it. One system can be gated on its own the same way: `app.addSystemToSchedule(schedule, system, { activeWhen: [MyComponent] })`. || `finish(app)` | optional | Runs once, after **all** plugins have built, when the app first ticks/runs — for wiring that needs the complete set. || `cleanup(app?)` | optional | Runs on `app.quit()`, in reverse install order. |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.mdxindex 20e099dae..85db7c7b1 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@@ -146,7 +146,7 @@ export const scorePlugin: Plugin = {| `dependencies` | `PluginDependency[]?` | 前置条件,每项是插件**名**(`string`)或**资源定义**。缺失时 `addPlugin` 抛错;`addPlugins` 还会用名字边为整批排序。 || `before` / `after` | `string[]?` | 相对其他插件名的软排序提示,在 `addPlugins` 批量安装时生效。 || `build(app)` | 必需 | 注册系统、资源与事件。`addPlugin` 时立即执行。 |-| `activeWhen` | `ComponentDef[]?` | 插件工作所针对的组件。当没有任何实体拥有其中之一时,它在 `build()` 里注册的系统会被跳过——从不放水体的游戏,每帧不为水体插件付出任何开销。最后一个组件消失后仍会再运行一帧,让插件释放持有的资源。不写则始终运行。引擎的 water、terrain、planet、foliage、tilemap、nav、bt、fsm、perception、velocity 插件已声明。 |+| `activeWhen` | `ComponentDef[]?` | 插件工作所针对的组件。当没有任何实体拥有其中之一时,它在 `build()` 里注册的系统会被跳过——从不放水体的游戏,每帧不为水体插件付出任何开销。最后一个组件消失后仍会再运行一帧,让插件释放持有的资源。不写则始终运行。引擎的 water、terrain、planet、foliage、tilemap、nav、bt、fsm、perception、velocity 插件已声明。单个系统也可以这样门控:`app.addSystemToSchedule(schedule, system, { activeWhen: [MyComponent] })`。 || `finish(app)` | 可选 | 在**所有**插件 build 完、应用首次 tick/run 时执行一次——用于需要完整集合的接线。 || `cleanup(app?)` | 可选 | `app.quit()` 时按安装逆序执行。 |diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex d81071d45..b41f42f6b 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -466,7 +466,13 @@ export class App {addSystemToSchedule(schedule: Schedule,system: SystemDef,- options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string }+ options?: {+ runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string;+ /** This system alone, gated as Plugin.activeWhen gates a whole plugin: skipped while no+ * entity has any of these, and run one frame past the last. Takes precedence over the+ * building plugin's gate. */+ activeWhen?: readonly AnyComponentDef[];+ }): this {const name = system._name || `System_${++this.systemCounter_}`;const scoped = rescopeSystem(system, name);@@ -478,7 +484,9 @@ export class App {subsystem: this.buildingPlugin_ ?? undefined,fromBundle: this.addingBundleSystems_ || undefined,domain: options?.profileDomain ?? this.registeringDomain_(),- ...(this.buildingGate_ ? { gate: this.buildingGate_ } : {}),+ ...(options?.activeWhen?.length+ ? { gate: { components: options.activeWhen, frame: -1, open: true, present: true } }+ : this.buildingGate_ ? { gate: this.buildingGate_ } : {}),});this.sortedSystemsCache_.delete(schedule);this.dependencyCache_.delete(schedule);diff --git a/sdk/src/render/coverFade.ts b/sdk/src/render/coverFade.tsindex f93b65177..586e5c8fa 100644--- a/sdk/src/render/coverFade.ts+++ b/sdk/src/render/coverFade.ts@@ -148,7 +148,8 @@ export function installCoverFade(app: App): () => void {},{ name: 'CoverFadeSystem' },);- app.addSystemToSchedule(Schedule.PostUpdate, system);+ // Nothing to do in a scene without one; the frame after the last goes still runs, to restore what it faded.+ app.addSystemToSchedule(Schedule.PostUpdate, system, { activeWhen: [CoverFade] });return () => {const world = app.world;diff --git a/sdk/src/render/fogOfWar.ts b/sdk/src/render/fogOfWar.tsindex b70d90d3d..18bf58e47 100644--- a/sdk/src/render/fogOfWar.ts+++ b/sdk/src/render/fogOfWar.ts@@ -351,7 +351,8 @@ export function installFogOfWar(app: App): () => void {{ name: 'FogOfWarSystem' },);// After the sight system has read the walls (it is installed first), and before the frame is drawn.- app.addSystemToSchedule(Schedule.PostUpdate, system);+ // Nothing to do in a scene without one; the frame after the last goes still runs, to let its texture go.+ app.addSystemToSchedule(Schedule.PostUpdate, system, { activeWhen: [FogOfWar] });return () => {fogNow = null;diff --git a/sdk/src/render/footsteps.ts b/sdk/src/render/footsteps.tsindex 47222af07..9128ae44b 100644--- a/sdk/src/render/footsteps.ts+++ b/sdk/src/render/footsteps.ts@@ -319,7 +319,8 @@ export function installFootsteps(app: App): () => void {},{ name: 'FootstepsSystem' },);- app.addSystemToSchedule(Schedule.PostUpdate, system);+ // Nothing to do in a scene without one; the frame after the last goes still runs, to finish what it started.+ app.addSystemToSchedule(Schedule.PostUpdate, system, { activeWhen: [Footsteps] });return () => {const world = app.world;diff --git a/sdk/src/render/rainShelter.ts b/sdk/src/render/rainShelter.tsindex 5a846ca2d..06044599b 100644--- a/sdk/src/render/rainShelter.ts+++ b/sdk/src/render/rainShelter.ts@@ -318,7 +318,8 @@ export function installRainShelter(app: App): () => void {{ name: 'RainShelterSystem' },);// After the cover fade has moved the sprites' alpha (it is installed first), and before the frame is drawn.- app.addSystemToSchedule(Schedule.PostUpdate, system);+ // Nothing to do in a scene without one; the frame after the last goes still runs, to put back what it changed.+ app.addSystemToSchedule(Schedule.PostUpdate, system, { activeWhen: [RainShelter, RainUpright] });return () => {sheltersNow = [];diff --git a/sdk/src/render/sight.ts b/sdk/src/render/sight.tsindex c8315121e..d0085c170 100644--- a/sdk/src/render/sight.ts+++ b/sdk/src/render/sight.ts@@ -218,7 +218,8 @@ export function installSight(app: App): () => void {},{ name: 'SightSystem' },);- app.addSystemToSchedule(Schedule.PostUpdate, system);+ // Nothing to do in a scene without one; the frame after the last goes still runs, to restore what it hid.+ app.addSystemToSchedule(Schedule.PostUpdate, system, { activeWhen: [SightViewer, SightTarget] });return () => {ringsNow = [];diff --git a/sdk/src/render/swayPush.ts b/sdk/src/render/swayPush.tsindex 9b2530c59..240fa0edc 100644--- a/sdk/src/render/swayPush.ts+++ b/sdk/src/render/swayPush.ts@@ -102,7 +102,8 @@ export function installSwayPush(app: App): () => void {},{ name: 'SwayPushSystem' },);- app.addSystemToSchedule(Schedule.PostUpdate, system);+ // Nothing to do in a scene without one; the frame after the last goes still runs, to clear the push it wrote.+ app.addSystemToSchedule(Schedule.PostUpdate, system, { activeWhen: [SwayPusher] });return () => { clear(); };}diff --git a/sdk/tests/plugin-active-when.test.ts b/sdk/tests/plugin-active-when.test.tsindex af0c8336e..b8eb64168 100644--- a/sdk/tests/plugin-active-when.test.ts+++ b/sdk/tests/plugin-active-when.test.ts@@ -49,4 +49,22 @@ describe('Plugin.activeWhen', () => {await app.tick(1 / 60);expect(runs).toBe(2);});++ it('gates one system on its own, inside a plugin that is not gated', async () => {+ const Lamp = defineComponent('ActiveWhenLamp', { on: true });+ let gated = 0, always = 0;+ const app = App.new();+ app.addPlugin({ name: 'mixed', build(a) {+ a.addSystemToSchedule(Schedule.Update, defineSystem([], () => { always++; }, { name: 'Always2' }));+ a.addSystemToSchedule(Schedule.Update, defineSystem([], () => { gated++; }, { name: 'LampSystem' }), { activeWhen: [Lamp] });+ } });+ await app.tick(1 / 60);+ gated = 0; always = 0;+ await app.tick(1 / 60);+ expect([gated, always]).toEqual([0, 1]);+ const e = app.world.spawn();+ app.world.insert(e, Lamp, { on: true });+ await app.tick(1 / 60);+ expect([gated, always]).toEqual([1, 2]);+ });});