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
refactor: SDK architecture cleanup — Disabled tag, runFrame extraction, nameIndex optimization
esengineb30f30400a19
diff --git a/sdk/src/app.ts b/sdk/src/app.tsindex e26d3ebc2..de59c735b 100644--- a/sdk/src/app.ts+++ b/sdk/src/app.ts@@ -397,43 +397,7 @@ export class App {}await this.flushStartupSystems_();-- this.eventRegistry_.swapAll();- this.world_.advanceTick();- this.updateTime(delta);- this.world_.resetQueryPool();- this.frame_paused_ = false;-- if (this.user_paused_ && !this.step_pending_) {- await this.runSchedule(Schedule.Last);- } else {- await this.runSchedule(Schedule.First);-- this.fixedAccumulator_ += delta;- let fixedSteps = 0;- while (this.fixedAccumulator_ >= this.fixedTimestep_ && fixedSteps < this.maxFixedSteps_) {- this.fixedAccumulator_ -= this.fixedTimestep_;- await this.runSchedule(Schedule.FixedPreUpdate);- await this.runSchedule(Schedule.FixedUpdate);- await this.runSchedule(Schedule.FixedPostUpdate);- fixedSteps++;- }- if (fixedSteps >= this.maxFixedSteps_) {- this.fixedAccumulator_ = this.fixedTimestep_;- }-- await this.runSchedule(Schedule.PreUpdate);- await this.runSchedule(Schedule.Update);- await this.runSchedule(Schedule.PostUpdate);- await this.runSchedule(Schedule.Last);-- if (this.step_pending_) {- this.step_pending_ = false;- }- }-- const REMOVED_BUFFER_RETENTION = 2;- this.world_.cleanRemovedBuffer(this.world_.getWorldTick() - REMOVED_BUFFER_RETENTION);+ await this.runFrame_(delta);}async run(): Promise<void> {@@ -469,7 +433,38 @@ export class App {const delta = rawDelta * this.play_speed_;await this.flushStartupSystems_();+ await this.runFrame_(delta);++ requestAnimationFrame(this.mainLoop);+ };++ quit(): void {+ this.running_ = false;++ for (let i = this.installed_plugins_.length - 1; i >= 0; i--) {+ try { this.installed_plugins_[i].cleanup?.(this); } catch (e) {+ console.error('[ESEngine] Plugin cleanup error:', e);+ }+ }+ this.installed_plugins_.length = 0;+ this.installedPluginSet_.clear();+ this.installedPluginNames_.clear();++ for (const entity of this.world_.getAllEntities()) {+ try { this.world_.despawn(entity); } catch (e) { console.warn('[App] Shutdown despawn error:', e); }+ }+ this.world_.disconnectCpp();++ this.pipeline_ = null;+ this.runner_ = null;+ this.module_ = null;+ }++ // =========================================================================+ // Internal+ // =========================================================================+ private async runFrame_(delta: number): Promise<void> {this.eventRegistry_.swapAll();this.world_.advanceTick();this.updateTime(delta);@@ -506,36 +501,8 @@ export class App {const REMOVED_BUFFER_RETENTION = 2;this.world_.cleanRemovedBuffer(this.world_.getWorldTick() - REMOVED_BUFFER_RETENTION);-- requestAnimationFrame(this.mainLoop);- };-- quit(): void {- this.running_ = false;-- for (let i = this.installed_plugins_.length - 1; i >= 0; i--) {- try { this.installed_plugins_[i].cleanup?.(this); } catch (e) {- console.error('[ESEngine] Plugin cleanup error:', e);- }- }- this.installed_plugins_.length = 0;- this.installedPluginSet_.clear();- this.installedPluginNames_.clear();-- for (const entity of this.world_.getAllEntities()) {- try { this.world_.despawn(entity); } catch (e) { console.warn('[App] Shutdown despawn error:', e); }- }- this.world_.disconnectCpp();-- this.pipeline_ = null;- this.runner_ = null;- this.module_ = null;}- // =========================================================================- // Internal- // =========================================================================-private finishPlugins_(): void {if (this.pluginsFinished_) return;this.pluginsFinished_ = true;diff --git a/sdk/src/component.ts b/sdk/src/component.tsindex 6597fd925..bacfbaf66 100644--- a/sdk/src/component.ts+++ b/sdk/src/component.ts@@ -229,10 +229,6 @@ function detectColorKeys(defaults: unknown): readonly string[] {return keys;}-export interface ComponentMetadata {- entityFields?: string[];-}-export function defineBuiltin<T>(name: string, defaults: T, metadata?: ComponentMetadata): BuiltinComponentDef<T> {const meta = COMPONENT_META[name];const def: BuiltinComponentDef<T> = {@@ -549,6 +545,8 @@ export const ParticleEmitter = defineBuiltin<ParticleEmitterData>('ParticleEmittmetaDefaults<ParticleEmitterData>('ParticleEmitter'));+export const Disabled = defineTag('Disabled');+export const Name = defineComponent<NameData>('Name', { value: '' });export const SceneOwner = defineComponent<SceneOwnerData>('SceneOwner', {diff --git a/sdk/src/core.ts b/sdk/src/core.tsindex 1d331a488..ccf5fa5e9 100644--- a/sdk/src/core.ts+++ b/sdk/src/core.ts@@ -80,6 +80,7 @@ export {BitmapText,SpineAnimation,Name,+ Disabled,SceneOwner,ProjectionType,ClearFlags,diff --git a/sdk/src/sceneManager.ts b/sdk/src/sceneManager.tsindex 06955cf3d..501d69430 100644--- a/sdk/src/sceneManager.ts+++ b/sdk/src/sceneManager.ts@@ -15,12 +15,19 @@ import { registerDrawCallback, unregisterDrawCallback } from './customDraw';import { PostProcess, PostProcessStack } from './postprocess';import { Draw } from './draw';import { defineResource } from './resource';-import { SceneOwner, Sprite, SpineAnimation, BitmapText } from './component';+import {+ SceneOwner, Disabled, Sprite, SpineAnimation, BitmapText,+ ShapeRenderer, ParticleEmitter,+ type AnyComponentDef,+} from './component';import { UIRenderer } from './ui/UIRenderer';-import type { UIRendererData } from './ui/UIRenderer';import { Assets } from './asset/AssetPlugin';import { RuntimeConfig } from './defaults';+const RENDERABLE_COMPONENTS: AnyComponentDef[] = [+ Sprite, SpineAnimation, BitmapText, ShapeRenderer, ParticleEmitter, UIRenderer,+];+// =============================================================================// Types// =============================================================================@@ -81,7 +88,7 @@ class SceneInstance {readonly entities = new Set<Entity>();readonly drawCallbacks = new Map<string, DrawCallback>();readonly postProcessBindings = new Map<Entity, PostProcessStack>();- readonly savedAlphas = new Map<Entity, { sprite?: number; spine?: number; bitmapText?: number; uiRenderer?: number }>();+ readonly savedEnabled = new Map<Entity, Map<AnyComponentDef, boolean>>();loadedAssets: LoadedSceneAssets | null = null;status: SceneStatus = 'loading';@@ -557,45 +564,25 @@ export class SceneManagerState {instance.status = 'sleeping';this.sleepingScenes_.add(name);this.setPostProcessPassesEnabled(instance, false);- instance.savedAlphas.clear();+ instance.savedEnabled.clear();const world = this.app_.world;for (const entity of instance.entities) {if (!world.valid(entity)) continue;- const saved: { sprite?: number; spine?: number; bitmapText?: number; uiRenderer?: number } = {};- let hasSaved = false;-- if (world.has(entity, Sprite)) {- const sprite = world.get(entity, Sprite);- saved.sprite = sprite.color.a;- sprite.color.a = 0;- world.insert(entity, Sprite, sprite);- hasSaved = true;- }- if (world.has(entity, SpineAnimation)) {- const spine = world.get(entity, SpineAnimation);- saved.spine = spine.color.a;- spine.color.a = 0;- world.insert(entity, SpineAnimation, spine);- hasSaved = true;- }- if (world.has(entity, BitmapText)) {- const bt = world.get(entity, BitmapText);- saved.bitmapText = bt.color.a;- bt.color.a = 0;- world.insert(entity, BitmapText, bt);- hasSaved = true;- }- if (world.has(entity, UIRenderer)) {- const r = world.get(entity, UIRenderer) as UIRendererData;- saved.uiRenderer = r.color.a;- r.color.a = 0;- world.insert(entity, UIRenderer, r);- hasSaved = true;+ world.insert(entity, Disabled, {});+ const entitySaved = new Map<AnyComponentDef, boolean>();+ for (const comp of RENDERABLE_COMPONENTS) {+ if (world.has(entity, comp)) {+ const data = world.get(entity, comp) as { enabled: boolean };+ entitySaved.set(comp, data.enabled);+ if (data.enabled) {+ data.enabled = false;+ world.set(entity, comp, data);+ }+ }}-- if (hasSaved) {- instance.savedAlphas.set(entity, saved);+ if (entitySaved.size > 0) {+ instance.savedEnabled.set(entity, entitySaved);}}}@@ -610,31 +597,18 @@ export class SceneManagerState {const world = this.app_.world;for (const entity of instance.entities) {if (!world.valid(entity)) continue;- const saved = instance.savedAlphas.get(entity);- if (!saved) continue;-- if (saved.sprite !== undefined && world.has(entity, Sprite)) {- const sprite = world.get(entity, Sprite);- sprite.color.a = saved.sprite;- world.insert(entity, Sprite, sprite);- }- if (saved.spine !== undefined && world.has(entity, SpineAnimation)) {- const spine = world.get(entity, SpineAnimation);- spine.color.a = saved.spine;- world.insert(entity, SpineAnimation, spine);- }- if (saved.bitmapText !== undefined && world.has(entity, BitmapText)) {- const bt = world.get(entity, BitmapText);- bt.color.a = saved.bitmapText;- world.insert(entity, BitmapText, bt);- }- if (saved.uiRenderer !== undefined && world.has(entity, UIRenderer)) {- const r = world.get(entity, UIRenderer) as UIRendererData;- r.color.a = saved.uiRenderer;- world.insert(entity, UIRenderer, r);+ world.remove(entity, Disabled);+ const entitySaved = instance.savedEnabled.get(entity);+ if (!entitySaved) continue;+ for (const [comp, wasEnabled] of entitySaved) {+ if (world.has(entity, comp)) {+ const data = world.get(entity, comp) as { enabled: boolean };+ data.enabled = wasEnabled;+ world.set(entity, comp, data);+ }}}- instance.savedAlphas.clear();+ instance.savedEnabled.clear();}private setPostProcessPassesEnabled(instance: SceneInstance, enabled: boolean): void {diff --git a/sdk/src/world.ts b/sdk/src/world.tsindex f8b5d2331..632d95cf1 100644--- a/sdk/src/world.ts+++ b/sdk/src/world.ts@@ -218,6 +218,7 @@ export class World {private despawnCallbacks_: Array<(entity: Entity) => void> = [];private nameIndex_ = new Map<string, Entity>();+ private entityToName_ = new Map<Entity, string>();private worldTick_ = 0;private componentAddedTicks_ = new Map<symbol, Map<Entity, number>>();@@ -710,23 +711,23 @@ export class World {// =========================================================================private updateNameIndex_(entity: Entity, name: string): void {- for (const [n, e] of this.nameIndex_) {- if (e === entity) {- this.nameIndex_.delete(n);- break;- }+ const oldName = this.entityToName_.get(entity);+ if (oldName !== undefined) {+ this.nameIndex_.delete(oldName);}if (name) {this.nameIndex_.set(name, entity);+ this.entityToName_.set(entity, name);+ } else {+ this.entityToName_.delete(entity);}}private removeNameIndex_(entity: Entity): void {- for (const [n, e] of this.nameIndex_) {- if (e === entity) {- this.nameIndex_.delete(n);- break;- }+ const oldName = this.entityToName_.get(entity);+ if (oldName !== undefined) {+ this.nameIndex_.delete(oldName);+ this.entityToName_.delete(entity);}}diff --git a/sdk/tests/sceneManager.test.ts b/sdk/tests/sceneManager.test.tsindex d0b3d1166..a42ea0e53 100644--- a/sdk/tests/sceneManager.test.ts+++ b/sdk/tests/sceneManager.test.ts@@ -43,10 +43,14 @@ vi.mock('../src/resource', () => ({vi.mock('../src/component', () => ({SceneOwner: Symbol('SceneOwner'),+ Disabled: { _id: Symbol('Disabled'), _name: 'Disabled', _builtin: false, _default: {} },Sprite: Symbol('Sprite'),SpineAnimation: Symbol('SpineAnimation'),BitmapText: Symbol('BitmapText'),+ ShapeRenderer: Symbol('ShapeRenderer'),+ ParticleEmitter: Symbol('ParticleEmitter'),defineBuiltin: (name: string, defaults: unknown) => Symbol(name),+ defineTag: (name: string) => ({ _id: Symbol(name), _name: name, _builtin: false, _default: {} }),}));vi.mock('../src/asset/AssetPlugin', () => ({@@ -86,6 +90,13 @@ function createMockApp() {if (!entities.has(e)) entities.set(e, new Map());entities.get(e)!.set(comp, data);}),+ set: vi.fn((e: number, comp: symbol, data: any) => {+ if (!entities.has(e)) entities.set(e, new Map());+ entities.get(e)!.set(comp, data);+ }),+ remove: vi.fn((e: number, comp: symbol) => {+ entities.get(e)?.delete(comp);+ }),};return {@@ -489,13 +500,13 @@ describe('SceneManager', () => {describe('sleep / wake', () => {function setupEntityWithComponents(entityId: number) {const entityComponents = new Map<symbol, any>();- entityComponents.set(Sprite, { color: { r: 1, g: 1, b: 1, a: 0.8 } });- entityComponents.set(SpineAnimation, { color: { r: 1, g: 1, b: 1, a: 0.6 } });- entityComponents.set(BitmapText, { color: { r: 1, g: 1, b: 1, a: 0.9 } });+ entityComponents.set(Sprite, { color: { r: 1, g: 1, b: 1, a: 0.8 }, enabled: true });+ entityComponents.set(SpineAnimation, { color: { r: 1, g: 1, b: 1, a: 0.6 }, enabled: true });+ entityComponents.set(BitmapText, { color: { r: 1, g: 1, b: 1, a: 0.9 }, enabled: true });app._entities.set(entityId, entityComponents);}- it('sleep() sets status=sleeping and saves entity alphas', async () => {+ it('sleep() sets status=sleeping and disables renderable components', async () => {const entityMap = new Map([[100, 1]]);vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);setupEntityWithComponents(1);@@ -507,9 +518,8 @@ describe('SceneManager', () => {expect(manager.getSceneStatus('level1')).toBe('sleeping');expect(manager.isSleeping('level1')).toBe(true);- // Alpha should be set to 0const sprite = app._entities.get(1)!.get(Sprite);- expect(sprite.color.a).toBe(0);+ expect(sprite.enabled).toBe(false);});it('sleep() only on running scenes', async () => {@@ -528,7 +538,7 @@ describe('SceneManager', () => {expect(manager.isSleeping('nonexistent')).toBe(false);});- it('wake() restores alphas from savedAlphas', async () => {+ it('wake() restores enabled state from saved values', async () => {const entityMap = new Map([[100, 1]]);vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);setupEntityWithComponents(1);@@ -543,13 +553,13 @@ describe('SceneManager', () => {expect(manager.isSleeping('level1')).toBe(false);const sprite = app._entities.get(1)!.get(Sprite);- expect(sprite.color.a).toBe(0.8);+ expect(sprite.enabled).toBe(true);const spine = app._entities.get(1)!.get(SpineAnimation);- expect(spine.color.a).toBe(0.6);+ expect(spine.enabled).toBe(true);const bt = app._entities.get(1)!.get(BitmapText);- expect(bt.color.a).toBe(0.9);+ expect(bt.enabled).toBe(true);});it('wake() only on sleeping scenes', async () => {