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
//
// The DragonBones side module against a real file. The point of these is the
// geometry: the adapter compiles whether or not its arithmetic is right, and the
// two places it can be wrong quietly — which space a weighted mesh is posed in,
// and whether the pivot is applied before the matrix — both look like a bad export
// rather than like a bug. So the assertions are about numbers, not about success.
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
const DB_JS = resolve(WASM_DIR, 'dragonbones.js');
const DB_WASM = resolve(WASM_DIR, 'dragonbones.wasm');
const ASSET_DIR = resolve(__dirname, 'assets/dragonbones');
const SKE = resolve(ASSET_DIR, 'DragonBoy_ske.json');
const TEX = resolve(ASSET_DIR, 'DragonBoy_tex.json');
const HAS_ASSETS = hasSideModule('dragonbones') && existsSync(SKE);
interface DbModule {
ccall(name: string, ret: string | null, sig: string[], args: unknown[]): never;
_malloc(bytes: number): number;
_free(ptr: number): void;
HEAPU8: Uint8Array;
HEAPF32: Float32Array;
HEAPU32: Uint32Array;
HEAP32: Int32Array;
}
describe.skipIf(!HAS_ASSETS)('DragonBones side module', () => {
let M: DbModule;
const call = <T>(name: string, ret: string | null, sig: string[], args: unknown[]): T =>
M.ccall(name, ret, sig, args) as unknown as T;
/// Copy a buffer into the module's heap; the parsers want bytes it owns.
const put = (buf: Uint8Array): number => {
const ptr = M._malloc(buf.length);
M.HEAPU8.set(buf, ptr);
return ptr;
};
beforeAll(async () => {
const factory = (await import(DB_JS)).default as (a: { wasmBinary: Uint8Array }) => Promise<DbModule>;
M = await factory({ wasmBinary: new Uint8Array(readFileSync(DB_WASM)) });
});
const load = (): number => {
const ske = new Uint8Array(readFileSync(SKE));
const tex = new Uint8Array(readFileSync(TEX));
return call<number>('db_loadSkeleton', 'number', ['number', 'number', 'number', 'number'], [
put(ske), ske.length, put(tex), tex.length,
]);
};
it('reads a file, and names the armatures inside it', () => {
const handle = load();
expect(handle, call<string>('db_getLastError', 'string', [], [])).toBeGreaterThanOrEqual(0);
// A DragonBones file is a project, not a skeleton — hence the list.
expect(JSON.parse(call<string>('db_getArmatures', 'string', ['number'], [handle]))).toEqual(['Dragon']);
expect(call<string>('db_getAtlasImageName', 'string', ['number'], [handle])).toBe('DragonBoy_tex.png');
call('db_unloadSkeleton', null, ['number'], [handle]);
});
it('refuses unreadable data instead of building half an armature', () => {
const junk = new Uint8Array([1, 2, 3, 4]);
const handle = call<number>('db_loadSkeleton', 'number', ['number', 'number', 'number', 'number'], [
put(junk), junk.length, put(junk), junk.length,
]);
expect(handle).toBeLessThan(0);
expect(call<string>('db_getLastError', 'string', [], [])).not.toBe('');
});
it('lists the animations the file declares', () => {
const handle = load();
const instance = call<number>('db_createInstance', 'number', ['number', 'string'], [handle, 'Dragon']);
expect(instance).toBeGreaterThanOrEqual(0);
expect(JSON.parse(call<string>('db_getAnimations', 'string', ['number'], [instance])).sort())
.toEqual(['fall', 'jump', 'stand', 'walk']);
call('db_destroyInstance', null, ['number'], [instance]);
call('db_unloadSkeleton', null, ['number'], [handle]);
});
it('poses triangles once a texture is bound, and none before', () => {
const handle = load();
const instance = call<number>('db_createInstance', 'number', ['number', 'string'], [handle, 'Dragon']);
call('db_playAnimation', 'number', ['number', 'string', 'number'], [instance, 'walk', 0]);
// A slot with no texture has nothing to draw — and must say so rather than
// emitting geometry that samples whatever id 0 happens to be.
call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
expect(call<number>('db_getMeshBatchCount', 'number', ['number'], [instance])).toBe(0);
call('db_setAtlasTexture', null, ['number', 'number'], [handle, 7]);
for (let i = 0; i < 10; i++) call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
const batches = call<number>('db_getMeshBatchCount', 'number', ['number'], [instance]);
expect(batches).toBeGreaterThan(0);
let vertices = 0;
let indices = 0;
for (let b = 0; b < batches; b++) {
vertices += call<number>('db_getMeshBatchVertexCount', 'number', ['number', 'number'], [instance, b]);
indices += call<number>('db_getMeshBatchIndexCount', 'number', ['number', 'number'], [instance, b]);
}
expect(vertices).toBeGreaterThan(0);
expect(indices % 3).toBe(0);
call('db_destroyInstance', null, ['number'], [instance]);
call('db_unloadSkeleton', null, ['number'], [handle]);
});
it('produces finite positions and in-range uvs', () => {
const handle = load();
call('db_setAtlasTexture', null, ['number', 'number'], [handle, 7]);
const instance = call<number>('db_createInstance', 'number', ['number', 'string'], [handle, 'Dragon']);
call('db_playAnimation', 'number', ['number', 'string', 'number'], [instance, 'walk', 0]);
for (let i = 0; i < 10; i++) call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
const vertexCount = call<number>('db_getMeshBatchVertexCount', 'number', ['number', 'number'], [instance, 0]);
const indexCount = call<number>('db_getMeshBatchIndexCount', 'number', ['number', 'number'], [instance, 0]);
const vp = M._malloc(vertexCount * 8 * 4);
const ip = M._malloc(indexCount * 2);
const tp = M._malloc(4);
const bp = M._malloc(4);
call('db_getMeshBatchData', null, ['number', 'number', 'number', 'number', 'number', 'number'], [
instance, 0, vp, ip, tp, bp,
]);
expect(M.HEAPU32[tp >> 2]).toBe(7);
const v = new Float32Array(M.HEAPF32.buffer, vp, vertexCount * 8);
for (let i = 0; i < vertexCount; i++) {
expect(Number.isFinite(v[i * 8])).toBe(true);
expect(Number.isFinite(v[i * 8 + 1])).toBe(true);
// Normalized against the atlas page, so a uv outside this means the
// page size was wrong or a rotated region was unpacked the wrong way.
expect(v[i * 8 + 2]).toBeGreaterThanOrEqual(0);
expect(v[i * 8 + 2]).toBeLessThanOrEqual(1);
expect(v[i * 8 + 3]).toBeGreaterThanOrEqual(0);
expect(v[i * 8 + 3]).toBeLessThanOrEqual(1);
}
call('db_destroyInstance', null, ['number'], [instance]);
call('db_unloadSkeleton', null, ['number'], [handle]);
});
it('tints the armature, multiplying rather than replacing the authored colour', () => {
const handle = load();
call('db_setAtlasTexture', null, ['number', 'number'], [handle, 7]);
const instance = call<number>('db_createInstance', 'number', ['number', 'string'], [handle, 'Dragon']);
call('db_playAnimation', 'number', ['number', 'string', 'number'], [instance, 'stand', 0]);
call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
/// Every vertex's RGBA from batch 0. getMeshBatchCount is what re-poses into
/// the shared batch list — the other getters read that snapshot — so asking
/// for it is how a reader says which instance it means.
const colours = (): { r: number; g: number; b: number; a: number }[] => {
call('db_getMeshBatchCount', 'number', ['number'], [instance]);
const vertexCount = call<number>('db_getMeshBatchVertexCount', 'number', ['number', 'number'], [instance, 0]);
const indexCount = call<number>('db_getMeshBatchIndexCount', 'number', ['number', 'number'], [instance, 0]);
const vp = M._malloc(vertexCount * 8 * 4);
const ip = M._malloc(indexCount * 2);
const tp = M._malloc(4);
const bp = M._malloc(4);
call('db_getMeshBatchData', null, ['number', 'number', 'number', 'number', 'number', 'number'], [
instance, 0, vp, ip, tp, bp,
]);
const v = new Float32Array(M.HEAPF32.buffer, vp, vertexCount * 8);
const out = [];
for (let i = 0; i < vertexCount; i++) {
out.push({ r: v[i * 8 + 4], g: v[i * 8 + 5], b: v[i * 8 + 6], a: v[i * 8 + 7] });
}
M._free(vp); M._free(ip); M._free(tp); M._free(bp);
return out;
};
// Untinted is the identity: whatever the file authored, unchanged.
const authored = colours();
expect(authored.length).toBeGreaterThan(0);
// Half red, half alpha. Each channel scales by its own factor, which a
// replace-instead-of-multiply implementation could not produce.
call('db_setColor', null, ['number', 'number', 'number', 'number', 'number'], [instance, 0.5, 1, 1, 0.5]);
call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
const tinted = colours();
expect(tinted.length).toBe(authored.length);
for (let i = 0; i < authored.length; i++) {
expect(tinted[i].r).toBeCloseTo(authored[i].r * 0.5, 5);
expect(tinted[i].g).toBeCloseTo(authored[i].g, 5);
expect(tinted[i].b).toBeCloseTo(authored[i].b, 5);
expect(tinted[i].a).toBeCloseTo(authored[i].a * 0.5, 5);
}
// And white puts it back, which is what clearing the field must do.
call('db_setColor', null, ['number', 'number', 'number', 'number', 'number'], [instance, 1, 1, 1, 1]);
call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
const restored = colours();
for (let i = 0; i < authored.length; i++) {
expect(restored[i].r).toBeCloseTo(authored[i].r, 5);
expect(restored[i].a).toBeCloseTo(authored[i].a, 5);
}
call('db_destroyInstance', null, ['number'], [instance]);
call('db_unloadSkeleton', null, ['number'], [handle]);
});
it('tints one instance without touching another sharing the skeleton', () => {
// The tint lives per instance, not on the shared skeleton — two entities of
// one file are the whole reason the sharing exists.
const handle = load();
call('db_setAtlasTexture', null, ['number', 'number'], [handle, 7]);
const a = call<number>('db_createInstance', 'number', ['number', 'string'], [handle, 'Dragon']);
const b = call<number>('db_createInstance', 'number', ['number', 'string'], [handle, 'Dragon']);
for (const id of [a, b]) {
call('db_playAnimation', 'number', ['number', 'string', 'number'], [id, 'stand', 0]);
call('db_update', null, ['number', 'number'], [id, 1 / 60]);
}
const firstAlpha = (id: number): number => {
call('db_getMeshBatchCount', 'number', ['number'], [id]); // pose THIS instance
// Sized from what the batch actually holds — a fixed guess is a buffer
// db_getMeshBatchData writes straight past.
const vertexCount = call<number>('db_getMeshBatchVertexCount', 'number', ['number', 'number'], [id, 0]);
const indexCount = call<number>('db_getMeshBatchIndexCount', 'number', ['number', 'number'], [id, 0]);
const vp = M._malloc(vertexCount * 8 * 4);
const ip = M._malloc(indexCount * 2);
const tp = M._malloc(4);
const bp = M._malloc(4);
call('db_getMeshBatchData', null, ['number', 'number', 'number', 'number', 'number', 'number'], [
id, 0, vp, ip, tp, bp,
]);
const alpha = new Float32Array(M.HEAPF32.buffer, vp, 8)[7];
M._free(vp); M._free(ip); M._free(tp); M._free(bp);
return alpha;
};
call('db_setColor', null, ['number', 'number', 'number', 'number', 'number'], [a, 1, 1, 1, 0.25]);
call('db_update', null, ['number', 'number'], [a, 1 / 60]);
const tintedA = firstAlpha(a);
call('db_update', null, ['number', 'number'], [b, 1 / 60]);
const untouchedB = firstAlpha(b);
expect(tintedA).toBeLessThan(untouchedB);
expect(untouchedB).toBeCloseTo(1, 5);
call('db_destroyInstance', null, ['number'], [a]);
call('db_destroyInstance', null, ['number'], [b]);
call('db_unloadSkeleton', null, ['number'], [handle]);
});
it('survives an animation being retired — a crossfade, then the state going away', () => {
// The runtime hands a finished animation state back through
// `_armature->_dragonBones->bufferObject(state)`, and BaseFactory leaves
// that pointer null unless an integration sets one. Nothing here failed
// when it was null: on wasm the null dereference lands in readable low
// memory, so this test passed against the broken build too — it took an
// arm64 SIGSEGV to see it. Kept because the wasm build is where the code
// is edited, and a leak (the buffer never drains) is the quiet half of the
// same bug.
const handle = load();
call('db_setAtlasTexture', null, ['number', 'number'], [handle, 7]);
const instance = call<number>('db_createInstance', 'number', ['number', 'string'], [handle, 'Dragon']);
call('db_playAnimation', 'number', ['number', 'string', 'number'], [instance, 'stand', 0]);
// Cross-fade repeatedly and run past each fade, so states really do retire
// rather than just being queued behind one another.
for (const name of ['walk', 'jump', 'fall', 'stand', 'walk']) {
call('db_fadeInAnimation', 'number', ['number', 'string', 'number', 'number'], [instance, name, 0.2, 0]);
for (let i = 0; i < 30; i++) call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
}
// Still posing afterwards: a recycled state that was handed back twice, or
// one still in use, shows up here as no geometry rather than as a throw.
expect(call<number>('db_getMeshBatchCount', 'number', ['number'], [instance])).toBeGreaterThan(0);
call('db_destroyInstance', null, ['number'], [instance]);
call('db_unloadSkeleton', null, ['number'], [handle]);
});
it('stands the character up, rather than posing it in the authoring tool\'s axes', () => {
// DragonBones poses y-DOWN and the engine's world is y-up, so the adapter
// flips. Nothing else catches it: every other assertion here is about
// magnitude or finiteness, and an upside-down armature satisfies all of
// them — it took a screenshot to notice, which is exactly why this exists.
//
// The test is DragonBoy's head against his feet. The head slot sits at the
// TOP of a standing character, so its vertices must have the greater y.
const handle = load();
call('db_setAtlasTexture', null, ['number', 'number'], [handle, 7]);
const instance = call<number>('db_createInstance', 'number', ['number', 'string'], [handle, 'Dragon']);
call('db_playAnimation', 'number', ['number', 'string', 'number'], [instance, 'stand', 0]);
call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
// Every posed vertex, across every batch — the split into batches is a
// texture/blend detail and says nothing about where a part is.
let minY = Infinity, maxY = -Infinity;
const batches = call<number>('db_getMeshBatchCount', 'number', ['number'], [instance]);
expect(batches).toBeGreaterThan(0);
for (let b = 0; b < batches; b++) {
const vertexCount = call<number>('db_getMeshBatchVertexCount', 'number', ['number', 'number'], [instance, b]);
const indexCount = call<number>('db_getMeshBatchIndexCount', 'number', ['number', 'number'], [instance, b]);
const vp = M._malloc(vertexCount * 8 * 4);
const ip = M._malloc(indexCount * 2);
const tp = M._malloc(4);
const bp = M._malloc(4);
call('db_getMeshBatchData', null, ['number', 'number', 'number', 'number', 'number', 'number'], [
instance, b, vp, ip, tp, bp,
]);
const v = new Float32Array(M.HEAPF32.buffer, vp, vertexCount * 8);
for (let i = 0; i < vertexCount; i++) {
const y = v[i * 8 + 1];
if (y < minY) minY = y;
if (y > maxY) maxY = y;
}
M._free(vp); M._free(ip); M._free(tp); M._free(bp);
}
// The armature's origin is at the feet, so a right-way-up DragonBoy
// reaches much further above it than below.
expect(maxY).toBeGreaterThan(0);
expect(maxY).toBeGreaterThan(Math.abs(minY));
call('db_destroyInstance', null, ['number'], [instance]);
call('db_unloadSkeleton', null, ['number'], [handle]);
});
it('moves the character as it walks, and keeps it a character-sized thing', () => {
const handle = load();
call('db_setAtlasTexture', null, ['number', 'number'], [handle, 7]);
const instance = call<number>('db_createInstance', 'number', ['number', 'string'], [handle, 'Dragon']);
call('db_playAnimation', 'number', ['number', 'string', 'number'], [instance, 'walk', 0]);
const bounds = (): [number, number, number, number] => {
const p = [M._malloc(4), M._malloc(4), M._malloc(4), M._malloc(4)];
call('db_getBounds', null, ['number', 'number', 'number', 'number', 'number'], [instance, ...p]);
const read = (ptr: number) => new Float32Array(M.HEAPF32.buffer, ptr, 1)[0];
return [read(p[0]), read(p[1]), read(p[2]), read(p[3])];
};
call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
const first = bounds();
for (let i = 0; i < 20; i++) call('db_update', null, ['number', 'number'], [instance, 1 / 60]);
const later = bounds();
// Roughly DragonBoy-sized. A weighted mesh posed in the wrong space lands
// hundreds of units away and blows this up; a pivot applied after the
// matrix instead of before collapses it.
expect(later[2]).toBeGreaterThan(10);
expect(later[2]).toBeLessThan(2000);
expect(later[3]).toBeGreaterThan(10);
expect(later[3]).toBeLessThan(2000);
// And it is an animation, not a still.
expect(first).not.toEqual(later);
call('db_destroyInstance', null, ['number'], [instance]);
call('db_unloadSkeleton', null, ['number'], [handle]);
});
});