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.

51.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, vi, beforeEach } from 'vitest';
import type { PrefabData, PrefabOverride, InstantiatePrefabOptions } from '../src/prefab';
import { SCENE_FORMAT_VERSION, type SceneData } from '../src/scene/scene';
import type { World } from '../src/ecs/world';
import type { Entity } from '../src/types';

vi.mock('../src/scene/scene', async (importOriginal) => {
    const actual = await importOriginal<typeof import('../src/scene/scene')>();
    return {
        ...actual,
        loadOwnedSceneWithAssets: vi.fn(),
    };
});

import { instantiatePrefab } from '../src/prefab';
import { loadOwnedSceneWithAssets } from '../src/scene/scene';
import { defineComponent } from '../src/ecs/component';

const mockLoadScene = vi.mocked(loadOwnedSceneWithAssets);

function withAssetLeases<T extends { loadPrefab: (path: string) => Promise<{ data: PrefabData }> }>(assets: T): T {
    Object.assign(assets, { acquireTyped: async (_type: string, path: string) => ({
        value: await assets.loadPrefab(path), release: vi.fn(),
    }) });
    return assets;
}

function createMockWorld(): World {
    const parentMap = new Map<Entity, Entity>();
    const setParent = vi.fn((child: Entity, parent: Entity) => {
        parentMap.set(child, parent);
    });
    return {
        spawn: vi.fn(() => 0 as Entity),
        setParent,
        trySetParent: vi.fn((child: Entity, parent: Entity) => { setParent(child, parent); return true; }),
        insert: vi.fn(),
        get: vi.fn(),
    } as unknown as World;
}

function simplePrefab(overrides?: Partial<PrefabData>): PrefabData {
    return {
        version: '1.0',
        name: 'TestPrefab',
        rootEntityId: '0',
        entities: [
            {
                prefabEntityId: '0',
                name: 'Root',
                parent: null,
                children: [ '1'],
                components: [
                    { type: 'Transform', data: { x: 0, y: 0 } },
                ],
                visible: true,
            },
            {
                prefabEntityId: '1',
                name: 'Child',
                parent: '0',
                children: [],
                components: [
                    { type: 'Sprite', data: { texture: 'test.png', color: 'red' } },
                ],
                visible: true,
            },
        ],
        ...overrides,
    };
}

describe('Prefab', () => {
    let world: World;
    let capturedSceneData: SceneData | null;

    beforeEach(() => {
        vi.clearAllMocks();
        world = createMockWorld();
        capturedSceneData = null;

        mockLoadScene.mockImplementation(async (_world, sceneData) => {
            capturedSceneData = sceneData;
            const entityMap = new Map<number, Entity>();
            for (const e of sceneData.entities) {
                entityMap.set(e.id, (e.id + 100) as Entity);
            }
            return entityMap;
        });
    });

    describe('instantiatePrefab - flat prefab', () => {
        it('should produce correct SceneData from a flat prefab', async () => {
            const prefab = simplePrefab();
            await instantiatePrefab(world, prefab);

            expect(capturedSceneData).not.toBeNull();
            expect(capturedSceneData!.version).toBe(SCENE_FORMAT_VERSION);
            expect(capturedSceneData!.name).toBe('TestPrefab');
            expect(capturedSceneData!.entities).toHaveLength(2);
        });

        it('should assign unique sequential IDs', async () => {
            const prefab = simplePrefab();
            await instantiatePrefab(world, prefab);

            const ids = capturedSceneData!.entities.map(e => e.id);
            const uniqueIds = new Set(ids);
            expect(uniqueIds.size).toBe(ids.length);
        });

        it('should preserve parent-child relationships', async () => {
            const prefab = simplePrefab();
            await instantiatePrefab(world, prefab);

            const root = capturedSceneData!.entities.find(e => e.name === 'Root')!;
            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(root.parent).toBeNull();
            expect(child.parent).toBe(root.id);
        });

        it('should set root parent to null even if prefab has parent value', async () => {
            const prefab = simplePrefab();
            await instantiatePrefab(world, prefab);

            const root = capturedSceneData!.entities.find(e => e.name === 'Root')!;
            expect(root.parent).toBeNull();
        });

        it('should deep clone component data', async () => {
            const prefab = simplePrefab();
            await instantiatePrefab(world, prefab);

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            child.components[0].data.texture = 'modified.png';
            expect(prefab.entities[1].components[0].data.texture).toBe('test.png');
        });

        it('should return root entity and entity map', async () => {
            const prefab = simplePrefab();
            const result = await instantiatePrefab(world, prefab);

            const rootId = capturedSceneData!.entities.find(e => e.name === 'Root')!.id;
            expect(result.root).toBe(rootId + 100);
            expect(result.entities.size).toBe(2);
        });

        it('should reject prefab whose children array references a missing entity', async () => {
            const prefab = simplePrefab();
            (prefab.entities[0] as { children: string[] }).children = ['1', '999'];
            // Strict: authoring a phantom child id is a structural corruption
            // we surface early instead of silently filtering.
            await expect(instantiatePrefab(world, prefab)).rejects.toThrow(
                /lists child "999" which does not exist/,
            );
        });

        it('should pass assets and assetBaseUrl to loadSceneWithAssets', async () => {
            const prefab = simplePrefab();
            const mockAssets = { loadPrefab: vi.fn() } as any;
            await instantiatePrefab(world, prefab, {
                assets: withAssetLeases(mockAssets),
                assetBaseUrl: '/assets',
            });

            expect(mockLoadScene).toHaveBeenCalledWith(
                world,
                expect.any(Object),
                { assets: withAssetLeases(mockAssets), assetBaseUrl: '/assets' },
            );
        });
    });

    describe('instantiatePrefab - parent option', () => {
        it('should call setParent when parent option is provided', async () => {
            const prefab = simplePrefab();
            const parentEntity = 42 as Entity;

            await instantiatePrefab(world, prefab, { parent: parentEntity });

            const rootId = capturedSceneData!.entities.find(e => e.name === 'Root')!.id;
            expect(world.setParent).toHaveBeenCalledWith(rootId + 100, parentEntity);
        });

        it('should not call setParent when parent option is not provided', async () => {
            const prefab = simplePrefab();
            await instantiatePrefab(world, prefab);

            expect(world.setParent).not.toHaveBeenCalled();
        });
    });

    describe('property overrides', () => {
        it('should apply property override to matching component', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'property',
                componentType: 'Sprite',
                propertyName: 'color',
                value: 'blue',
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            const sprite = child.components.find(c => c.type === 'Sprite')!;
            expect(sprite.data.color).toBe('blue');
        });

        it('should not modify non-matching entity', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '0',
                type: 'property',
                componentType: 'Transform',
                propertyName: 'x',
                value: 99,
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            const sprite = child.components.find(c => c.type === 'Sprite')!;
            expect(sprite.data.color).toBe('red');
        });

        it('should ignore property override for non-existing component', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'property',
                componentType: 'NonExistent',
                propertyName: 'x',
                value: 42,
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(child.components).toHaveLength(1);
            expect(child.components[0].type).toBe('Sprite');
        });
    });

    describe('name overrides', () => {
        it('should apply name override', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'name',
                value: 'RenamedChild',
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'RenamedChild')!;
            expect(child).toBeDefined();
        });

        it('should ignore name override with non-string value', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'name',
                value: 42,
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(child).toBeDefined();
        });
    });

    describe('visibility overrides', () => {
        it('should apply visibility override', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'visibility',
                value: false,
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(child.visible).toBe(false);
        });

        it('should ignore visibility override with non-boolean value', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'visibility',
                value: 'false',
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(child.visible).toBe(true);
        });
    });

    describe('component_added overrides', () => {
        it('should add a new component via override', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'component_added',
                componentData: { type: 'Health', data: { value: 50 } },
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(child.components).toHaveLength(2);
            const health = child.components.find(c => c.type === 'Health')!;
            expect(health.data.value).toBe(50);
        });

        it('should not add duplicate component', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'component_added',
                componentData: { type: 'Sprite', data: { texture: 'new.png' } },
            }];

            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('test.png');
        });

        it('should deep clone component_added data', async () => {
            const componentData = { type: 'Health', data: { value: 50 } };
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'component_added',
                componentData,
            }];

            await instantiatePrefab(world, simplePrefab(), { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            const health = child.components.find(c => c.type === 'Health')!;
            health.data.value = 999;
            expect(componentData.data.value).toBe(50);
        });

        it('should ignore component_added without componentData', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'component_added',
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(child.components).toHaveLength(1);
        });
    });

    describe('component_removed overrides', () => {
        it('should remove a component via override', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'component_removed',
                componentType: 'Sprite',
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(child.components).toHaveLength(0);
        });

        it('should ignore removal of non-existing component', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [{
                prefabEntityId: '1',
                type: 'component_removed',
                componentType: 'NonExistent',
            }];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(child.components).toHaveLength(1);
        });
    });

    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', {
                fillEntity: 0,
                handleEntity: 0,
                value: 0,
            }, { entityFields: ['fillEntity', 'handleEntity'] });
        });

        it('should remap entity references in components', async () => {
            const prefab: PrefabData = {
                version: '1.0',
                name: 'SliderPrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'SliderRoot',
                        parent: null,
                        children: [ '1', '2'],
                        components: [
                            { type: 'Slider', data: { fillEntity: 1, handleEntity: 2, value: 0.5 } },
                        ],
                        visible: true,
                    },
                    {
                        prefabEntityId: '1',
                        name: 'Fill',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                    },
                    {
                        prefabEntityId: '2',
                        name: 'Handle',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                    },
                ],
            };

            await instantiatePrefab(world, prefab);

            const root = capturedSceneData!.entities.find(e => e.name === 'SliderRoot')!;
            const fill = capturedSceneData!.entities.find(e => e.name === 'Fill')!;
            const handle = capturedSceneData!.entities.find(e => e.name === 'Handle')!;
            const slider = root.components.find(c => c.type === 'Slider')!;
            expect(slider.data.fillEntity).toBe(fill.id);
            expect(slider.data.handleEntity).toBe(handle.id);
            expect(slider.data.value).toBe(0.5);
        });

        it('should not remap zero entity references', async () => {
            const prefab: PrefabData = {
                version: '1.0',
                name: 'SliderPrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'SliderRoot',
                        parent: null,
                        children: [],
                        components: [
                            { type: 'Slider', data: { fillEntity: 0, handleEntity: 0, value: 0 } },
                        ],
                        visible: true,
                    },
                ],
            };

            await instantiatePrefab(world, prefab);

            const root = capturedSceneData!.entities.find(e => e.name === 'SliderRoot')!;
            const slider = root.components.find(c => c.type === 'Slider')!;
            expect(slider.data.fillEntity).toBe(0);
            expect(slider.data.handleEntity).toBe(0);
        });

        it('should skip components without entity fields', async () => {
            const prefab: PrefabData = {
                version: '1.0',
                name: 'Test',
                rootEntityId: '0',
                entities: [{
                    prefabEntityId: '0',
                    name: 'Root',
                    parent: null,
                    children: [],
                    components: [
                        { type: 'Transform', data: { x: 10, y: 20 } },
                    ],
                    visible: true,
                }],
            };

            await instantiatePrefab(world, prefab);

            const root = capturedSceneData!.entities.find(e => e.name === 'Root')!;
            expect(root.components[0].data.x).toBe(10);
        });

        it('remaps entity fields in a component_added override', async () => {
            // Override adds a Slider pointing at prefab-entity-ids 1 and 2.
            // Expect those to become the allocated entity ids after flatten.
            const prefab: PrefabData = {
                version: '1.0',
                name: 'SliderPrefab',
                rootEntityId: '0',
                entities: [
                    { prefabEntityId: '0', name: 'Root',   parent: null, children: [ '1', '2'], components: [], visible: true },
                    { prefabEntityId: '1', name: 'Fill',   parent: '0',    children: [],     components: [], visible: true },
                    { prefabEntityId: '2', name: 'Handle', parent: '0',    children: [],     components: [], visible: true },
                ],
            };

            await instantiatePrefab(world, prefab, {
                overrides: [{
                    prefabEntityId: '0',
                    type: 'component_added',
                    componentData: {
                        type: 'Slider',
                        data: { fillEntity: 1, handleEntity: 2, value: 0.25 },
                    },
                }],
            });

            const root = capturedSceneData!.entities.find(e => e.name === 'Root')!;
            const fill = capturedSceneData!.entities.find(e => e.name === 'Fill')!;
            const handle = capturedSceneData!.entities.find(e => e.name === 'Handle')!;
            const slider = root.components.find(c => c.type === 'Slider')!;
            expect(slider.data.fillEntity).toBe(fill.id);
            expect(slider.data.handleEntity).toBe(handle.id);
            expect(slider.data.value).toBe(0.25);
        });

        it('remaps entity fields in a component_replaced override', async () => {
            const prefab: PrefabData = {
                version: '1.0',
                name: 'SliderPrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'Root',
                        parent: null,
                        children: [ '1', '2'],
                        components: [{ type: 'Slider', data: { fillEntity: 0, handleEntity: 0, value: 0 } }],
                        visible: true,
                    },
                    { prefabEntityId: '1', name: 'Fill',   parent: '0', children: [], components: [], visible: true },
                    { prefabEntityId: '2', name: 'Handle', parent: '0', children: [], components: [], visible: true },
                ],
            };

            await instantiatePrefab(world, prefab, {
                overrides: [{
                    prefabEntityId: '0',
                    type: 'component_replaced',
                    componentData: {
                        type: 'Slider',
                        data: { fillEntity: 1, handleEntity: 2, value: 1 },
                    },
                }],
            });

            const root = capturedSceneData!.entities.find(e => e.name === 'Root')!;
            const fill = capturedSceneData!.entities.find(e => e.name === 'Fill')!;
            const handle = capturedSceneData!.entities.find(e => e.name === 'Handle')!;
            const slider = root.components.find(c => c.type === 'Slider')!;
            expect(slider.data.fillEntity).toBe(fill.id);
            expect(slider.data.handleEntity).toBe(handle.id);
        });

        it('remaps an entity field set by a property override', async () => {
            const prefab: PrefabData = {
                version: '1.0',
                name: 'SliderPrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'Root',
                        parent: null,
                        children: [ '1'],
                        components: [{ type: 'Slider', data: { fillEntity: 0, handleEntity: 0, value: 0 } }],
                        visible: true,
                    },
                    { prefabEntityId: '1', name: 'Fill', parent: '0', children: [], components: [], visible: true },
                ],
            };

            await instantiatePrefab(world, prefab, {
                overrides: [{
                    prefabEntityId: '0',
                    type: 'property',
                    componentType: 'Slider',
                    propertyName: 'fillEntity',
                    value: 1,
                }],
            });

            const root = capturedSceneData!.entities.find(e => e.name === 'Root')!;
            const fill = capturedSceneData!.entities.find(e => e.name === 'Fill')!;
            const slider = root.components.find(c => c.type === 'Slider')!;
            expect(slider.data.fillEntity).toBe(fill.id);
        });
    });

    describe('nested prefabs', () => {
        it('should flatten nested prefab entities into parent', async () => {
            const childPrefab: PrefabData = {
                version: '1.0',
                name: 'ChildPrefab',
                rootEntityId: '0',
                entities: [{
                    prefabEntityId: '0',
                    name: 'NestedRoot',
                    parent: null,
                    children: [],
                    components: [{ type: 'Transform', data: { x: 5 } }],
                    visible: true,
                }],
            };

            const parentPrefab: PrefabData = {
                version: '1.0',
                name: 'ParentPrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'ParentRoot',
                        parent: null,
                        children: [ '1'],
                        components: [{ type: 'Transform', data: { x: 0 } }],
                        visible: true,
                    },
                    {
                        prefabEntityId: '1',
                        name: 'NestedSlot',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                        nestedPrefab: {
                            prefabPath: 'child.prefab',
                            overrides: [],
                        },
                    },
                ],
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
            } as any;

            await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });

            expect(capturedSceneData!.entities).toHaveLength(2);
            const names = capturedSceneData!.entities.map(e => e.name);
            expect(names).toContain('ParentRoot');
            expect(names).toContain('NestedRoot');
        });

        it('should remap nested prefab entity IDs to avoid collisions', async () => {
            const childPrefab: PrefabData = {
                version: '1.0',
                name: 'ChildPrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'NestedRoot',
                        parent: null,
                        children: [ '1'],
                        components: [],
                        visible: true,
                    },
                    {
                        prefabEntityId: '1',
                        name: 'NestedChild',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                    },
                ],
            };

            const parentPrefab: PrefabData = {
                version: '1.0',
                name: 'ParentPrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'ParentRoot',
                        parent: null,
                        children: [ '1'],
                        components: [],
                        visible: true,
                    },
                    {
                        prefabEntityId: '1',
                        name: 'NestedSlot',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                        nestedPrefab: {
                            prefabPath: 'child.prefab',
                            overrides: [],
                        },
                    },
                ],
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
            } as any;

            await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });

            const ids = capturedSceneData!.entities.map(e => e.id);
            const uniqueIds = new Set(ids);
            expect(uniqueIds.size).toBe(ids.length);
        });

        it('should set nested root parent to slot parent', async () => {
            const childPrefab: PrefabData = {
                version: '1.0',
                name: 'ChildPrefab',
                rootEntityId: '0',
                entities: [{
                    prefabEntityId: '0',
                    name: 'NestedRoot',
                    parent: null,
                    children: [],
                    components: [],
                    visible: true,
                }],
            };

            const parentPrefab: PrefabData = {
                version: '1.0',
                name: 'ParentPrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'ParentRoot',
                        parent: null,
                        children: [ '1'],
                        components: [],
                        visible: true,
                    },
                    {
                        prefabEntityId: '1',
                        name: 'NestedSlot',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                        nestedPrefab: {
                            prefabPath: 'child.prefab',
                            overrides: [],
                        },
                    },
                ],
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
            } as any;

            await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });

            const parentRoot = capturedSceneData!.entities.find(e => e.name === 'ParentRoot')!;
            const nestedRoot = capturedSceneData!.entities.find(e => e.name === 'NestedRoot')!;
            expect(nestedRoot.parent).toBe(parentRoot.id);
        });

        it('should apply overrides to nested prefab entities', async () => {
            const childPrefab: PrefabData = {
                version: '1.0',
                name: 'ChildPrefab',
                rootEntityId: '0',
                entities: [{
                    prefabEntityId: '0',
                    name: 'NestedRoot',
                    parent: null,
                    children: [],
                    components: [{ type: 'Sprite', data: { color: 'red' } }],
                    visible: true,
                }],
            };

            const parentPrefab: PrefabData = {
                version: '1.0',
                name: 'ParentPrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'ParentRoot',
                        parent: null,
                        children: [ '1'],
                        components: [],
                        visible: true,
                    },
                    {
                        prefabEntityId: '1',
                        name: 'NestedSlot',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                        nestedPrefab: {
                            prefabPath: 'child.prefab',
                            overrides: [{
                                prefabEntityId: '0',
                                type: 'property',
                                componentType: 'Sprite',
                                propertyName: 'color',
                                value: 'green',
                            }],
                        },
                    },
                ],
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
            } as any;

            await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });

            const nestedRoot = capturedSceneData!.entities.find(e => e.name === 'NestedRoot')!;
            const sprite = nestedRoot.components.find(c => c.type === 'Sprite')!;
            expect(sprite.data.color).toBe('green');
        });

        it('should detect circular reference', async () => {
            const selfRefPrefab: PrefabData = {
                version: '1.0',
                name: 'SelfRef',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'Root',
                        parent: null,
                        children: [ '1'],
                        components: [],
                        visible: true,
                    },
                    {
                        prefabEntityId: '1',
                        name: 'Nested',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                        nestedPrefab: {
                            prefabPath: 'self.prefab',
                            overrides: [],
                        },
                    },
                ],
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: selfRefPrefab }),
            } as any;

            await expect(
                instantiatePrefab(world, selfRefPrefab, { assets: withAssetLeases(mockAssetServer) }),
            ).rejects.toThrow('Circular reference detected');
        });

        it('should throw when nesting depth exceeds maximum', async () => {
            const deepPrefab: PrefabData = {
                version: '1.0',
                name: 'Deep',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'Root',
                        parent: null,
                        children: [ '1'],
                        components: [],
                        visible: true,
                    },
                    {
                        prefabEntityId: '1',
                        name: 'Nested',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                        nestedPrefab: {
                            prefabPath: 'deep.prefab',
                            overrides: [],
                        },
                    },
                ],
            };

            let callCount = 0;
            const mockAssetServer = {
                loadPrefab: vi.fn().mockImplementation(() => {
                    callCount++;
                    return Promise.resolve({ data: {
                        ...deepPrefab,
                        name: `Deep_${callCount}`,
                        entities: deepPrefab.entities.map(e => ({
                            ...e,
                            nestedPrefab: e.nestedPrefab
                                ? { ...e.nestedPrefab, prefabPath: `deep_${callCount}.prefab` }
                                : undefined,
                        })),
                    }});
                }),
            } as any;

            await expect(
                instantiatePrefab(world, deepPrefab, { assets: withAssetLeases(mockAssetServer) }),
            ).rejects.toThrow('nesting depth exceeded');
        });

        it('should throw when nested prefab cannot be loaded', async () => {
            const parentPrefab: PrefabData = {
                version: '1.0',
                name: 'Parent',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'Root',
                        parent: null,
                        children: [ '1'],
                        components: [],
                        visible: true,
                    },
                    {
                        prefabEntityId: '1',
                        name: 'Nested',
                        parent: '0',
                        children: [],
                        components: [],
                        visible: true,
                        nestedPrefab: {
                            prefabPath: 'child.prefab',
                            overrides: [],
                        },
                    },
                ],
            };

            await expect(
                instantiatePrefab(world, parentPrefab),
            ).rejects.toThrow('Failed to load nested prefab');
        });
    });

    describe('multiple overrides on same entity', () => {
        it('should apply multiple override types together', async () => {
            const prefab = simplePrefab();
            const overrides: PrefabOverride[] = [
                {
                    prefabEntityId: '1',
                    type: 'name',
                    value: 'RenamedChild',
                },
                {
                    prefabEntityId: '1',
                    type: 'property',
                    componentType: 'Sprite',
                    propertyName: 'color',
                    value: 'blue',
                },
                {
                    prefabEntityId: '1',
                    type: 'component_added',
                    componentData: { type: 'Health', data: { value: 100 } },
                },
            ];

            await instantiatePrefab(world, prefab, { overrides });

            const child = capturedSceneData!.entities.find(e => e.name === 'RenamedChild')!;
            expect(child).toBeDefined();
            expect(child.components.find(c => c.type === 'Sprite')!.data.color).toBe('blue');
            expect(child.components.find(c => c.type === 'Health')!.data.value).toBe(100);
        });
    });

    describe('nested prefab edge cases', () => {
        it('should set nested root parent to null when slot has null parent', async () => {
            const childPrefab: PrefabData = {
                version: '1.0',
                name: 'ChildPrefab',
                rootEntityId: '0',
                entities: [{
                    prefabEntityId: '0',
                    name: 'NestedRoot',
                    parent: null,
                    children: [],
                    components: [],
                    visible: true,
                }],
            };

            const parentPrefab: PrefabData = {
                version: '1.0',
                name: 'ParentPrefab',
                rootEntityId: '0',
                entities: [{
                    prefabEntityId: '0',
                    name: 'Slot',
                    parent: null,
                    children: [],
                    components: [],
                    visible: true,
                    nestedPrefab: {
                        prefabPath: 'child.prefab',
                        overrides: [],
                    },
                }],
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
            } as any;

            await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });

            const nestedRoot = capturedSceneData!.entities.find(e => e.name === 'NestedRoot')!;
            expect(nestedRoot.parent).toBeNull();
        });

        it('should throw when root entity ID only appears in nested prefabs', async () => {
            const prefab: PrefabData = {
                version: '1.0',
                name: 'BadPrefab',
                rootEntityId: '99',
                entities: [{
                    prefabEntityId: '0',
                    name: 'Root',
                    parent: null,
                    children: [],
                    components: [],
                    visible: true,
                }],
            };

            await expect(
                instantiatePrefab(world, prefab),
            ).rejects.toThrow('Failed to resolve prefab root entity');
        });
    });

    describe('edge cases', () => {
        it('should handle prefab with single entity', async () => {
            const prefab: PrefabData = {
                version: '1.0',
                name: 'SingleEntity',
                rootEntityId: '0',
                entities: [{
                    prefabEntityId: '0',
                    name: 'OnlyEntity',
                    parent: null,
                    children: [],
                    components: [],
                    visible: true,
                }],
            };

            const result = await instantiatePrefab(world, prefab);

            expect(capturedSceneData!.entities).toHaveLength(1);
            const rootId = capturedSceneData!.entities[0].id;
            expect(result.root).toBe(rootId + 100);
        });

        it('should handle non-sequential entity IDs', async () => {
            const prefab: PrefabData = {
                version: '1.0',
                name: 'NonSequential',
                rootEntityId: '5',
                entities: [
                    {
                        prefabEntityId: '5',
                        name: 'Root',
                        parent: null,
                        children: [ '10'],
                        components: [],
                        visible: true,
                    },
                    {
                        prefabEntityId: '10',
                        name: 'Child',
                        parent: '5',
                        children: [],
                        components: [],
                        visible: true,
                    },
                ],
            };

            await instantiatePrefab(world, prefab);

            expect(capturedSceneData!.entities).toHaveLength(2);
            const root = capturedSceneData!.entities.find(e => e.name === 'Root')!;
            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(root.parent).toBeNull();
            expect(child.parent).toBe(root.id);
            expect(root.children).toContain(child.id);
        });

        it('should handle empty overrides array', async () => {
            const prefab = simplePrefab();
            await instantiatePrefab(world, prefab, { overrides: [] });

            const child = capturedSceneData!.entities.find(e => e.name === 'Child')!;
            expect(child.name).toBe('Child');
            expect(child.components[0].data.color).toBe('red');
        });
    });

    describe('Prefab Variant', () => {
        it('should flatten variant by loading base and applying overrides', async () => {
            const basePrefab: PrefabData = {
                version: '1.0',
                name: 'BasePrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'Root',
                        parent: null,
                        children: [],
                        components: [{ type: 'Transform', data: { x: 0, y: 0 } }],
                        visible: true,
                    },
                ],
            };

            const variant: PrefabData = {
                version: '1.0',
                name: 'VariantPrefab',
                rootEntityId: '0',
                entities: [],
                basePrefab: 'base.prefab',
                overrides: [
                    {
                        prefabEntityId: '0',
                        type: 'property',
                        componentType: 'Transform',
                        propertyName: 'x',
                        value: 42,
                    },
                ],
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: basePrefab }),
            } as any;

            await instantiatePrefab(world, variant, { assets: withAssetLeases(mockAssetServer) });

            expect(capturedSceneData!.entities).toHaveLength(1);
            const root = capturedSceneData!.entities[0];
            expect(root.name).toBe('Root');
            const transform = root.components.find(c => c.type === 'Transform')!;
            expect(transform.data.x).toBe(42);
        });

        it('should combine variant overrides with instance overrides', async () => {
            const basePrefab: PrefabData = {
                version: '1.0',
                name: 'BasePrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'Root',
                        parent: null,
                        children: [],
                        components: [{ type: 'Sprite', data: { color: 'red', size: 10 } }],
                        visible: true,
                    },
                ],
            };

            const variant: PrefabData = {
                version: '1.0',
                name: 'VariantPrefab',
                rootEntityId: '0',
                entities: [],
                basePrefab: 'base.prefab',
                overrides: [
                    {
                        prefabEntityId: '0',
                        type: 'property',
                        componentType: 'Sprite',
                        propertyName: 'color',
                        value: 'blue',
                    },
                ],
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: basePrefab }),
            } as any;

            const instanceOverrides: PrefabOverride[] = [
                {
                    prefabEntityId: '0',
                    type: 'property',
                    componentType: 'Sprite',
                    propertyName: 'size',
                    value: 20,
                },
            ];

            await instantiatePrefab(world, variant, {
                assets: withAssetLeases(mockAssetServer),
                overrides: instanceOverrides,
            });

            const root = capturedSceneData!.entities[0];
            const sprite = root.components.find(c => c.type === 'Sprite')!;
            expect(sprite.data.color).toBe('blue');
            expect(sprite.data.size).toBe(20);
        });

        it('should detect circular variant reference', async () => {
            const variant: PrefabData = {
                version: '1.0',
                name: 'CircularVariant',
                rootEntityId: '0',
                entities: [],
                basePrefab: 'self.prefab',
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: variant }),
            } as any;

            await expect(
                instantiatePrefab(world, variant, { assets: withAssetLeases(mockAssetServer) }),
            ).rejects.toThrow('Circular variant reference');
        });

        it('should apply variant name override', async () => {
            const basePrefab: PrefabData = {
                version: '1.0',
                name: 'BasePrefab',
                rootEntityId: '0',
                entities: [
                    {
                        prefabEntityId: '0',
                        name: 'OriginalName',
                        parent: null,
                        children: [],
                        components: [],
                        visible: true,
                    },
                ],
            };

            const variant: PrefabData = {
                version: '1.0',
                name: 'VariantPrefab',
                rootEntityId: '0',
                entities: [],
                basePrefab: 'base.prefab',
                overrides: [
                    {
                        prefabEntityId: '0',
                        type: 'name',
                        value: 'RenamedInVariant',
                    },
                ],
            };

            const mockAssetServer = {
                loadPrefab: vi.fn().mockResolvedValue({ data: basePrefab }),
            } as any;

            await instantiatePrefab(world, variant, { assets: withAssetLeases(mockAssetServer) });

            const root = capturedSceneData!.entities[0];
            expect(root.name).toBe('RenamedInVariant');
        });
    });
});