Skip to content

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.

fix(spine): the atlas reaches the module through the heap as UTF-8 bytes, so an atlas past 60 KB or with non-ASCII names loads

yhh3467ee9015a8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f33fe4f44..a97a3f4c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ published separately; it ships inside the editor.
### Fixed
+- **A Spine atlas of any size loads.** The atlas text went to the Spine module through its 64 KB stack, so an atlas past about 60 KB wrote over the module's memory: a crash or a corrupted skeleton, whatever the skeleton's format. Its length was also counted in UTF-16 units rather than bytes, so an atlas with non-ASCII page or region names was cut short. The atlas now goes through the heap as UTF-8 with its byte length, as the skeleton data and DragonBones' atlas already did; a 150 KB atlas named in Chinese loads on Spine 3.8 and 4.2.
- **A material parameter named like an engine uniform is refused on every platform.** A `#pragma param u_ambient` in a `Lit` shader compiled on WebGPU and failed only on WebGL, a WeChat mini-game among them, with `redefinition of an interface block member name`. The names a parameter may not take are no longer a hand-kept list of three: they are read from what the engine actually declares for the shader's domain, so every member of the light block is refused at load, a name only the light block uses stays free in an `Unlit` shader, and the error says which block owns it.
- **World text under a perspective camera no longer eats the memory.** A `Text` left on `renderMode: Auto` in world space, seen through a perspective camera, was rasterized as if the camera were orthographic: a 32 px label asked for glyphs tens of thousands of pixels high. On a phone the native heap swung between 2.4 and 4.2 GB and the game drew about one frame in two seconds. Auto now draws world text under a perspective camera as SDF, since no single bitmap size lands 1:1 at every depth; the same eight floating labels hold the heap at about 45 MB and 60 fps. A bitmap glyph is also never rasterized larger than half an atlas page (512 px), which also covers an orthographic camera zoomed far in and a forced `Bitmap`; past that it is drawn from 512 px and the log says so once.
- **Sound comes back when a device's audio dies on its own.** On the Android and iOS hosts, a game whose audio device did not start again on returning from the background, or whose output stream was dropped while it was away, stayed silent until it was restarted. The host now checks every frame that the device is still taking sound while the game wants it; after half a second of nothing it restarts the device, and from the third try rebuilds it, retrying at growing intervals of up to 5 seconds. Sounds that were playing carry on where they were, and the log says each time it acts.
diff --git a/sdk/src/spine/SpineController.ts b/sdk/src/spine/SpineController.ts
index 4190fe6d6..2d2c07c92 100644
--- a/sdk/src/spine/SpineController.ts
+++ b/sdk/src/spine/SpineController.ts
@@ -73,21 +73,16 @@ export class SpineModuleController {
loadSkeleton(skelData: Uint8Array | string, atlasText: string, isBinary: boolean): number {
return withScratch(this.raw_, alloc => {
- let ptr: number;
- let len: number;
- if (typeof skelData === 'string') {
- const encoder = new TextEncoder();
- const bytes = encoder.encode(skelData);
- len = bytes.length;
- ptr = alloc(len + 1);
+ const put = (bytes: Uint8Array, terminate: boolean): number => {
+ const ptr = alloc(bytes.length + (terminate ? 1 : 0));
this.raw_.HEAPU8.set(bytes, ptr);
- this.raw_.HEAPU8[ptr + len] = 0;
- } else {
- len = skelData.length;
- ptr = alloc(len);
- this.raw_.HEAPU8.set(skelData, ptr);
- }
- return this.api_.loadSkeleton(ptr, len, atlasText, atlasText.length, isBinary);
+ if (terminate) this.raw_.HEAPU8[ptr + bytes.length] = 0;
+ return ptr;
+ };
+ const encoder = new TextEncoder();
+ const skel = typeof skelData === 'string' ? encoder.encode(skelData) : skelData;
+ const atlas = encoder.encode(atlasText);
+ return this.api_.loadSkeleton(put(skel, typeof skelData === 'string'), skel.length, put(atlas, true), atlas.length, isBinary);
});
}
diff --git a/sdk/src/spine/SpineModuleLoader.ts b/sdk/src/spine/SpineModuleLoader.ts
index 26eb6fffe..105bcd6fd 100644
--- a/sdk/src/spine/SpineModuleLoader.ts
+++ b/sdk/src/spine/SpineModuleLoader.ts
@@ -8,7 +8,7 @@
import { log } from '../util/logger';
export interface SpineWasmModule {
- _spine_loadSkeleton(skelDataPtr: number, skelDataLen: number, atlasText: number, atlasLen: number, isBinary: number): number;
+ _spine_loadSkeleton(skelDataPtr: number, skelDataLen: number, atlasPtr: number, atlasLen: number, isBinary: number): number;
_spine_unloadSkeleton(handle: number): void;
_spine_getAtlasPageCount(handle: number): number;
_spine_getAtlasPageTextureName(handle: number, pageIndex: number): number;
@@ -89,7 +89,7 @@ export interface SpineWasmModule {
}
export interface SpineWrappedAPI {
- loadSkeleton(skelDataPtr: number, skelDataLen: number, atlasText: string, atlasLen: number, isBinary: boolean): number;
+ loadSkeleton(skelDataPtr: number, skelDataLen: number, atlasPtr: number, atlasLen: number, isBinary: boolean): number;
getLastError(): string;
unloadSkeleton(handle: number): void;
getAtlasPageCount(handle: number): number;
@@ -180,7 +180,7 @@ export interface SpineWrappedAPI {
export function wrapSpineModule(raw: SpineWasmModule): SpineWrappedAPI {
const cw = raw.cwrap.bind(raw);
return {
- loadSkeleton: cw('spine_loadSkeleton', 'number', ['number', 'number', 'string', 'number', 'number']) as SpineWrappedAPI['loadSkeleton'],
+ loadSkeleton: cw('spine_loadSkeleton', 'number', ['number', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['loadSkeleton'],
getLastError: cw('spine_getLastError', 'string', []) as SpineWrappedAPI['getLastError'],
unloadSkeleton: cw('spine_unloadSkeleton', null, ['number']) as SpineWrappedAPI['unloadSkeleton'],
getAtlasPageCount: cw('spine_getAtlasPageCount', 'number', ['number']) as SpineWrappedAPI['getAtlasPageCount'],
diff --git a/sdk/tests/spine-large-atlas-wasm.test.ts b/sdk/tests/spine-large-atlas-wasm.test.ts
new file mode 100644
index 000000000..13443b921
--- /dev/null
+++ b/sdk/tests/spine-large-atlas-wasm.test.ts
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
+import { SpineModuleController } from '../src/spine/SpineController';
+import { wrapSpineModule, type SpineWasmModule } from '../src/spine/SpineModuleLoader';
+
+function paddedAtlas(atlas: string, targetChars: number): string {
+ let page = '\n填充页.png\nsize: 64,64\nformat: RGBA8888\nfilter: Linear,Linear\nrepeat: none\n';
+ for (let i = 0; page.length < targetChars; i++) {
+ page += `区域名称_${i}_第二块区域\n rotate: false\n xy: 0, 0\n size: 8, 8\n orig: 8, 8\n offset: 0, 0\n index: -1\n`;
+ }
+ return page + '\n' + atlas;
+}
+
+for (const version of ['3.8', '4.2']) {
+ const moduleName = 'spine' + version.replace('.', '');
+ describe.skipIf(!hasSideModule(moduleName))('Spine ' + version + ' with a large, non-ASCII atlas', () => {
+ it('loads an atlas far past the module stack, measured in UTF-8 bytes', async () => {
+ const factory = (await import(resolve(WASM_DIR, moduleName + '.js'))).default;
+ const raw: SpineWasmModule = await factory({ wasmBinary: readFileSync(resolve(WASM_DIR, moduleName + '.wasm')) });
+ const controller = new SpineModuleController(raw, wrapSpineModule(raw));
+ const dir = resolve(__dirname, '../../third_party/spine-runtimes-' + version, 'examples/spineboy/export');
+ const atlas = paddedAtlas(readFileSync(resolve(dir, 'spineboy.atlas'), 'utf8'), 130000);
+ expect(new TextEncoder().encode(atlas).length).toBeGreaterThan(150000);
+ const handle = controller.loadSkeleton(new Uint8Array(readFileSync(resolve(dir, 'spineboy-pro.json'))), atlas, false);
+ expect(controller.getLastError()).toBe('');
+ expect(handle).toBeGreaterThan(0);
+ expect(controller.getAtlasPageCount(handle)).toBe(2);
+ const id = controller.createInstance(handle);
+ expect(controller.play(id, 'walk', true)).toBe(true);
+ controller.update(id, 0.25);
+ controller.destroyInstance(id);
+ controller.unloadSkeleton(handle);
+ });
+ });
+}
diff --git a/src/esengine/bindings/modules/spine/SpineBindings.hpp b/src/esengine/bindings/modules/spine/SpineBindings.hpp
index b4259c4f9..ad642b023 100644
--- a/src/esengine/bindings/modules/spine/SpineBindings.hpp
+++ b/src/esengine/bindings/modules/spine/SpineBindings.hpp
@@ -29,7 +29,7 @@
extern "C" {
-int spine_loadSkeleton(uintptr_t skelDataPtr, int skelDataLen, const char* atlasText, int atlasLen, int isBinary);
+int spine_loadSkeleton(uintptr_t skelDataPtr, int skelDataLen, uintptr_t atlasPtr, int atlasLen, int isBinary);
const char* spine_getLastError();
void spine_unloadSkeleton(int handle);
int spine_getAtlasPageCount(int handle);
diff --git a/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp b/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp
index be1738331..3d6102c8a 100644
--- a/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp
+++ b/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp
@@ -153,12 +153,12 @@ extern "C" {
EMSCRIPTEN_KEEPALIVE
int spine_loadSkeleton(uintptr_t skelDataPtr, int skelDataLen,
- const char* atlasText, int atlasLen, int isBinary) {
+ uintptr_t atlasPtr, int atlasLen, int isBinary) {
g_ctx.lastError.clear();
es::spine::Skeleton* loaded = es::spine::loadSkeleton(
reinterpret_cast<const void*>(skelDataPtr), skelDataLen,
- atlasText, atlasLen, isBinary != 0, g_ctx.lastError);
+ reinterpret_cast<const char*>(atlasPtr), atlasLen, isBinary != 0, g_ctx.lastError);
if (!loaded) return -1;
const int id = g_ctx.skeletons.add(SkeletonPtr(loaded));
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index f4aa0f828..286624409 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4126,4 +4126,6 @@ export const NOTED = {
{"note": "World text under a perspective camera no longer eats the memory."},
"fix(shader): a param may not take a name the engine declares for its domain, read from what the engine injects rather than a list of three":
{"note": "A material parameter named like an engine uniform is refused on every platform."},
+ "fix(spine): the atlas reaches the module through the heap as UTF-8 bytes, so an atlas past 60 KB or with non-ASCII names loads":
+ {"note": "A Spine atlas of any size loads."},
};