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
fix(ecs): a Mut row is no longer rewritten by its own write-back, so walking one on the web keeps its colours and a list field crosses as a vector
yhhfcf8f09f4be2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bc13d0c32..5c6e75624 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -23,6 +23,7 @@ published separately; it ships inside the editor.### Fixed+- **`Mut()` on the web no longer turns a component's colours to NaN** (#107). Since 0.98.0 a `Mut` row is written back when the loop moves on and once more when the system returns, and the first write rewrote the row's colour into the engine's shape, so the second sent NaN. A loop over `Mut(UIVisual)` that wrote nothing made the element vanish. Components read through the wasm heap, and every native build, were not affected. Writing back no longer touches the row. The same write also handed a list field to the engine as a JS array, so `Mut` on a component with one threw every frame; it now takes the one marshalled write `world.set` and `insert` use.- **A new character costs a phone about a third of what it did.** A glyph was drawn and distance-transformed at 4x its stored size, 16 times the pixels, and on a phone most of the time went there. It is now 2x, on the web and on every native host alike: at 12x magnification 2x and 4x look the same on the densest CJK glyph, where 1x loses its counters. The distance transform also leaves out the sites that cannot change a byte of its result, tested byte for byte against the plain transform. On a Snapdragon 8 Elite a new CJK glyph with its distance field went from 5.3 to 1.8 ms, and a Latin one from 3.4 to 0.74 ms. Text can differ from before by a few levels at its edges, up to 6 of 255 in the field.- **A native Android build shows CJK text from the system font.** Android 16's system CJK font (NotoSansCJK-Regular.ttc) has CFF2 outlines, which stb_truetype cannot read, and only Apple had the platform fallback for that, so on such a phone every CJK character from the system font drew nothing. Android now draws such a face with android.graphics: the same file and face its font matcher chose, with synthetic bold and italic where the face lacks them, handed back as coverage so the distance field and the atlas tile stay the shared code's. A project that bundles its own font is not affected.- **A new glyph on a native build no longer stalls the frame reading a whole system font** (#106). Every native host (Android, iOS, macOS, Windows, Linux) read the matched font file whole on every call, which is every glyph rasterized, and the rasterizer then dropped those bytes for a face it had already parsed. A system CJK font is tens of MB: on a Snapdragon 8 Elite phone that read was 9.7 ms a glyph (63 ms for the first). A platform now only answers which file and which face (Platform::matchFont), and the shared rasterizer maps each face's file the first time it sees it, so the OS pages in only the tables and glyphs it touches. The read is gone: looking a face up costs 0.02 ms on the phone. On Windows a new CJK glyph, rasterized and turned into a distance field, costs 0.9 ms.diff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.tsindex a5300ca1a..afacf1584 100644--- a/sdk/src/ecs/bridge/BuiltinBridge.ts+++ b/sdk/src/ecs/bridge/BuiltinBridge.ts@@ -51,24 +51,24 @@ export function convertFromWasm(}/**- * Rewrite color-typed fields from the SDK {r,g,b,a} shape into the WASM- * {x,y,z,w} shape. The outer object is always a fresh merge constructed- * by the caller, but inner color values may alias user-supplied data or- * the shared component defaults, so we replace those slots with fresh- * {x,y,z,w} objects rather than mutating them.+ * The SDK's {r,g,b,a} colour fields in the WASM {x,y,z,w} shape, as a new object:+ * @p obj is left as it was. It can be a Mut row, which the game still holds and+ * which is written back more than once; rewritten in place, its colour had no `r`+ * the second time and every channel crossed as NaN (issue #107).*/export function convertForWasm(obj: Record<string, unknown>,colorKeys: readonly string[],): Record<string, unknown> {if (colorKeys.length === 0) return obj;+ const out = { ...obj };for (const key of colorKeys) {const val = obj[key] as { r?: number; g?: number; b?: number; a?: number } | null | undefined;if (val && typeof val === 'object') {- obj[key] = { x: val.r, y: val.g, z: val.b, w: val.a };+ out[key] = { x: val.r, y: val.g, z: val.b, w: val.a };}}- return obj;+ return out;}/** An embind std::vector, which its owner has to free. */@@ -889,10 +889,13 @@ export class BuiltinBridge {entityFields: readonly string[] = []): void {const module = this.module_ as unknown as{ VectorEntity?: new () => WasmVector; VectorFloat?: new () => WasmVector } | null;- const vectors = materializeEntityVectors(payload, entityFields, module);- vectors.push(...materializeNumberVectors(payload, numberListFieldsOf(cppName), module));+ const numberFields = numberListFieldsOf(cppName);+ // On a copy: the vectors are freed below, and @p payload can be a Mut row the game still holds.+ const out = entityFields.length > 0 || numberFields.length > 0 ? { ...payload } : payload;+ const vectors = materializeEntityVectors(out, entityFields, module);+ vectors.push(...materializeNumberVectors(out, numberFields, module));try {- this.getBuiltinMethods(cppName).add(entity, payload);+ this.getBuiltinMethods(cppName).add(entity, out);} finally {for (const v of vectors) v.delete();}diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.tsindex 6fcf14ab4..ba57f0651 100644--- a/sdk/src/ecs/world.ts+++ b/sdk/src/ecs/world.ts@@ -1182,12 +1182,15 @@ export class World {if (ptrSetter) return ptrSetter;}- const methods = this.builtin_.getBuiltinMethods(component._cppName);- const colorKeys = component.colorKeys;- if (colorKeys.length === 0) {+ const name = component._cppName;+ const { colorKeys, entityFields } = component;+ if (colorKeys.length === 0 && entityFields.length === 0 && numberListFieldsOf(name).length === 0) {+ const methods = this.builtin_.getBuiltinMethods(name);return (e, d) => methods.add(e, d);}- return (e, d) => methods.add(e, convertForWasm(d as Record<string, unknown>, colorKeys));+ // The one marshalled write, as world.set and insert take it: a list field crosses as the vector embind+ // registered, never as the JS array a row holds.+ return (e, d) => this.builtin_.replace(e, name, convertForWasm(d as Record<string, unknown>, colorKeys), entityFields);}// Through ScriptStorage, not into the map: a pooled component's stored// value is a live view onto its row, and replacing it with a plaindiff --git a/sdk/tests/color-conversion.test.ts b/sdk/tests/color-conversion.test.tsindex 238d5f25b..948402e99 100644--- a/sdk/tests/color-conversion.test.ts+++ b/sdk/tests/color-conversion.test.ts@@ -60,10 +60,18 @@ describe('convertForWasm', () => {expect(out.color).toEqual({ x: 0.1, y: 0.2, z: 0.3, w: 0.4 });});- it('returns the same outer object (zero outer allocation)', () => {- const src = { color: { r: 1, g: 0, b: 0, a: 1 } };+ it('leaves its input as it was: the input can be a row the game still holds', () => {+ const color = { r: 1, g: 0, b: 0, a: 1 };+ const src = { color };const out = convertForWasm(src as Record<string, unknown>, ['color']);- expect(out).toBe(src);+ expect(out).not.toBe(src);+ expect(src.color).toBe(color);+ expect(color).toEqual({ r: 1, g: 0, b: 0, a: 1 });+ });++ it('converts the same row twice to the same thing', () => {+ const src = { color: { r: 1, g: 0.5, b: 0.25, a: 1 } } as Record<string, unknown>;+ expect(convertForWasm(src, ['color'])).toEqual(convertForWasm(src, ['color']));});});diff --git a/sdk/tests/mut-uivisual-wasm.test.ts b/sdk/tests/mut-uivisual-wasm.test.tsnew file mode 100644index 000000000..e0688a9f4--- /dev/null+++ b/sdk/tests/mut-uivisual-wasm.test.ts@@ -0,0 +1,136 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Issue #107: walking `Mut(UIVisual)` without writing a thing turned the+ * colour of every row to NaN, on the web core only, and the element vanished.+ * A row is written back more than once, and the write rewrote it in place.+ * Held against every engine component, since the path is shared.+ */+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';+import { App } from '../src/app/app';+import { Transform, builtinComponentRegistry, defineComponent } from '../src/ecs/component';+import { Query, Mut } from '../src/ecs/query';+import { defineSystem, Schedule } from '../src/ecs/system';+import { UIVisual } from '../src/ui/core/ui-visual';+import { UINode } from '../src/ui/core/ui-node';+import { uiPlugins } from '../src/app/uiPlugins';+import type { ESEngineModule } from '../src/wasm';+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';+import { log } from '../src/util/logger';++let engine: ESEngineModule;+const apps: App[] = [];+afterEach(() => { for (const app of apps.splice(0)) app.quit(); vi.restoreAllMocks(); });++const PressScale = defineComponent('MutUIVisualPressScale', { value: 1 });+const RED = { r: 0.25, g: 0.5, b: 0.75, a: 1 };++function rgba(app: App, e: never | number) {+ const { r, g, b, a } = app.world.get(e as never, UIVisual).color;+ return { r, g, b, a };+}++function start(withUI: boolean): App {+ const app = App.new();+ apps.push(app);+ app.connectCpp(new engine.Registry(), engine, { ownedRegistry: true });+ if (withUI) for (const plugin of uiPlugins) app.addPlugin(plugin);+ return app;+}++describe.skipIf(!HAS_WASM)('Mut(UIVisual) on the web core', () => {+ beforeAll(async () => { engine = await loadWasmModule(); });++ it('a walk that writes nothing leaves the colour alone', async () => {+ const app = start(false);+ const e = app.world.spawn();+ app.world.insert(e, Transform, {});+ app.world.insert(e, UIVisual, { color: RED });+ app.world.insert(e, PressScale, {});+ let rows = 0;+ app.addSystemToSchedule(Schedule.Update, defineSystem([Query(Mut(UIVisual), PressScale)], (q) => {+ for (const [, vis] of q) { void vis; rows++; }+ }));+ await app.tick(1 / 60);+ expect(rows).toBe(1);+ expect(rgba(app, e)).toEqual(RED);+ });++ it('nor does it with the UI plugins running, frame after frame', async () => {+ const app = start(true);+ const e = app.world.spawn();+ app.world.insert(e, Transform, {});+ app.world.insert(e, UINode, {});+ app.world.insert(e, UIVisual, { color: RED });+ app.world.insert(e, PressScale, {});+ app.addSystemToSchedule(Schedule.Update, defineSystem([Query(Mut(UIVisual), PressScale)], (q) => {+ for (const [, vis] of q) void vis;+ }));+ for (let i = 0; i < 5; i++) await app.tick(1 / 60);+ expect(rgba(app, e)).toEqual(RED);+ });++ it('and a colour written through the row is the colour read back', async () => {+ const app = start(false);+ const e = app.world.spawn();+ app.world.insert(e, Transform, {});+ app.world.insert(e, UIVisual, { color: RED });+ app.addSystemToSchedule(Schedule.Update, defineSystem([Query(Mut(UIVisual))], (q) => {+ for (const [, vis] of q) vis.color = { r: 0, g: 1, b: 0, a: 0.5 };+ }));+ await app.tick(1 / 60);+ expect(rgba(app, e)).toEqual({ r: 0, g: 1, b: 0, a: 0.5 });+ });++ it('edited after the loop, a kept row still writes colour, and the row keeps its shape', async () => {+ const app = start(false);+ const e = app.world.spawn();+ app.world.insert(e, Transform, {});+ app.world.insert(e, UIVisual, { color: RED });+ let kept: { color: { r: number; g: number; b: number; a: number } } | null = null;+ let afterLoop: unknown = null;+ app.addSystemToSchedule(Schedule.Update, defineSystem([Query(Mut(UIVisual))], (q) => {+ for (const [, vis] of q) kept = vis;+ afterLoop = kept!.color.r;+ kept!.color.g = 0.125;+ }));+ await app.tick(1 / 60);+ expect(afterLoop).toBe(0.25);+ expect(rgba(app, e)).toEqual({ ...RED, g: 0.125 });+ });++ it('a walk that writes nothing changes no engine component, whichever it is', async () => {+ const app = start(false);+ const errors = vi.spyOn(log, 'error');+ const skipped: string[] = [];+ const checked: string[] = [];+ const before = new Map<string, { e: never; def: never; was: string }>();+ for (const [name, def] of builtinComponentRegistry()) {+ const e = app.world.spawn();+ try {+ if (def !== Transform) app.world.insert(e, Transform, {});+ app.world.insert(e, def as never, {} as never);+ before.set(name, { e: e as never, def: def as never, was: JSON.stringify(app.world.get(e, def as never)) });+ } catch {+ skipped.push(name);+ continue;+ }+ app.addSystemToSchedule(Schedule.Update, defineSystem([Query(Mut(def as never))], (q) => {+ for (const [, row] of q as Iterable<[unknown, unknown]>) void row;+ }));+ }+ await app.tick(1 / 60);+ await app.tick(1 / 60);+ const changed: string[] = [];+ for (const [name, { e, def, was }] of before) {+ checked.push(name);+ const now = JSON.stringify(app.world.get(e, def));+ if (now !== was) changed.push(`${name}: ${was} -> ${now}`);+ }+ expect(changed).toEqual([]);+ // A write-back that throws is swallowed by the runner and logged, and leaves the data as it was.+ expect(errors.mock.calls.map((c) => c.map(String).join(' '))).toEqual([]);+ expect(skipped).toEqual([]);+ expect(checked.length).toBeGreaterThan(20);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex f177cfe39..f06e7d8b9 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3844,4 +3844,6 @@ export const NOTED = {{"note":"Glyphs can be put on the atlas before they are shown."},"fix(tools): the preload note's golden classification waits for the release, which is when check-golden reads a feature as shipped":{"internal":"a release-gate table, nothing a creator can observe"},+ "fix(ecs): a Mut row is no longer rewritten by its own write-back, so walking one on the web keeps its colours and a list field crosses as a vector":+ {"note":"`Mut()` on the web no longer turns a component's colours to NaN"},};