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.

20.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, beforeEach } from 'vitest';
import { World } from '../src/ecs/world';
import {
    Query, QueryInstance, Mut,
    Added, Changed, Removed,
    isMutWrapper, isAddedWrapper, isChangedWrapper,
    RemovedQueryInstance,
} from '../src/ecs/query';
import { defineComponent } from '../src/ecs/component';


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

    const Position = defineComponent('QPosition', { x: 0, y: 0 });
    const Velocity = defineComponent('QVelocity', { dx: 0, dy: 0 });
    const Health = defineComponent('QHealth', { value: 100 });
    const Enemy = defineComponent('QEnemy', {});

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

    describe('Query creation', () => {
        it('should create query with single component', () => {
            const query = Query(Position);
            expect(query).toBeDefined();
        });

        it('should create query with multiple components', () => {
            const query = Query(Position, Velocity);
            expect(query).toBeDefined();
        });

        it('should create query with Mut wrapper', () => {
            const query = Query(Mut(Position), Velocity);
            expect(query).toBeDefined();
        });
    });

    describe('Query iteration', () => {
        it('should iterate over entities with components', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 2 });
            world.insert(e1, Velocity, { dx: 3, dy: 4 });

            const e2 = world.spawn();
            world.insert(e2, Position, { x: 5, y: 6 });
            world.insert(e2, Velocity, { dx: 7, dy: 8 });

            const query = Query(Position, Velocity);
            const results: Array<{ entity: number; pos: any; vel: any }> = [];

            const instance = new QueryInstance(world, query);
            instance.forEach((entity, pos, vel) => {
                results.push({ entity, pos, vel });
            });

            expect(results).toHaveLength(2);
            expect(results[0].pos).toEqual({ x: 1, y: 2 });
            expect(results[1].pos).toEqual({ x: 5, y: 6 });
        });

        it('should only return entities with all required components', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });

            const e2 = world.spawn();
            world.insert(e2, Position, { x: 2, y: 2 });
            world.insert(e2, Velocity, { dx: 1, dy: 1 });

            const query = Query(Position, Velocity);
            const results: number[] = [];

            const instance = new QueryInstance(world, query);
            instance.forEach((entity) => {
                results.push(entity);
            });

            expect(results).toHaveLength(1);
            expect(results[0]).toBe(e2);
        });

        it('should handle empty query results', () => {
            const query = Query(Position);
            let count = 0;

            const instance = new QueryInstance(world, query);
            instance.forEach(() => {
                count++;
            });

            expect(count).toBe(0);
        });
    });

    describe('Query caching', () => {
        it('should cache query results', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });

            const query = Query(Position);

            let count1 = 0;
            new QueryInstance(world, query).forEach(() => { count1++; });

            let count2 = 0;
            new QueryInstance(world, query).forEach(() => { count2++; });

            expect(count1).toBe(1);
            expect(count2).toBe(1);
        });

        it('should invalidate cache on structural changes', () => {
            const query = Query(Position);

            let count1 = 0;
            new QueryInstance(world, query).forEach(() => { count1++; });

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

            let count2 = 0;
            new QueryInstance(world, query).forEach(() => { count2++; });

            expect(count1).toBe(0);
            expect(count2).toBe(1);
        });

        it('should not invalidate cache on component data changes', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });

            const query = Query(Position);

            new QueryInstance(world, query).forEach(() => {});

            world.update(e1, Position, (pos) => { pos.x = 999; });

            let count = 0;
            new QueryInstance(world, query).forEach(() => { count++; });

            expect(count).toBe(1);
        });
    });

    describe('Mut wrapper', () => {
        it('should provide mutable access', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });

            const query = Query(Mut(Position));

            new QueryInstance(world, query).forEach((entity, pos) => {
                pos.x = 100;
                pos.y = 200;
            });

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

        it('should mix mutable and immutable components', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.insert(e1, Velocity, { dx: 2, dy: 2 });

            const query = Query(Mut(Position), Velocity);

            new QueryInstance(world, query).forEach((entity, pos, vel) => {
                pos.x += vel.dx;
                pos.y += vel.dy;
            });

            const updated = world.get(e1, Position);
            expect(updated.x).toBe(3);
            expect(updated.y).toBe(3);
        });

        // The contract is not "a query that ran dirties what it touched" — it is
        // that only a Mut projection reports. The AOT roads mark from the same
        // declaration, so this is where that rule is pinned.
        it('reports the Mut component and not the read-only one beside it', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.insert(e1, Velocity, { dx: 2, dy: 2 });
            world.enableChangeTracking(Position);
            world.enableChangeTracking(Velocity);
            world.advanceTick();
            const since = world.getWorldTick() - 1;

            new QueryInstance(world, Query(Mut(Position), Velocity)).forEach(() => { /* reads */ });

            expect(world.isChangedSince(e1, Position, since)).toBe(true);
            expect(world.isChangedSince(e1, Velocity, since)).toBe(false);
        });
    });

    describe('complex queries', () => {
        it('should handle three-component queries', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.insert(e1, Velocity, { dx: 1, dy: 1 });
            world.insert(e1, Health, { value: 50 });

            const query = Query(Position, Velocity, Health);
            let count = 0;

            new QueryInstance(world, query).forEach((entity, pos, vel, hp) => {
                expect(pos.x).toBe(1);
                expect(vel.dx).toBe(1);
                expect(hp.value).toBe(50);
                count++;
            });

            expect(count).toBe(1);
        });

        it('should filter correctly with multiple components', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.insert(e1, Enemy, {});

            const e2 = world.spawn();
            world.insert(e2, Position, { x: 2, y: 2 });
            world.insert(e2, Health, { value: 100 });

            const e3 = world.spawn();
            world.insert(e3, Position, { x: 3, y: 3 });
            world.insert(e3, Enemy, {});

            const query = Query(Position, Enemy);
            const results: number[] = [];

            new QueryInstance(world, query).forEach((entity) => {
                results.push(entity);
            });

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

    describe('entity lifecycle during iteration', () => {
        it('should handle entity creation during iteration', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });

            const query = Query(Position);
            let iterations = 0;

            expect(() => {
                new QueryInstance(world, query).forEach((entity) => {
                    iterations++;
                    if (iterations === 1) {
                        world.spawn();
                    }
                });
            }).toThrow(/Cannot spawn entity during query iteration/);
        });

        it('should handle component removal during iteration', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.insert(e1, Velocity, { dx: 1, dy: 1 });

            const query = Query(Position);

            expect(() => {
                new QueryInstance(world, query).forEach((entity) => {
                    world.remove(entity, Velocity);
                });
            }).toThrow(/Cannot remove component during query iteration/);
        });
    });

    // =========================================================================
    // with / without filters
    // =========================================================================

    describe('with / without filters', () => {
        it('should filter entities that also have a with component', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.insert(e1, Enemy, {});

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

            const query = Query(Position).with(Enemy);
            const results: number[] = [];
            new QueryInstance(world, query).forEach((entity) => {
                results.push(entity);
            });
            expect(results).toEqual([e1]);
        });

        it('should exclude entities with a without component', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.insert(e1, Enemy, {});

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

            const query = Query(Position).without(Enemy);
            const results: number[] = [];
            new QueryInstance(world, query).forEach((entity) => {
                results.push(entity);
            });
            expect(results).toEqual([e2]);
        });

        it('should chain with and without', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.insert(e1, Velocity, { dx: 1, dy: 1 });
            world.insert(e1, Enemy, {});

            const e2 = world.spawn();
            world.insert(e2, Position, { x: 2, y: 2 });
            world.insert(e2, Velocity, { dx: 2, dy: 2 });

            const e3 = world.spawn();
            world.insert(e3, Position, { x: 3, y: 3 });
            world.insert(e3, Enemy, {});

            const query = Query(Position).with(Velocity).without(Enemy);
            const results: number[] = [];
            new QueryInstance(world, query).forEach((entity) => {
                results.push(entity);
            });
            expect(results).toEqual([e2]);
        });
    });

    // =========================================================================
    // Added / Changed wrappers and type guards
    // =========================================================================

    describe('Added / Changed wrappers', () => {
        it('Added should create an added filter wrapper', () => {
            const wrapper = Added(Position);
            expect(wrapper._filterType).toBe('added');
            expect(wrapper._component).toBe(Position);
        });

        it('Changed should create a changed filter wrapper', () => {
            const wrapper = Changed(Position);
            expect(wrapper._filterType).toBe('changed');
            expect(wrapper._component).toBe(Position);
        });

        it('isAddedWrapper should detect Added wrappers', () => {
            expect(isAddedWrapper(Added(Position))).toBe(true);
            expect(isAddedWrapper(Changed(Position))).toBe(false);
            expect(isAddedWrapper(Mut(Position))).toBe(false);
            expect(isAddedWrapper(null)).toBe(false);
        });

        it('isChangedWrapper should detect Changed wrappers', () => {
            expect(isChangedWrapper(Changed(Position))).toBe(true);
            expect(isChangedWrapper(Added(Position))).toBe(false);
            expect(isChangedWrapper(Mut(Position))).toBe(false);
            expect(isChangedWrapper(null)).toBe(false);
        });

        it('isMutWrapper should detect Mut wrappers', () => {
            expect(isMutWrapper(Mut(Position))).toBe(true);
            expect(isMutWrapper(Added(Position))).toBe(false);
            expect(isMutWrapper(Position)).toBe(false);
            expect(isMutWrapper(null)).toBe(false);
        });
    });

    describe('Added query filtering', () => {
        it('should only return entities added since last run tick', () => {
            world.enableChangeTracking(Position);
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });

            const query = Query(Added(Position));
            const instance = new QueryInstance(world, query, -1);
            const results: number[] = [];
            instance.forEach((entity) => {
                results.push(entity);
            });
            expect(results).toContain(e1);
        });
    });

    describe('Changed query filtering', () => {
        it('should only return entities changed since last run tick', () => {
            world.enableChangeTracking(Position);
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });

            const query = Query(Changed(Position));
            const instance = new QueryInstance(world, query, -1);
            const results: number[] = [];
            instance.forEach((entity) => {
                results.push(entity);
            });
            expect(results).toContain(e1);
        });

        it('should skip entities not changed since a future tick', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });

            const query = Query(Changed(Position));
            const instance = new QueryInstance(world, query, Infinity);
            const results: number[] = [];
            instance.forEach((entity) => {
                results.push(entity);
            });
            expect(results).toHaveLength(0);
        });
    });

    // =========================================================================
    // single / isEmpty / count / toArray
    // =========================================================================

    describe('single()', () => {
        it('should return first result', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 10, y: 20 });

            const query = Query(Position);
            const instance = new QueryInstance(world, query);
            const result = instance.single();
            expect(result).not.toBeNull();
            expect(result![0]).toBe(e1);
        });

        it('should return null when no results', () => {
            const query = Query(Position);
            const instance = new QueryInstance(world, query);
            expect(instance.single()).toBeNull();
        });
    });

    describe('isEmpty()', () => {
        it('should return true when no matching entities', () => {
            const query = Query(Position);
            const instance = new QueryInstance(world, query);
            expect(instance.isEmpty()).toBe(true);
        });

        it('should return false when matching entities exist', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 0, y: 0 });

            const query = Query(Position);
            const instance = new QueryInstance(world, query);
            expect(instance.isEmpty()).toBe(false);
        });
    });

    describe('count()', () => {
        it('should return 0 for empty query', () => {
            const query = Query(Position);
            expect(new QueryInstance(world, query).count()).toBe(0);
        });

        it('should return correct count', () => {
            for (let i = 0; i < 3; i++) {
                const e = world.spawn();
                world.insert(e, Position, { x: i, y: i });
            }

            const query = Query(Position);
            expect(new QueryInstance(world, query).count()).toBe(3);
        });
    });

    describe('toArray()', () => {
        it('should return empty array for no results', () => {
            const query = Query(Position);
            expect(new QueryInstance(world, query).toArray()).toEqual([]);
        });

        it('should return all results as array', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            const e2 = world.spawn();
            world.insert(e2, Position, { x: 2, y: 2 });

            const query = Query(Position);
            const arr = new QueryInstance(world, query).toArray();
            expect(arr).toHaveLength(2);
            expect(arr[0][0]).toBe(e1);
            expect(arr[1][0]).toBe(e2);
        });
    });

    // =========================================================================
    // Mut write-back with multiple entities
    // =========================================================================

    describe('Mut write-back across multiple entities', () => {
        it('should write back mutations for all entities', () => {
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 0, y: 0 });

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

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

            const query = Query(Mut(Position));
            new QueryInstance(world, query).forEach((entity, pos) => {
                pos.x = entity * 10;
                pos.y = entity * 20;
            });

            expect(world.get(e1, Position)).toEqual({ x: e1 * 10, y: e1 * 20 });
            expect(world.get(e2, Position)).toEqual({ x: e2 * 10, y: e2 * 20 });
            expect(world.get(e3, Position)).toEqual({ x: e3 * 10, y: e3 * 20 });
        });
    });

    // =========================================================================
    // Removed query
    // =========================================================================

    describe('Removed query', () => {
        it('should create a removed descriptor', () => {
            const desc = Removed(Position);
            expect(desc._type).toBe('removed');
            expect(desc._component).toBe(Position);
        });

        // History begins when the reader claims it: a reader does not inherit
        // removals from before it existed, so the claim comes first.
        it('should iterate over removed entities', () => {
            const instance = new RemovedQueryInstance(world, Position, -1);
            instance.activateRetention();
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.remove(e1, Position);

            expect(instance.toArray()).toContain(e1);
        });

        it('should report isEmpty correctly', () => {
            const instance = new RemovedQueryInstance(world, Position, -1);
            instance.activateRetention();
            expect(instance.isEmpty()).toBe(true);

            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.remove(e1, Position);

            expect(instance.isEmpty()).toBe(false);
        });

        it('should be iterable', () => {
            const instance = new RemovedQueryInstance(world, Position, -1);
            instance.activateRetention();
            const e1 = world.spawn();
            world.insert(e1, Position, { x: 1, y: 1 });
            world.remove(e1, Position);

            const results: number[] = [];
            for (const entity of instance) {
                results.push(entity);
            }
            expect(results).toContain(e1);
        });
    });
});