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.

36.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { World, computeQueryCacheKey } from '../src/ecs/world';
import { defineComponent, defineTag, defineBuiltin, Name, Transform } from '../src/ecs/component';
import { createMockModule } from './mocks/wasm';

describe('World', () => {
    let world: World;

    const Position = defineComponent('TestPosition', { x: 0, y: 0 });
    const Velocity = defineComponent('TestVelocity', { dx: 0, dy: 0 });
    const Health = defineComponent('TestHealth', { value: 100 });
    const Player = defineTag('TestPlayer');

    beforeEach(() => {
        const mod = createMockModule();
        world = new World();
        world.connectCpp(mod.getRegistry(), mod);
    });

    describe('entity lifecycle', () => {
        it('should spawn a new entity', () => {
            const entity = world.spawn();
            expect(entity).toBeGreaterThan(0);
        });

        it('should spawn entity with name', () => {
            const entity = world.spawn('Player');
            expect(entity).toBeGreaterThan(0);
            const name = world.get(entity, Name);
            expect(name.value).toBe('Player');
        });

        it('should spawn entity without name when omitted', () => {
            const entity = world.spawn();
            expect(world.has(entity, Name)).toBe(false);
        });

        it('should find entity by name via index', () => {
            const e1 = world.spawn('Player');
            const e2 = world.spawn('Enemy');
            expect(world.findEntityByName('Player')).toBe(e1);
            expect(world.findEntityByName('Enemy')).toBe(e2);
            expect(world.findEntityByName('NonExistent')).toBeNull();
        });

        it('should remove name from index on despawn', () => {
            const entity = world.spawn('Player');
            expect(world.findEntityByName('Player')).toBe(entity);
            world.despawn(entity);
            expect(world.findEntityByName('Player')).toBeNull();
        });

        it('should update name index on rename via set', () => {
            const entity = world.spawn('OldName');
            expect(world.findEntityByName('OldName')).toBe(entity);
            world.set(entity, Name, { value: 'NewName' });
            expect(world.findEntityByName('OldName')).toBeNull();
            expect(world.findEntityByName('NewName')).toBe(entity);
        });

        it('should update name index on re-insert', () => {
            const entity = world.spawn('First');
            world.insert(entity, Name, { value: 'Second' });
            expect(world.findEntityByName('First')).toBeNull();
            expect(world.findEntityByName('Second')).toBe(entity);
        });

        it('should remove name from index on component remove', () => {
            const entity = world.spawn('Player');
            world.remove(entity, Name);
            expect(world.findEntityByName('Player')).toBeNull();
        });

        it('should handle duplicate names (last wins)', () => {
            world.spawn('Same');
            const e2 = world.spawn('Same');
            expect(world.findEntityByName('Same')).toBe(e2);
        });

        it('keeps a duplicate-named survivor findable when the other leaves', () => {
            const e1 = world.spawn('Enemy');
            const e2 = world.spawn('Enemy');
            world.despawn(e2); // removing the last-registered duplicate must not orphan e1
            expect(world.findEntityByName('Enemy')).toBe(e1);
            world.despawn(e1);
            expect(world.findEntityByName('Enemy')).toBeNull();
        });

        it('renaming one duplicate leaves the other resolvable', () => {
            const e1 = world.spawn('Enemy');
            const e2 = world.spawn('Enemy');
            world.set(e1, Name, { value: 'Boss' }); // must not drop e2's "Enemy" mapping
            expect(world.findEntityByName('Enemy')).toBe(e2);
            expect(world.findEntityByName('Boss')).toBe(e1);
        });

        it('should spawn multiple entities', () => {
            const e1 = world.spawn();
            const e2 = world.spawn();
            const e3 = world.spawn();

            expect(e1).not.toBe(e2);
            expect(e2).not.toBe(e3);
            expect(e1).not.toBe(e3);
        });

        it('should despawn an entity', () => {
            const entity = world.spawn();
            world.despawn(entity);

            expect(() => world.get(entity, Position)).toThrow();
        });
    });

    describe('component operations', () => {
        it('should insert component with data', () => {
            const entity = world.spawn();
            world.insert(entity, Position, { x: 10, y: 20 });

            const pos = world.get(entity, Position);
            expect(pos.x).toBe(10);
            expect(pos.y).toBe(20);
        });

        it('should insert component with defaults', () => {
            const entity = world.spawn();
            world.insert(entity, Position);

            const pos = world.get(entity, Position);
            expect(pos.x).toBe(0);
            expect(pos.y).toBe(0);
        });

        it('should insert component with partial data', () => {
            const entity = world.spawn();
            world.insert(entity, Position, { x: 5 });

            const pos = world.get(entity, Position);
            expect(pos.x).toBe(5);
            expect(pos.y).toBe(0);
        });

        it('should get component data', () => {
            const entity = world.spawn();
            world.insert(entity, Health, { value: 75 });

            const health = world.get(entity, Health);
            expect(health.value).toBe(75);
        });

        it('should throw when getting non-existent component', () => {
            const entity = world.spawn();

            expect(() => world.get(entity, Position)).toThrow();
        });

        it('should check if entity has component', () => {
            const entity = world.spawn();
            world.insert(entity, Position);

            expect(world.has(entity, Position)).toBe(true);
            expect(world.has(entity, Velocity)).toBe(false);
        });

        it('should remove component', () => {
            const entity = world.spawn();
            world.insert(entity, Position, { x: 1, y: 1 });
            world.insert(entity, Velocity, { dx: 1, dy: 1 });

            world.remove(entity, Position);

            expect(world.has(entity, Position)).toBe(false);
            expect(world.has(entity, Velocity)).toBe(true);
        });
    });

    describe('tag components', () => {
        it('should insert tag component', () => {
            const entity = world.spawn();
            world.insert(entity, Player);

            expect(world.has(entity, Player)).toBe(true);
        });

        it('should remove tag component', () => {
            const entity = world.spawn();
            world.insert(entity, Player);
            world.remove(entity, Player);

            expect(world.has(entity, Player)).toBe(false);
        });
    });

    describe('multiple components', () => {
        it('should add multiple components to one entity', () => {
            const entity = world.spawn();
            world.insert(entity, Position, { x: 1, y: 2 });
            world.insert(entity, Velocity, { dx: 3, dy: 4 });
            world.insert(entity, Health, { value: 100 });

            expect(world.has(entity, Position)).toBe(true);
            expect(world.has(entity, Velocity)).toBe(true);
            expect(world.has(entity, Health)).toBe(true);
        });

        it('should remove specific components while keeping others', () => {
            const entity = world.spawn();
            world.insert(entity, Position);
            world.insert(entity, Velocity);
            world.insert(entity, Health);

            world.remove(entity, Velocity);

            expect(world.has(entity, Position)).toBe(true);
            expect(world.has(entity, Velocity)).toBe(false);
            expect(world.has(entity, Health)).toBe(true);
        });
    });

    describe('getEntitiesWithComponents', () => {
        it('should find entities with single component', () => {
            const e1 = world.spawn();
            world.insert(e1, Position);

            const e2 = world.spawn();
            world.insert(e2, Velocity);

            const e3 = world.spawn();
            world.insert(e3, Position);

            const entities = world.getEntitiesWithComponents([Position]);

            expect(entities).toHaveLength(2);
            expect(entities).toContain(e1);
            expect(entities).toContain(e3);
        });

        it('should find entities with multiple components', () => {
            const e1 = world.spawn();
            world.insert(e1, Position);
            world.insert(e1, Velocity);

            const e2 = world.spawn();
            world.insert(e2, Position);

            const e3 = world.spawn();
            world.insert(e3, Position);
            world.insert(e3, Velocity);

            const entities = world.getEntitiesWithComponents([Position, Velocity]);

            expect(entities).toHaveLength(2);
            expect(entities).toContain(e1);
            expect(entities).toContain(e3);
        });

        it('should return empty array when no entities match', () => {
            const e1 = world.spawn();
            world.insert(e1, Position);

            const entities = world.getEntitiesWithComponents([Velocity, Health]);

            expect(entities).toHaveLength(0);
        });
    });

    // The supported edit is `update`. Writing to a `get` result does still stick
    // for a script component, but nothing observes it.
    describe('component data updates', () => {
        it('stores what the edit wrote', () => {
            const entity = world.spawn();
            world.insert(entity, Position, { x: 0, y: 0 });

            world.update(entity, Position, (pos) => {
                pos.x = 100;
                pos.y = 200;
            });

            const updated = world.get(entity, Position);
            expect(updated.x).toBe(100);
            expect(updated.y).toBe(200);
        });

        it('is visible to the next read', () => {
            const entity = world.spawn();
            world.insert(entity, Health, { value: 100 });

            world.update(entity, Health, (hp) => { hp.value -= 25; });

            expect(world.get(entity, Health).value).toBe(75);
        });
    });

    describe('structural changes', () => {
        it('should invalidate queries on entity spawn', () => {
            const e1 = world.spawn();
            world.insert(e1, Position);

            const entities1 = world.getEntitiesWithComponents([Position]);
            expect(entities1).toHaveLength(1);

            const e2 = world.spawn();
            world.insert(e2, Position);

            const entities2 = world.getEntitiesWithComponents([Position]);
            expect(entities2).toHaveLength(2);
        });

        it('should invalidate queries on entity despawn', () => {
            const e1 = world.spawn();
            world.insert(e1, Position);

            const e2 = world.spawn();
            world.insert(e2, Position);

            const entities1 = world.getEntitiesWithComponents([Position]);
            expect(entities1).toHaveLength(2);

            world.despawn(e1);

            const entities2 = world.getEntitiesWithComponents([Position]);
            expect(entities2).toHaveLength(1);
        });

        it('should invalidate queries on component insert', () => {
            const e1 = world.spawn();

            const entities1 = world.getEntitiesWithComponents([Position]);
            expect(entities1).toHaveLength(0);

            world.insert(e1, Position);

            const entities2 = world.getEntitiesWithComponents([Position]);
            expect(entities2).toHaveLength(1);
        });

        it('should invalidate queries on component remove', () => {
            const e1 = world.spawn();
            world.insert(e1, Position);

            const entities1 = world.getEntitiesWithComponents([Position]);
            expect(entities1).toHaveLength(1);

            world.remove(e1, Position);

            const entities2 = world.getEntitiesWithComponents([Position]);
            expect(entities2).toHaveLength(0);
        });

        it('keeps an unrelated query cached across churn of other components', () => {
            const a = world.spawn();
            world.insert(a, Position);

            // Prime the [Position] query, then watch it survive unrelated churn.
            expect(world.getEntitiesWithComponents([Position])).toHaveLength(1);
            world.resetQueryCacheStats();

            for (let i = 0; i < 20; i++) {
                const e = world.spawn();
                world.insert(e, Velocity);
                world.despawn(e);
            }

            const result = world.getEntitiesWithComponents([Position]);
            expect(result).toHaveLength(1);
            const stats = world.getQueryCacheStats();
            expect(stats.hits).toBe(1);
            expect(stats.misses).toBe(0);
        });
    });

    describe('complex scenarios', () => {
        it('should handle many entities', () => {
            const entities: number[] = [];

            for (let i = 0; i < 1000; i++) {
                const entity = world.spawn();
                world.insert(entity, Position, { x: i, y: i * 2 });
                entities.push(entity);
            }

            const queried = world.getEntitiesWithComponents([Position]);
            expect(queried).toHaveLength(1000);
        });

        it('should handle complex component combinations', () => {
            const enemy1 = world.spawn();
            world.insert(enemy1, Position);
            world.insert(enemy1, Velocity);
            world.insert(enemy1, Health);

            const enemy2 = world.spawn();
            world.insert(enemy2, Position);
            world.insert(enemy2, Health);

            const player = world.spawn();
            world.insert(player, Position);
            world.insert(player, Velocity);
            world.insert(player, Health);
            world.insert(player, Player);

            const movingEntities = world.getEntitiesWithComponents([Position, Velocity]);
            expect(movingEntities).toHaveLength(2);

            const players = world.getEntitiesWithComponents([Player]);
            expect(players).toHaveLength(1);

            const allLiving = world.getEntitiesWithComponents([Health]);
            expect(allLiving).toHaveLength(3);
        });
    });

    // =========================================================================
    // Pure JS mode (no C++ registry)
    // =========================================================================

    describe('pure JS mode (no cpp)', () => {
        let jsWorld: World;

        beforeEach(() => {
            jsWorld = new World();
        });

        it('should spawn entities with incrementing ids', () => {
            const e1 = jsWorld.spawn();
            const e2 = jsWorld.spawn();
            expect(e1).not.toBe(e2);
            expect(e1).toBeGreaterThan(0);
        });

        it('should validate entities', () => {
            const e = jsWorld.spawn();
            expect(jsWorld.valid(e)).toBe(true);
            jsWorld.despawn(e);
            expect(jsWorld.valid(e)).toBe(false);
        });

        it('should report entity count', () => {
            expect(jsWorld.entityCount()).toBe(0);
            const e1 = jsWorld.spawn();
            jsWorld.spawn();
            expect(jsWorld.entityCount()).toBe(2);
            jsWorld.despawn(e1);
            expect(jsWorld.entityCount()).toBe(1);
        });

        it('should list all entities', () => {
            const e1 = jsWorld.spawn();
            const e2 = jsWorld.spawn();
            expect(jsWorld.getAllEntities()).toContain(e1);
            expect(jsWorld.getAllEntities()).toContain(e2);
        });

        it('hasCpp should return false', () => {
            expect(jsWorld.hasCpp).toBe(false);
        });

        it('getCppRegistry should return null', () => {
            expect(jsWorld.getCppRegistry()).toBeNull();
        });
    });

    // =========================================================================
    // connectCpp / disconnectCpp
    // =========================================================================

    describe('connectCpp / disconnectCpp', () => {
        it('should connect and disconnect', () => {
            const w = new World();
            expect(w.hasCpp).toBe(false);

            const mod = createMockModule();
            w.connectCpp(mod.getRegistry(), mod);
            expect(w.hasCpp).toBe(true);
            expect(w.getCppRegistry()).not.toBeNull();

            w.disconnectCpp();
            expect(w.hasCpp).toBe(false);
            expect(w.getCppRegistry()).toBeNull();
        });
    });

    // =========================================================================
    // tryGet
    // =========================================================================

    describe('tryGet', () => {
        it('should return component data if present', () => {
            const entity = world.spawn();
            world.insert(entity, Position, { x: 42, y: 99 });
            const result = world.tryGet(entity, Position);
            expect(result).not.toBeNull();
            expect(result!.x).toBe(42);
        });

        it('should return null if component not present', () => {
            const entity = world.spawn();
            expect(world.tryGet(entity, Position)).toBeNull();
        });
    });

    // =========================================================================
    // set
    // =========================================================================

    describe('set', () => {
        it('should overwrite script component data', () => {
            const entity = world.spawn();
            world.insert(entity, Position, { x: 1, y: 2 });
            world.set(entity, Position, { x: 100, y: 200 });
            expect(world.get(entity, Position)).toEqual({ x: 100, y: 200 });
        });
    });

    // =========================================================================
    // Spawn / Despawn callbacks
    // =========================================================================

    describe('onSpawn / onDespawn callbacks', () => {
        it('should call spawn callbacks', () => {
            const w = new World();
            const spawned: number[] = [];
            w.onSpawn((e) => spawned.push(e));
            const e1 = w.spawn();
            const e2 = w.spawn();
            expect(spawned).toEqual([e1, e2]);
        });

        it('should call despawn callbacks', () => {
            const w = new World();
            const despawned: number[] = [];
            w.onDespawn((e) => despawned.push(e));
            const e1 = w.spawn();
            w.despawn(e1);
            expect(despawned).toEqual([e1]);
        });

        it('should support unsubscribing spawn callback', () => {
            const w = new World();
            const spawned: number[] = [];
            const unsub = w.onSpawn((e) => spawned.push(e));
            w.spawn();
            unsub();
            w.spawn();
            expect(spawned).toHaveLength(1);
        });

        it('should support unsubscribing despawn callback', () => {
            const w = new World();
            const despawned: number[] = [];
            const unsub = w.onDespawn((e) => despawned.push(e));
            const e1 = w.spawn();
            w.despawn(e1);
            unsub();
            const e2 = w.spawn();
            w.despawn(e2);
            expect(despawned).toHaveLength(1);
        });

        it('should not throw if callback throws', () => {
            const w = new World();
            w.onSpawn(() => { throw new Error('boom'); });
            expect(() => w.spawn()).not.toThrow();
        });
    });

    // =========================================================================
    // Iteration guards
    // =========================================================================

    describe('iteration guards', () => {
        it('should throw on spawn during iteration', () => {
            world.beginIteration();
            expect(() => world.spawn()).toThrow('Cannot spawn entity during query iteration');
            world.endIteration();
        });

        it('should throw on despawn during iteration', () => {
            const e = world.spawn();
            world.beginIteration();
            expect(() => world.despawn(e)).toThrow('Cannot despawn entity during query iteration');
            world.endIteration();
        });

        it('should throw on remove during iteration', () => {
            const e = world.spawn();
            world.insert(e, Position, { x: 0, y: 0 });
            world.beginIteration();
            expect(() => world.remove(e, Position)).toThrow('Cannot remove component during query iteration');
            world.endIteration();
        });

        it('should reset iteration depth', () => {
            world.beginIteration();
            world.beginIteration();
            world.resetIterationDepth();
            expect(world.isIterating()).toBe(false);
        });

        it('should warn on mismatched endIteration', () => {
            const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
            world.endIteration();
            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('mismatched'));
            warnSpy.mockRestore();
        });
    });

    // =========================================================================
    // Change detection
    // =========================================================================

    describe('change detection', () => {
        it('should advance tick', () => {
            const w = new World();
            expect(w.getWorldTick()).toBe(0);
            w.advanceTick();
            expect(w.getWorldTick()).toBe(1);
        });

        it('isAddedSince should detect newly added components', () => {
            const w = new World();
            w.enableChangeTracking(Position);
            const e = w.spawn();
            w.advanceTick();
            w.insert(e, Position, { x: 1, y: 1 });
            expect(w.isAddedSince(e, Position, 0)).toBe(true);
            expect(w.isAddedSince(e, Position, 1)).toBe(false);
        });

        it('isAddedSince should return false for unknown component', () => {
            const w = new World();
            const e = w.spawn();
            expect(w.isAddedSince(e, Position, -1)).toBe(false);
        });

        it('isChangedSince should detect changed components', () => {
            const w = new World();
            w.enableChangeTracking(Position);
            const e = w.spawn();
            w.insert(e, Position, { x: 0, y: 0 });
            w.advanceTick();
            w.set(e, Position, { x: 5, y: 5 });
            expect(w.isChangedSince(e, Position, 0)).toBe(true);
        });

        it('isChangedSince should return false for unknown component', () => {
            const w = new World();
            const e = w.spawn();
            expect(w.isChangedSince(e, Position, -1)).toBe(false);
        });

        it('getRemovedEntitiesSince should detect removed components', () => {
            const w = new World();
            // History is produced for a component someone READS history of —
            // change tracking alone says the topology moved, not who lost what.
            w.registerRemovedReader(Position);
            const e = w.spawn();
            w.insert(e, Position, { x: 0, y: 0 });
            w.advanceTick();
            w.remove(e, Position);
            const removed = w.getRemovedEntitiesSince(Position, 0);
            expect(removed).toContain(e);
        });

        it('getRemovedEntitiesSince should return empty for unknown component', () => {
            const w = new World();
            expect(w.getRemovedEntitiesSince(Velocity, -1)).toEqual([]);
        });

        it('despawn should record removed ticks for all components', () => {
            const w = new World();
            w.registerRemovedReader(Position);
            w.registerRemovedReader(Velocity);
            const e = w.spawn();
            w.insert(e, Position, { x: 0, y: 0 });
            w.insert(e, Velocity, { dx: 1, dy: 1 });
            w.advanceTick();
            w.despawn(e);
            expect(w.getRemovedEntitiesSince(Position, 0)).toContain(e);
            expect(w.getRemovedEntitiesSince(Velocity, 0)).toContain(e);
        });
    });

    // =========================================================================
    // setParent / removeParent
    // =========================================================================

    describe('setParent / removeParent', () => {
        it('should call setParent on cpp registry', () => {
            const e1 = world.spawn();
            const e2 = world.spawn();
            expect(() => world.setParent(e1, e2)).not.toThrow();
        });

        it('should call removeParent on cpp registry', () => {
            const e1 = world.spawn();
            expect(() => world.removeParent(e1)).not.toThrow();
        });

        it('should be no-op without cpp registry', () => {
            const w = new World();
            const e1 = w.spawn();
            const e2 = w.spawn();
            expect(() => w.setParent(e1, e2)).not.toThrow();
            expect(() => w.removeParent(e1)).not.toThrow();
        });
    });

    // =========================================================================
    // getEntitiesWithComponents with filters
    // =========================================================================

    describe('getEntitiesWithComponents with filters', () => {
        it('should return all entities when no components specified', () => {
            const e1 = world.spawn();
            const e2 = world.spawn();
            const result = world.getEntitiesWithComponents([]);
            expect(result).toContain(e1);
            expect(result).toContain(e2);
        });

        it('should apply withFilters', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 0, y: 0 });
            world.insert(e1, Health, { value: 100 });

            const e2 = world.spawn();
            world.insert(e2, Position, { x: 0, y: 0 });

            const result = world.getEntitiesWithComponents([Position], [Health]);
            expect(result).toHaveLength(1);
            expect(result).toContain(e1);
        });

        it('should apply withoutFilters', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 0, y: 0 });
            world.insert(e1, Health, { value: 100 });

            const e2 = world.spawn();
            world.insert(e2, Position, { x: 0, y: 0 });

            const result = world.getEntitiesWithComponents([Position], [], [Health]);
            expect(result).toHaveLength(1);
            expect(result).toContain(e2);
        });
    });

    // =========================================================================
    // computeQueryCacheKey
    // =========================================================================

    describe('computeQueryCacheKey', () => {
        it('should produce a stable key', () => {
            const key1 = computeQueryCacheKey([Position, Velocity]);
            const key2 = computeQueryCacheKey([Position, Velocity]);
            expect(key1).toBe(key2);
        });

        it('should include with filter in key', () => {
            const keyBase = computeQueryCacheKey([Position]);
            const keyWith = computeQueryCacheKey([Position], [Velocity]);
            expect(keyWith).not.toBe(keyBase);
            expect(keyWith).toContain('|+');
        });

        it('should include without filter in key', () => {
            const keyBase = computeQueryCacheKey([Position]);
            const keyWithout = computeQueryCacheKey([Position], [], [Velocity]);
            expect(keyWithout).not.toBe(keyBase);
            expect(keyWithout).toContain('|-');
        });
    });

    // =========================================================================
    // resetQueryPool
    // =========================================================================

    describe('resetQueryPool', () => {
        it('should reset the pool index', () => {
            world.getEntitiesWithComponents([Position]);
            world.resetQueryPool();
            world.getEntitiesWithComponents([Position]);
        });
    });

    // =========================================================================
    // getComponentTypes
    // =========================================================================

    describe('getComponentTypes', () => {
        it('bulk inspection keeps late builtin extensions and clears bindings on reconnect', () => {
            const module = createMockModule();
            const registry = module.getRegistry();
            registry.getBuiltinComponentNames = () => '';
            const inspected = new World();
            inspected.connectCpp(registry, module);
            const entity = inspected.spawn();
            expect(inspected.getComponentTypes(entity)).toEqual([]);
            const extension = defineBuiltin('BulkInspectionExtension', { value: 0 });
            inspected.insert(entity, extension, { value: 3 });
            expect(inspected.getComponentTypes(entity)).toContain('BulkInspectionExtension');
            inspected.remove(entity, extension);
            expect(inspected.getComponentTypes(entity)).not.toContain('BulkInspectionExtension');
            inspected.insert(entity, extension, { value: 4 });
            const nextModule = createMockModule();
            const nextRegistry = nextModule.getRegistry();
            nextRegistry.getBuiltinComponentNames = () => '';
            inspected.disconnectCpp();
            inspected.connectCpp(nextRegistry, nextModule);
            expect(inspected.getComponentTypes(entity)).not.toContain('BulkInspectionExtension');
        });

        it('checks each known builtin once and reflects component mutations immediately', () => {
            const module = createMockModule();
            const registry = module.getRegistry();
            const original = registry.hasTransform!;
            const has = vi.fn((entity: number) => original(entity));
            registry.hasTransform = has;
            const inspected = new World();
            inspected.connectCpp(registry, module);
            const entity = inspected.spawn();
            has.mockClear();
            expect(inspected.getComponentTypes(entity)).not.toContain('Transform');
            expect(has).toHaveBeenCalledTimes(1);
            inspected.insert(entity, Transform);
            expect(inspected.getComponentTypes(entity)).toContain('Transform');
            inspected.remove(entity, Transform);
            expect(inspected.getComponentTypes(entity)).not.toContain('Transform');
            inspected.insert(entity, Position, { x: 1, y: 2 });
            expect(inspected.getComponentTypes(entity)).toContain('TestPosition');
            inspected.remove(entity, Position);
            expect(inspected.getComponentTypes(entity)).not.toContain('TestPosition');
        });

        it('should return an array (may be empty for script-only without registry)', () => {
            const entity = world.spawn();
            world.insert(entity, Position, { x: 0, y: 0 });
            const types = world.getComponentTypes(entity);
            expect(Array.isArray(types)).toBe(true);
        });

        it('should return empty array for entity with no components', () => {
            const entity = world.spawn();
            const types = world.getComponentTypes(entity);
            expect(types).toEqual([]);
        });
    });

    // =========================================================================
    // Builtin component operations via mock
    // =========================================================================

    describe('builtin components', () => {
        const Transform = defineBuiltin('WTestTransform', {
            x: 0, y: 0, rotation: 0, scaleX: 1, scaleY: 1,
        });

        it('should insert and get builtin component', () => {
            const entity = world.spawn();
            world.insert(entity, Transform, { x: 10, y: 20 });
            const data = world.get(entity, Transform);
            expect(data.x).toBe(10);
            expect(data.y).toBe(20);
        });

        it('should check has for builtin component', () => {
            const entity = world.spawn();
            expect(world.has(entity, Transform)).toBe(false);
            world.insert(entity, Transform, { x: 0, y: 0 });
            expect(world.has(entity, Transform)).toBe(true);
        });

        it('should remove builtin component', () => {
            const entity = world.spawn();
            world.insert(entity, Transform, { x: 0, y: 0 });
            world.remove(entity, Transform);
            expect(world.has(entity, Transform)).toBe(false);
        });

        it('should set builtin component data', () => {
            const entity = world.spawn();
            world.insert(entity, Transform, { x: 0, y: 0 });
            world.set(entity, Transform, { x: 50, y: 60, rotation: 0, scaleX: 1, scaleY: 1 });
            const data = world.get(entity, Transform);
            expect(data.x).toBe(50);
            expect(data.y).toBe(60);
        });

        it('tryGet should return builtin data if present', () => {
            const entity = world.spawn();
            world.insert(entity, Transform, { x: 7, y: 8 });
            const data = world.tryGet(entity, Transform);
            expect(data).not.toBeNull();
            expect(data!.x).toBe(7);
        });

        it('tryGet should return null if builtin not present', () => {
            const entity = world.spawn();
            expect(world.tryGet(entity, Transform)).toBeNull();
        });

        it('tryGet should return null without cpp registry', () => {
            const w = new World();
            const e = w.spawn();
            expect(w.tryGet(e, Transform)).toBeNull();
        });

        it('hasBuiltin should return false without cpp registry', () => {
            const w = new World();
            const e = w.spawn();
            expect(w.has(e, Transform)).toBe(false);
        });

        it('removeBuiltin should be no-op without cpp registry', () => {
            const w = new World();
            const e = w.spawn();
            expect(() => w.remove(e, Transform)).not.toThrow();
        });
    });

    // =========================================================================
    // getWorldVersion
    // =========================================================================

    describe('getWorldVersion', () => {
        it('should increment on structural changes', () => {
            const v0 = world.getWorldVersion();
            const e = world.spawn();
            expect(world.getWorldVersion()).toBeGreaterThan(v0);
            const v1 = world.getWorldVersion();
            world.insert(e, Position, { x: 0, y: 0 });
            expect(world.getWorldVersion()).toBeGreaterThan(v1);
        });
    });

    // =========================================================================
    // Color conversion via builtin components (convertFromWasm/convertForWasm)
    // =========================================================================

    describe('color conversion (rgba <-> xyzw)', () => {
        const ColorComp = defineBuiltin('WTestColor', {
            tint: { r: 1, g: 1, b: 1, a: 1 },
        });

        it('should convert rgba to xyzw when setting builtin', () => {
            const entity = world.spawn();
            world.insert(entity, ColorComp, { tint: { r: 1, g: 0, b: 0, a: 0.5 } });
            const data = world.get(entity, ColorComp);
            expect(data.tint.r).toBe(1);
            expect(data.tint.a).toBe(0.5);
        });

        it('should round-trip color data through set/get', () => {
            const entity = world.spawn();
            world.insert(entity, ColorComp, { tint: { r: 0.2, g: 0.4, b: 0.6, a: 0.8 } });
            world.set(entity, ColorComp, { tint: { r: 0.2, g: 0.4, b: 0.6, a: 0.8 } });
            const data = world.get(entity, ColorComp);
            expect(data.tint.r).toBeCloseTo(0.2);
            expect(data.tint.g).toBeCloseTo(0.4);
            expect(data.tint.b).toBeCloseTo(0.6);
            expect(data.tint.a).toBeCloseTo(0.8);
        });
    });

    // =========================================================================
    // Validation errors
    // =========================================================================

    describe('component validation', () => {
        it('should throw on invalid builtin data type', () => {
            const Sprite = defineBuiltin('WTestSprite', { width: 100, height: 100 });
            const entity = world.spawn();
            expect(() => world.insert(entity, Sprite, { width: 'abc' as any })).toThrow();
        });

        it('should throw on invalid script data type', () => {
            const entity = world.spawn();
            expect(() => world.insert(entity, Position, { x: 'abc' as any })).toThrow();
        });
    });
});