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 } from 'vitest';
import {
resolveAssetGroup,
resolveAtlas,
activeRemoteRoot,
modeToDelivery,
folderGroupMode,
withFolderGroup,
withActiveRemoteRoot,
type AssetGroupsConfig,
} from '../src/asset/assetGroups';
describe('modeToDelivery', () => {
it('maps subpackage → lazy, others to themselves', () => {
expect(modeToDelivery('subpackage')).toBe('lazy');
expect(modeToDelivery('remote')).toBe('remote');
expect(modeToDelivery('local')).toBe('local');
});
});
describe('resolveAssetGroup — explicit config decouples delivery from folder name', () => {
const config: AssetGroupsConfig = {
version: '1.0',
groups: {
dlc: { folder: 'assets/dlc', mode: 'remote' },
level2: { folder: 'assets/level2', mode: 'subpackage' },
hd: { folder: 'assets/dlc/hd', mode: 'subpackage' }, // nested, longer prefix
},
};
it('assigns an ordinarily-named folder to a remote group', () => {
expect(resolveAssetGroup('assets/dlc/boss.png', config)).toEqual({ name: 'dlc', delivery: 'remote', alwaysInclude: false });
});
it('maps a subpackage-mode group to lazy delivery', () => {
expect(resolveAssetGroup('assets/level2/map.png', config)).toEqual({ name: 'level2', delivery: 'lazy', alwaysInclude: false });
});
it('longest folder prefix wins for nested groups', () => {
expect(resolveAssetGroup('assets/dlc/hd/[email protected]', config)).toEqual({ name: 'hd', delivery: 'lazy', alwaysInclude: false });
expect(resolveAssetGroup('assets/dlc/boss.png', config)).toEqual({ name: 'dlc', delivery: 'remote', alwaysInclude: false });
});
it('unconfigured paths fall through to main/local', () => {
expect(resolveAssetGroup('assets/hero.png', config)).toEqual({ name: 'main', delivery: 'local', alwaysInclude: false });
});
it('normalizes backslashes and a trailing folder slash', () => {
const cfg: AssetGroupsConfig = { version: '1.0', groups: { g: { folder: 'assets/g/', mode: 'remote' } } };
expect(resolveAssetGroup('assets\\g\\a.png', cfg)).toEqual({ name: 'g', delivery: 'remote', alwaysInclude: false });
});
});
describe('resolveAssetGroup — legacy folder-name convention (fallback / back-compat)', () => {
it('still honors subpackages/<name>/ and remote/<name>/ with no config', () => {
expect(resolveAssetGroup('subpackages/level1/a.png', null)).toEqual({ name: 'level1', delivery: 'lazy', alwaysInclude: false });
expect(resolveAssetGroup('remote/cdn/a.png', null)).toEqual({ name: 'cdn', delivery: 'remote', alwaysInclude: false });
expect(resolveAssetGroup('assets/a.png', null)).toEqual({ name: 'main', delivery: 'local', alwaysInclude: false });
});
it('explicit config takes priority over the folder-name convention', () => {
const cfg: AssetGroupsConfig = { version: '1.0', groups: { pack: { folder: 'remote/cdn', mode: 'subpackage' } } };
// The path is under remote/cdn/, but the config re-declares it a subpackage.
expect(resolveAssetGroup('remote/cdn/a.png', cfg)).toEqual({ name: 'pack', delivery: 'lazy', alwaysInclude: false });
});
});
describe('withFolderGroup / folderGroupMode — the editor authoring mutation', () => {
it('adds a remote group for an ordinarily-named folder', () => {
const cfg = withFolderGroup(null, 'assets/cdn', 'remote');
expect(cfg.groups).toEqual({ cdn: { folder: 'assets/cdn', mode: 'remote' } });
expect(folderGroupMode(cfg, 'assets/cdn')).toBe('remote');
});
it('local removes the folder\'s group', () => {
const withGroup = withFolderGroup(null, 'assets/cdn', 'subpackage');
const cleared = withFolderGroup(withGroup, 'assets/cdn', 'local');
expect(cleared.groups).toEqual({});
expect(folderGroupMode(cleared, 'assets/cdn')).toBe('local');
});
it('re-marking a folder replaces its mode, not duplicates it', () => {
let cfg = withFolderGroup(null, 'assets/cdn', 'remote');
cfg = withFolderGroup(cfg, 'assets/cdn', 'subpackage');
expect(Object.keys(cfg.groups ?? {})).toHaveLength(1);
expect(folderGroupMode(cfg, 'assets/cdn')).toBe('subpackage');
});
it('dedupes the group name when two folders share a last segment', () => {
let cfg = withFolderGroup(null, 'assets/a/cdn', 'remote');
cfg = withFolderGroup(cfg, 'assets/b/cdn', 'remote');
expect(Object.keys(cfg.groups ?? {}).sort()).toEqual(['cdn', 'cdn2']);
expect(folderGroupMode(cfg, 'assets/b/cdn')).toBe('remote');
});
it('folderGroupMode is per-folder (a parent group does not count for a child)', () => {
const cfg = withFolderGroup(null, 'assets/dlc', 'remote');
expect(folderGroupMode(cfg, 'assets/dlc')).toBe('remote');
expect(folderGroupMode(cfg, 'assets/dlc/hd')).toBe('local'); // not directly configured
});
it('preserves profiles when editing groups', () => {
const base: AssetGroupsConfig = { version: '1.0', activeProfile: 'dev', profiles: { dev: { remoteRoot: 'u' } } };
const cfg = withFolderGroup(base, 'assets/cdn', 'remote');
expect(cfg.profiles).toEqual({ dev: { remoteRoot: 'u' } });
expect(cfg.activeProfile).toBe('dev');
});
});
describe('withActiveRemoteRoot', () => {
it('sets the active profile CDN root, creating a dev profile by default', () => {
const cfg = withActiveRemoteRoot(null, 'https://cdn.x');
expect(cfg.activeProfile).toBe('dev');
expect(activeRemoteRoot(cfg)).toBe('https://cdn.x');
});
it('updates the existing active profile and preserves groups', () => {
const base = withFolderGroup(null, 'assets/cdn', 'remote');
const cfg = withActiveRemoteRoot({ ...base, activeProfile: 'prod', profiles: { prod: {} } }, 'https://p');
expect(activeRemoteRoot(cfg)).toBe('https://p');
expect(cfg.groups).toEqual({ cdn: { folder: 'assets/cdn', mode: 'remote' } });
});
});
describe('activeRemoteRoot', () => {
const config: AssetGroupsConfig = {
version: '1.0',
activeProfile: 'dev',
profiles: {
dev: { remoteRoot: 'http://localhost:8080/' },
prod: { remoteRoot: 'https://cdn.mygame.com' },
},
};
it('returns the active profile CDN root, trailing slash trimmed', () => {
expect(activeRemoteRoot(config)).toBe('http://localhost:8080');
});
it('follows activeProfile when switched', () => {
expect(activeRemoteRoot({ ...config, activeProfile: 'prod' })).toBe('https://cdn.mygame.com');
});
it('undefined when no active profile / no root / no config', () => {
expect(activeRemoteRoot(null)).toBeUndefined();
expect(activeRemoteRoot({ version: '1.0' })).toBeUndefined();
expect(activeRemoteRoot({ version: '1.0', activeProfile: 'x', profiles: { x: {} } })).toBeUndefined();
expect(activeRemoteRoot({ version: '1.0', activeProfile: 'missing', profiles: { dev: { remoteRoot: 'u' } } })).toBeUndefined();
});
it('carries a group\'s always-include declaration through to the cook', () => {
const cfg: AssetGroupsConfig = {
version: '1.0',
groups: {
markup: { folder: 'assets/markup', mode: 'local', alwaysInclude: true },
plain: { folder: 'assets/plain', mode: 'local' },
},
};
// What only code names (a rich-text <img>, a path built at run time) ships
// because the project said so — reachability from a scene would cull it.
expect(resolveAssetGroup('assets/markup/heart.png', cfg).alwaysInclude).toBe(true);
expect(resolveAssetGroup('assets/plain/hero.png', cfg).alwaysInclude).toBe(false);
});
});
describe('resolveAtlas — packing is its own axis, declared or by folder', () => {
const config: AssetGroupsConfig = {
version: '1.0',
groups: { cdn: { folder: 'assets/art', mode: 'remote' } },
atlases: { ui: { folder: 'assets/art/ui' } },
};
it('packs a texture into the atlas whose folder is the longest prefix', () => {
expect(resolveAtlas('assets/art/ui/button.png', config)).toEqual({ name: 'ui', folder: 'assets/art/ui' });
});
it('leaves a texture outside every declared folder standalone', () => {
expect(resolveAtlas('assets/art/background.png', config)).toBeNull();
});
// The two axes are independent: this texture is in the `cdn` DELIVERY group
// and the `ui` atlas at once, which a flag on the group could not express.
it('is orthogonal to the delivery group', () => {
expect(resolveAssetGroup('assets/art/ui/button.png', config).name).toBe('cdn');
expect(resolveAtlas('assets/art/ui/button.png', config)?.name).toBe('ui');
});
it('falls back to the <name>.atlas/ folder convention, keyed by directory', () => {
expect(resolveAtlas('assets/textures/sprites.atlas/player.png', null))
.toEqual({ name: 'assets/textures/sprites.atlas', folder: 'assets/textures/sprites.atlas' });
// Same-named dirs in different places stay distinct atlases.
expect(resolveAtlas('assets/hud/sprites.atlas/heart.png', null)?.name)
.toBe('assets/hud/sprites.atlas');
expect(resolveAtlas('assets/textures/player.png', null)).toBeNull();
});
it('prefers a declared atlas over a .atlas/ folder the file also sits in', () => {
const both: AssetGroupsConfig = { version: '1.0', atlases: { hud: { folder: 'assets/x.atlas' } } };
expect(resolveAtlas('assets/x.atlas/a.png', both)?.name).toBe('hud');
});
});