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
/**
* @file native-assets.test.ts
* @brief The native asset channel (Stage B): the SAME `Assets` class + loaders
* the web build uses, over the native core. A mock host scope stands in
* for the QuickJS globals (es_rm_createTextureEx / es_rm_releaseTexture /
* es_getTextureDimensions) and a mock NativeBridge decodes images, so
* `Assets.loadTexture` flows end-to-end — TextureLoader -> pixel decode ->
* native ResourceManager createTextureFromBytes — with no wasm module,
* headless.
*/
import { afterEach, describe, expect, it, vi } from 'vitest';
import { createNativeApp } from '../src/ecs/bridge/nativeRuntime';
import { setNativeEngineApi } from '../src/ecs/bridge/engineApi';
import { builtinMeshTemplate } from '../src/asset/builtinMeshes';
import { createNativeResourceManager } from '../src/ecs/bridge/nativeResourceManager';
import { Assets } from '../src/asset/AssetPlugin';
import { shutdownResourceManager } from '../src/wasm/resourceManager';
import { TextureContent } from '../src/wasm';
import { setPlatform } from '../src/platform/base';
import type { NativeBridge } from '../src/platform/native/bridge';
import { withRegistryOps } from './helpers/nativeRegistryOps';
/** A mock native ResourceManager scope: a Map-backed texture pool addressed by
* handle, exposed through the es_* host globals the SDK's native RM binds to. */
function makeTextureScope() {
const textures = new Map<number, { width: number; height: number; pixels: Uint8Array; format: number; flip: boolean }>();
let nextHandle = 1;
// The engine's own rm_createTextureEx, as its generated QuickJS wrapper binds
// it: a byte COUNT beside the buffer (a heap offset on the web), and explicit
// filter/wrap codes.
const createSpy = vi.fn(
(width: number, height: number, pixels: Uint8Array, pixelsLen: number,
format: number, flip: boolean, filter: number, wrap: number) => {
const handle = nextHandle++;
textures.set(handle, { width, height, pixels, format, flip });
void pixelsLen; void filter; void wrap;
return handle;
},
);
const releaseSpy = vi.fn((handle: number) => { textures.delete(handle); });
const scope: Record<string, unknown> = {
es_rm_createTextureEx: createSpy,
es_rm_releaseTexture: releaseSpy,
es_getTextureDimensions: (handle: number) => {
const t = textures.get(handle);
return t ? { width: t.width, height: t.height } : null;
},
};
return { scope, textures, createSpy, releaseSpy };
}
/** RGBA pixels for a solid w×h image (top-first), matching loadImagePixels. */
function solidImage(width: number, height: number, r = 255, g = 128, b = 64) {
const pixels = new Uint8Array(width * height * 4);
for (let i = 0; i < pixels.length; i += 4) {
pixels[i] = r; pixels[i + 1] = g; pixels[i + 2] = b; pixels[i + 3] = 255;
}
return { width, height, pixels };
}
/** A NativeBridge that decodes a known image path; other calls are stubs. */
function makeBridge(images: Record<string, { width: number; height: number; pixels: Uint8Array }>) {
const bridge: NativeBridge = {
readFile: async () => new ArrayBuffer(0),
fileExists: async (p) => p in images,
fetch: async () => ({ ok: false, status: 404 }),
loadImagePixels: async (path) => {
const img = images[path];
if (!img) throw new Error(`no image: ${path}`);
return img;
},
getStorageItem: () => null,
setStorageItem: () => {},
removeStorageItem: () => {},
storageKeys: () => [],
registerInput: () => () => {},
devicePixelRatio: () => 1,
};
return bridge;
}
afterEach(() => {
shutdownResourceManager();
// Drop the native platform this suite installed so it can't leak into others.
setPlatform(null as never);
});
describe('createNativeResourceManager', () => {
it('uploads bytes through es_rm_createTextureEx and reads dims / releases', () => {
const { scope, createSpy, releaseSpy } = makeTextureScope();
const rm = createNativeResourceManager(scope);
const px = new Uint8Array([1, 2, 3, 4]);
const handle = rm.createTextureFromBytes!(1, 1, px, 1, true, TextureContent.Asset);
expect(handle).toBe(1);
// Byte count beside the buffer, and the plain path's defaults where the
// caller gave no import settings (filter Linear, wrap ClampToEdge).
expect(createSpy).toHaveBeenCalledWith(1, 1, px, px.length, 1, true, 1, 1, TextureContent.Asset);
expect(rm.getTextureDimensions(handle)).toEqual({ width: 1, height: 1 });
rm.releaseTexture(handle);
expect(releaseSpy).toHaveBeenCalledWith(handle);
expect(rm.getTextureDimensions(handle)).toBeNull();
});
it('makes a texture array from its layers as bytes, without a wasm heap', async () => {
const calls: unknown[][] = [];
const rm = createNativeResourceManager({
es_rm_createTextureArray: (...args: unknown[]) => { calls.push(args); return 7; },
});
const { createTextureArrayFromPixels } = await import('../src/runtime/runtimeAssets');
const a = new Uint8Array(16).fill(1);
const b = new Uint8Array(16).fill(2);
// No module, no heap: the device has neither, and used to refuse the terrain's layer arrays for it.
const handle = createTextureArrayFromPixels(null, { width: 2, height: 2, layers: [a, b] }, TextureContent.Asset, undefined, rm);
expect(handle).toBe(7);
const [w, h, layers, bytes, len] = calls[0] as [number, number, number, Uint8Array, number];
expect([w, h, layers, len]).toEqual([2, 2, 2, 32]);
expect([...bytes]).toEqual([...a, ...b]);
});
it('fails loud on the wasm/GL-only surface (no heap or GL on native)', () => {
const rm = createNativeResourceManager({});
expect(() => rm.createTexture(1, 1, 0, 4, 1, true, TextureContent.Asset)).toThrow(/not supported/);
expect(() => rm.registerExternalTexture(0, 1, 1, TextureContent.Asset)).toThrow(/not supported/);
});
});
describe('native Assets.loadTexture', () => {
it('decodes through the bridge and uploads via the native ResourceManager', async () => {
const { scope, createSpy, releaseSpy } = makeTextureScope();
const bridge = makeBridge({ 'logo.png': solidImage(4, 2) });
const app = createNativeApp(bridge, withRegistryOps(scope));
await app.tick(0); // finish plugin builds + install platform
const assets = app.getResource(Assets);
const tex = await assets.loadTexture('logo.png');
// A real handle from the native pool, with the decoded dimensions.
expect(tex.handle).toBe(1);
expect(tex.width).toBe(4);
expect(tex.height).toBe(2);
// The bytes reached the engine entry point: 4×2 RGBA, format 1 (gamma),
// flip=true, and — with no import settings on this texture — Linear with a
// mip chain (code 1|2), as the WebGL upload gives an asset, and ClampToEdge.
expect(createSpy).toHaveBeenCalledTimes(1);
const [w, h, pixels, pixelsLen, format, flip, filter, wrap] = createSpy.mock.calls[0];
expect([w, h, format, flip, filter, wrap]).toEqual([4, 2, 1, true, 3, 1]);
expect((pixels as Uint8Array).length).toBe(4 * 2 * 4);
expect(pixelsLen).toBe(4 * 2 * 4);
// A second load hits the cache — no second upload.
const again = await assets.loadTexture('logo.png');
expect(again.handle).toBe(1);
expect(createSpy).toHaveBeenCalledTimes(1);
// Releasing both references frees the native texture (no residency budget).
assets.releaseTexture('logo.png');
expect(releaseSpy).not.toHaveBeenCalled(); // still one reference
assets.releaseTexture('logo.png');
expect(releaseSpy).toHaveBeenCalledWith(1);
});
});
// A device's core is the host's bindings, not a wasm module. The two loaders that
// marshal bulk data took only the module, so no native package ever loaded a mesh.
describe('native Assets mesh loading', () => {
it('marshals built-in geometry through the native core, with no wasm module', async () => {
const { scope } = makeTextureScope();
const heap = new Uint8Array(1 << 20);
let brk = 16;
const created: Array<{ channels: number; stride: number; indices: number }> = [];
Object.assign(scope, {
es_heap: () => heap,
es_malloc: (n: number) => { const p = brk; brk += n + (8 - (n % 8)); return p; },
es_free: () => {},
es_mesh_createFromChannels: (
_table: number, channelCount: number, stride: number,
_verts: number, _vertBytes: number, _idx: number, indexCount: number,
) => {
created.push({ channels: channelCount, stride, indices: indexCount });
return 7;
},
});
setNativeEngineApi({
HEAPU8: heap,
HEAPU16: new Uint16Array(heap.buffer),
HEAPU32: new Uint32Array(heap.buffer),
HEAPI32: new Int32Array(heap.buffer),
HEAPF32: new Float32Array(heap.buffer),
HEAPF64: new Float64Array(heap.buffer),
_malloc: (n: number) => (scope.es_malloc as (n: number) => number)(n),
_free: () => {},
mesh_createFromChannels: scope.es_mesh_createFromChannels as never,
});
try {
const app = createNativeApp(makeBridge({}), withRegistryOps(scope));
await app.tick(0);
const assets = app.getResource(Assets);
const scene = {
version: '1.0', name: 'Main',
entities: [{
id: 0, name: 'Block', parent: null, children: [], visible: true,
components: [
{ type: 'Transform', data: {} },
{ type: 'MeshRenderer', data: { mesh: 'builtin:cube' } },
],
}],
};
const result = await assets.preloadSceneAssets(scene as never);
expect(result.missing).toEqual([]);
expect(created).toHaveLength(1);
// The geometry that crossed is the cube's own, not an empty upload.
const cube = builtinMeshTemplate('builtin:cube')!.build();
expect(created[0]!.indices).toBe(cube.indices.length);
expect(created[0]!.channels).toBe(cube.channels.length);
} finally {
setNativeEngineApi(null);
}
});
});