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(wechat): a WeChat package registers the engine components and AI names again

esengine1742e1ce0aa7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4fee3f1f..00631e53b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ published separately; it ships inside the editor.
- **EmscriptenGLX on WeChat.** A WeChat project can ship the engine linked with WeChat's EmscriptenGLX (Project Settings → WeChat → Render through EmscriptenGLX, off by default), which issues the engine's GL calls natively instead of through JavaScript: a draw-heavy scene spent about 12% less time rendering on an Android phone. It adds about 310KB of wasm and needs base library 3.8.12 on Android, or iOS in 高性能+ mode; any other host renders through WebGL2 as before, and the log says which. The engine is built once with `node build-tools/cli.js build -t wechat-glx`, which fetches WeChat's library at a pinned version and hash, and emsdk 4.0.10 beside the main one; an export that asks for it without it says so.
- A connected development build says which graphics API it draws through — WebGL2, EmscriptenGLX or WebGPU — once its game has started: the Profiler shows it beside the device's controls, the Output Log notes it, and `device_targets` returns it as `graphics`. A WeChat build set to EmscriptenGLX reports WebGL2 on a host that does not offer it.
- A connected development build can be asked for the whole frame it composited — every camera and the UI over them — as the player sees it: `device_screenshot` returns it as a PNG, read back by the device's own engine. The frame debugger's replay shows one pass of a captured frame.
+- Web and mini-game packages decode KTX2 textures under Zstandard supercompression, as the native host already did. UASTC textures made outside Estella usually are, and every one failed to decode; the transcoder module grows by about 21KB compressed, in packages that carry KTX2.
- **Export profiles.** A project can name several exports of one target in `packaging.profiles` — a test and a production WeChat build, each with its own AppID, CDN root and development or shipping configuration, writing only what differs from the project's settings. The Build dialog creates, edits and deletes them per target, marking each setting a profile overrides with a reset that hands it back to the project; `estella export --profile <name>` and the agent's `export_game` build the same one, and the size history records which profile a build used.
### Changed
@@ -28,6 +29,10 @@ published separately; it ships inside the editor.
### Fixed
+- The package size report on Windows attributes the SDK's bytes to the directories they come from again: every module read as "project", since the source map's paths were spelled with backslashes.
+- A WeChat package registers every engine component and the built-in AI names again. The WeChat entries lost their start-up calls to the bundler, so a scene using a component with no typed definition — a rigged model's MeshSkin among them — loaded without it ("Unknown component type") and its character was never skinned.
+- Reading a component whose field is a list of entities — a node's Children, a skin's joints — returns an array from every read path and frees the engine's copy. `world.tryGet` and query iteration handed back the engine's vector: an animated rig leaked one per joint per frame, and on the WeChat EmscriptenGLX engine, whose vectors cannot be iterated, the animator threw every frame.
+- `estella import-model` registers the images a model references on disk, so an export ships them. It wrote the materials and prefab that name them and left the images themselves unregistered, and a package built from the command line carried none of its textures.
- A WeChat or other mini-game package draws each sprite from a packed atlas as its own frame again, not as the whole atlas page shrunk into the sprite. The package's scenes now keep their `@uuid:` references as the web package does, and a reference by bare uuid finds its atlas frame too.
- Sprite masks work in WeChat and other mini-game packages: the game's WebGL context was created without a stencil buffer, so every mask drew as if it were not there (space-shooter's hull bar read as empty). The web, playable and mini-game hosts now create the context with the same attributes.
- On a host that compresses the engine binary (most CDNs and static hosts), the web boot bar no longer runs to the end of the engine download a third of the way through and stands there for the rest of it: the page divided decompressed bytes by the compressed Content-Length. The export now records the binary's own size (`engineBytes` in `game.config.json`) and the bar measures against that.
diff --git a/sdk/src/index.wechat.base.ts b/sdk/src/index.wechat.base.ts
index 74fb16470..b527bf02d 100644
--- a/sdk/src/index.wechat.base.ts
+++ b/sdk/src/index.wechat.base.ts
@@ -5,20 +5,6 @@
* @brief ESEngine SDK - WeChat MiniGame entry, minus the optional subsystems
*/
-import { setPlatform } from './platform';
-import { wechatAdapter, initWeChatPlatform } from './platform/wechat';
-import { ensureBuiltinComponentsRegistered, markEngineComponentBaseline } from './ecs/component';
-import { ensureBuiltinAiRegistrations } from './ai/builtins';
-
-initWeChatPlatform();
-setPlatform(wechatAdapter);
-
-// Register every engine component (COMPONENT_META) so scenes never silently drop
-// a component that exists in the engine but lacks a typed const.
-ensureBuiltinComponentsRegistered();
-ensureBuiltinAiRegistrations();
-markEngineComponentBaseline();
-
export * from './core';
export * from './runtime/webAppFactory';
diff --git a/sdk/src/index.wechat.lean.ts b/sdk/src/index.wechat.lean.ts
index 14a8f8005..230577a99 100644
--- a/sdk/src/index.wechat.lean.ts
+++ b/sdk/src/index.wechat.lean.ts
@@ -12,4 +12,8 @@
* A scene that needs one nobody imported loads without it and says so, rather
* than failing: what a lean build IS, is a build that ships less.
*/
+import { installWeChatEntry } from './runtime/wechatEntry';
+
+installWeChatEntry();
+
export * from './index.wechat.base';
diff --git a/sdk/src/index.wechat.ts b/sdk/src/index.wechat.ts
index 36bd46203..5195a4785 100644
--- a/sdk/src/index.wechat.ts
+++ b/sdk/src/index.wechat.ts
@@ -9,7 +9,9 @@
* package that imports back only what its project uses.
*/
import { installOptionalPlugins } from './runtime/optionalPlugins';
+import { installWeChatEntry } from './runtime/wechatEntry';
+installWeChatEntry();
installOptionalPlugins();
export * from './index.wechat.base';
diff --git a/sdk/src/runtime/wechatEntry.ts b/sdk/src/runtime/wechatEntry.ts
new file mode 100644
index 000000000..0900088dd
--- /dev/null
+++ b/sdk/src/runtime/wechatEntry.ts
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file wechatEntry.ts — what every WeChat entry does before it hands the SDK over.
+ *
+ * A CALL, for the reason webEntry is one: as module side effects in the shared
+ * base these were dropped from both WeChat entries, so a WeChat package never
+ * registered the engine components that have no typed const (MeshSkin among
+ * them) or the built-in AI names.
+ */
+import { setPlatform } from '../platform';
+import { wechatAdapter, initWeChatPlatform } from '../platform/wechat';
+import { ensureBuiltinComponentsRegistered, markEngineComponentBaseline } from '../ecs/component';
+import { ensureBuiltinAiRegistrations } from '../ai/builtins';
+
+export function installWeChatEntry(): void {
+ initWeChatPlatform();
+ setPlatform(wechatAdapter);
+ ensureBuiltinComponentsRegistered();
+ ensureBuiltinAiRegistrations();
+ markEngineComponentBaseline();
+}
diff --git a/tools/check-entry-boots.mjs b/tools/check-entry-boots.mjs
index 8db9e8e07..c073422d9 100644
--- a/tools/check-entry-boots.mjs
+++ b/tools/check-entry-boots.mjs
@@ -25,12 +25,21 @@ import { fileURLToPath } from 'node:url';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const SDK = path.join(ROOT, 'sdk');
+/** Enough of `wx` for a WeChat entry's prologue to run in node. */
+const WX_STUB = "globalThis.wx = new Proxy({}, { get: (t, k) => k === 'env' ? {} : (() => ({})) });";
+
/** Each entry a consumer can resolve, and the platform it must have installed. */
const ENTRIES = [
{ specifier: 'esengine', platform: 'web' },
{ specifier: 'esengine/lean', file: 'dist/index.lean.js', platform: 'web' },
+ { specifier: 'esengine/wechat', file: 'dist/index.wechat.js', platform: 'wechat', banner: WX_STUB },
+ { specifier: 'esengine/wechat-lean', file: 'dist/index.wechat.lean.js', platform: 'wechat', banner: WX_STUB },
];
+/** An engine component with no typed const: only the entry's prologue registers
+ * it, so a scene that uses it is where a lost prologue shows. */
+const UNTYPED_BUILTIN = 'MeshSkin';
+
const work = mkdtempSync(path.join(tmpdir(), 'estella-entry-boots-'));
const fail = (message, detail) => {
console.error(`check-entry-boots: ${message}`);
@@ -52,8 +61,8 @@ for (const entry of ENTRIES) {
const name = entry.specifier.replace(/\W+/g, '-');
const src = path.join(work, `${name}.mjs`);
const out = path.join(work, `${name}.bundle.mjs`);
- writeFileSync(src, `import { getPlatformType } from ${JSON.stringify(entry.specifier)};\n`
- + `console.log(getPlatformType());\n`);
+ writeFileSync(src, `import { getPlatformType, getComponent } from ${JSON.stringify(entry.specifier)};\n`
+ + `console.log(JSON.stringify({ platform: getPlatformType(), untyped: !!getComponent(${JSON.stringify(UNTYPED_BUILTIN)}) }));\n`);
try {
await build({
entryPoints: [src], outfile: out, bundle: true, format: 'esm',
@@ -61,20 +70,27 @@ for (const entry of ENTRIES) {
// A subpath the package does not publish still has to be reachable
// by the file it is: this asks what the BUILD produced.
...(entry.file ? { alias: { [entry.specifier]: path.join(SDK, entry.file) } } : {}),
+ ...(entry.banner ? { banner: { js: entry.banner } } : {}),
});
} catch (err) {
fail(`${entry.specifier} did not bundle.`, err?.message ?? err);
}
const run = spawnSync(process.execPath, [out], { encoding: 'utf8' });
- const got = (run.stdout ?? '').trim();
if (run.status !== 0) fail(`${entry.specifier} threw on import.`, run.stderr);
- if (got !== entry.platform) {
- fail(`${entry.specifier} installed no platform after bundling — got ${got || '(nothing)'},`
- + ` expected ${entry.platform}.\n\nIts prologue is a statement in a module the bundler`
- + ' put in an unlisted chunk. Make it a call the entry makes (runtime/webEntry.ts),'
- + ' or list that file in sdk/package.json "sideEffects".');
+ let got = null;
+ try { got = JSON.parse((run.stdout ?? '').trim().split('\n').at(-1)); } catch { /* reported below */ }
+ const prologueLost = '\n\nIts prologue is a statement in a module the bundler put in an unlisted chunk.'
+ + ' Make it a call the entry makes (runtime/webEntry.ts, runtime/wechatEntry.ts),'
+ + ' or list that file in sdk/package.json "sideEffects".';
+ if (got?.platform !== entry.platform) {
+ fail(`${entry.specifier} installed no platform after bundling — got ${got?.platform || '(nothing)'},`
+ + ` expected ${entry.platform}.${prologueLost}`);
+ }
+ if (!got.untyped) {
+ fail(`${entry.specifier} never registered ${UNTYPED_BUILTIN} after bundling, so a scene using it`
+ + ` loads without it ("Unknown component type").${prologueLost}`);
}
- results.push(`${entry.specifier} → ${got}`);
+ results.push(`${entry.specifier} → ${got.platform}`);
}
// One process can hold two entries: a node tool reaches `esengine` through
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index b4fa089f1..99477c6b0 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -1198,4 +1198,18 @@ export const NOTED = {
{ note: 'A connected development build can be asked for the whole frame it composited — every camera and the UI over them — as the player sees it: `device_screenshot` returns it as a PNG, read back by the device\'s own engine. The frame debugger\'s replay shows one pass of a captured frame.' },
'feat(agent): device_screenshot shows what a connected build shows its player':
{ note: 'A connected development build can be asked for the whole frame it composited — every camera and the UI over them — as the player sees it: `device_screenshot` returns it as a PNG, read back by the device\'s own engine. The frame debugger\'s replay shows one pass of a captured frame.' },
+ 'fix(wechat): a WeChat package registers the engine components and AI names again':
+ { note: 'A WeChat package registers every engine component and the built-in AI names again. The WeChat entries lost their start-up calls to the bundler, so a scene using a component with no typed definition — a rigged model\'s MeshSkin among them — loaded without it ("Unknown component type") and its character was never skinned.' },
+ 'fix(ecs): a list field reads back as an array on every read path':
+ { note: 'Reading a component whose field is a list of entities — a node\'s Children, a skin\'s joints — returns an array from every read path and frees the engine\'s copy. `world.tryGet` and query iteration handed back the engine\'s vector: an animated rig leaked one per joint per frame, and on the WeChat EmscriptenGLX engine, whose vectors cannot be iterated, the animator threw every frame.' },
+ 'fix(import): import-model registers the images a model names on disk':
+ { note: '`estella import-model` registers the images a model references on disk, so an export ships them. It wrote the materials and prefab that name them and left the images themselves unregistered, and a package built from the command line carried none of its textures.' },
+ 'feat(render): KTX2 textures under zstd supercompression decode on web and mini-games':
+ { note: 'Web and mini-game packages decode KTX2 textures under Zstandard supercompression, as the native host already did. UASTC textures made outside Estella usually are, and every one failed to decode; the transcoder module grows by about 21KB compressed, in packages that carry KTX2.' },
+ 'refactor(build): the GLX engine adds its exports to the WeChat lists':
+ { internal: 'The WeChat GLX engine exports the same functions as before; its link flags now extend the WeChat lists instead of restating them.' },
+ 'fix(export): the size report reads a Windows path as it reads any other':
+ { note: 'The package size report on Windows attributes the SDK\'s bytes to the directories they come from again: every module read as "project", since the source map\'s paths were spelled with backslashes.' },
+ 'test(launch): the launchers print every warning and error, and count a logged error':
+ { internal: 'Repository launchers; no creator runs them.' },
};