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(profiler): capture every frame from the play realm

yhhdda66ec91f68
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 858f190d5..5227a3319 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Play-mode performance captures include every recorded frame.** The editor's `profile_frames` command captures the running world's frame-end stream instead of its 250 ms telemetry snapshots, so frame counts, tail latency and system costs come from actual frames. Captures discard data if the play world is replaced, keep editor overhead visible, and can observe existing instrumentation without resetting timings or toggling another recorder's profiling switches.
+
- **Inactive 2D bodies retain pending collider and body edits.** Physics reconciliation tracks the last synchronization of each body, so changes made while a parent or entity is inactive are applied on reactivation instead of being skipped by another body's newer global synchronization. Collider enable flags and rigid-body properties update in place, preserving the body and its existing simulation state.
- **Paused sprites refresh replaced animation clips.** A sprite that has already applied a clip follows a newly published clip while paused, updating its displayed frame without advancing the frame index or timer or firing playback events. Unchanged paused frames avoid component writes, and an initially paused animator still leaves the authored sprite untouched until playback or an explicit frame selection.
diff --git a/desktop b/desktop
index 55e1de1ec..3edce7a5a 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 55e1de1ecf924849eb62290511d65cee97009a6d
+Subproject commit 3edce7a5a6a0c44d39fcf36e6bce0aee668935b1
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 5b429a646..025d77751 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -6530,6 +6530,7 @@ static prototype: ProfileRecorder
## ProfileRecorderOptions — interface @experimental
```
budgetMs: number | undefined
+instrumentation: "enable" | "existing" | undefined
maxFrames: number | undefined
source: CaptureSource | undefined
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a41d6f79d..7aefafee4 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -6725,6 +6725,7 @@ static prototype: ProfileRecorder
## ProfileRecorderOptions — interface @experimental
```
budgetMs: number | undefined
+instrumentation: "enable" | "existing" | undefined
maxFrames: number | undefined
source: CaptureSource | undefined
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 9a02483aa..04991764c 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -6525,6 +6525,7 @@ static prototype: ProfileRecorder
## ProfileRecorderOptions — interface @experimental
```
budgetMs: number | undefined
+instrumentation: "enable" | "existing" | undefined
maxFrames: number | undefined
source: CaptureSource | undefined
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 72c0a856b..5508cd6e4 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -6806,6 +6806,7 @@ static prototype: ProfileRecorder
## ProfileRecorderOptions — interface @experimental
```
budgetMs: number | undefined
+instrumentation: "enable" | "existing" | undefined
maxFrames: number | undefined
source: CaptureSource | undefined
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index e1c23849f..d74413195 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -6532,6 +6532,7 @@ static prototype: ProfileRecorder
## ProfileRecorderOptions — interface @experimental
```
budgetMs: number | undefined
+instrumentation: "enable" | "existing" | undefined
maxFrames: number | undefined
source: CaptureSource | undefined
```
diff --git a/sdk/src/app/profileRecorder.ts b/sdk/src/app/profileRecorder.ts
index 95924b25a..38e1dcf7c 100644
--- a/sdk/src/app/profileRecorder.ts
+++ b/sdk/src/app/profileRecorder.ts
@@ -15,6 +15,8 @@ import {
import type { ScopeCost } from './frameProfile';
export interface ProfileRecorderOptions {
+ /** Use already enabled timings without changing their instrumentation switches. */
+ instrumentation?: 'enable' | 'existing';
/** Frames kept before the oldest is dropped. 1800 is ~30s at 60Hz. */
maxFrames?: number;
/** The budget a reader judges the capture against. Defaults to 60Hz. */
@@ -82,8 +84,10 @@ export class ProfileRecorder {
if (this.recording_) return;
this.frames_.length = 0;
this.seq_ = 0;
- this.app_.enableStats();
- engineApi(this.app_)?.engine_setCpuProfiling?.(true);
+ if (this.options_.instrumentation !== 'existing') {
+ this.app_.enableStats();
+ engineApi(this.app_)?.engine_setCpuProfiling?.(true);
+ }
this.recording_ = true;
this.detach_ = this.app_.onFrameEnd((dtMs) => this.capture_(dtMs));
}
@@ -94,7 +98,7 @@ export class ProfileRecorder {
this.recording_ = false;
this.detach_?.();
this.detach_ = null;
- engineApi(this.app_)?.engine_setCpuProfiling?.(false);
+ if (this.options_.instrumentation !== 'existing') engineApi(this.app_)?.engine_setCpuProfiling?.(false);
}
/** Throw away what has been recorded, keeping the recorder running. */
diff --git a/sdk/tests/profile-recorder.test.ts b/sdk/tests/profile-recorder.test.ts
index c55fdbd80..b0f9dd697 100644
--- a/sdk/tests/profile-recorder.test.ts
+++ b/sdk/tests/profile-recorder.test.ts
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
import { App } from '../src/app/app';
import { Schedule, defineSystem } from '../src/ecs/system';
import { ProfileRecorder, ProfileRecorderPlugin } from '../src/app/profileRecorder';
@@ -12,6 +12,21 @@ function appWithSystem(name = 'Worker'): App {
return app;
}
+it('can observe existing timings without resetting stats or toggling native profiling', async () => {
+ const app = appWithSystem().enableStats();
+ const reset = vi.spyOn(app, 'enableStats');
+ const profiling = vi.fn();
+ const api = await import('../src/ecs/bridge/engineApi');
+ const native = vi.spyOn(api, 'engineApi').mockReturnValue({ engine_setCpuProfiling: profiling } as ReturnType<typeof api.engineApi>);
+ try {
+ const recorder = new ProfileRecorder(app, { instrumentation: 'existing' });
+ recorder.start(); await app.tick(1 / 60); await app.tick(1 / 60); recorder.stop();
+ expect(recorder.take().frames).toHaveLength(2);
+ await app.tick(1 / 60); expect(recorder.take().frames).toHaveLength(2);
+ expect(reset).not.toHaveBeenCalled(); expect(profiling).not.toHaveBeenCalled();
+ } finally { native.mockRestore(); reset.mockRestore(); app.quit(); }
+});
+
describe('App.onFrameEnd', () => {
it('fires once a frame, after the systems ran', async () => {
const app = App.new();
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index e440c33ae..0cfc0ef75 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(profiler): capture every frame from the play realm':
+ { note: 'Play-mode performance captures include every recorded frame.' },
'fix(physics): retain edits made to inactive 2d bodies':
{ note: 'Inactive 2D bodies retain pending collider and body edits.' },
'fix(animation): refresh replaced clips on paused sprites':