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, afterEach, vi } from 'vitest';
import {
Renderer,
RenderStage,
initRendererAPI,
shutdownRendererAPI,
} from '../src/render/renderer';
import type { RenderStats } from '../src/render/renderer';
import type { ESEngineModule } from '../src/wasm';
import { initResourceManager, shutdownResourceManager } from '../src/wasm/resourceManager';
// =============================================================================
// Mock WASM module for Renderer API
// =============================================================================
function createRendererMockModule() {
const heapBuffer = new ArrayBuffer(1024 * 1024);
const resourceManager = {
measureBitmapText: vi.fn(() => ({ width: 120, height: 30 })),
};
const mock = {
_malloc: vi.fn((size: number) => size),
_free: vi.fn(),
HEAPF32: new Float32Array(heapBuffer),
renderer_init: vi.fn(),
renderer_resize: vi.fn(),
renderer_begin: vi.fn(),
renderer_flush: vi.fn(),
renderer_end: vi.fn(),
renderer_beginFrame: vi.fn(),
renderer_updateTransforms: vi.fn(),
renderer_submitAll: vi.fn(),
renderer_createTarget: vi.fn(() => 42),
renderer_releaseTarget: vi.fn(),
renderer_getTargetTexture: vi.fn(() => 100),
renderer_getTargetDepthTexture: vi.fn(() => 200),
renderer_setClearColor: vi.fn(),
renderer_setViewport: vi.fn(),
renderer_setStage: vi.fn(),
renderer_getDrawCalls: vi.fn(() => 10),
renderer_getGpuDrawCalls: vi.fn(() => 31),
renderer_getTriangles: vi.fn(() => 500),
renderer_getSprites: vi.fn(() => 25),
renderer_getText: vi.fn(() => 5),
renderer_getSkeletal: vi.fn(() => 3),
renderer_getMeshes: vi.fn(() => 8),
renderer_getCulled: vi.fn(() => 12),
resourceManager,
getResourceManager: vi.fn(() => resourceManager),
};
return mock;
}
type MockModule = ReturnType<typeof createRendererMockModule>;
// =============================================================================
// Tests
// =============================================================================
describe('Renderer API', () => {
let mock: MockModule;
beforeEach(() => {
mock = createRendererMockModule();
initResourceManager(mock.getResourceManager() as any);
initRendererAPI(mock as unknown as ESEngineModule);
});
afterEach(() => {
shutdownRendererAPI();
shutdownResourceManager();
});
// =========================================================================
// initRendererAPI / shutdownRendererAPI
// =========================================================================
// The mock returns the size as the pointer, so each buffer is its own value.
const allocated = (): number[] => mock._malloc.mock.results.map((r) => r.value as number);
const freed = (): number[] => mock._free.mock.calls.map((c) => c[0] as number);
describe('initRendererAPI', () => {
it('should allocate a viewProjection buffer (16 * 4 = 64 bytes)', () => {
expect(mock._malloc).toHaveBeenCalledWith(64);
});
});
describe('shutdownRendererAPI', () => {
// Every reader that marshals through the heap takes a buffer here. A
// COUNT has to be rewritten each time one is added, which is how it comes
// to be updated rather than read; the invariant does not move.
it('gives back every scratch buffer it took, and takes nothing else', () => {
shutdownRendererAPI();
expect([...freed()].sort()).toEqual([...allocated()].sort());
});
it('should handle double shutdown gracefully', () => {
shutdownRendererAPI();
const once = freed().length;
shutdownRendererAPI();
expect(freed()).toHaveLength(once);
});
});
// =========================================================================
// Uninitialized guard
// =========================================================================
describe('uninitialized guard', () => {
beforeEach(() => {
shutdownRendererAPI();
});
it('should return silently from begin when uninitialized', () => {
const vp = new Float32Array(16);
expect(() => Renderer.begin(vp)).not.toThrow();
expect(mock.renderer_begin).not.toHaveBeenCalled();
});
it('should return all-zero stats when uninitialized', () => {
const stats = Renderer.getStats();
expect(stats).toEqual({
drawCalls: 0,
gpuDraws: 0,
triangles: 0,
sprites: 0,
text: 0,
skeletal: 0,
meshes: 0,
culled: 0,
});
});
it('should return zero-size from measureBitmapText when uninitialized', () => {
const result = Renderer.measureBitmapText(1, 'hello', 16, 0);
expect(result).toEqual({ width: 0, height: 0 });
});
it('should no-op beginFrame when uninitialized', () => {
Renderer.beginFrame();
expect(mock.renderer_beginFrame).not.toHaveBeenCalled();
});
it('should no-op updateTransforms when uninitialized', () => {
Renderer.updateTransforms({ _cpp: 1 as any });
expect(mock.renderer_updateTransforms).not.toHaveBeenCalled();
});
it('should no-op submitAll when uninitialized', () => {
Renderer.submitAll({ _cpp: 1 as any }, 0, 0, 800, 600);
expect(mock.renderer_submitAll).not.toHaveBeenCalled();
});
});
// =========================================================================
// Renderer.init
// =========================================================================
describe('Renderer.init', () => {
it('should call renderer_init with width and height', () => {
Renderer.init(800, 600);
expect(mock.renderer_init).toHaveBeenCalledWith(800, 600);
});
});
// =========================================================================
// Renderer.resize
// =========================================================================
describe('Renderer.resize', () => {
it('should call renderer_resize with width and height', () => {
Renderer.resize(1024, 768);
expect(mock.renderer_resize).toHaveBeenCalledWith(1024, 768);
});
});
// =========================================================================
// Renderer.begin
// =========================================================================
describe('Renderer.begin', () => {
it('should copy viewProjection to HEAPF32 and call renderer_begin', () => {
const vp = new Float32Array(16);
for (let i = 0; i < 16; i++) vp[i] = i + 1;
Renderer.begin(vp);
const ptr = 64;
const offset = ptr / 4;
for (let i = 0; i < 16; i++) {
expect(mock.HEAPF32[offset + i]).toBe(i + 1);
}
// No clear requested: flags 0, defaults, empty rect (load-op contract).
expect(mock.renderer_begin).toHaveBeenCalledWith(ptr, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0);
});
it('should default target to 0 when not specified', () => {
Renderer.begin(new Float32Array(16));
expect(mock.renderer_begin).toHaveBeenCalledWith(expect.any(Number), 0, 0, 0, 0, 0, 1, 0, 0, 0, 0);
});
it('should pass target when specified', () => {
Renderer.begin(new Float32Array(16), 5);
expect(mock.renderer_begin).toHaveBeenCalledWith(expect.any(Number), 5, 0, 0, 0, 0, 1, 0, 0, 0, 0);
});
it('carries the clear as a load-op: flags, color, and region', () => {
Renderer.begin(new Float32Array(16), 0, 3,
{ x: 0.2, y: 0.4, z: 0.6, w: 1 }, { x: 10, y: 20, w: 400, h: 300 });
expect(mock.renderer_begin).toHaveBeenCalledWith(
expect.any(Number), 0, 3, 0.2, 0.4, 0.6, 1, 10, 20, 400, 300);
});
});
// =========================================================================
// Renderer.flush
// =========================================================================
describe('Renderer.flush', () => {
it('should call renderer_flush', () => {
Renderer.flush();
expect(mock.renderer_flush).toHaveBeenCalledOnce();
});
});
// =========================================================================
// Renderer.end
// =========================================================================
describe('Renderer.end', () => {
it('should call renderer_end', () => {
Renderer.end();
expect(mock.renderer_end).toHaveBeenCalledOnce();
});
});
// =========================================================================
// Renderer.beginFrame
// =========================================================================
describe('Renderer.beginFrame', () => {
it('should call renderer_beginFrame', () => {
Renderer.beginFrame();
expect(mock.renderer_beginFrame).toHaveBeenCalledOnce();
});
});
// =========================================================================
// Renderer.updateTransforms
// =========================================================================
describe('Renderer.updateTransforms', () => {
it('should call renderer_updateTransforms with registry._cpp', () => {
const registry = { _cpp: 99 as any };
Renderer.updateTransforms(registry);
expect(mock.renderer_updateTransforms).toHaveBeenCalledWith(99);
});
});
// =========================================================================
// Renderer.submitAll
// =========================================================================
describe('Renderer.submitAll', () => {
it('should call renderer_submitAll with registry and viewport', () => {
const registry = { _cpp: 55 as any };
Renderer.submitAll(registry, 10, 20, 800, 600);
expect(mock.renderer_submitAll).toHaveBeenCalledWith(55, 10, 20, 800, 600);
});
});
// =========================================================================
// RenderTarget lifecycle
// =========================================================================
describe('RenderTarget lifecycle', () => {
it('should create render target and return handle from WASM', () => {
const handle = Renderer.createRenderTarget(256, 256);
expect(handle).toBe(42);
expect(mock.renderer_createTarget).toHaveBeenCalledWith(256, 256, 1);
});
it('should default flags to 1', () => {
Renderer.createRenderTarget(128, 128);
expect(mock.renderer_createTarget).toHaveBeenCalledWith(128, 128, 1);
});
it('should pass custom flags', () => {
Renderer.createRenderTarget(128, 128, 3);
expect(mock.renderer_createTarget).toHaveBeenCalledWith(128, 128, 3);
});
it('should release render target', () => {
const handle = Renderer.createRenderTarget(256, 256);
Renderer.releaseRenderTarget(handle);
expect(mock.renderer_releaseTarget).toHaveBeenCalledWith(handle);
});
it('should get target texture', () => {
const tex = Renderer.getTargetTexture(42);
expect(tex).toBe(100);
expect(mock.renderer_getTargetTexture).toHaveBeenCalledWith(42);
});
it('should get target depth texture', () => {
const depthTex = Renderer.getTargetDepthTexture(42);
expect(depthTex).toBe(200);
expect(mock.renderer_getTargetDepthTexture).toHaveBeenCalledWith(42);
});
it('should return 0 for createRenderTarget when uninitialized', () => {
shutdownRendererAPI();
expect(Renderer.createRenderTarget(256, 256)).toBe(0);
});
it('should return 0 for getTargetTexture when uninitialized', () => {
shutdownRendererAPI();
expect(Renderer.getTargetTexture(1)).toBe(0);
});
it('should return 0 for getTargetDepthTexture when uninitialized', () => {
shutdownRendererAPI();
expect(Renderer.getTargetDepthTexture(1)).toBe(0);
});
});
// =========================================================================
// Rendering state
// =========================================================================
describe('Rendering state', () => {
it('should call renderer_setClearColor', () => {
Renderer.setClearColor(0.1, 0.2, 0.3, 1.0);
expect(mock.renderer_setClearColor).toHaveBeenCalledWith(0.1, 0.2, 0.3, 1.0);
});
it('should call renderer_setViewport', () => {
Renderer.setViewport(0, 0, 800, 600);
expect(mock.renderer_setViewport).toHaveBeenCalledWith(0, 0, 800, 600);
});
it('should call renderer_setStage', () => {
Renderer.setStage(RenderStage.Transparent);
expect(mock.renderer_setStage).toHaveBeenCalledWith(RenderStage.Transparent);
});
});
// =========================================================================
// RenderStage enum
// =========================================================================
describe('RenderStage enum', () => {
it('should have correct values', () => {
expect(RenderStage.Background).toBe(0);
expect(RenderStage.Opaque).toBe(1);
expect(RenderStage.Transparent).toBe(2);
expect(RenderStage.Overlay).toBe(3);
});
});
// =========================================================================
// getStats
// =========================================================================
describe('Renderer.getStats', () => {
it('should aggregate stats from WASM calls', () => {
const stats = Renderer.getStats();
expect(stats).toEqual({
drawCalls: 10,
gpuDraws: 31,
triangles: 500,
sprites: 25,
text: 5,
skeletal: 3,
meshes: 8,
culled: 12,
});
});
it('should call all stat getter functions', () => {
Renderer.getStats();
expect(mock.renderer_getDrawCalls).toHaveBeenCalledOnce();
expect(mock.renderer_getTriangles).toHaveBeenCalledOnce();
expect(mock.renderer_getSprites).toHaveBeenCalledOnce();
expect(mock.renderer_getText).toHaveBeenCalledOnce();
expect(mock.renderer_getSkeletal).toHaveBeenCalledOnce();
expect(mock.renderer_getMeshes).toHaveBeenCalledOnce();
expect(mock.renderer_getCulled).toHaveBeenCalledOnce();
});
});
// =========================================================================
// measureBitmapText
// =========================================================================
describe('Renderer.measureBitmapText', () => {
it('should proxy to resourceManager.measureBitmapText()', () => {
const result = Renderer.measureBitmapText(1, 'hello', 16, 0);
expect(result).toEqual({ width: 120, height: 30 });
});
it('should pass all arguments to measureBitmapText', () => {
Renderer.measureBitmapText(7, 'test', 24, 2);
expect(mock.resourceManager.measureBitmapText).toHaveBeenCalledWith(7, 'test', 24, 2);
});
});
// =========================================================================
// HEAPF32 viewProjection copy
// =========================================================================
describe('HEAPF32 viewProjection copy', () => {
it('should write Float32Array values at correct offset', () => {
const vp = new Float32Array([
1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
10, 20, 0, 1,
]);
Renderer.begin(vp);
const ptr = 64;
const offset = ptr / 4;
expect(mock.HEAPF32[offset + 0]).toBe(1);
expect(mock.HEAPF32[offset + 5]).toBe(1);
expect(mock.HEAPF32[offset + 10]).toBe(1);
expect(mock.HEAPF32[offset + 12]).toBe(10);
expect(mock.HEAPF32[offset + 13]).toBe(20);
expect(mock.HEAPF32[offset + 15]).toBe(1);
});
});
});