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.

refactor: SDK architecture cleanup — Disabled tag, runFrame extraction, nameIndex optimization

esengineb30f30400a19
diff --git a/sdk/src/app.ts b/sdk/src/app.ts
index 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.ts
index 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>('ParticleEmitt
metaDefaults<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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 0
const 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 () => {