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.

fix(profiling): attribute async Box2D systems to physics

yhhaf37628dd82a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 28a4ded35..cf46aa793 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Async Box2D systems retain their physics performance category.** Physics stepping, interpolation, contact event delivery, and character controllers now appear under physics after module loading completes. Deferred system registration can explicitly provide its profiling domain without changing the classification of later registrations.
+
- **Box2D initialization and shutdown belong to their App.** Stopping an App before its module finishes loading prevents late physics initialization and system installation. Shared plugin instances keep independent bridges and module ownership, so an older App cannot shut down or replace a newer App's physics world; cancelled load failures do not change the stopped App's subsystem status.
- **Screen-excluded UI scissor regions no longer submit draws.** Root scissor masks intersect the current view's viewport before propagating to descendants. Empty regions skip UI visual collection and batch geometry/index/command allocation, including text submissions; stencil-only entries remain drawable. Moving a masked subtree back into view restores its draws on the next frame.
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 69ce8fbed..abf2358ba 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -742,7 +742,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 5a43e5337..085e43665 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -742,7 +742,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index e41e4369e..e9b028e04 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -737,7 +737,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 03fc6e27f..100af1e6c 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -737,7 +737,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index e40aed0d7..3ee71f612 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -737,7 +737,7 @@ addStartupSystem: (system: SystemDef) => App
addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
-addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string; }) => App
compiledSystemCount: number
compiledSystems: { readonly installed: readonly string[]; readonly calls: number; }
enableStats: () => App
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 67d316f8c..a7fc211b4 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -389,14 +389,14 @@ export class App {
}
/**
- * Register `system` onto `schedule`. Ordering given here is added to
- * whatever the definition already declared, so a system can carry its own
- * edges and still be constrained further at the registration site.
+ * Register `system` onto `schedule`, adding ordering to its declared edges.
+ * `profileDomain` attributes systems registered after an async plugin build
+ * returns; otherwise the current build context supplies it.
*/
addSystemToSchedule(
schedule: Schedule,
system: SystemDef,
- options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition }
+ options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string }
): this {
const name = system._name || `System_${++this.systemCounter_}`;
const scoped = rescopeSystem(system, name);
@@ -407,7 +407,7 @@ export class App {
runIf: options?.runIf,
subsystem: this.buildingPlugin_ ?? undefined,
fromBundle: this.addingBundleSystems_ || undefined,
- domain: this.registeringDomain_(),
+ domain: options?.profileDomain ?? this.registeringDomain_(),
});
this.sortedSystemsCache_.delete(schedule);
this.dependencyCache_.delete(schedule);
diff --git a/sdk/src/physics/CharacterController2DSystem.ts b/sdk/src/physics/CharacterController2DSystem.ts
index d29e8cf4c..68775c4bd 100644
--- a/sdk/src/physics/CharacterController2DSystem.ts
+++ b/sdk/src/physics/CharacterController2DSystem.ts
@@ -176,6 +176,6 @@ export function registerCharacterController2DSystem(app: App): void {
},
},
),
- { runIf: playModeOnly },
+ { runIf: playModeOnly, profileDomain: 'physics' },
);
}
diff --git a/sdk/src/physics/PhysicsEventBridge.ts b/sdk/src/physics/PhysicsEventBridge.ts
index 110c4ab64..eec542be0 100644
--- a/sdk/src/physics/PhysicsEventBridge.ts
+++ b/sdk/src/physics/PhysicsEventBridge.ts
@@ -90,6 +90,6 @@ export function registerPhysics2DEventBridge(app: App): void {
}
}
}, { name: 'PhysicsEventBridgeSystem' }),
- { runIf: playModeOnly },
+ { runIf: playModeOnly, profileDomain: 'physics' },
);
}
diff --git a/sdk/src/physics/PhysicsSystem.ts b/sdk/src/physics/PhysicsSystem.ts
index c0f196f4b..042f377bb 100644
--- a/sdk/src/physics/PhysicsSystem.ts
+++ b/sdk/src/physics/PhysicsSystem.ts
@@ -924,7 +924,7 @@ export function registerPhysics2DSystem(
},
{ name: 'PhysicsStepSystem' }
),
- { runIf: playModeOnly }
+ { runIf: playModeOnly, profileDomain: 'physics' }
);
// ── Interpolate + publish (render cadence) ──────────────────────────────
@@ -954,6 +954,6 @@ export function registerPhysics2DSystem(
},
{ name: 'PhysicsInterpolateSystem' }
),
- { runIf: playModeOnly }
+ { runIf: playModeOnly, profileDomain: 'physics' }
);
}
diff --git a/sdk/tests/frame-costs.test.ts b/sdk/tests/frame-costs.test.ts
index 1dfa4eede..1fba53332 100644
--- a/sdk/tests/frame-costs.test.ts
+++ b/sdk/tests/frame-costs.test.ts
@@ -42,6 +42,22 @@ describe('App.getFrameCosts', () => {
expect(domainOf(app, 'RenderSystem')).toBe('render');
});
+ it('attributes a deferred registration without changing subsequent registrations', async () => {
+ const app = App.new().enableStats();
+ let ready!: Promise<void>;
+ app.addPlugin({ name: 'physics', build() {
+ ready = Promise.resolve().then(() => {
+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {}, { name: 'DeferredPhysics' }),
+ { profileDomain: 'physics' });
+ });
+ } });
+ await ready;
+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {}, { name: 'LooseAfterPhysics' }));
+ await app.tick(1 / 60);
+ expect(domainOf(app, 'DeferredPhysics')).toBe('physics');
+ expect(domainOf(app, 'LooseAfterPhysics')).toBe(DOMAIN_UNATTRIBUTED);
+ });
+
it('files project systems under scripts', async () => {
const app = App.new().enableStats();
app.addBundleSystems([
diff --git a/sdk/tests/physics-plugin-lifecycle.test.ts b/sdk/tests/physics-plugin-lifecycle.test.ts
index 9e7264c8c..d208cece7 100644
--- a/sdk/tests/physics-plugin-lifecycle.test.ts
+++ b/sdk/tests/physics-plugin-lifecycle.test.ts
@@ -12,10 +12,21 @@ function module() {
'_physics_capturePoses', '_physics_getInterpolatedCount', '_physics_getInterpolatedTransforms',
'_physics_collectEvents', '_physics_getDynamicBodyCount', '_physics_getDynamicBodyTransforms',
'_physics_setBodyTransform',
+ '_physics_getCollisionEnterCount', '_physics_getCollisionExitCount', '_physics_getHitEventCount',
+ '_physics_getSensorEnterCount', '_physics_getSensorExitCount',
].map(name => [name, vi.fn(() => 0)])) as unknown as PhysicsWasmModule;
}
function build(plugin: Physics2DPlugin) { const app = App.new(); apps.push(app); app.addPlugin(plugin); return app; }
afterEach(() => { for (const app of apps.splice(0)) app.quit(); });
+it('attributes asynchronously installed physics systems to the physics cost domain', async () => {
+ const app = build(new Physics2DPlugin('', {}, async () => module())).enableStats();
+ await app.getResource(Physics2DRuntime).initPromise;
+ await app.stepFrames(2, 1 / 30);
+ const costs = app.getFrameCosts()!.systems;
+ for (const name of ['PhysicsStepSystem', 'PhysicsInterpolateSystem', 'PhysicsEventBridgeSystem', 'CharacterController2DSystem']) {
+ expect(costs.find(system => system.name === name)?.domain).toBe('physics');
+ }
+});
it('quitting before the module arrives prevents late initialization and system installation', async () => {
const loaded = module(); let resolve!: (m: PhysicsWasmModule) => void;
const plugin = new Physics2DPlugin('', {}, () => new Promise(done => { resolve = done; }));
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 096fa3e3f..4e9017e9a 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(profiling): attribute async Box2D systems to physics':
+ { note: 'Async Box2D systems retain their physics performance category.' },
'fix(physics): isolate async Box2D module ownership by app':
{ note: 'Box2D initialization and shutdown belong to their App.' },
'perf(render): skip geometry outside UI scissor viewports':