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.

18.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import {
    Schedule,
    GetWorld,
    defineSystem,
    addSystem,
    addStartupSystem,
    addSystemToSchedule,
    SystemRunner,
} from '../src/ecs/system';
import { getDefaultContext } from '../src/ecs/context';
import { Query, Mut, Added, Changed, QueryInstance, Removed, RemovedQueryInstance } from '../src/ecs/query';
import { Res, ResMut, ResMutInstance, defineResource, ResourceStorage } from '../src/ecs/resource';
import { Commands, CommandsInstance } from '../src/ecs/commands';
import { EventWriter, EventReader, EventWriterInstance, EventReaderInstance, defineEvent, EventRegistry } from '../src/ecs/event';
import { defineComponent } from '../src/ecs/component';
import type { World } from '../src/ecs/world';
import type { Entity } from '../src/types';

// =============================================================================
// Test components and resources
// =============================================================================

const Position = defineComponent('SysTestPosition', { x: 0, y: 0 });
const Velocity = defineComponent('SysTestVelocity', { dx: 0, dy: 0 });

const GameState = defineResource({ score: 0, level: 1 }, 'GameState');

const DamageEvent = defineEvent<{ target: Entity; amount: number }>('Damage');

// =============================================================================
// Mock World
// =============================================================================

function createMockWorld() {
    let nextId = 1;
    const entities = new Set<Entity>();
    const worldTick = { value: 0 };

    const world = {
        spawn: vi.fn(() => {
            const e = nextId++ as Entity;
            entities.add(e);
            return e;
        }),
        despawn: vi.fn((e: Entity) => entities.delete(e)),
        insert: vi.fn(),
        remove: vi.fn(),
        get: vi.fn(),
        set: vi.fn(),
        valid: vi.fn((e: Entity) => entities.has(e)),
        getEntitiesWithComponents: vi.fn(() => [] as Entity[]),
        // What QueryInstance actually calls: the precomputed-key path.
        queryEntities: vi.fn(() => [] as Entity[]),
        beginIteration: vi.fn(),
        endIteration: vi.fn(),
        resetIterationDepth: vi.fn(),
        getWorldTick: vi.fn(() => worldTick.value),
        getChangeSequence: vi.fn(() => 0),
        enableChangeSequenceTracking: vi.fn(),
        resolveChangeSequenceMatcher: vi.fn(() => () => false),
        isAddedAfterSequence: vi.fn(() => false),
        isChangedAfterSequence: vi.fn(() => false),
        anyAddedAfterSequence: vi.fn(() => false),
        anyChangedAfterSequence: vi.fn(() => false),
        isAddedSince: vi.fn(() => false),
        isChangedSince: vi.fn(() => false),
        getRemovedEntitiesSince: vi.fn(() => []),
        enableChangeTracking: vi.fn(),
        // Modelled with the runner's lifecycle in mind: it registers on commit,
        // releases on completion and disposes on evict, and a stub that answers
        // nothing would let a change to that order pass unnoticed here.
        registerRemovedReader: vi.fn(() => 1),
        advanceRemovedReader: vi.fn(),
        registerRemovedCursorReader: vi.fn(() => 1),
        getRemovalSequence: vi.fn(() => 0),
        getRemovedEntitiesForReader: vi.fn(() => []),
        advanceRemovedCursorReader: vi.fn(),
        disposeRemovedReader: vi.fn(),
        resolveGetter: vi.fn(() => null),
    };

    return { world: world as unknown as World, entities, worldTick };
}

// =============================================================================
// Schedule enum
// =============================================================================

describe('Schedule', () => {
    it('should have correct phase values', () => {
        expect(Schedule.Startup).toBe(0);
        expect(Schedule.First).toBe(1);
        expect(Schedule.PreUpdate).toBe(2);
        expect(Schedule.Update).toBe(3);
        expect(Schedule.PostUpdate).toBe(4);
        expect(Schedule.Last).toBe(5);
        expect(Schedule.FixedPreUpdate).toBe(10);
        expect(Schedule.FixedUpdate).toBe(11);
        expect(Schedule.FixedPostUpdate).toBe(12);
    });
});

// =============================================================================
// GetWorld descriptor
// =============================================================================

describe('GetWorld', () => {
    it('should create a get_world descriptor', () => {
        const desc = GetWorld();
        expect(desc._type).toBe('get_world');
    });
});

// =============================================================================
// defineSystem
// =============================================================================

describe('defineSystem', () => {
    it('should create a system with unique symbol id', () => {
        const sys = defineSystem([], () => {});
        expect(typeof sys._id).toBe('symbol');
    });

    it('should store params and fn', () => {
        const fn = vi.fn();
        const params = [Query(Position)] as const;
        const sys = defineSystem([...params], fn);
        expect(sys._params).toHaveLength(1);
        expect(sys._fn).toBe(fn);
    });

    it('should use provided name', () => {
        const sys = defineSystem([], () => {}, { name: 'MovementSystem' });
        expect(sys._name).toBe('MovementSystem');
    });

    it('should default to empty name when not provided', () => {
        const sys = defineSystem([], () => {});
        expect(sys._name).toBe('');
    });

    it('should create unique ids for different systems', () => {
        const a = defineSystem([], () => {});
        const b = defineSystem([], () => {});
        expect(a._id).not.toBe(b._id);
    });
});

// =============================================================================
// Global registration (addSystem, addStartupSystem, addSystemToSchedule)
// =============================================================================

describe('Global system registration', () => {
    afterEach(() => {
        getDefaultContext().pendingSystems.length = 0;
    });

    it('addSystem should register with Update schedule', () => {
        const sys = defineSystem([], () => {});
        addSystem(sys);
        const pending = getDefaultContext().pendingSystems;
        expect(pending).toContainEqual({ schedule: Schedule.Update, system: sys });
    });

    it('addStartupSystem should register with Startup schedule', () => {
        const sys = defineSystem([], () => {});
        addStartupSystem(sys);
        const pending = getDefaultContext().pendingSystems;
        expect(pending).toContainEqual({ schedule: Schedule.Startup, system: sys });
    });

    it('addSystemToSchedule should register with specified schedule', () => {
        const sys = defineSystem([], () => {});
        addSystemToSchedule(Schedule.Last, sys);
        const pending = getDefaultContext().pendingSystems;
        expect(pending).toContainEqual({ schedule: Schedule.Last, system: sys });
    });

    it('drainPendingSystems should return entries and clear queue', () => {
        const sys = defineSystem([], () => {});
        addSystem(sys);
        const ctx = getDefaultContext();
        expect(ctx.pendingSystems.length).toBe(1);

        const drained = ctx.drainPendingSystems();
        expect(drained).toHaveLength(1);
        expect(drained[0].system).toBe(sys);
        expect(ctx.pendingSystems.length).toBe(0);
    });
});

// =============================================================================
// SystemRunner
// =============================================================================

describe('SystemRunner', () => {
    let mockWorld: ReturnType<typeof createMockWorld>;
    let world: World;
    let resources: ResourceStorage;
    let eventRegistry: EventRegistry;
    let runner: SystemRunner;

    beforeEach(() => {
        mockWorld = createMockWorld();
        world = mockWorld.world;
        resources = new ResourceStorage();
        eventRegistry = new EventRegistry();
        runner = new SystemRunner(world, resources, eventRegistry);
    });

    describe('run with no params', () => {
        it('should call the system function', () => {
            const fn = vi.fn();
            const sys = defineSystem([], fn);
            runner.run(sys);
            expect(fn).toHaveBeenCalledOnce();
        });
    });

    describe('a first run that throws while building its params', () => {
        /**
         * The real shape of this: a system queries a component the world does not
         * know, so building that query instance throws — naming the component,
         * which is the useful error. The runner used to publish its query cache
         * before filling it, so the next frame found a short array, read
         * `undefined` where the failing query belonged, and reported
         * "cannot read properties of undefined (reading 'resetTick')" from then
         * on. Every frame after the first blamed the runner and the true cause
         * scrolled out of the log.
         */
        it('re-raises the real error next frame instead of a resetTick TypeError', () => {
            const Broken = defineComponent('SysTestBroken', { v: 0 });
            (world.resolveGetter as ReturnType<typeof vi.fn>).mockImplementation(
                (comp: { _name: string }) => {
                    if (comp._name === 'SysTestBroken') throw new Error('component SysTestBroken is not registered');
                    return null;
                },
            );
            const fn = vi.fn();
            const sys = defineSystem([Query(Position), Query(Broken)], fn);

            expect(() => runner.run(sys)).toThrow(/SysTestBroken is not registered/);
            expect(() => runner.run(sys)).toThrow(/SysTestBroken is not registered/);
            expect(() => runner.run(sys)).not.toThrow(/resetTick/);
            expect(fn).not.toHaveBeenCalled();
        });

        it('still caches query instances across runs when setup succeeds', () => {
            const seen: unknown[] = [];
            const sys = defineSystem([Query(Position), Query(Velocity)], (a, b) => { seen.push(a, b); });
            runner.run(sys);
            runner.run(sys);
            expect(seen).toHaveLength(4);
            expect(seen[0]).toBe(seen[2]);
            expect(seen[1]).toBe(seen[3]);
        });
    });

    describe('parameter resolution', () => {
        it('should resolve Query parameter', () => {
            let received: unknown = null;
            const sys = defineSystem([Query(Position)], (q) => {
                received = q;
            });
            runner.run(sys);
            expect(received).toBeInstanceOf(QueryInstance);
        });

        it('should accept a Query(Added(...)) change-detection filter (issue #52)', () => {
            let received: unknown = null;
            // Must type-check: Query(Added(...)) is a valid SystemParam, and the
            // callback element is inferred as the unwrapped component data.
            const sys = defineSystem([Query(Added(Position))], (q) => {
                received = q;
                for (const [, pos] of q) {
                    void pos.x;
                }
            });
            runner.run(sys);
            expect(received).toBeInstanceOf(QueryInstance);
        });

        it('should accept a Query(Changed(...)) change-detection filter (issue #52)', () => {
            let received: unknown = null;
            const sys = defineSystem([Query(Changed(Velocity))], (q) => {
                received = q;
                for (const [, vel] of q) {
                    void vel.dx;
                }
            });
            runner.run(sys);
            expect(received).toBeInstanceOf(QueryInstance);
        });

        it('should resolve Res parameter', () => {
            resources.insert(GameState, { score: 42, level: 3 });
            let received: unknown = null;
            const sys = defineSystem([Res(GameState)], (state) => {
                received = state;
            });
            runner.run(sys);
            expect(received).toEqual({ score: 42, level: 3 });
        });

        it('should resolve ResMut parameter', () => {
            resources.insert(GameState, { score: 0, level: 1 });
            let received: unknown = null;
            const sys = defineSystem([ResMut(GameState)], (state) => {
                received = state;
            });
            runner.run(sys);
            expect(received).toBeInstanceOf(ResMutInstance);
        });

        it('should resolve Commands parameter', () => {
            let received: unknown = null;
            const sys = defineSystem([Commands()], (cmds) => {
                received = cmds;
            });
            runner.run(sys);
            expect(received).toBeInstanceOf(CommandsInstance);
        });

        it('should resolve EventWriter parameter', () => {
            let received: unknown = null;
            const sys = defineSystem([EventWriter(DamageEvent)], (writer) => {
                received = writer;
            });
            runner.run(sys);
            expect(received).toBeInstanceOf(EventWriterInstance);
        });

        it('should resolve EventReader parameter', () => {
            let received: unknown = null;
            const sys = defineSystem([EventReader(DamageEvent)], (reader) => {
                received = reader;
            });
            runner.run(sys);
            expect(received).toBeInstanceOf(EventReaderInstance);
        });

        it('should resolve Removed parameter', () => {
            let received: unknown = null;
            const sys = defineSystem([Removed(Position)], (removed) => {
                received = removed;
            });
            runner.run(sys);
            expect(received).toBeInstanceOf(RemovedQueryInstance);
        });

        it('should resolve GetWorld parameter', () => {
            let received: unknown = null;
            const sys = defineSystem([GetWorld()], (w) => {
                received = w;
            });
            runner.run(sys);
            expect(received).toBe(world);
        });

        it('should resolve multiple mixed parameters', () => {
            resources.insert(GameState, { score: 10, level: 2 });
            const received: unknown[] = [];
            const sys = defineSystem(
                [Query(Position), Res(GameState), Commands()],
                (q, state, cmds) => {
                    received.push(q, state, cmds);
                }
            );
            runner.run(sys);
            expect(received[0]).toBeInstanceOf(QueryInstance);
            expect(received[1]).toEqual({ score: 10, level: 2 });
            expect(received[2]).toBeInstanceOf(CommandsInstance);
        });
    });

    describe('Commands auto-flush', () => {
        it('should flush Commands after system runs', () => {
            const sys = defineSystem([Commands()], (cmds) => {
                cmds.despawn(1 as Entity);
            });
            runner.run(sys);
            expect((world.despawn as any) || true).toBeTruthy();
        });
    });

    describe('resetIterationDepth', () => {
        it('should call resetIterationDepth after system runs', () => {
            const sys = defineSystem([], () => {});
            runner.run(sys);
            expect((world as any).resetIterationDepth).toHaveBeenCalled();
        });

        it('should call resetIterationDepth even if system throws', () => {
            const sys = defineSystem([], () => {
                throw new Error('boom');
            });
            expect(() => runner.run(sys)).toThrow('boom');
            expect((world as any).resetIterationDepth).toHaveBeenCalled();
        });
    });

    describe('system tick tracking', () => {
        it('should update system tick after run', () => {
            mockWorld.worldTick.value = 5;
            const sys = defineSystem([], () => {});
            runner.run(sys);
            // Second run should have lastRunTick from first run
            mockWorld.worldTick.value = 10;
            runner.run(sys);
            // Verify the world tick is queried
            expect((world as any).getWorldTick).toHaveBeenCalled();
        });
    });

    describe('args caching', () => {
        it('should reuse args array on subsequent runs', () => {
            const calls: unknown[][] = [];
            const sys = defineSystem([Res(GameState)], (...args: unknown[]) => {
                calls.push(args);
            });
            resources.insert(GameState, { score: 0, level: 1 });
            runner.run(sys);
            runner.run(sys);
            expect(calls).toHaveLength(2);
        });
    });

    describe('EventRegistry not available', () => {
        it('should throw when EventWriter used without registry', () => {
            const runnerNoEvents = new SystemRunner(world, resources);
            const sys = defineSystem([EventWriter(DamageEvent)], () => {});
            expect(() => runnerNoEvents.run(sys)).toThrow('EventRegistry not available');
        });

        it('should throw when EventReader used without registry', () => {
            const runnerNoEvents = new SystemRunner(world, resources);
            const sys = defineSystem([EventReader(DamageEvent)], () => {});
            expect(() => runnerNoEvents.run(sys)).toThrow('EventRegistry not available');
        });
    });

    describe('unknown parameter type', () => {
        it('should throw for unknown parameter type', () => {
            const badParam = { _type: 'unknown_thing' } as any;
            const sys = defineSystem([badParam], () => {});
            expect(() => runner.run(sys)).toThrow('Unknown system parameter type');
        });
    });

    describe('evict and reset', () => {
        it('evict should clear cached state for a system', () => {
            const fn = vi.fn();
            const sys = defineSystem([], fn);
            runner.run(sys);
            expect(fn).toHaveBeenCalledOnce();

            runner.evict(sys._id);
            runner.run(sys);
            expect(fn).toHaveBeenCalledTimes(2);
        });

        it('reset should clear all cached state', () => {
            const fn1 = vi.fn();
            const fn2 = vi.fn();
            const sys1 = defineSystem([], fn1);
            const sys2 = defineSystem([], fn2);
            runner.run(sys1);
            runner.run(sys2);

            runner.reset();
            runner.run(sys1);
            runner.run(sys2);
            expect(fn1).toHaveBeenCalledTimes(2);
            expect(fn2).toHaveBeenCalledTimes(2);
        });
    });
});