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): seven more subsystems sit out the frames a scene gives them nothing to do
yhh788e2291bf56
diff --git a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdxindex 0c568d7b7..8bf29e583 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 and planet 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. || `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 abd0eb839..20e099dae 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 插件已声明。 |+| `activeWhen` | `ComponentDef[]?` | 插件工作所针对的组件。当没有任何实体拥有其中之一时,它在 `build()` 里注册的系统会被跳过——从不放水体的游戏,每帧不为水体插件付出任何开销。最后一个组件消失后仍会再运行一帧,让插件释放持有的资源。不写则始终运行。引擎的 water、terrain、planet、foliage、tilemap、nav、bt、fsm、perception、velocity 插件已声明。 || `finish(app)` | 可选 | 在**所有**插件 build 完、应用首次 tick/run 时执行一次——用于需要完整集合的接线。 || `cleanup(app?)` | 可选 | `app.quit()` 时按安装逆序执行。 |diff --git a/sdk/src/ai/bt/BtPlugin.ts b/sdk/src/ai/bt/BtPlugin.tsindex 56aae9ae9..4ba633592 100644--- a/sdk/src/ai/bt/BtPlugin.ts+++ b/sdk/src/ai/bt/BtPlugin.ts@@ -149,6 +149,8 @@ export const AiBt = defineResource<BehaviorTrees>(null!, 'AiBt');export class BtPlugin implements Plugin {name = 'bt';+ /** Nothing to tick without an agent; state per entity is dropped on despawn. */+ readonly activeWhen = [BehaviorTreeAgent];build(app: App): void {ensureBuiltinAiRegistrations();diff --git a/sdk/src/ai/fsm/FsmPlugin.ts b/sdk/src/ai/fsm/FsmPlugin.tsindex de44c49fd..efe49e5ff 100644--- a/sdk/src/ai/fsm/FsmPlugin.ts+++ b/sdk/src/ai/fsm/FsmPlugin.ts@@ -171,6 +171,8 @@ export const AiFsm = defineResource<StateMachines>(null!, 'AiFsm');export class FsmPlugin implements Plugin {name = 'fsm';+ /** Nothing to step without an agent; state per entity is dropped on despawn. */+ readonly activeWhen = [StateMachineAgent];build(app: App): void {ensureBuiltinAiRegistrations();diff --git a/sdk/src/ai/nav/NavPlugin.ts b/sdk/src/ai/nav/NavPlugin.tsindex cc7e1cfa2..617d197f9 100644--- a/sdk/src/ai/nav/NavPlugin.ts+++ b/sdk/src/ai/nav/NavPlugin.ts@@ -576,6 +576,8 @@ const WAYPOINT_REACH = 8;export class NavPlugin implements Plugin {name = 'nav';+ /** A volume to bake or an agent to move; the frame after the last one goes still runs, so a mesh is let go. */+ readonly activeWhen = [NavVolume, NavAgent];build(app: App): void {app.insertResource(Nav, new Navigation());diff --git a/sdk/src/ai/perception/PerceptionPlugin.ts b/sdk/src/ai/perception/PerceptionPlugin.tsindex 9c331694b..4514ff1f8 100644--- a/sdk/src/ai/perception/PerceptionPlugin.ts+++ b/sdk/src/ai/perception/PerceptionPlugin.ts@@ -118,6 +118,8 @@ export function makeLosCheck3D(queries: Physics3DQueries): LosCheck {export class PerceptionPlugin implements Plugin {name = 'perception';+ /** Perception is a perceiver's: without one there is no one to see. */+ readonly activeWhen = [Perceiver];build(app: App): void {app.addSystemToSchedule(diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 8994acc9e..d81071d45 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -424,7 +424,14 @@ export class App {let present = false;for (const c of gate.components) {// A cached query: unchanged structure answers without walking anything.- if (world.queryEntities([c]).length > 0) { present = true; break; }+ // A core that cannot answer for the component (compiled out) is not a+ // reason to stop the plugin: it runs as it did before there was a gate.+ try {+ if (world.queryEntities([c]).length > 0) { present = true; break; }+ } catch {+ present = true;+ break;+ }}gate.open = present || gate.present;gate.present = present;diff --git a/sdk/src/foliage/foliagePlugin.ts b/sdk/src/foliage/foliagePlugin.tsindex f880aac12..e3ffd7c7f 100644--- a/sdk/src/foliage/foliagePlugin.ts+++ b/sdk/src/foliage/foliagePlugin.ts@@ -166,6 +166,8 @@ export const FoliageRes = defineResource<FoliageField>(new FoliageField(), 'Foliexport class FoliagePlugin implements Plugin {name = 'foliage';+ /** No foliage, no work; the frame after the last one goes still runs its sweep. */+ readonly activeWhen = [Foliage];build(app: App): void {const field = new FoliageField();diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.tsindex e10db275a..4bc286aa9 100644--- a/sdk/src/tilemap/tilemapPlugin.ts+++ b/sdk/src/tilemap/tilemapPlugin.ts@@ -806,6 +806,8 @@ export const TilemapRuntimeState = defineResource<TilemapRuntime>(null!, 'Tilema*/export class TilemapPlugin implements Plugin {name = 'tilemap';+ /** Layers to sync, animate and give colliders; the frame after the last one goes still tears them down. */+ readonly activeWhen = [TilemapLayer, Tilemap];build(app: App): void {const runtime = new TilemapRuntime();diff --git a/sdk/src/velocity.ts b/sdk/src/velocity.tsindex 792aa0c4b..63f2aec43 100644--- a/sdk/src/velocity.ts+++ b/sdk/src/velocity.ts@@ -71,6 +71,8 @@ export const velocitySystem = defineSystem(export const velocityPlugin: Plugin = {name: 'Velocity',+ // One query over Velocity: with none in the scene, skipped rather than walked.+ activeWhen: [Velocity],profileDomain: 'velocity',build(app) {app.addSystemToSchedule(Schedule.Update, velocitySystem, { runIf: playModeOnly });