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.

feat(sdk): extend EditorBridge with entity/component lifecycle callbacks

esengine89adb9ec6a1c
diff --git a/sdk/src/context.ts b/sdk/src/context.ts
index ad2b32105..8977cbb04 100644
--- a/sdk/src/context.ts
+++ b/sdk/src/context.ts
@@ -3,8 +3,38 @@
* @brief Explicit application context replacing globalThis implicit coupling
*/
+/**
+ * Surface the engine exposes to an attached editor host.
+ *
+ * `registerComponent` is called eagerly during `defineComponent` so the
+ * editor knows the full component catalogue. The `on*` callbacks are all
+ * optional — an editor that only needs the catalogue (no live inspector)
+ * can leave them unset and avoid any per-mutation overhead.
+ *
+ * All entity values are the engine's numeric Entity handle. Component
+ * identification is by the string name that was passed to
+ * `registerComponent` / `defineComponent`.
+ */
export interface EditorBridge {
registerComponent(name: string, defaults: Record<string, unknown>, isTag: boolean): void;
+
+ /** Fired after an entity is created (optionally with a Name component). */
+ onEntitySpawned?(entity: number, name?: string): void;
+
+ /** Fired just before an entity is destroyed. Components are still attached. */
+ onEntityDespawned?(entity: number): void;
+
+ /** Fired when a component is first attached to an entity. */
+ onComponentAdded?(entity: number, component: string): void;
+
+ /** Fired when a component is detached from an entity. */
+ onComponentRemoved?(entity: number, component: string): void;
+
+ /** Fired when component data changes (insert with new data, set, or edit). */
+ onComponentChanged?(entity: number, component: string): void;
+
+ /** Fired when a parent link changes. `parent === null` means the entity was unparented. */
+ onParentChanged?(child: number, parent: number | null): void;
}
export interface PendingSystemEntry {
diff --git a/sdk/src/world.ts b/sdk/src/world.ts
index 2933e3000..36d8129a9 100644
--- a/sdk/src/world.ts
+++ b/sdk/src/world.ts
@@ -13,6 +13,26 @@ import { NameIndex } from './ecs/NameIndex';
import { ChangeTracker } from './ecs/ChangeTracker';
import { QueryCache, type QueryCacheStats } from './ecs/QueryCache';
import { log } from './logger';
+import { getDefaultContext, type EditorBridge } from './context';
+
+function editorBridge(): EditorBridge | null {
+ return getDefaultContext().editorBridge;
+}
+
+function notifyBridge<K extends keyof EditorBridge>(
+ method: K,
+ ...args: Parameters<NonNullable<EditorBridge[K]>>
+): void {
+ const bridge = editorBridge();
+ if (!bridge) return;
+ const fn = bridge[method] as ((...a: unknown[]) => void) | undefined;
+ if (typeof fn !== 'function') return;
+ try {
+ fn.apply(bridge, args as unknown[]);
+ } catch (e) {
+ log.warn('world', `EditorBridge.${String(method)} threw`, e);
+ }
+}
export { PTR_LAYOUTS } from './ptrLayouts.generated';
export { BuiltinBridge } from './ecs/BuiltinBridge';
@@ -174,6 +194,8 @@ export class World {
try { cb(entity); } catch (e) { log.warn('world', 'Spawn callback error', e); }
}
+ notifyBridge('onEntitySpawned', entity, name);
+
return entity;
}
@@ -185,6 +207,8 @@ export class World {
);
}
+ notifyBridge('onEntityDespawned', entity);
+
for (const cb of this.despawnCallbacks_) {
try { cb(entity); } catch (e) { log.warn('world', 'Despawn callback error', e); }
}
@@ -295,6 +319,7 @@ export class World {
}
}
this.queries_.markStructuralChange();
+ notifyBridge('onParentChanged', child, parent);
}
removeParent(entity: Entity): void {
@@ -307,6 +332,7 @@ export class World {
}
}
this.queries_.markStructuralChange();
+ notifyBridge('onParentChanged', entity, null);
}
// =========================================================================
@@ -342,6 +368,7 @@ export class World {
}
}
this.changes_.recordChanged(component, entity);
+ notifyBridge('onComponentChanged', entity, component._name);
return;
}
this.scripts_.set(entity, component as ComponentDef<any>, data);
@@ -349,6 +376,7 @@ export class World {
if ((component as ComponentDef<any>)._id === Name._id) {
this.names_.update(entity, (data as { value: string }).value);
}
+ notifyBridge('onComponentChanged', entity, component._name);
}
get<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C> {
@@ -405,6 +433,7 @@ export class World {
this.changes_.recordRemoved(component, entity);
this.queries_.markComponentDirty(component._id);
this.queries_.markStructuralChange();
+ notifyBridge('onComponentRemoved', entity, component._name);
} else {
this.removeScript_(entity, component as ComponentDef<any>);
}
@@ -420,8 +449,10 @@ export class World {
this.queries_.markComponentDirty(component._id);
this.queries_.markStructuralChange();
this.changes_.recordAdded(component, entity);
+ notifyBridge('onComponentAdded', entity, component._name);
}
this.changes_.recordChanged(component, entity);
+ notifyBridge('onComponentChanged', entity, component._name);
return merged;
}
@@ -435,11 +466,13 @@ export class World {
this.queries_.markComponentDirty(component._id);
this.queries_.markStructuralChange();
this.changes_.recordAdded(component, entity);
+ notifyBridge('onComponentAdded', entity, component._name);
}
this.changes_.recordChanged(component, entity);
if (component._id === Name._id) {
this.names_.update(entity, (value as { value: string }).value);
}
+ notifyBridge('onComponentChanged', entity, component._name);
return value;
}
@@ -451,6 +484,7 @@ export class World {
this.changes_.recordRemoved(component, entity);
this.queries_.markComponentDirty(component._id);
this.queries_.markStructuralChange();
+ notifyBridge('onComponentRemoved', entity, component._name);
}
// =========================================================================