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(prefab): add component_replaced override type

esengine83b269ab0507
diff --git a/sdk/src/prefab/override.ts b/sdk/src/prefab/override.ts
index 4df98a27d..7703ad885 100644
--- a/sdk/src/prefab/override.ts
+++ b/sdk/src/prefab/override.ts
@@ -37,6 +37,20 @@ export function applyOverrides(entity: ProcessedEntity, overrides: PrefabOverrid
}
}
break;
+ case 'component_replaced':
+ if (override.componentData) {
+ const type = override.componentData.type;
+ const existing = entity.components.find(c => c.type === type);
+ if (existing) {
+ existing.data = cloneComponentData(override.componentData.data);
+ } else {
+ entity.components.push({
+ type,
+ data: cloneComponentData(override.componentData.data),
+ });
+ }
+ }
+ break;
case 'component_removed':
if (override.componentType) {
entity.components = entity.components.filter(
diff --git a/sdk/src/prefab/types.ts b/sdk/src/prefab/types.ts
index 33fff9336..987cd10ad 100644
--- a/sdk/src/prefab/types.ts
+++ b/sdk/src/prefab/types.ts
@@ -27,9 +27,33 @@ export interface NestedPrefabRef {
overrides: PrefabOverride[];
}
+/**
+ * Override types applied to an entity in an instantiated prefab.
+ *
+ * - `property` — patch one field of one component.
+ * Requires: componentType, propertyName, value.
+ * - `name` — change the entity's name. Requires: value (string).
+ * - `visibility` — change the entity's visibility. Requires: value (boolean).
+ * - `component_added` — add a component **only if not already present**
+ * (idempotent insert). Requires: componentData.
+ * Use this for variants that want to *augment* the
+ * base without silently stomping existing data.
+ * - `component_replaced`— upsert: replace the component's data if the
+ * component already exists, or insert it if not.
+ * Requires: componentData. Use this when you
+ * explicitly want to override the base's copy.
+ * - `component_removed` — delete the component if present.
+ * Requires: componentType.
+ */
export interface PrefabOverride {
prefabEntityId: number;
- type: 'property' | 'component_added' | 'component_removed' | 'name' | 'visibility';
+ type:
+ | 'property'
+ | 'component_added'
+ | 'component_replaced'
+ | 'component_removed'
+ | 'name'
+ | 'visibility';
componentType?: string;
propertyName?: string;
value?: unknown;
diff --git a/sdk/tests/prefab.test.ts b/sdk/tests/prefab.test.ts
index d6f9aaa54..66325a86f 100644
--- a/sdk/tests/prefab.test.ts
+++ b/sdk/tests/prefab.test.ts
@@ -386,6 +386,99 @@ describe('Prefab', () => {
});
});
+ describe('component_replaced overrides', () => {
+ it('replaces the component data when the component exists', async () => {
+ const prefab = simplePrefab();
+ const overrides: PrefabOverride[] = [{
+ prefabEntityId: 1,
+ type: 'component_replaced',
+ componentData: { type: 'Sprite', data: { texture: 'replaced.png', color: 'blue' } },
+ }];
+
+ await instantiatePrefab(world, prefab, { overrides });
+
+ const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
+ const sprites = child.components.filter(c => c.type === 'Sprite');
+ expect(sprites).toHaveLength(1);
+ expect(sprites[0].data.texture).toBe('replaced.png');
+ expect(sprites[0].data.color).toBe('blue');
+ });
+
+ it('inserts the component when it does not already exist (upsert)', async () => {
+ const prefab = simplePrefab();
+ const overrides: PrefabOverride[] = [{
+ prefabEntityId: 1,
+ type: 'component_replaced',
+ componentData: { type: 'Health', data: { value: 75 } },
+ }];
+
+ await instantiatePrefab(world, prefab, { overrides });
+
+ const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
+ const health = child.components.find(c => c.type === 'Health')!;
+ expect(health).toBeDefined();
+ expect(health.data.value).toBe(75);
+ });
+
+ it('deep clones the replacement data', async () => {
+ const componentData = { type: 'Sprite', data: { texture: 'other.png', color: 'green' } };
+ const overrides: PrefabOverride[] = [{
+ prefabEntityId: 1,
+ type: 'component_replaced',
+ componentData,
+ }];
+
+ await instantiatePrefab(world, simplePrefab(), { overrides });
+
+ const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
+ const sprite = child.components.find(c => c.type === 'Sprite')!;
+ sprite.data.texture = 'mutated.png';
+ expect(componentData.data.texture).toBe('other.png');
+ });
+
+ it('ignores component_replaced without componentData', async () => {
+ const prefab = simplePrefab();
+ const overrides: PrefabOverride[] = [{
+ prefabEntityId: 1,
+ type: 'component_replaced',
+ }];
+
+ await instantiatePrefab(world, prefab, { overrides });
+
+ const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
+ expect(child.components).toHaveLength(1);
+ expect(child.components[0].data.texture).toBe('test.png');
+ });
+
+ it('distinguishes component_replaced from component_added (the latter keeps existing)', async () => {
+ const prefab = simplePrefab();
+
+ // Added — idempotent; existing Sprite stays as 'test.png'.
+ await instantiatePrefab(world, prefab, {
+ overrides: [{
+ prefabEntityId: 1,
+ type: 'component_added',
+ componentData: { type: 'Sprite', data: { texture: 'A.png' } },
+ }],
+ });
+ let child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
+ expect(child.components.find(c => c.type === 'Sprite')!.data.texture).toBe('test.png');
+
+ capturedSceneData = null;
+
+ // Replaced — upserts; Sprite is now 'B.png'.
+ await instantiatePrefab(world, prefab, {
+ overrides: [{
+ prefabEntityId: 1,
+ type: 'component_replaced',
+ componentData: { type: 'Sprite', data: { texture: 'B.png' } },
+ }],
+ });
+ child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
+ expect(child.components.find(c => c.type === 'Sprite')!.data.texture).toBe('B.png');
+ });
+ });
+
describe('entity reference remapping', () => {
beforeEach(() => {
defineComponent('Slider', {