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(subsystems): auto-report liveness from each plugin's systems

esengine2cb4a75890b7
diff --git a/sdk/src/app.ts b/sdk/src/app.ts
index 0e7c17113..1e842ecfc 100644
--- a/sdk/src/app.ts
+++ b/sdk/src/app.ts
@@ -56,6 +56,9 @@ interface SystemEntry {
runBefore?: string[];
runAfter?: string[];
runIf?: RunCondition;
+ /** The subsystem (owning plugin name) this system belongs to — pets that
+ * subsystem's liveness watchdog when it runs (observability). */
+ subsystem?: string;
}
// =============================================================================
@@ -93,6 +96,9 @@ export class App {
private readonly installedPluginNames_ = new Set<string>();
// Per-App (per-realm) so isolated realms never alias; not a shared resource default.
private readonly subsystems_ = new SubsystemRegistry();
+ /** The plugin currently in build(), so systems it adds inherit its name for
+ * liveness reporting. Null outside a build. */
+ private buildingPlugin_: string | null = null;
// The realm's acquirer for optional native modules (physics, spine). Set once
// at app creation; physics/spine self-gate off it. Null in headless/test apps.
private sideModules_: SideModuleHost | null = null;
@@ -187,6 +193,8 @@ export class App {
),
});
}
+ const prevBuilding = this.buildingPlugin_;
+ this.buildingPlugin_ = plugin.name ?? null;
try {
plugin.build(this);
// Sync plugin: live once build() returns → promote. An async plugin
@@ -203,6 +211,8 @@ export class App {
this.subsystems_.markError(plugin.name, e instanceof Error ? e.message : String(e));
}
throw e;
+ } finally {
+ this.buildingPlugin_ = prevBuilding;
}
return this;
}
@@ -235,6 +245,7 @@ export class App {
runBefore: options?.runBefore,
runAfter: options?.runAfter,
runIf: options?.runIf,
+ subsystem: this.buildingPlugin_ ?? undefined,
});
this.sortedSystemsCache_.delete(schedule);
return this;
@@ -281,6 +292,7 @@ export class App {
runBefore: mergedRunBefore,
runAfter: mergedRunAfter,
runIf,
+ subsystem: this.buildingPlugin_ ?? undefined,
});
}
this.sortedSystemsCache_.delete(schedule);
@@ -883,6 +895,8 @@ export class App {
if (result instanceof Promise) {
await result;
}
+ // Liveness: a system ran, so its owning subsystem stepped this frame.
+ if (entry.subsystem) this.subsystems_.markStepped(entry.subsystem);
} catch (e) {
const name = entry.system._name;
log.error('app', `System "${name}" threw an error`, e);
diff --git a/sdk/src/physics/PhysicsSystem.ts b/sdk/src/physics/PhysicsSystem.ts
index 875ae23b0..94af839d3 100644
--- a/sdk/src/physics/PhysicsSystem.ts
+++ b/sdk/src/physics/PhysicsSystem.ts
@@ -658,9 +658,8 @@ export function registerPhysicsSystem(
defineSystem(
[],
() => {
- // Watchdog beat: gated by playModeOnly, so a fresh beat means
- // "physics is actually stepping" (vs loaded-but-frozen in edit mode).
- app.subsystems.markStepped('physics');
+ // Liveness is now auto-reported by the scheduler (this system is tagged
+ // 'physics' and gated by playModeOnly, so it only beats while stepping).
// Read pixelsPerUnit live each tick so a Canvas property
// change at runtime (editor: user edits Canvas.pixelsPerUnit)
// propagates to physics transforms instead of staying at the
diff --git a/sdk/tests/subsystems.test.ts b/sdk/tests/subsystems.test.ts
index 400f64898..9570ccc30 100644
--- a/sdk/tests/subsystems.test.ts
+++ b/sdk/tests/subsystems.test.ts
@@ -3,6 +3,7 @@
import { describe, it, expect, vi } from 'vitest';
import { SubsystemRegistry } from '../src/subsystems';
import { App, type Plugin } from '../src/app';
+import { Schedule, defineSystem } from '../src/system';
describe('SubsystemRegistry', () => {
it('registers in the registered phase, in install order, inactive', () => {
@@ -119,3 +120,41 @@ describe('App auto-registers plugin lifecycle into the subsystem registry', () =
expect(b?.dependsOn).toEqual(['a']);
});
});
+
+describe('App reports subsystem liveness from its systems (auto-watchdog)', () => {
+ const activityOf = (app: App, id: string) =>
+ app.subsystems.getStatuses().find((s) => s.id === id)?.activity;
+
+ it('marks a plugin stepping once one of its systems runs in a frame', async () => {
+ const app = App.new();
+ app.addPlugin({
+ name: 'ticker',
+ build(a) { a.addSystemToSchedule(Schedule.Update, defineSystem([], () => {}, { name: 'TickSys' })); },
+ });
+ expect(activityOf(app, 'ticker')).toBe('inactive'); // ready, never beat
+ await app.tick(1 / 60);
+ expect(activityOf(app, 'ticker')).toBe('stepping');
+ });
+
+ it('leaves a gated-off subsystem inactive (load≠run)', async () => {
+ const app = App.new();
+ app.addPlugin({
+ name: 'gated',
+ build(a) {
+ a.addSystemToSchedule(
+ Schedule.Update, defineSystem([], () => {}, { name: 'GatedSys' }), { runIf: () => false },
+ );
+ },
+ });
+ await app.tick(1 / 60);
+ expect(activityOf(app, 'gated')).toBe('inactive'); // system never ran → no beat
+ });
+
+ it('does not attribute systems added outside a plugin build to any subsystem', async () => {
+ const app = App.new();
+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {}, { name: 'LooseSys' }));
+ await app.tick(1 / 60);
+ // No subsystem was registered for a loose system, so nothing to assert beyond no throw.
+ expect(app.subsystems.getStatuses()).toEqual([]);
+ });
+});