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.

12.5 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 { defineResource, Res, ResMut, ResourceStorage, ResMutInstance } from '../src/ecs/resource';

describe('Resource System', () => {
    describe('defineResource', () => {
        it('should create a resource with initial data', () => {
            const Counter = defineResource({ count: 0 }, 'Counter');

            expect(Counter._name).toBe('Counter');
            expect(Counter._default).toEqual({ count: 0 });
        });

        it('should create a resource with complex data', () => {
            const GameState = defineResource({
                score: 0,
                level: 1,
                paused: false,
                playerName: 'Player',
            }, 'GameState');

            expect(GameState._default).toEqual({
                score: 0,
                level: 1,
                paused: false,
                playerName: 'Player',
            });
        });

        it('should create a resource with empty data', () => {
            const EmptyResource = defineResource({}, 'EmptyResource');

            expect(EmptyResource._default).toEqual({});
        });
    });

    describe('Res descriptor', () => {
        it('should create immutable resource descriptor', () => {
            const Counter = defineResource({ count: 0 }, 'Counter');
            const descriptor = Res(Counter);

            expect(descriptor).toBeDefined();
            expect(descriptor._resource).toBe(Counter);
        });
    });

    describe('ResMut descriptor', () => {
        it('should create mutable resource descriptor', () => {
            const Counter = defineResource({ count: 0 }, 'Counter');
            const descriptor = ResMut(Counter);

            expect(descriptor).toBeDefined();
            expect(descriptor._resource).toBe(Counter);
        });
    });

    describe('resource data types', () => {
        it('should support numeric resources', () => {
            const DeltaTime = defineResource({ value: 0.016 }, 'DeltaTime');

            expect(DeltaTime._default.value).toBe(0.016);
        });

        it('should support string resources', () => {
            const Config = defineResource({ apiKey: 'test-key' }, 'Config');

            expect(Config._default.apiKey).toBe('test-key');
        });

        it('should support boolean resources', () => {
            const DebugMode = defineResource({ enabled: false }, 'DebugMode');

            expect(DebugMode._default.enabled).toBe(false);
        });

        it('should support array resources', () => {
            const History = defineResource({ events: [] as string[] }, 'History');

            expect(Array.isArray(History._default.events)).toBe(true);
        });

        it('should support nested object resources', () => {
            const Settings = defineResource({
                audio: {
                    volume: 1.0,
                    muted: false,
                },
                graphics: {
                    quality: 'high',
                    vsync: true,
                },
            }, 'Settings');

            expect(Settings._default.audio.volume).toBe(1.0);
            expect(Settings._default.graphics.quality).toBe('high');
        });
    });

    describe('resource naming', () => {
        it('should support different naming conventions', () => {
            const CamelCase = defineResource({ value: 1 }, 'camelCase');
            const PascalCase = defineResource({ value: 2 }, 'PascalCase');
            const snake_case = defineResource({ value: 3 }, 'snake_case');

            expect(CamelCase._name).toBe('camelCase');
            expect(PascalCase._name).toBe('PascalCase');
            expect(snake_case._name).toBe('snake_case');
        });
    });

    describe('complex scenarios', () => {
        it('should handle multiple resources', () => {
            const Time = defineResource({ delta: 0, elapsed: 0 }, 'Time');
            const Input = defineResource({ mouseX: 0, mouseY: 0 }, 'Input');
            const Score = defineResource({ value: 0 }, 'Score');

            expect(Time._name).toBe('Time');
            expect(Input._name).toBe('Input');
            expect(Score._name).toBe('Score');
        });

        it('should support resource composition', () => {
            const Physics = defineResource({
                gravity: { x: 0, y: -9.8 },
                timeScale: 1.0,
                substeps: 4,
            }, 'Physics');

            expect(Physics._default.gravity.y).toBe(-9.8);
            expect(Physics._default.substeps).toBe(4);
        });
    });

    describe('defineResource auto-naming', () => {
        it('should generate a name when none provided', () => {
            const res = defineResource({ v: 0 });
            expect(res._name).toMatch(/^Resource_\d+$/);
        });
    });
});

// =============================================================================
// ResourceStorage
// =============================================================================

describe('ResourceStorage', () => {
    let storage: ResourceStorage;
    const Counter = defineResource({ count: 0 }, 'StorageCounter');
    const Config = defineResource({ debug: false }, 'StorageConfig');

    beforeEach(() => {
        storage = new ResourceStorage();
    });

    describe('insert and get', () => {
        it('should store and retrieve a resource', () => {
            storage.insert(Counter, { count: 42 });
            expect(storage.get(Counter)).toEqual({ count: 42 });
        });

        it('should return default when not inserted', () => {
            expect(storage.get(Counter)).toEqual({ count: 0 });
        });

        it('should overwrite on re-insert', () => {
            storage.insert(Counter, { count: 1 });
            storage.insert(Counter, { count: 2 });
            expect(storage.get(Counter)).toEqual({ count: 2 });
        });
    });

    describe('set', () => {
        it('should set a resource value', () => {
            storage.set(Counter, { count: 99 });
            expect(storage.get(Counter)).toEqual({ count: 99 });
        });
    });

    describe('has', () => {
        it('should return false for missing resource', () => {
            expect(storage.has(Counter)).toBe(false);
        });

        it('should return true after insert', () => {
            storage.insert(Counter, { count: 0 });
            expect(storage.has(Counter)).toBe(true);
        });

        // Self-gating subsystems install on `has` being false, so materialising
        // a default must not answer it — otherwise one system taking the
        // resource as a parameter convinces the gate its plugin is installed.
        it('stays false after a read materialises the default', () => {
            expect(storage.get(Counter)).toEqual({ count: 0 });
            expect(storage.has(Counter)).toBe(false);
            storage.insert(Counter, { count: 7 });
            expect(storage.has(Counter)).toBe(true);
        });

        it('goes back to false after remove, even once read again', () => {
            storage.insert(Counter, { count: 3 });
            storage.remove(Counter);
            storage.get(Counter);
            expect(storage.has(Counter)).toBe(false);
        });

        it('is true after set, which is a value somebody put there', () => {
            storage.get(Counter);
            storage.set(Counter, { count: 5 });
            expect(storage.has(Counter)).toBe(true);
        });
    });

    describe('remove', () => {
        it('should remove an inserted resource', () => {
            storage.insert(Counter, { count: 10 });
            storage.remove(Counter);
            expect(storage.has(Counter)).toBe(false);
        });

        it('should return default after removal', () => {
            storage.insert(Counter, { count: 10 });
            storage.remove(Counter);
            expect(storage.get(Counter)).toEqual({ count: 0 });
        });
    });

    describe('getResMut', () => {
        it('should return a ResMutInstance', () => {
            storage.insert(Counter, { count: 5 });
            const mut = storage.getResMut(Counter);
            expect(mut).toBeInstanceOf(ResMutInstance);
            expect(mut.get()).toEqual({ count: 5 });
        });

        it('should set value back to storage', () => {
            storage.insert(Counter, { count: 0 });
            const mut = storage.getResMut(Counter);
            mut.set({ count: 42 });
            expect(storage.get(Counter)).toEqual({ count: 42 });
        });

        it('should modify value in-place', () => {
            storage.insert(Counter, { count: 10 });
            const mut = storage.getResMut(Counter);
            mut.modify((v) => { v.count += 5; });
            expect(storage.get(Counter)).toEqual({ count: 15 });
        });

        it('should reuse the same ResMutInstance on subsequent calls', () => {
            storage.insert(Counter, { count: 0 });
            const mut1 = storage.getResMut(Counter);
            const mut2 = storage.getResMut(Counter);
            expect(mut1).toBe(mut2);
        });

        it('should update cached instance value on subsequent call', () => {
            storage.insert(Counter, { count: 1 });
            const mut = storage.getResMut(Counter);
            storage.set(Counter, { count: 99 });
            const mut2 = storage.getResMut(Counter);
            expect(mut2.get()).toEqual({ count: 99 });
        });

        it('should use default when resource not inserted', () => {
            const mut = storage.getResMut(Counter);
            expect(mut.get()).toEqual({ count: 0 });
        });

        it('should cleanup pool on remove', () => {
            storage.insert(Counter, { count: 1 });
            const mut1 = storage.getResMut(Counter);
            storage.remove(Counter);
            const mut2 = storage.getResMut(Counter);
            expect(mut1).not.toBe(mut2);
        });
    });

    describe('multiple resources', () => {
        it('should store different resources independently', () => {
            storage.insert(Counter, { count: 10 });
            storage.insert(Config, { debug: true });
            expect(storage.get(Counter)).toEqual({ count: 10 });
            expect(storage.get(Config)).toEqual({ debug: true });
        });
    });

    describe('default isolation', () => {
        it('does not alias the shared default across two storages', () => {
            const Shared = defineResource({ score: 0, tags: [] as string[] }, 'IsoConfig');
            const a = new ResourceStorage();
            const b = new ResourceStorage();

            const va = a.get(Shared);
            va.score = 42;
            va.tags.push('x');

            const vb = b.get(Shared);
            expect(vb.score).toBe(0);
            expect(vb.tags).toEqual([]);
        });

        it('materialising a default never mutates the ResourceDef itself', () => {
            const Shared = defineResource({ n: 0 }, 'IsoConfig2');
            new ResourceStorage().get(Shared).n = 7;
            expect(Shared._default.n).toBe(0);
        });

        it('a class-instance default keeps its prototype and methods (not cloned to a bare object)', () => {
            class Svc { hits = 0; ping(): number { return ++this.hits; } }
            const Service = defineResource(new Svc(), 'IsoService');
            const got = new ResourceStorage().get(Service);
            expect(got).toBeInstanceOf(Svc);
            expect(got.ping()).toBe(1); // method survived; a plain-object clone would throw
        });
    });
});

/** What an inspector shows: the DECLARED name, never one recovered from the id. */
describe('ResourceStorage.entries', () => {
    it('answers the DECLARED name, not the symbol that addresses it', () => {
        const storage = new ResourceStorage();
        storage.insert(defineResource({ total: 0 }, 'EntriesScore'), { total: 3 });

        expect(storage.entries()).toEqual([['EntriesScore', { total: 3 }]]);
    });

    it('includes a slot only a READ has materialised — most of them, in a running game', () => {
        const storage = new ResourceStorage();
        storage.get(defineResource({ phase: 'menu' }, 'EntriesPhase'));

        expect(storage.entries()).toEqual([['EntriesPhase', { phase: 'menu' }]]);
    });

    it('drops a removed one rather than reporting it under an empty name', () => {
        const storage = new ResourceStorage();
        const Gone = defineResource(0, 'EntriesGone');
        storage.insert(Gone, 1);
        storage.remove(Gone);

        expect(storage.entries()).toEqual([]);
    });
});