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
feat(prefab): add component_replaced override type
esengine83b269ab0507
diff --git a/sdk/src/prefab/override.ts b/sdk/src/prefab/override.tsindex 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.tsindex 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.tsindex 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', {