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: strengthen plugin dependency management with before/after constraints

esengine7d4c3f040d10
diff --git a/sdk/src/app.ts b/sdk/src/app.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index ba5831568..c5dd6daa0 100644
--- a/sdk/src/ui/ImagePlugin.ts
+++ b/sdk/src/ui/ImagePlugin.ts
@@ -12,7 +12,7 @@ import { getEffectiveWidth, getEffectiveHeight, ensureUIRenderer } from './uiHel
import { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 './uiConstan
import { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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);
+ });
+});