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: strengthen plugin dependency management with before/after constraints
esengine7d4c3f040d10
diff --git a/sdk/src/app.ts b/sdk/src/app.tsindex 676fa9264..6def35c73 100644--- a/sdk/src/app.ts+++ b/sdk/src/app.ts@@ -31,6 +31,8 @@ export type PluginDependency = string | ResourceDef<any>;export interface Plugin {name?: string;dependencies?: PluginDependency[];+ before?: string[];+ after?: string[];build(app: App): void;finish?(app: App): void;cleanup?(app?: App): void;@@ -555,29 +557,67 @@ export class App {const nameToIndex = new Map<string, number>();for (let i = 0; i < plugins.length; i++) {const name = plugins[i].name;- if (name) nameToIndex.set(name, i);+ if (name) {+ if (nameToIndex.has(name)) {+ console.warn(`[ESEngine] Duplicate plugin name "${name}" at indices ${nameToIndex.get(name)} and ${i}`);+ }+ nameToIndex.set(name, i);+ }+ }++ const edges = new Map<number, Set<number>>();+ for (let i = 0; i < plugins.length; i++) {+ edges.set(i, new Set());+ }++ for (let i = 0; i < plugins.length; i++) {+ const plugin = plugins[i];+ if (plugin.dependencies) {+ for (const dep of plugin.dependencies) {+ if (typeof dep !== 'string') continue;+ const depIndex = nameToIndex.get(dep);+ if (depIndex !== undefined) {+ edges.get(i)!.add(depIndex);+ }+ }+ }+ if (plugin.after) {+ for (const target of plugin.after) {+ const targetIndex = nameToIndex.get(target);+ if (targetIndex !== undefined) {+ edges.get(i)!.add(targetIndex);+ }+ }+ }+ if (plugin.before) {+ for (const target of plugin.before) {+ const targetIndex = nameToIndex.get(target);+ if (targetIndex !== undefined) {+ edges.get(targetIndex)!.add(i);+ }+ }+ }}const sorted: Plugin[] = [];const visited = new Set<number>();const visiting = new Set<number>();+ const path: number[] = [];const visit = (index: number): void => {if (visited.has(index)) return;if (visiting.has(index)) {- throw new Error(`Circular plugin dependency detected involving "${plugins[index].name ?? index}"`);+ const cycleStart = path.indexOf(index);+ const cycle = path.slice(cycleStart).concat(index);+ const names = cycle.map(i => plugins[i].name ?? `<index ${i}>`);+ throw new Error(`Circular plugin dependency: ${names.join(' -> ')}`);}visiting.add(index);- const deps = plugins[index].dependencies;- if (deps) {- for (const dep of deps) {- if (typeof dep !== 'string') continue;- const depIndex = nameToIndex.get(dep);- if (depIndex !== undefined) {- visit(depIndex);- }- }+ path.push(index);+ for (const dep of edges.get(index)!) {+ visit(dep);}+ path.pop();visiting.delete(index);visited.add(index);sorted.push(plugins[index]);diff --git a/sdk/src/systemLabels.ts b/sdk/src/systemLabels.tsindex fe8214457..04d249c41 100644--- a/sdk/src/systemLabels.ts+++ b/sdk/src/systemLabels.ts@@ -6,10 +6,27 @@export const PluginName = {UILayout: 'uiLayout',UIInteraction: 'uiInteraction',+ UIRenderOrder: 'uiRenderOrder',+ UIMask: 'uiMask',CollectionView: 'collectionView',Text: 'text',Image: 'image',Focus: 'focus',+ DataBinding: 'dataBinding',+ ScrollView: 'scrollView',+ Dropdown: 'dropdown',+ ProgressBar: 'progressBar',+ Slider: 'slider',+ Toggle: 'toggle',+ Drag: 'drag',+ SafeArea: 'safeArea',+ TextInput: 'textInput',+ StateMachine: 'stateMachine',+ LayoutGroup: 'layoutGroup',+ FanLayout: 'fanLayout',+ Selectable: 'selectable',+ LinearLayout: 'linearLayout',+ GridLayout: 'gridLayout',} as const;export const SystemLabel = {diff --git a/sdk/src/ui/CollectionViewPlugin.ts b/sdk/src/ui/CollectionViewPlugin.tsindex 38d5dfd22..ef2e3d7f1 100644--- a/sdk/src/ui/CollectionViewPlugin.ts+++ b/sdk/src/ui/CollectionViewPlugin.ts@@ -31,7 +31,7 @@ export function getCollectionState(entity: Entity): CollectionState | null {}export class CollectionViewPlugin implements Plugin {- name = 'collectionView';+ name = PluginName.CollectionView;dependencies = [PluginName.UILayout];private states_: Map<Entity, CollectionState> | null = null;diff --git a/sdk/src/ui/DataBindingPlugin.ts b/sdk/src/ui/DataBindingPlugin.tsindex 8fc2c0506..bc561d626 100644--- a/sdk/src/ui/DataBindingPlugin.ts+++ b/sdk/src/ui/DataBindingPlugin.ts@@ -18,7 +18,7 @@ function getCachedComponentDef(name: string): AnyComponentDef | null {}export class DataBindingPlugin implements Plugin {- name = 'dataBinding';+ name = PluginName.DataBinding;dependencies = [PluginName.Text, PluginName.Image];build(app: App): void {diff --git a/sdk/src/ui/DragPlugin.ts b/sdk/src/ui/DragPlugin.tsindex bda629f92..682466c33 100644--- a/sdk/src/ui/DragPlugin.ts+++ b/sdk/src/ui/DragPlugin.ts@@ -71,7 +71,7 @@ function applyConstraints(}export class DragPlugin implements Plugin {- name = 'drag';+ name = PluginName.Drag;dependencies = [PluginName.UIInteraction];build(app: App): void {diff --git a/sdk/src/ui/DropdownPlugin.ts b/sdk/src/ui/DropdownPlugin.tsindex 1465b08fc..044e23fc3 100644--- a/sdk/src/ui/DropdownPlugin.ts+++ b/sdk/src/ui/DropdownPlugin.ts@@ -32,7 +32,7 @@ interface DropdownState {}export class DropdownPlugin implements Plugin {- name = 'dropdown';+ name = PluginName.Dropdown;dependencies = [PluginName.UIInteraction];private cleanup_: (() => void) | null = null;diff --git a/sdk/src/ui/FanLayoutPlugin.ts b/sdk/src/ui/FanLayoutPlugin.tsindex ad7247f04..2be6bb271 100644--- a/sdk/src/ui/FanLayoutPlugin.ts+++ b/sdk/src/ui/FanLayoutPlugin.ts@@ -1,9 +1,10 @@import type { App, Plugin } from '../app';import { registerComponent } from '../component';import { FanLayout } from './layouts/FanLayout';+import { PluginName } from '../systemLabels';export class FanLayoutPlugin implements Plugin {- name = 'fanLayout';+ name = PluginName.FanLayout;build(_app: App): void {registerComponent('FanLayout', FanLayout);diff --git a/sdk/src/ui/FocusPlugin.ts b/sdk/src/ui/FocusPlugin.tsindex 53bb01235..594756a86 100644--- a/sdk/src/ui/FocusPlugin.ts+++ b/sdk/src/ui/FocusPlugin.ts@@ -16,7 +16,7 @@ import { UIEvents, UIEventQueue } from './UIEvents';import { PluginName } from '../systemLabels';export class FocusPlugin implements Plugin {- name = 'focus';+ name = PluginName.Focus;dependencies = [PluginName.UIInteraction];build(app: App): void {diff --git a/sdk/src/ui/GridLayoutPlugin.ts b/sdk/src/ui/GridLayoutPlugin.tsindex fce28660b..120e040b7 100644--- a/sdk/src/ui/GridLayoutPlugin.ts+++ b/sdk/src/ui/GridLayoutPlugin.ts@@ -1,9 +1,10 @@import type { App, Plugin } from '../app';import { registerComponent } from '../component';import { GridLayout } from './layouts/GridLayout';+import { PluginName } from '../systemLabels';export class GridLayoutPlugin implements Plugin {- name = 'gridLayout';+ name = PluginName.GridLayout;build(_app: App): void {registerComponent('GridLayout', GridLayout);diff --git a/sdk/src/ui/ImagePlugin.ts b/sdk/src/ui/ImagePlugin.tsindex ba5831568..c5dd6daa0 100644--- a/sdk/src/ui/ImagePlugin.ts+++ b/sdk/src/ui/ImagePlugin.ts@@ -12,7 +12,7 @@ import { getEffectiveWidth, getEffectiveHeight, ensureUIRenderer } from './uiHelimport { SystemLabel, PluginName } from '../systemLabels';export class ImagePlugin implements Plugin {- name = 'image';+ name = PluginName.Image;dependencies = [PluginName.UILayout];build(app: App): void {diff --git a/sdk/src/ui/LayoutGroupPlugin.ts b/sdk/src/ui/LayoutGroupPlugin.tsindex a0f4f0b16..9e8960b38 100644--- a/sdk/src/ui/LayoutGroupPlugin.ts+++ b/sdk/src/ui/LayoutGroupPlugin.ts@@ -4,7 +4,7 @@ import { LayoutGroup } from './LayoutGroup';import { PluginName } from '../systemLabels';export class LayoutGroupPlugin implements Plugin {- name = 'layoutGroup';+ name = PluginName.LayoutGroup;dependencies = [PluginName.UILayout];build(_app: App): void {diff --git a/sdk/src/ui/LinearLayoutPlugin.ts b/sdk/src/ui/LinearLayoutPlugin.tsindex e3ac807ba..4d69f4c42 100644--- a/sdk/src/ui/LinearLayoutPlugin.ts+++ b/sdk/src/ui/LinearLayoutPlugin.ts@@ -1,9 +1,10 @@import type { App, Plugin } from '../app';import { registerComponent } from '../component';import { LinearLayout } from './layouts/LinearLayout';+import { PluginName } from '../systemLabels';export class LinearLayoutPlugin implements Plugin {- name = 'linearLayout';+ name = PluginName.LinearLayout;build(_app: App): void {registerComponent('LinearLayout', LinearLayout);diff --git a/sdk/src/ui/ProgressBarPlugin.ts b/sdk/src/ui/ProgressBarPlugin.tsindex 05971297f..b3b36a1cf 100644--- a/sdk/src/ui/ProgressBarPlugin.ts+++ b/sdk/src/ui/ProgressBarPlugin.ts@@ -9,7 +9,7 @@ import { applyDirectionalFill, withChildEntity } from './uiHelpers';import { SystemLabel, PluginName } from '../systemLabels';export class ProgressBarPlugin implements Plugin {- name = 'progressBar';+ name = PluginName.ProgressBar;dependencies = [PluginName.UILayout];build(app: App): void {diff --git a/sdk/src/ui/SafeAreaPlugin.ts b/sdk/src/ui/SafeAreaPlugin.tsindex 2ede16f22..661a2f7f1 100644--- a/sdk/src/ui/SafeAreaPlugin.ts+++ b/sdk/src/ui/SafeAreaPlugin.ts@@ -61,7 +61,7 @@ function getSafeAreaInsets(): SafeAreaInsets {}export class SafeAreaPlugin implements Plugin {- name = 'safeArea';+ name = PluginName.SafeArea;dependencies = [PluginName.UILayout];build(app: App): void {diff --git a/sdk/src/ui/ScrollViewPlugin.ts b/sdk/src/ui/ScrollViewPlugin.tsindex 7397df805..db8f72e42 100644--- a/sdk/src/ui/ScrollViewPlugin.ts+++ b/sdk/src/ui/ScrollViewPlugin.ts@@ -69,7 +69,7 @@ interface ScrollState {}export class ScrollViewPlugin implements Plugin {- name = 'scrollView';+ name = PluginName.ScrollView;dependencies = [PluginName.UILayout];private cleanup_: (() => void) | null = null;diff --git a/sdk/src/ui/SelectablePlugin.ts b/sdk/src/ui/SelectablePlugin.tsindex 60ee15a7c..d0a1894de 100644--- a/sdk/src/ui/SelectablePlugin.ts+++ b/sdk/src/ui/SelectablePlugin.ts@@ -10,7 +10,7 @@ import { UIEvents, UIEventQueue } from './UIEvents';import { PluginName } from '../systemLabels';export class SelectablePlugin implements Plugin {- name = 'selectable';+ name = PluginName.Selectable;dependencies = [PluginName.UIInteraction];build(app: App): void {diff --git a/sdk/src/ui/SliderPlugin.ts b/sdk/src/ui/SliderPlugin.tsindex 52c4870a6..f0de1b6cc 100644--- a/sdk/src/ui/SliderPlugin.ts+++ b/sdk/src/ui/SliderPlugin.ts@@ -80,7 +80,7 @@ function syncHandleRect(}export class SliderPlugin implements Plugin {- name = 'slider';+ name = PluginName.Slider;dependencies = [PluginName.UIInteraction];build(app: App): void {diff --git a/sdk/src/ui/TextInputPlugin.ts b/sdk/src/ui/TextInputPlugin.tsindex 4931fb643..1feb5f633 100644--- a/sdk/src/ui/TextInputPlugin.ts+++ b/sdk/src/ui/TextInputPlugin.ts@@ -20,7 +20,7 @@ import { CURSOR_BLINK_INTERVAL, TEXT_INPUT_LINE_HEIGHT_RATIO } from './uiConstanimport { SystemLabel, PluginName } from '../systemLabels';export class TextInputPlugin implements Plugin {- name = 'textInput';+ name = PluginName.TextInput;dependencies = [PluginName.Focus];private cleanupListeners_: (() => void) | null = null;diff --git a/sdk/src/ui/TextPlugin.ts b/sdk/src/ui/TextPlugin.tsindex 5074a1444..b210a9c6f 100644--- a/sdk/src/ui/TextPlugin.ts+++ b/sdk/src/ui/TextPlugin.ts@@ -13,7 +13,7 @@ import { parseRichText } from './RichTextParser';import { SystemLabel, PluginName } from '../systemLabels';export class TextPlugin implements Plugin {- name = 'text';+ name = PluginName.Text;dependencies = [PluginName.UILayout];build(app: App): void {diff --git a/sdk/src/ui/TogglePlugin.ts b/sdk/src/ui/TogglePlugin.tsindex a95cbd7b0..29b113c7c 100644--- a/sdk/src/ui/TogglePlugin.ts+++ b/sdk/src/ui/TogglePlugin.ts@@ -35,7 +35,7 @@ function setRendererEnabled(world: import('../world').World, entity: Entity, ena}export class TogglePlugin implements Plugin {- name = 'toggle';+ name = PluginName.Toggle;dependencies = [PluginName.UIInteraction];build(app: App): void {diff --git a/sdk/src/ui/UIInteractionPlugin.ts b/sdk/src/ui/UIInteractionPlugin.tsindex 09e3e0424..d9d40b11a 100644--- a/sdk/src/ui/UIInteractionPlugin.ts+++ b/sdk/src/ui/UIInteractionPlugin.ts@@ -50,7 +50,7 @@ function emitWithBubbling(}export class UIInteractionPlugin implements Plugin {- name = 'uiInteraction';+ name = PluginName.UIInteraction;dependencies = [PluginName.UILayout];build(app: App): void {diff --git a/sdk/src/ui/UIMaskPlugin.ts b/sdk/src/ui/UIMaskPlugin.tsindex 8667a6189..e31d803f7 100644--- a/sdk/src/ui/UIMaskPlugin.ts+++ b/sdk/src/ui/UIMaskPlugin.ts@@ -1,9 +1,10 @@import type { App, Plugin } from '../app';import { registerComponent } from '../component';import { UIMask } from './UIMask';+import { PluginName } from '../systemLabels';export class UIMaskPlugin implements Plugin {- name = 'uiMask';+ name = PluginName.UIMask;build(app: App): void {registerComponent('UIMask', UIMask);diff --git a/sdk/src/ui/UIRenderOrderPlugin.ts b/sdk/src/ui/UIRenderOrderPlugin.tsindex c4e96cd51..eb48231bb 100644--- a/sdk/src/ui/UIRenderOrderPlugin.ts+++ b/sdk/src/ui/UIRenderOrderPlugin.ts@@ -4,8 +4,13 @@ import type { ESEngineModule, CppRegistry } from '../wasm';import { PluginName } from '../systemLabels';export class UIRenderOrderPlugin implements Plugin {- name = 'uiRenderOrder';+ name = PluginName.UIRenderOrder;dependencies = [PluginName.UILayout];+ after = [+ PluginName.Text, PluginName.Image, PluginName.UIMask,+ PluginName.UIInteraction, PluginName.ScrollView,+ PluginName.CollectionView, PluginName.LayoutGroup,+ ];build(app: App): void {const world = app.world;diff --git a/sdk/tests/plugin-sort.test.ts b/sdk/tests/plugin-sort.test.tsnew file mode 100644index 000000000..4b4e5a0cc--- /dev/null+++ b/sdk/tests/plugin-sort.test.ts@@ -0,0 +1,110 @@+import { describe, it, expect } from 'vitest';+import { App, type Plugin } from '../src/app';++function makePlugin(name: string, opts?: { dependencies?: string[]; before?: string[]; after?: string[] }): Plugin {+ return {+ name,+ dependencies: opts?.dependencies,+ before: opts?.before,+ after: opts?.after,+ build() {},+ };+}++describe('Plugin dependency sorting', () => {+ it('should sort by dependencies', () => {+ const app = App.new();+ const order: string[] = [];+ const a: Plugin = { name: 'a', build() { order.push('a'); } };+ const b: Plugin = { name: 'b', dependencies: ['a'], build() { order.push('b'); } };+ const c: Plugin = { name: 'c', dependencies: ['b'], build() { order.push('c'); } };++ app.addPlugins([c, a, b]);+ expect(order).toEqual(['a', 'b', 'c']);+ });++ it('should sort by after constraints', () => {+ const app = App.new();+ const order: string[] = [];+ const a: Plugin = { name: 'a', build() { order.push('a'); } };+ const b: Plugin = { name: 'b', after: ['a'], build() { order.push('b'); } };++ app.addPlugins([b, a]);+ expect(order).toEqual(['a', 'b']);+ });++ it('should sort by before constraints', () => {+ const app = App.new();+ const order: string[] = [];+ const a: Plugin = { name: 'a', before: ['b'], build() { order.push('a'); } };+ const b: Plugin = { name: 'b', build() { order.push('b'); } };++ app.addPlugins([b, a]);+ expect(order).toEqual(['a', 'b']);+ });++ it('should combine dependencies, before, and after', () => {+ const app = App.new();+ const order: string[] = [];+ const a: Plugin = { name: 'a', build() { order.push('a'); } };+ const b: Plugin = { name: 'b', dependencies: ['a'], build() { order.push('b'); } };+ const c: Plugin = { name: 'c', after: ['b'], build() { order.push('c'); } };+ const d: Plugin = { name: 'd', before: ['c'], build() { order.push('d'); } };++ app.addPlugins([d, c, b, a]);+ expect(order.indexOf('a')).toBeLessThan(order.indexOf('b'));+ expect(order.indexOf('b')).toBeLessThan(order.indexOf('c'));+ expect(order.indexOf('d')).toBeLessThan(order.indexOf('c'));+ });++ it('should detect circular dependencies', () => {+ const app = App.new();+ const a = makePlugin('a', { dependencies: ['b'] });+ const b = makePlugin('b', { dependencies: ['a'] });++ expect(() => app.addPlugins([a, b])).toThrow(/Circular plugin dependency/);+ });++ it('should include cycle path in error message', () => {+ const app = App.new();+ const a = makePlugin('a', { dependencies: ['c'] });+ const b = makePlugin('b', { dependencies: ['a'] });+ const c = makePlugin('c', { dependencies: ['b'] });++ expect(() => app.addPlugins([a, b, c])).toThrow(/a -> c -> b -> a/);+ });++ it('should detect cycles involving before/after', () => {+ const app = App.new();+ const a = makePlugin('a', { before: ['b'] });+ const b = makePlugin('b', { before: ['a'] });++ expect(() => app.addPlugins([a, b])).toThrow(/Circular plugin dependency/);+ });++ it('should warn on duplicate plugin names', () => {+ const app = App.new();+ const warnings: string[] = [];+ const origWarn = console.warn;+ console.warn = (msg: string) => { warnings.push(msg); };++ try {+ const a1 = makePlugin('a');+ const a2 = makePlugin('a');+ app.addPlugins([a1, a2]);+ expect(warnings.some(w => w.includes('Duplicate plugin name "a"'))).toBe(true);+ } finally {+ console.warn = origWarn;+ }+ });++ it('should ignore before/after referencing unknown plugins', () => {+ const app = App.new();+ const order: string[] = [];+ const a: Plugin = { name: 'a', before: ['nonexistent'], build() { order.push('a'); } };+ const b: Plugin = { name: 'b', after: ['nonexistent'], build() { order.push('b'); } };++ app.addPlugins([a, b]);+ expect(order).toHaveLength(2);+ });+});