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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// 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([]);
});
});