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(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.ts
index 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.ts
index 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();