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
fix(app): a frame-rate cap keeps a cadence, so 30 on a 60 Hz display is 30
esengine8495fb1eb568
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 006a1874f..23e5bf043 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -129,6 +129,9 @@ function describeSchedule(value: unknown): string {// App// =============================================================================++/** How early a capped frame may land and still count as on time: vsync jitter. */+const CAP_JITTER_MS = 1;export class App {private readonly world_: World;private readonly resources_: ResourceStorage;@@ -157,6 +160,7 @@ export class App {// always runs (the check is after a step), so the sim always advances.private fixedStepBudgetMs_ = 8;private targetFrameInterval_ = 0;+ private nextCapFrameAt_ = 0;private module_: ESEngineModule | null = null;private pipeline_: RenderPipeline | null = null;@@ -738,6 +742,7 @@ export class App {setTargetFrameRate(fps: number): void {this.targetFrameInterval_ = fps > 0 ? 1000 / fps : 0;+ this.nextCapFrameAt_ = 0;}getTargetFrameRate(): number {@@ -1072,9 +1077,17 @@ export class App {const currentTime = typeof rafTime === 'number' && rafTime > 0 ? rafTime : platformNow();const deltaMs = currentTime - this.lastTime_;- if (this.targetFrameInterval_ > 0 && deltaMs < this.targetFrameInterval_) {- requestAnimationFrame(this.mainLoop);- return;+ // A cadence, not a minimum gap: a cap of two vsyncs measured frame to frame+ // loses to jitter half the time and waits a third (30 fps on 60 Hz ran at 24).+ if (this.targetFrameInterval_ > 0) {+ if (currentTime < this.nextCapFrameAt_ - CAP_JITTER_MS) {+ requestAnimationFrame(this.mainLoop);+ return;+ }+ // More than a frame behind (a stall, a hidden page): the cadence restarts here.+ this.nextCapFrameAt_ = currentTime - this.nextCapFrameAt_ > this.targetFrameInterval_+ ? currentTime + this.targetFrameInterval_+ : this.nextCapFrameAt_ + this.targetFrameInterval_;}this.lastTime_ = currentTime;diff --git a/sdk/tests/app-tick.test.ts b/sdk/tests/app-tick.test.tsindex bae048ad2..639efb7c9 100644--- a/sdk/tests/app-tick.test.ts+++ b/sdk/tests/app-tick.test.ts@@ -213,6 +213,40 @@ describe('App.stepFrames()', () => {}});+ it.each([30, 48])('a %i fps cap on a 60 Hz display runs at the cap, whatever the jitter', async (cap) => {+ const realRaf = globalThis.requestAnimationFrame;+ let pending: ((ts: number) => void) | null = null;+ globalThis.requestAnimationFrame = ((fn: FrameRequestCallback) => {+ pending = fn as unknown as (ts: number) => void;+ return 1;+ }) as unknown as typeof globalThis.requestAnimationFrame;+ setPlatform({ now: () => 1000 } as unknown as PlatformAdapter);+ const app = App.new();+ let frames = 0;+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => { frames++; }, { name: 'CountFrames' }));+ const settle = async (): Promise<void> => { for (let i = 0; i < 30; i++) await Promise.resolve(); };+ try {+ app.setTargetFrameRate(cap);+ await app.run();+ await settle();+ frames = 0;+ // A 60 Hz display: vsyncs every 16.67 ms, each a fraction of a ms off.+ const VSYNC = 1000 / 60;+ for (let i = 1; i <= 120; i++) {+ const fire = pending!;+ pending = null;+ await fire(1000 + i * VSYNC + (i % 2 ? -0.3 : 0.3));+ await settle();+ }+ // Two seconds of vsyncs: never faster than the cap, and not a frame short of it.+ expect(frames).toBeGreaterThanOrEqual(cap * 2 - 1);+ expect(frames).toBeLessThanOrEqual(cap * 2 + 1);+ } finally {+ app.quit();+ globalThis.requestAnimationFrame = realRaf;+ }+ });+it('defaults to one frame', async () => {const app = App.new();await app.stepFrames();