Skip to content

3D engine that AI agents drive

Skip a GLB with a missing sibling image in scene_asset_catalog (#2072)

Nguyen Xuan An6ba62b23e8a6
diff --git a/changes/2072.md b/changes/2072.md
new file mode 100644
index 00000000..83fc531d
--- /dev/null
+++ b/changes/2072.md
@@ -0,0 +1 @@
+- `scene_asset_catalog` now lists the good files and puts a GLB with a missing sibling image under `skipped` with the same reason and fix, instead of failing for the whole folder; reading that file by name keeps its error (#2072).
diff --git a/docs/mcp.md b/docs/mcp.md
index 68968f1b..e2daa894 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -147,7 +147,7 @@ Inspect or export the recipe before retrying. Context loss still permits recipe
| --- | --- | --- |
| `scene_capabilities` | `topic` (optional; a name or a list of up to 8; in a list, unknown names come back in `unknown` with suggestions beside the answers of the valid ones) | A short index of topics; with a topic, its limits and fields (`motion`, `environment`, `materialFields`, `meshEdit` (each op with its arguments as `name:type`, `?` for optional, and the face, edge and vertex rules once), `meshEdit.<op>` (every field with its notes), `physics`, `jobs`, `examples` and more; `examples.<tool>` is a complete call for `scene_create`, `scene_apply`, `scene_create_asset` or `scene_render_submit`) |
| `scene_create` | `recipe` | Session ID, revision, inspection, and render status |
-| `scene_asset_catalog` | None | Configured catalog and content-bound GLB, image, `.hdr` (kind `environment`) and `.cube` (kind `look`) IDs; an ID goes in `environment.hdri` or `environment.look`, see [agent-look](agent-look.md#catalog-hdris-and-looks). A file over its limit (an `.hdr` over 8 MiB, a `.cube` over 4 MiB, an image over 1024 pixels a side or 64 MiB decoded, read from its header) is left out and listed with a reason in `skipped`, so the other IDs still list. A folder of more than 256 consecutively numbered images is listed once under `sequences` (`name` such as `frame_####.png`, `first`, `last`, `frames`, `width`, `height`), and a material `map.sequence` names it with `catalog` instead of listing the frame IDs, see [agent-scene](agent-scene.md#image-sequence-maps) |
+| `scene_asset_catalog` | None | Configured catalog and content-bound GLB, image, `.hdr` (kind `environment`) and `.cube` (kind `look`) IDs; an ID goes in `environment.hdri` or `environment.look`, see [agent-look](agent-look.md#catalog-hdris-and-looks). A file over its limit (an `.hdr` over 8 MiB, a `.cube` over 4 MiB, an image over 1024 pixels a side or 64 MiB decoded, read from its header), or a GLB whose image is missing next to it (the reason says which file to copy), is left out and listed with a reason in `skipped`, so the other IDs still list. A folder of more than 256 consecutively numbered images is listed once under `sequences` (`name` such as `frame_####.png`, `first`, `last`, `frames`, `width`, `height`), and a material `map.sequence` names it with `catalog` instead of listing the frame IDs, see [agent-scene](agent-scene.md#image-sequence-maps) |
| `scene_create_asset` | `recipe` using `crucible.asset` | Imported scene ID, revision, inspection and render status |
| `scene_inspect` | `sessionId`, optional `ids`, `limit`, `includeBounds` | Compact node records and revision |
| `scene_apply` | `sessionId`, `expectedRevision`, `operations` | Updated revision, render status, results and diff |
diff --git a/scripts/agent-asset-catalog.mjs b/scripts/agent-asset-catalog.mjs
index 57a373ca..76c16bb4 100644
--- a/scripts/agent-asset-catalog.mjs
+++ b/scripts/agent-asset-catalog.mjs
@@ -16,7 +16,7 @@ const MAXIMUM_BYTES = AGENT_ASSET_LIMITS.maxBytes;
const IMAGE_EXTENSIONS = { png: /\.png$/i, jpeg: /\.jpe?g$/i, webp: /\.webp$/i };
/**
- * A file the catalog refuses for its size or pixel bounds. Listing skips it and says why, so one such file does not hide the
+ * A file the catalog refuses for its size, its pixel bounds or a texture it cannot find (#2072). Listing skips it and says why, so one such file does not hide the
* others; reading it by name still throws.
*/
export class SkippableCatalogFileError extends RangeError {
@@ -179,7 +179,7 @@ async function readSiblingImage(directory, glbName, uri, segments) {
try {
original = await lstat(path);
} catch {
- throw new Error(`${label} was not found next to the GLB. Copy that file into the GLB's folder at the same relative path.`);
+ throw new SkippableCatalogFileError(`${label} was not found next to the GLB. Copy that file into the GLB's folder at the same relative path.`);
}
if (!original.isFile() || original.isSymbolicLink()) throw new Error(`${label} must be a regular file, without links.`);
const resolved = await realpath(path);
diff --git a/tests/agent-asset-catalog.test.js b/tests/agent-asset-catalog.test.js
index f4c327ef..8bff3068 100644
--- a/tests/agent-asset-catalog.test.js
+++ b/tests/agent-asset-catalog.test.js
@@ -7,7 +7,7 @@ import { join, dirname } from 'node:path';
import { mat4 } from 'gl-matrix';
import { box } from '../src/geometry.js';
import { exportGlb } from '../src/export.js';
-import { createAgentAssetCatalog } from '../scripts/agent-asset-catalog.mjs';
+import { createAgentAssetCatalog, readCatalogFile } from '../scripts/agent-asset-catalog.mjs';
import { AGENT_ASSET_LIMITS, agentAssetDecodeOptions, withCatalogLimitAdvice } from '../src/agent-asset-limits.js';
import { GLTF_CAPABILITIES, parseGltf } from '../src/gltf.js';
@@ -182,11 +182,10 @@ test('a Kenney GLB loads with the colormap that sits next to it, embedded into t
assert.equal(listing.assets[0].assetId, createHash('sha256').update(stored).digest('hex'));
});
-test('a GLB texture that is missing, remote, outside the folder or not an image is refused with the file and the fix', async context => {
+test('a GLB texture that is missing, remote, outside the folder or not an image is refused with the file and the fix (a missing one is skipped, see #2072)', async context => {
const directory = await boatFixture(context);
const boat = await readFile(join(directory, 'boat-fishing-small.glb'));
const attempts = [
- ['Textures/absent.png', /boat-fishing-small\.glb: image "Textures\/absent\.png" was not found next to the GLB/],
['https://example.invalid/colormap.png', /remote or embedded address.*relative path/],
['data:image/png;base64,AAAA', /remote or embedded address/],
['../colormap.png', /leaves the GLB's folder.*relative path/],
@@ -204,6 +203,19 @@ test('a GLB texture that is missing, remote, outside the folder or not an image
await assert.rejects(createAgentAssetCatalog(directory), /not a PNG, JPEG or WebP/);
});
+test('a GLB whose texture is missing is skipped with the fix while the good GLB still lists, and naming it directly keeps the error (#2072)', async context => {
+ const directory = await boatFixture(context);
+ const boat = await readFile(join(directory, 'boat-fishing-small.glb'));
+ await writeFile(join(directory, 'bad.glb'), withDocument(boat, document => { document.images[0].uri = 'Textures/absent.png'; }));
+ const listing = (await createAgentAssetCatalog(directory)).list();
+ assert.deepEqual(listing.assets.map(asset => asset.name), ['boat-fishing-small.glb']);
+ assert.deepEqual(listing.skipped, [{
+ name: 'bad.glb',
+ reason: "bad.glb: image \"Textures/absent.png\" was not found next to the GLB. Copy that file into the GLB's folder at the same relative path.",
+ }]);
+ await assert.rejects(readCatalogFile(directory, 'bad.glb'), /bad\.glb: image "Textures\/absent\.png" was not found next to the GLB\. Copy that file into the GLB's folder/);
+});
+
test('a texture folder that links out of the catalog folder is refused', async context => {
const directory = await boatFixture(context);
const outside = await mkdtemp(join(tmpdir(), 'crucible-outside-'));