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(editor): "Use less CPU in background" — focus-driven engine frame cap

yhhf64fb510ae46
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index b4b7f98a9..45cda46e4 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -47,6 +47,7 @@ class EngineHostImpl {
private canvas_: HTMLCanvasElement | null = null;
private app_: App | null = null;
private module_: ESEngineModule | null = null;
+ private targetFps_ = 0;
private booted = false;
private resizeObserver: ResizeObserver | null = null;
@@ -93,6 +94,11 @@ class EngineHostImpl {
getResource<T>(resource: ResourceDef<T>): T | undefined {
return this.app_?.getResource(resource);
}
+ /** Cap the edit-realm engine loop (0 = uncapped). Survives reboot. */
+ setTargetFrameRate(fps: number): void {
+ this.targetFps_ = fps;
+ this.app_?.setTargetFrameRate(fps);
+ }
/** Animation names of a spine entity's loaded skeleton (for the inspector dropdown); empty if none. */
spineAnimations(runtimeId: number): string[] {
return this.app_?.getPlugin(SpinePlugin)?.spineManager?.getAnimations(runtimeId as never) ?? [];
@@ -444,6 +450,7 @@ class EngineHostImpl {
wasmBaseUrl: '/wasm',
});
this.app_ = app;
+ if (this.targetFps_ > 0) app.setTargetFrameRate(this.targetFps_);
app.enableStats();
module.engine_setCpuProfiling?.(true);
diff --git a/desktop/src/engine/backgroundThrottle.ts b/desktop/src/engine/backgroundThrottle.ts
new file mode 100644
index 000000000..0e0e37e84
--- /dev/null
+++ b/desktop/src/engine/backgroundThrottle.ts
@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file backgroundThrottle.ts — editor-side "use less CPU in background".
+ *
+ * Chromium's own background throttling is disabled (main.ts) so automation
+ * never freezes; this is the smart replacement: cap the engine loop at a low
+ * frame rate while the window is unfocused (Unreal's "Use Less CPU when in
+ * Background"), restore on focus. Driven by the `performance.*` setting.
+ */
+import { EngineHost } from './EngineHost';
+
+const BACKGROUND_FPS = 10;
+
+let enabled = true;
+let focused = true;
+
+function apply(): void {
+ EngineHost.setTargetFrameRate(enabled && !focused ? BACKGROUND_FPS : 0);
+}
+
+/** Settings backing: toggle the background cap (applies immediately). */
+export function setUseLessCpuInBackground(on: boolean): void {
+ enabled = on;
+ apply();
+}
+
+/** Attach the focus listeners once at boot. Automation windows are driven
+ * unfocused, so `?automation=1` opts out entirely. */
+export function initBackgroundThrottle(): void {
+ if (new URLSearchParams(location.search).has('automation')) return;
+ focused = document.hasFocus();
+ window.addEventListener('focus', () => { focused = true; apply(); });
+ window.addEventListener('blur', () => { focused = false; apply(); });
+ apply();
+}
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 617578c50..2b7f7bff7 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -40,6 +40,7 @@ import { EditorControlSurface } from './engine/EditorSession';
import { PerfMonitor } from './engine/PerfMonitor';
import { LogStore } from './store/LogStore';
import { initFsWatch } from './project/fsWatch';
+import { initBackgroundThrottle } from './engine/backgroundThrottle';
// Register the built-in settings (side effect) and replay persisted ones.
import './settings';
import { applySettings } from './store/settingsStore';
@@ -52,6 +53,10 @@ applySettings();
// edits made outside the editor) via the main-process project watcher.
initFsWatch();
+// Focus-driven engine frame cap (the smart replacement for Chromium's
+// disabled background throttling).
+initBackgroundThrottle();
+
// Automation hook (screenshots / visual-regression): with `?automation=1`, expose the
// minimum to drive the launcher→editor flow from a headless driver. Gated so the normal
// editor never carries it; mirrors the headless render host's `window.__estellaHeadless`.
diff --git a/desktop/src/settings/editorSettings.ts b/desktop/src/settings/editorSettings.ts
index dd3cd070e..514cb36cd 100644
--- a/desktop/src/settings/editorSettings.ts
+++ b/desktop/src/settings/editorSettings.ts
@@ -14,14 +14,16 @@ import { settingsRegistry } from './registry';
import { useEditorStore } from '@/store/editorStore';
import { LogStore } from '@/store/LogStore';
import { commands } from '@/commands';
+import { setUseLessCpuInBackground } from '@/engine/backgroundThrottle';
const root = () => document.documentElement.style;
// ── Sections (editor category) ──────────────────────────────────────────────
settingsRegistry.registerSection({ id: 'appearance', label: 'Appearance', category: 'editor', order: 1 });
settingsRegistry.registerSection({ id: 'viewport', label: 'Viewport', category: 'editor', order: 2 });
-settingsRegistry.registerSection({ id: 'shortcuts', label: 'Keyboard Shortcuts', category: 'editor', order: 3 });
-settingsRegistry.registerSection({ id: 'console', label: 'Console', category: 'editor', order: 4 });
+settingsRegistry.registerSection({ id: 'performance', label: 'Performance', category: 'editor', order: 3 });
+settingsRegistry.registerSection({ id: 'shortcuts', label: 'Keyboard Shortcuts', category: 'editor', order: 4 });
+settingsRegistry.registerSection({ id: 'console', label: 'Console', category: 'editor', order: 5 });
// ── Appearance (store-owned, applied via CSS) ───────────────────────────────
settingsRegistry.register({
@@ -110,6 +112,19 @@ settingsRegistry.register({
bind: { get: () => ed().showGizmos, set: (v) => useEditorStore.setState({ showGizmos: v }) },
});
+// ── Performance ──────────────────────────────────────────────────────────────
+settingsRegistry.register({
+ id: 'performance.useLessCpuInBackground',
+ type: 'boolean',
+ scope: 'editor',
+ section: 'performance',
+ group: 'Background',
+ label: 'Use less CPU in background',
+ description: 'Caps the engine at 10 fps while the editor window is unfocused.',
+ default: true,
+ effect: (v) => setUseLessCpuInBackground(v),
+});
+
// ── Console (store-owned, applied to the log ring buffer) ────────────────────
settingsRegistry.register({
id: 'console.maxLines',