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(pipeline): a bake writes the ref a package can resolve
esenginea8beb6e642e8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 37c7d369b..a943ac8cd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -240,6 +240,24 @@ published separately; it ships inside the editor.### Fixed+- **A baked room is lit in the package too.** `bake-scene` wrote the atlas's file+ NAME into every `MeshLightmap`, and an asset ref resolves from the PROJECT+ root — so the name meant something beside the scene and nothing anywhere else.+ The editor drew the room correctly, because it reads the file off the disk it+ is sitting on. The packaged game asked its server for `main_lightmap.png`, got+ a 404, and ran the room unlit with the atlas sitting right there in the package+ under its content hash. The probe grid went the same way. Both doors now write+ the `@uuid:` the product's own `.meta` carries, which is what the editor's bake+ already did — of the two halves of "an asset ref is project-relative", the+ reading one was fixed this release and the writing one was not.++ `check-asset-refs` holds every asset-valued field in the corpus to a ref a+ package can resolve: a `@uuid:`, a `builtin:`, or a path from the project root.+ Which fields those are it reads from `component.assetFields`, not a list of its+ own. Nothing shorter reaches this: the bake is deterministic and its own gate+ compares a fresh bake to the committed one, so both sides spelled the same+ wrong name and agreed.+- **The command line bakes the meshes a scene actually names.** An asset ref isPROJECT-relative, and `bake-scene` resolved it against the scene's own folder —so every object drawing a real `.esmesh` fell out of the bake with "draws nodiff --git a/examples/physics-3d/assets/scenes/main.esscene b/examples/physics-3d/assets/scenes/main.essceneindex e7928a37a..e10a4c43e 100644--- a/examples/physics-3d/assets/scenes/main.esscene+++ b/examples/physics-3d/assets/scenes/main.esscene@@ -89,7 +89,7 @@{"type": "MeshLightmap","data": {- "lightmap": "main_lightmap.png",+ "lightmap": "@uuid:b55cdc1e-9d77-4868-aa6e-e24c4156a10f","scaleOffset": {"x": 0.59765625,"y": 0.59765625,@@ -157,7 +157,7 @@{"type": "MeshLightmap","data": {- "lightmap": "main_lightmap.png",+ "lightmap": "@uuid:b55cdc1e-9d77-4868-aa6e-e24c4156a10f","scaleOffset": {"x": 0.1455078125,"y": 0.1455078125,@@ -225,7 +225,7 @@{"type": "MeshLightmap","data": {- "lightmap": "main_lightmap.png",+ "lightmap": "@uuid:b55cdc1e-9d77-4868-aa6e-e24c4156a10f","scaleOffset": {"x": 0.169921875,"y": 0.169921875,@@ -293,7 +293,7 @@{"type": "MeshLightmap","data": {- "lightmap": "main_lightmap.png",+ "lightmap": "@uuid:b55cdc1e-9d77-4868-aa6e-e24c4156a10f","scaleOffset": {"x": 0.21875,"y": 0.21875,@@ -535,7 +535,7 @@{"type": "MeshLightmap","data": {- "lightmap": "main_lightmap.png",+ "lightmap": "@uuid:b55cdc1e-9d77-4868-aa6e-e24c4156a10f","scaleOffset": {"x": 0.0712890625,"y": 0.0712890625,@@ -966,7 +966,7 @@{"type": "MeshLightmap","data": {- "lightmap": "main_lightmap.png",+ "lightmap": "@uuid:b55cdc1e-9d77-4868-aa6e-e24c4156a10f","scaleOffset": {"x": 0.15234375,"y": 0.15234375,@@ -1033,7 +1033,7 @@{"type": "MeshLightmap","data": {- "lightmap": "main_lightmap.png",+ "lightmap": "@uuid:b55cdc1e-9d77-4868-aa6e-e24c4156a10f","scaleOffset": {"x": 0.033203125,"y": 0.033203125,@@ -1290,7 +1290,7 @@{"type": "MeshLightmap","data": {- "lightmap": "main_lightmap.png",+ "lightmap": "@uuid:b55cdc1e-9d77-4868-aa6e-e24c4156a10f","scaleOffset": {"x": 0.0283203125,"y": 0.0283203125,@@ -1421,7 +1421,7 @@{"type": "MeshLightmap","data": {- "lightmap": "main_lightmap.png",+ "lightmap": "@uuid:b55cdc1e-9d77-4868-aa6e-e24c4156a10f","scaleOffset": {"x": 0.025390625,"y": 0.025390625,@@ -1547,7 +1547,7 @@{"type": "LightProbeVolume","data": {- "probes": "main_probes_50.esprobes",+ "probes": "@uuid:23105ef9-d948-48f2-808c-266c136c0b46","halfExtents": {"x": 750,"y": 220,diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex 61e570d11..92a1eabe9 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -281,14 +281,25 @@ async function bakeScene(baker, sceneFile, check) {const atlasName = `${stem}_lightmap.png`;const atlasFile = path.join(sceneDir, atlasName);+ // The REF and not the file name: a package addresses assets by uuid and renames+ // files to their content hash. Read from the product's own `.meta`, since `byUuid`+ // was built before this bake wrote anything.+ const refTo = (absFile) => {+ try {+ const meta = JSON.parse(readFileSync(`${absFile}.meta`, 'utf8'));+ return typeof meta.uuid === 'string' ? `@uuid:${meta.uuid}` : '';+ } catch { return ''; }+ };+ const atlasRef = refTo(atlasFile);+// One file per volume, named for the entity that holds it: adding a second// volume must not rename the first one's grid.const grids = new Map();result.probes.forEach((doc, i) => {if (!doc) return;+ const name = `${stem}_probes_${volumes[i].entity}.esprobes`;grids.set(volumes[i].entity, {- name: `${stem}_probes_${volumes[i].entity}.esprobes`,- text: baker.probeDocumentText(doc),+ name, text: baker.probeDocumentText(doc), ref: refTo(path.join(sceneDir, name)),});});@@ -301,7 +312,7 @@ async function bakeScene(baker, sceneFile, check) {if (at >= 0) entity.components.splice(at, 1);continue;}- const data = { lightmap: atlasName,+ const data = { lightmap: atlasRef || atlasName,scaleOffset: { x: rect[0], y: rect[1], z: rect[2], w: rect[3] } };if (at >= 0) entity.components[at] = { type: 'MeshLightmap', data };else entity.components.push({ type: 'MeshLightmap', data });@@ -322,7 +333,7 @@ async function bakeScene(baker, sceneFile, check) {const grid = grids.get(entity.id);entity.components[at] = {type: 'LightProbeVolume',- data: { ...entity.components[at].data, probes: grid ? grid.name : '' },+ data: { ...entity.components[at].data, probes: grid ? (grid.ref || grid.name) : '' },};}const document = `${JSON.stringify(scene, null, 2)}\n`;@@ -363,6 +374,17 @@ async function bakeScene(baker, sceneFile, check) {writeFileSync(atlasFile, result.atlasBytes);for (const g of grids.values()) writeFileSync(path.join(sceneDir, g.name), g.text);writeFileSync(sceneFile, document);++ // A product written for the first time has no `.meta` yet, so the scene had to+ // name it by file name — which an export cannot resolve. Said here rather than+ // left to --check, since this is the run that produced it.+ const nameless = [atlasRef ? '' : atlasName,+ ...[...grids.values()].filter((g) => !g.ref).map((g) => g.name)].filter(Boolean);+ if (nameless.length > 0) {+ console.warn(`bake-scene: ${nameless.join(', ')} — no .meta, so the scene names it by file`+ + ' name and a package cannot carry it. Mint one and bake again:'+ + ` node tools/asset-meta.js ${path.relative(REPO, sceneDir)}`);+ }console.log(`bake-scene: ${result.lumels} lumel(s) over ${placed.size} object(s)`+ `${grids.size ? `, ${grids.size} probe grid(s)` : ''}`+ ` -> ${path.relative(REPO, atlasFile)}`);diff --git a/tools/check-asset-refs.mjs b/tools/check-asset-refs.mjsnew file mode 100644index 000000000..85ad512e5--- /dev/null+++ b/tools/check-asset-refs.mjs@@ -0,0 +1,125 @@+#!/usr/bin/env node+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-asset-refs.mjs — a ref a package cannot resolve is a ref to nothing.+ *+ * `component.assetFields` is what makes a field an asset reference: cook+ * inclusion, dependency tracking and `@uuid:` resolution all read it. What a+ * document may SPELL in one is a `@uuid:`, a `builtin:`, or a path from the+ * PROJECT root. An export renames every asset to its content hash and addresses+ * it by one of those, so anything else resolves only in the editor, which reads+ * the file off the disk it is sitting on.+ *+ * That is how a bake shipped dark. `bake-scene` wrote the atlas's bare file+ * name, which means something beside the scene and nothing anywhere else; the+ * packaged game asked its server for `main_lightmap.png` and got a 404, with+ * every gate green — the editor drew the room correctly, and the only tier that+ * launches that project is one CI does not run.+ *+ * node tools/check-asset-refs.mjs+ */+import { readFileSync, readdirSync, existsSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+/** The shipped corpus: what a creator opens, and what a release argues from. */+const CORPUS = ['examples', 'templates', 'sdk/src', 'tools/fixtures'];++/** Which fields carry an asset, read from the declaration rather than listed+ * here: a list would be a second author, and it is the one that goes stale. */+function assetFieldsByComponent() {+ const gen = readFileSync(path.join(ROOT, 'sdk/src/ecs/component.generated.ts'), 'utf8');+ const entry = /^ {4}([A-Za-z0-9_]+): \{$/gm;+ const marks = [];+ let m;+ while ((m = entry.exec(gen))) marks.push({ name: m[1], at: m.index });+ const out = new Map();+ for (let i = 0; i < marks.length; i++) {+ const body = gen.slice(marks[i].at, marks[i + 1]?.at ?? gen.length);+ const decl = /assetFields: \[(.*?)\],\n/s.exec(body);+ if (!decl) continue;+ const fields = [...decl[1].matchAll(/field: '([^']+)'/g)].map((x) => x[1]);+ if (fields.length > 0) out.set(marks[i].name, fields);+ }+ return out;+}++function documents() {+ const out = [];+ const walk = (dir) => {+ let entries;+ try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }+ for (const e of entries) {+ if (e.name === 'node_modules' || e.name === 'dist' || e.name.startsWith('.')) continue;+ const p = path.join(dir, e.name);+ if (e.isDirectory()) walk(p);+ else if (/\.(esscene|esprefab)$/i.test(e.name)) out.push(p);+ }+ };+ for (const d of CORPUS) walk(path.join(ROOT, d));+ return out;+}++/** A path ref is relative to the project, which is the directory the asset+ * browser shows — not to the document, which is why this walks up. */+function projectRootOf(file) {+ let dir = path.dirname(file);+ while (dir.startsWith(ROOT) && dir !== ROOT) {+ if (existsSync(path.join(dir, 'project.esproject'))) return dir;+ dir = path.dirname(dir);+ }+ return null;+}++const fieldsOf = assetFieldsByComponent();+if (fieldsOf.size === 0) {+ console.error('check-asset-refs: read no assetFields declarations — the reader is broken,'+ + ' not the corpus');+ process.exit(1);+}++const problems = [];+let refs = 0;+let loose = 0;+const docs = documents();+for (const file of docs) {+ let doc;+ try { doc = JSON.parse(readFileSync(file, 'utf8')); } catch { continue; }+ const root = projectRootOf(file);+ const rel = path.relative(ROOT, file);+ const visit = (node) => {+ if (Array.isArray(node)) { node.forEach(visit); return; }+ if (node === null || typeof node !== 'object') return;+ const fields = typeof node.type === 'string' ? fieldsOf.get(node.type) : undefined;+ if (fields && node.data !== null && typeof node.data === 'object') {+ for (const field of fields) {+ const value = node.data[field];+ if (typeof value !== 'string' || value === '') continue;+ refs++;+ if (value.startsWith('@uuid:') || value.startsWith('builtin:')) continue;+ // Outside a project there is no root to resolve against, so the shape is+ // all that can be judged. Counted rather than skipped silently.+ if (!root) { loose++; continue; }+ if (existsSync(path.join(root, value))) continue;+ const beside = path.join(path.dirname(file), value);+ problems.push(`${rel}: ${node.type}.${field} = "${value}" resolves to nothing`+ + (existsSync(beside) ? ' from the project root (it names a file beside the document —'+ + ' a ref is project-relative, and a package carries no such path)' : ''));+ }+ }+ for (const v of Object.values(node)) visit(v);+ };+ visit(doc);+}++if (problems.length > 0) {+ console.error(`\ncheck-asset-refs: ${problems.length} ref(s) a package cannot resolve\n`);+ for (const p of problems) console.error(` - ${p}`);+ console.error('\n A ref is "@uuid:<uuid>", "builtin:<name>", or a path from the project root.\n');+ process.exit(1);+}++console.log(`check-asset-refs: ${refs} asset ref(s) over ${docs.length} document(s) all resolve`+ + `${loose > 0 ? `; ${loose} outside any project, judged by shape only` : ''}.`);diff --git a/tools/gates.mjs b/tools/gates.mjsindex 83ee786bd..6bc4e6202 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -235,6 +235,7 @@ export const GATES = [why: 'the bake reads the meshes the scene names, and takes about ten seconds',},{ id: 'asset-vocabulary', run: 'node tools/check-asset-vocabulary.mjs' },+ { id: 'asset-refs', run: 'node tools/check-asset-refs.mjs' },{ id: 'lod-authoring', run: 'node tools/check-lod-authoring.mjs', needs: 'editor' },{ id: 'shadow-plan', run: 'node tools/check-shadow-plan.mjs' },{ id: 'light-cap', run: 'node tools/check-light-cap.mjs' },diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex a9f04dbc2..22aaba0b3 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'fix(pipeline): a bake writes the ref a package can resolve':+ { note: 'A baked room is lit in the package too.' },+'feat(lighting): a scene says how it is lit, and whether its light still describes it':{ note: 'A scene says how it is lit, and whether its light still describes it.' },'feat(lighting): a Lighting panel, and a scene that says whether its light is stale':