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, vi, beforeEach } from 'vitest';
import { World } from '../src/ecs/world';
import { createMockModule } from './mocks/wasm';
import { defineComponent, defineBuiltin, Name, Camera } from '../src/ecs/component';
import { INVALID_ENTITY } from '../src/types';
import {
loadSceneData,
loadSceneWithAssets,
loadOwnedSceneWithAssets,
resetWorldTo,
loadComponent,
remapEntityFields,
findEntityByName,
updateCameraAspectRatio,
migrateSceneData,
SCENE_FORMAT_VERSION,
registerSceneComponentCodec,
serializeEntityComponents,
getComponentAssetFields,
getComponentAssetFieldDescriptors,
getComponentSkeletalFieldDescriptor,
type SceneData,
type SceneComponentData,
} from '../src/scene/scene';
import type { Entity } from '../src/types';
import { discoverSceneAssets } from '../src/asset/discoverAssets';
import { initResourceManager, shutdownResourceManager } from '../src/wasm/resourceManager';
const Transform = defineBuiltin('Transform', {
position: { x: 0, y: 0, z: 0 },
rotation: { w: 1, x: 0, y: 0, z: 0 },
scale: { x: 1, y: 1, z: 1 },
});
const UIMask = defineBuiltin('UIMask', {
mode: 0,
enabled: true,
});
const Sprite = defineBuiltin('Sprite', {
texture: 0,
color: { x: 1, y: 1, z: 1, w: 1 },
size: { x: 100, y: 100 },
material: 0,
});
const Slider = defineBuiltin('Slider', {
fillEntity: 0,
handleEntity: 0,
value: 0,
}, { entityFields: ['fillEntity', 'handleEntity'] });
describe('Scene', () => {
let world: World;
beforeEach(() => {
const module = createMockModule();
world = new World();
world.connectCpp(module.getRegistry(), module);
initResourceManager(module.getResourceManager());
});
it.each([loadSceneWithAssets, loadOwnedSceneWithAssets])('registers resolved entity ownership through %s', async (load) => {
const track = vi.fn((_scene, entities: ReadonlyMap<number, Entity>) => {
expect(entities).toBeInstanceOf(Map);
expect(world.valid(entities.get(7)!)).toBe(true);
});
const assets = { preloadSceneAssets: vi.fn(async () => ({missing: [], textureHandles: new Map()})),
resolveSceneAssetPaths: vi.fn(), trackSceneAssetReferences: track };
const data = {version:4,name:'Tracked',entities:[{id:7,name:'Owner',parent:null,children:[],visible:true,components:[]}]};
const entities = await load(world, data as SceneData, {assets: assets as never});
expect(track).toHaveBeenCalledTimes(1);
expect(track.mock.calls[0][1]).toBe(entities);
});
describe('serialize detaches from live storage', () => {
it('clones script-component data so the snapshot does not alias the world', () => {
const Stats = defineComponent('SerStats', { hp: 10, tags: [] as string[] });
const e = world.spawn();
world.insert(e, Stats, { hp: 10, tags: ['a'] });
const snapshot = serializeEntityComponents(world, e);
const snap = snapshot.find((c) => c.type === 'SerStats')!.data as { hp: number; tags: string[] };
// Change the component — a detached snapshot must not follow.
world.update(e, Stats, (live) => {
(live as { hp: number }).hp = 99;
(live as { tags: string[] }).tags.push('b');
});
expect(snap.hp).toBe(10);
expect(snap.tags).toEqual(['a']);
});
});
// =========================================================================
// Component Asset Field Registry
// =========================================================================
describe('Component Asset Field Registry', () => {
it('should return asset fields for registered components', () => {
const fields = getComponentAssetFields('Sprite');
expect(fields).toContain('texture');
expect(fields).toContain('material');
});
it('should return empty array for unregistered component', () => {
const fields = getComponentAssetFields('NonExistent');
expect(fields).toEqual([]);
});
it('should include spine fields when present', () => {
const fields = getComponentAssetFields('SpineAnimation');
expect(fields).toContain('skeletonPath');
expect(fields).toContain('atlasPath');
expect(fields).toContain('material');
});
it('should return field descriptors with type info', () => {
const descriptors = getComponentAssetFieldDescriptors('Sprite');
expect(descriptors).toEqual([
{ field: 'texture', type: 'texture' },
{ field: 'material', type: 'material' },
]);
});
it('should return empty array for unregistered descriptors', () => {
expect(getComponentAssetFieldDescriptors('NonExistent')).toEqual([]);
});
it('pairs a skeletal component`s two halves, and says whose they are', () => {
// The runtime rides along because the pair alone cannot tell a Spine
// skeleton from a DragonBones one — the field names are the same.
expect(getComponentSkeletalFieldDescriptor('SpineAnimation')).toEqual({
skeletonField: 'skeletonPath',
atlasField: 'atlasPath',
runtime: 'spine',
});
expect(getComponentSkeletalFieldDescriptor('DragonBonesAnimation')).toEqual({
skeletonField: 'skeletonPath',
atlasField: 'atlasPath',
runtime: 'dragonbones',
});
});
it('should return null spine descriptor for non-spine component', () => {
expect(getComponentSkeletalFieldDescriptor('Sprite')).toBeNull();
});
});
// =========================================================================
// remapEntityFields
// =========================================================================
describe('remapEntityFields', () => {
it('should remap entity references using entityMap', () => {
const compData: SceneComponentData = {
type: 'Slider',
data: { fillEntity: 10, handleEntity: 20, value: 0.5 },
};
const entityMap = new Map<number, Entity>([
[10, 100 as Entity],
[20, 200 as Entity],
]);
remapEntityFields(compData, entityMap);
expect(compData.data.fillEntity).toBe(100);
expect(compData.data.handleEntity).toBe(200);
expect(compData.data.value).toBe(0.5);
});
it('should set INVALID_ENTITY for missing entity references', () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const compData: SceneComponentData = {
type: 'Slider',
data: { fillEntity: 999, handleEntity: 0 },
};
const entityMap = new Map<number, Entity>();
remapEntityFields(compData, entityMap);
expect(compData.data.fillEntity).toBe(INVALID_ENTITY);
expect(warnSpy).toHaveBeenCalledWith(
expect.stringContaining('Entity reference not found'),
);
warnSpy.mockRestore();
});
it('should not remap INVALID_ENTITY (0) references', () => {
const compData: SceneComponentData = {
type: 'Slider',
data: { fillEntity: INVALID_ENTITY, handleEntity: INVALID_ENTITY },
};
const entityMap = new Map<number, Entity>();
remapEntityFields(compData, entityMap);
expect(compData.data.fillEntity).toBe(INVALID_ENTITY);
expect(compData.data.handleEntity).toBe(INVALID_ENTITY);
});
it('should skip components without entity fields', () => {
const compData: SceneComponentData = {
type: 'Transform',
data: { x: 10, y: 20 },
};
const entityMap = new Map<number, Entity>();
remapEntityFields(compData, entityMap);
expect(compData.data.x).toBe(10);
expect(compData.data.y).toBe(20);
});
it('should skip non-number entity field values', () => {
const compData: SceneComponentData = {
type: 'Slider',
data: { fillEntity: 'not-a-number', handleEntity: null },
};
const entityMap = new Map<number, Entity>();
remapEntityFields(compData, entityMap);
expect(compData.data.fillEntity).toBe('not-a-number');
expect(compData.data.handleEntity).toBeNull();
});
});
// =========================================================================
// loadComponent
// =========================================================================
describe('loadComponent', () => {
it('should load a known component', () => {
const entity = world.spawn();
loadComponent(world, entity, {
type: 'Transform',
data: { position: { x: 10, y: 20, z: 0 } },
});
const transform = world.get(entity, Transform);
expect(transform.position.x).toBe(10);
expect(transform.position.y).toBe(20);
});
it('should carry out-of-band codec fields around insert (strip + replay)', () => {
const captured: Record<string, unknown> = {};
registerSceneComponentCodec('Sprite', {
outOfBandFields: ['_blob'],
importData: (_entity, oob) => { captured.blob = oob._blob; },
});
const entity = world.spawn();
// `_blob` is not a Sprite field; the codec must strip it before
// insert (so validation/insert don't choke) and replay it after.
loadComponent(world, entity, {
type: 'Sprite',
data: { texture: 0, _blob: 'XYZ' },
});
expect(captured.blob).toBe('XYZ');
expect(world.has(entity, Sprite)).toBe(true);
// Cleanup: unregister so the codec doesn't leak into other tests.
registerSceneComponentCodec('Sprite', {});
});
it('should warn for unknown component type', () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const entity = world.spawn();
loadComponent(world, entity, {
type: 'NonExistentComponent',
data: {},
}, 'TestEntity');
expect(warnSpy).toHaveBeenCalledWith(
expect.stringContaining('Unknown component type: NonExistentComponent'),
);
expect(warnSpy).toHaveBeenCalledWith(
expect.stringContaining('on entity "TestEntity"'),
);
warnSpy.mockRestore();
});
it('should warn without entity name when not provided', () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const entity = world.spawn();
loadComponent(world, entity, {
type: 'NonExistentComponent',
data: {},
});
expect(warnSpy).toHaveBeenCalledWith(
expect.stringContaining('Unknown component type: NonExistentComponent'),
);
warnSpy.mockRestore();
});
it('salvages invalid fields — dropped to defaults with a warning, the rest loads', () => {
// One stale string in a saved scene must cost that FIELD, not the
// component (the storage validator throws) and never the scene.
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const entity = world.spawn();
expect(() =>
loadComponent(world, entity, {
type: 'Sprite',
// size.x garbage (nested type mismatch) + a stray top-level key —
// the exact corruption shape a broken automation client once wrote.
data: { texture: 0, size: { x: 'garbage', y: 16 }, 'size.x': '16' },
}, 'ninja'),
).not.toThrow();
expect(world.has(entity, Sprite)).toBe(true);
const sprite = world.get(entity, Sprite);
expect(sprite.size).toMatchObject({ x: 100, y: 100 }); // dropped → default
expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('invalid fields dropped'));
expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('entity "ninja"'));
warnSpy.mockRestore();
});
});
// =========================================================================
// migrateSceneData (versioned, non-mutating)
// =========================================================================
describe('migrateSceneData', () => {
const oneCompScene = (comp: SceneComponentData, version = '1.0'): SceneData => ({
version,
name: 't',
entities: [{ id: 0, name: 'E', parent: null, children: [], components: [comp] }],
});
it('converts LocalTransform / WorldTransform to Transform', () => {
expect(
migrateSceneData(oneCompScene({ type: 'LocalTransform', data: { position: { x: 5, y: 5, z: 0 } } }))
.data.entities[0].components[0].type,
).toBe('Transform');
expect(
migrateSceneData(oneCompScene({ type: 'WorldTransform', data: {} }))
.data.entities[0].components[0].type,
).toBe('Transform');
});
it('converts UIMask mode strings to ints', () => {
expect(migrateSceneData(oneCompScene({ type: 'UIMask', data: { mode: 'scissor' } }))
.data.entities[0].components[0].data.mode).toBe(0);
expect(migrateSceneData(oneCompScene({ type: 'UIMask', data: { mode: 'stencil' } }))
.data.entities[0].components[0].data.mode).toBe(1);
});
it('drops components retired by an engine upgrade, keeping live ones', () => {
const scene: SceneData = {
version: '1.0',
name: 't',
entities: [{
id: 0, name: 'Button', parent: null, children: [],
components: [
{ type: 'Transform', data: { position: { x: 0, y: 0, z: 0 } } },
{ type: 'StateMachine', data: {} },
{ type: 'StateVisuals', data: { states: [] } },
],
}],
};
const { data, migrated } = migrateSceneData(scene);
expect(migrated).toBe(true);
expect(data.entities[0].components.map((c) => c.type)).toEqual(['Transform']);
});
it('reports migrated=true for legacy data, false for current', () => {
expect(migrateSceneData(oneCompScene({ type: 'LocalTransform', data: {} })).migrated).toBe(true);
expect(migrateSceneData(oneCompScene({ type: 'Transform', data: { position: { x: 0, y: 0, z: 0 } } })).migrated).toBe(false);
});
it('stamps the current format version', () => {
expect(migrateSceneData(oneCompScene({ type: 'Transform', data: {} }, '0.9')).data.version)
.toBe(SCENE_FORMAT_VERSION);
});
it('rejects data newer than the engine supports', () => {
expect(() => migrateSceneData({ version: '99.0', name: 't', entities: [] }))
.toThrow(/newer than this engine/);
});
it('does not mutate the caller input (snapshots stay reusable)', () => {
const input = oneCompScene({ type: 'LocalTransform', data: { position: { x: 5, y: 5, z: 0 } } });
migrateSceneData(input);
expect(input.entities[0].components[0].type).toBe('LocalTransform');
expect(input.version).toBe('1.0');
});
});
// =========================================================================
// resetWorldTo (play-state restore)
// =========================================================================
describe('resetWorldTo', () => {
const snapshot = (): SceneData => ({
version: '1.0',
name: 'snap',
entities: [
{ id: 0, name: 'A', parent: null, children: [1], components: [{ type: 'Transform', data: { position: { x: 1, y: 2, z: 0 } } }] },
{ id: 1, name: 'B', parent: 0, children: [], components: [{ type: 'Transform', data: { position: { x: 3, y: 4, z: 0 } } }] },
],
});
it('despawns all entities and reloads the snapshot', () => {
const snap = snapshot();
loadSceneData(world, snap);
expect(world.getAllEntities().length).toBe(2);
// Mutate the live world (as Play would): add an entity.
const extra = world.spawn();
world.insert(extra, Transform, { position: { x: 9, y: 9, z: 0 } });
expect(world.getAllEntities().length).toBe(3);
resetWorldTo(world, snap);
// Extra is gone; A and B are back with their original transforms.
const xs = world.getEntitiesWithComponents([Transform])
.map(e => world.get(e, Transform).position.x)
.sort((a, b) => a - b);
expect(xs).toEqual([1, 3]);
});
it('restores repeatedly from the same snapshot (non-mutating)', () => {
const snap = snapshot();
loadSceneData(world, snap);
world.despawn(world.getAllEntities()[0]);
resetWorldTo(world, snap);
expect(world.getAllEntities().length).toBe(2);
world.despawn(world.getAllEntities()[0]);
resetWorldTo(world, snap);
expect(world.getAllEntities().length).toBe(2);
});
});
// =========================================================================
// loadSceneData (sync)
// =========================================================================
describe('loadSceneData', () => {
it('should spawn entities and return entity map', () => {
const sceneData: SceneData = {
version: '1.0',
name: 'TestScene',
entities: [
{
id: 0,
name: 'Root',
parent: null,
children: [1],
components: [],
},
{
id: 1,
name: 'Child',
parent: 0,
children: [],
components: [],
},
],
};
const entityMap = loadSceneData(world, sceneData);
expect(entityMap.size).toBe(2);
expect(entityMap.has(0)).toBe(true);
expect(entityMap.has(1)).toBe(true);
});
it('should assign Name component to entities', () => {
const sceneData: SceneData = {
version: '1.0',
name: 'TestScene',
entities: [{
id: 0,
name: 'MyEntity',
parent: null,
children: [],
components: [],
}],
};
const entityMap = loadSceneData(world, sceneData);
const entity = entityMap.get(0)!;
const name = world.get(entity, Name);
expect(name.value).toBe('MyEntity');
});
it('should set up parent-child hierarchy', () => {
const setParentSpy = vi.spyOn(world, 'setParent');
const sceneData: SceneData = {
version: '1.0',
name: 'TestScene',
entities: [
{ id: 0, name: 'Root', parent: null, children: [1], components: [] },
{ id: 1, name: 'Child', parent: 0, children: [], components: [] },
],
};
const entityMap = loadSceneData(world, sceneData);
expect(setParentSpy).toHaveBeenCalledWith(
entityMap.get(1),
entityMap.get(0),
);
});
it('should skip invisible entities', () => {
const sceneData: SceneData = {
version: '1.0',
name: 'TestScene',
entities: [
{ id: 0, name: 'Visible', parent: null, children: [], components: [], visible: true },
{ id: 1, name: 'Hidden', parent: null, children: [], components: [], visible: false },
],
};
const entityMap = loadSceneData(world, sceneData);
expect(entityMap.size).toBe(1);
expect(entityMap.has(0)).toBe(true);
expect(entityMap.has(1)).toBe(false);
});
it('should load components for each entity', () => {
const sceneData: SceneData = {
version: '1.0',
name: 'TestScene',
entities: [{
id: 0,
name: 'WithTransform',
parent: null,
children: [],
components: [
{ type: 'Transform', data: { position: { x: 10, y: 20, z: 0 } } },
],
}],
};
const entityMap = loadSceneData(world, sceneData);
const entity = entityMap.get(0)!;
const transform = world.get(entity, Transform);
expect(transform.position.x).toBe(10);
});
it('should handle empty scene', () => {
const sceneData: SceneData = {
version: '1.0',
name: 'EmptyScene',
entities: [],
};
const entityMap = loadSceneData(world, sceneData);
expect(entityMap.size).toBe(0);
});
it('should remap entity fields during component loading', () => {
const sceneData: SceneData = {
version: '1.0',
name: 'SliderScene',
entities: [
{
id: 0,
name: 'SliderRoot',
parent: null,
children: [1, 2],
components: [
{ type: 'Slider', data: { fillEntity: 1, handleEntity: 2, value: 0.5 } },
],
},
{ id: 1, name: 'Fill', parent: 0, children: [], components: [] },
{ id: 2, name: 'Handle', parent: 0, children: [], components: [] },
],
};
const entityMap = loadSceneData(world, sceneData);
const root = entityMap.get(0)!;
const slider = world.get(root, Slider);
expect(slider.fillEntity).toBe(entityMap.get(1));
expect(slider.handleEntity).toBe(entityMap.get(2));
});
it('should handle parent reference to non-existent entity gracefully', () => {
const sceneData: SceneData = {
version: '1.0',
name: 'BrokenParent',
entities: [
{ id: 0, name: 'Orphan', parent: 999, children: [], components: [] },
],
};
const entityMap = loadSceneData(world, sceneData);
expect(entityMap.size).toBe(1);
});
});
// =========================================================================
// loadSceneWithAssets (async)
// =========================================================================
describe('loadSceneWithAssets', () => {
let nextTextureHandle: number;
let nextMaterialHandle: number;
let nextFontHandle: number;
beforeEach(() => {
nextTextureHandle = 100;
nextMaterialHandle = 200;
nextFontHandle = 300;
});
function createMockAssets(overrides?: {
textureHandleMap?: Map<string, number>;
materialHandleMap?: Map<string, number>;
fontHandleMap?: Map<string, number>;
failTextures?: Set<string>;
failMaterials?: Set<string>;
failFonts?: Set<string>;
failSpines?: Set<string>;
}) {
const preloadSceneAssets = vi.fn().mockImplementation(async (sceneData: SceneData) => {
const discovered = discoverSceneAssets(sceneData);
const textureHandles = new Map<string, number>();
const materialHandles = new Map<string, number>();
const fontHandles = new Map<string, number>();
const texturePaths = discovered.byType.get('texture') ?? new Set<string>();
for (const path of texturePaths) {
if (overrides?.failTextures?.has(path)) {
console.warn(`[Assets] Failed to load texture: ${path}`, new Error('load failed'));
textureHandles.set(path, 0);
} else {
const handle = overrides?.textureHandleMap?.get(path) ?? nextTextureHandle++;
textureHandles.set(path, handle);
}
}
const materialPaths = discovered.byType.get('material') ?? new Set<string>();
for (const path of materialPaths) {
if (overrides?.failMaterials?.has(path)) {
console.warn(`[Assets] Failed to load material: ${path}`, new Error('load failed'));
materialHandles.set(path, 0);
} else {
const handle = overrides?.materialHandleMap?.get(path) ?? nextMaterialHandle++;
materialHandles.set(path, handle);
}
}
const fontPaths = discovered.byType.get('font') ?? new Set<string>();
for (const path of fontPaths) {
if (overrides?.failFonts?.has(path)) {
console.warn(`[Assets] Failed to load font: ${path}`, new Error('load failed'));
fontHandles.set(path, 0);
} else {
const handle = overrides?.fontHandleMap?.get(path) ?? nextFontHandle++;
fontHandles.set(path, handle);
}
}
for (const pair of discovered.spines) {
const key = `${pair.skeleton}:${pair.atlas}`;
if (overrides?.failSpines?.has(key)) {
console.warn(`[Assets] Failed to load spine: ${pair.skeleton}`, new Error('load failed'));
}
}
return { textureHandles, materialHandles, fontHandles, releaseCallbacks: [] };
});
const resolveSceneAssetPaths = vi.fn().mockImplementation(
(sceneData: SceneData, result: { textureHandles: Map<string, number>; materialHandles: Map<string, number>; fontHandles: Map<string, number> }) => {
for (const entity of sceneData.entities) {
for (const comp of entity.components) {
const fields = getComponentAssetFieldDescriptors(comp.type);
for (const { field, type } of fields) {
const value = comp.data[field];
if (typeof value !== 'string' || !value) continue;
switch (type) {
case 'texture':
comp.data[field] = result.textureHandles.get(value) ?? 0;
break;
case 'material':
comp.data[field] = result.materialHandles.get(value) ?? 0;
break;
case 'font':
comp.data[field] = result.fontHandles.get(value) ?? 0;
break;
}
}
}
}
},
);
return {
preloadSceneAssets,
resolveSceneAssetPaths,
trackSceneAssetReferences: vi.fn(),
} as any;
}
it('should load scene without assets when no assets option', async () => {
const sceneData: SceneData = {
version: '1.0',
name: 'NoAssets',
entities: [{
id: 0,
name: 'Root',
parent: null,
children: [],
components: [{ type: 'Transform', data: {} }],
}],
};
const entityMap = await loadSceneWithAssets(world, sceneData);
expect(entityMap.size).toBe(1);
});
it('should preload textures and replace path with handle', async () => {
const mockAssets = createMockAssets({
textureHandleMap: new Map([['hero.png', 42]]),
});
const sceneData: SceneData = {
version: '1.0',
name: 'WithTexture',
entities: [{
id: 0,
name: 'SpriteEntity',
parent: null,
children: [],
components: [
{ type: 'Sprite', data: { texture: 'hero.png', material: 0 } },
],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
expect(mockAssets.preloadSceneAssets).toHaveBeenCalledTimes(1);
const entity = world.getEntitiesWithComponents([Sprite])[0];
const sprite = world.get(entity, Sprite);
expect(sprite.texture).toBe(42);
});
it('should preload materials and replace path with handle', async () => {
const mockAssets = createMockAssets({
materialHandleMap: new Map([['custom.mat', 55]]),
});
const sceneData: SceneData = {
version: '1.0',
name: 'WithMaterial',
entities: [{
id: 0,
name: 'SpriteEntity',
parent: null,
children: [],
components: [
{ type: 'Sprite', data: { texture: 0, material: 'custom.mat' } },
],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
const entity = world.getEntitiesWithComponents([Sprite])[0];
const sprite = world.get(entity, Sprite);
expect(sprite.material).toBe(55);
});
it('should preload bitmap fonts and replace path with handle', async () => {
const mockAssets = createMockAssets({
fontHandleMap: new Map([['arial.fnt', 77]]),
});
defineBuiltin('BitmapText', { font: 0, text: '' });
const sceneData: SceneData = {
version: '1.0',
name: 'WithFont',
entities: [{
id: 0,
name: 'TextEntity',
parent: null,
children: [],
components: [
{ type: 'BitmapText', data: { font: 'arial.fnt' } },
],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
expect(mockAssets.preloadSceneAssets).toHaveBeenCalledTimes(1);
});
it('should call preloadSceneAssets for spine assets', async () => {
const mockAssets = createMockAssets();
const sceneData: SceneData = {
version: '1.0',
name: 'WithSpine',
entities: [{
id: 0,
name: 'SpineEntity',
parent: null,
children: [],
components: [{
type: 'SpineAnimation',
data: {
skeletonPath: 'hero.skel',
atlasPath: 'hero.atlas',
material: 0,
},
}],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
expect(mockAssets.preloadSceneAssets).toHaveBeenCalledTimes(1);
});
it('should handle texture load failure gracefully', async () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const mockAssets = createMockAssets({
failTextures: new Set(['missing.png']),
});
const sceneData: SceneData = {
version: '1.0',
name: 'FailedTexture',
entities: [{
id: 0,
name: 'SpriteEntity',
parent: null,
children: [],
components: [
{ type: 'Sprite', data: { texture: 'missing.png', material: 0 } },
],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
expect(warnSpy).toHaveBeenCalledWith(
expect.stringContaining('Failed to load texture'),
expect.any(Error),
);
const entity = world.getEntitiesWithComponents([Sprite])[0];
const sprite = world.get(entity, Sprite);
expect(sprite.texture).toBe(0);
warnSpy.mockRestore();
});
it('should handle material load failure gracefully', async () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const mockAssets = createMockAssets({
failMaterials: new Set(['bad.mat']),
});
const sceneData: SceneData = {
version: '1.0',
name: 'FailedMaterial',
entities: [{
id: 0,
name: 'SpriteEntity',
parent: null,
children: [],
components: [
{ type: 'Sprite', data: { texture: 0, material: 'bad.mat' } },
],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
expect(warnSpy).toHaveBeenCalledWith(
expect.stringContaining('Failed to load material'),
expect.any(Error),
);
const entity = world.getEntitiesWithComponents([Sprite])[0];
const sprite = world.get(entity, Sprite);
expect(sprite.material).toBe(0);
warnSpy.mockRestore();
});
it('should handle font load failure gracefully', async () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const mockAssets = createMockAssets({
failFonts: new Set(['bad.fnt']),
});
const sceneData: SceneData = {
version: '1.0',
name: 'FailedFont',
entities: [{
id: 0,
name: 'TextEntity',
parent: null,
children: [],
components: [
{ type: 'BitmapText', data: { font: 'bad.fnt' } },
],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
expect(warnSpy).toHaveBeenCalledWith(
expect.stringContaining('Failed to load font'),
expect.any(Error),
);
warnSpy.mockRestore();
});
it('should warn on failed spine load', async () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const mockAssets = createMockAssets({
failSpines: new Set(['bad.skel:bad.atlas']),
});
const sceneData: SceneData = {
version: '1.0',
name: 'FailedSpine',
entities: [{
id: 0,
name: 'SpineEntity',
parent: null,
children: [],
components: [{
type: 'SpineAnimation',
data: { skeletonPath: 'bad.skel', atlasPath: 'bad.atlas', material: 0 },
}],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
expect(warnSpy).toHaveBeenCalledWith(
expect.stringContaining('Failed to load spine'),
expect.any(Error),
);
warnSpy.mockRestore();
});
it('should apply textureMetadata sliceBorder via applyTextureMetadata', async () => {
const mockAssets = createMockAssets({
textureHandleMap: new Map([['border.png', 10]]),
});
const sceneData: SceneData = {
version: '1.0',
name: 'WithMetadata',
entities: [{
id: 0,
name: 'Entity',
parent: null,
children: [],
components: [
{ type: 'Sprite', data: { texture: 'border.png', material: 0 } },
],
}],
textureMetadata: {
'border.png': {
version: '1.0',
type: 'texture',
sliceBorder: { left: 10, right: 10, top: 5, bottom: 5 },
},
},
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
expect(mockAssets.preloadSceneAssets).toHaveBeenCalledTimes(1);
expect(mockAssets.resolveSceneAssetPaths).toHaveBeenCalled();
});
it('should skip invisible entities during asset preloading', async () => {
const mockAssets = createMockAssets();
const sceneData: SceneData = {
version: '1.0',
name: 'InvisibleAssets',
entities: [{
id: 0,
name: 'Hidden',
parent: null,
children: [],
components: [
{ type: 'Sprite', data: { texture: 'hidden.png', material: 0 } },
],
visible: false,
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
const result = await mockAssets.preloadSceneAssets.mock.results[0].value;
expect(result.textureHandles.size).toBe(0);
});
it('should replace multiple asset fields on the same component', async () => {
const mockAssets = createMockAssets({
textureHandleMap: new Map([['hero.png', 11]]),
materialHandleMap: new Map([['glow.mat', 22]]),
});
const sceneData: SceneData = {
version: '1.0',
name: 'MultiField',
entities: [{
id: 0,
name: 'Entity',
parent: null,
children: [],
components: [
{ type: 'Sprite', data: { texture: 'hero.png', material: 'glow.mat' } },
],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
const entity = world.getEntitiesWithComponents([Sprite])[0];
const sprite = world.get(entity, Sprite);
expect(sprite.texture).toBe(11);
expect(sprite.material).toBe(22);
});
it('should not modify numeric asset values (already handles)', async () => {
const mockAssets = createMockAssets();
const sceneData: SceneData = {
version: '1.0',
name: 'NumericAsset',
entities: [{
id: 0,
name: 'Entity',
parent: null,
children: [],
components: [
{ type: 'Sprite', data: { texture: 5, material: 0 } },
],
}],
};
await loadSceneWithAssets(world, sceneData, { assets: mockAssets });
const entity = world.getEntitiesWithComponents([Sprite])[0];
const sprite = world.get(entity, Sprite);
expect(sprite.texture).toBe(5);
expect(sprite.material).toBe(0);
});
});
// =========================================================================
// findEntityByName
// =========================================================================
describe('findEntityByName', () => {
it('should find entity by name', () => {
const entity = world.spawn();
world.insert(entity, Name, { value: 'Player' });
const found = findEntityByName(world, 'Player');
expect(found).toBe(entity);
});
it('should return null when entity not found', () => {
const found = findEntityByName(world, 'NonExistent');
expect(found).toBeNull();
});
it('should return last match when multiple entities have same name', () => {
const e1 = world.spawn();
world.insert(e1, Name, { value: 'Duplicate' });
const e2 = world.spawn();
world.insert(e2, Name, { value: 'Duplicate' });
const found = findEntityByName(world, 'Duplicate');
expect(found).toBe(e2);
});
});
// =========================================================================
// updateCameraAspectRatio
// =========================================================================
describe('updateCameraAspectRatio', () => {
it('should update camera aspect ratio', () => {
const entity = world.spawn();
world.insert(entity, Camera, { aspectRatio: 1.0, nearPlane: 0.1, farPlane: 100 });
updateCameraAspectRatio(world, 16 / 9);
const camera = world.get(entity, Camera);
expect(camera.aspectRatio).toBeCloseTo(16 / 9);
});
it('should update all cameras', () => {
const e1 = world.spawn();
world.insert(e1, Camera, { aspectRatio: 1.0 });
const e2 = world.spawn();
world.insert(e2, Camera, { aspectRatio: 1.0 });
updateCameraAspectRatio(world, 2.0);
expect(world.get(e1, Camera).aspectRatio).toBe(2.0);
expect(world.get(e2, Camera).aspectRatio).toBe(2.0);
});
it('should do nothing when no cameras exist', () => {
expect(() => updateCameraAspectRatio(world, 1.5)).not.toThrow();
});
});
});