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
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.tsindex 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.tsnew file mode 100644index 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.tsxindex 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.tsindex 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',