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(pipeline): a bake writes the ref a package can resolve

esenginea8beb6e642e8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 is
PROJECT-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 no
diff --git a/examples/physics-3d/assets/scenes/main.esscene b/examples/physics-3d/assets/scenes/main.esscene
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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':