@bitmagic/cli 0.1.52-dev.0 → 0.1.52-dev.2

package/README.md

@@ -191,7 +191,11 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic publish [--visibility public\|private] [--name <name>] [--description <desc>] [--force]` | Verify-gate, build if needed, and upload straight to GCS. **Private unless `--visibility public` is passed.** |
 | `bitmagic upgrade [--engine <version>] [--force]` | Refresh vendored platform files and the CLI's own skills to the currently published engine. Refuses a dirty git tree unless `--force`. Also records the project's `environment` in `bitmagic.json` if it has none yet — the engine it just vendored came from that api-server — and says so when it does. |
 | `bitmagic generate <skybox\|sound\|image\|character\|animation\|prop\|vehicle> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. `prop` upgrades an existing placeholder asset in place, `vehicle` adds a new drivable one, `animation` takes a parameter spec rather than a prompt — see below. |
+| `bitmagic assets add <file> [--name <n>] [--asset-id <id>] [--keep-glb] [--voxel-size <m>] [--max-voxel-size <m>] [--height <m>] [--hollow\|--solid] [--force]` | Upload **your own** file — `.glb`, `.vxl`, `.png/.jpg/.webp`, `.opus/.ogg/.m4a/.mp3`, `.json` — into the game's assets and write its entry into `src/work/world.json`. A `.glb` is voxelized in a headless browser (Chrome + a free port in 3000–3199, like `prop`) unless `--keep-glb`. Free — no sparks. See **Adding your own assets** below. |
+| `bitmagic assets list` | The assets in `world.json`: id, name, type, size, placed instances, and total references. Local, no network. |
+| `bitmagic assets remove <assetId> [--force]` | Remove an asset from `world.json` (the uploaded file stays in storage). Refuses while anything in `world.json` still references it; `--force` removes the asset and its placed instances together. |
 | `bitmagic cover [--prompt "..."] [--force] [--no-start-screen]` | Generate the game's cover art from `GAME-DESIGN.md`: sets the start screen, saves `.bitmagic/cover.webp`, becomes the publish thumbnail. Costs sparks. |
+| `bitmagic judge [--genre <name>] [--min-score <1-10>]` | Grade the screenshot `bitmagic verify` captured against a quality rubric built from `GAME-DESIGN.md` (plus an optional genre hint) with a vision model, and print a scorecard: four dimension scores and at most three actionable findings, also written to `.bitmagic/judge.json`. Informs rather than gates — exits 0 whatever the score, unless `--min-score` sets a bar (exit 4 below it). Warns when the project changed since the screenshot. Costs sparks (one small model call). |
 | `bitmagic forge --prompt "..." [--city\|--dungeon\|--platformer\|--freeform] [--name <name>] [--resume <jobId>]` | Design and bake a whole playable level into `world.json`. Costs sparks, and takes many minutes — the bake alone can take twenty. `--resume <jobId>` picks a failed run back up from the last step that finished, rather than redoing the whole thing. |
 
 Every command exits non-zero on failure with a single-line message (no stack trace) and, where a
@@ -497,6 +501,66 @@ engine's terrain tools, but saving them needs an asset upload this command does
 editor warns you as soon as you change a voxel and offers to discard it. Use the web Creator for
 terrain work.
 
+## Adding your own assets
+
+`bitmagic assets add` is the Creator's Assets-tab upload for a project your own agent edits: a
+Blender model, a sound library, a texture, a `.vxl` exported from the Creator or a config JSON goes
+into storage and into `src/work/world.json` in one command. Nothing here costs sparks.
+
+```bash
+bitmagic assets add ./models/lantern.glb                 # voxelized in a headless browser → a `vxl` asset
+bitmagic assets add ./models/lantern.glb --keep-glb      # kept as a polygon mesh (`glb`), 2 m tall
+bitmagic assets add ./models/lantern.glb --voxel-size 0.05 --height 1.2 --hollow
+bitmagic assets add ./sfx/door-slam.mp3 --name doorSlam  # audio, uploaded as-is
+bitmagic assets add ./textures/rune.png                  # image; the thumbnail is the image
+bitmagic assets add ./data/waves.json                    # config data for `loadJsonAsset`
+bitmagic assets list
+bitmagic assets remove asset_1755600000000_k3j9x1
+```
+
+What each file becomes:
+
+| File | Asset `type` | Notes |
+|---|---|---|
+| `.glb` | `vxl` | Uploaded first (kept as `sourceGlbUrl`), then the engine voxelizes it: `--voxel-size` (finest, default 0.1 m), `--max-voxel-size` (flat areas, default 0.5 m), `--height` (scale to this height; default the model's own size). Interiors fill solid for prop-scale models and stay hollow above 6 m, matching `generate prop` — a solid-filled building is millions of wasted voxels. `--hollow` and `--solid` override that either way. Needs Chrome and a free port between 3000 and 3199. |
+| `.glb --keep-glb` | `glb` | A polygon mesh, no voxelizing, no browser. `--height` sets `targetHeight` (default 2 m). |
+| `.vxl` | `vxl` | Must be the binary VXL3 format (versions 3-9) the Creator and the engine export. Bounds, voxel size and voxel count are read from the file's own header. |
+| `.png .jpg .jpeg .webp` | `image` | Uploaded as-is. |
+| `.opus .ogg .m4a .mp3` | `audio` | Uploaded as-is. The engine plays all four; the Creator would transcode to `.opus` for a smaller download, and the command prints the `ffmpeg` line that does the same. |
+| `.json` | `json` | The config-data assets `game/agent-docs/json-assets.md` describes. |
+| `.gltf` | refused | Its buffers and textures live in files beside it, and the game loads one URL. Export a self-contained `.glb`. |
+| `.vox .qb .fbx .spz .ply .sog .mp4` | refused | Each needs a conversion the Creator runs server-side (voxel-model import, FBX animation import, splat transcode, video faststart). Upload those through the Creator's Assets tab. |
+
+The name defaults to the filename without its extension (`--name` overrides). The id is minted as
+`asset_<timestamp>_<random>` unless `--asset-id` gives one — re-running with the same id **replaces**
+the asset, which is how a `--asset-id` retry stays idempotent. A replacement **merges**: fields the
+upload does not determine (`fitBox`, `vehicleFitment`, `collision`, `light`, …) survive it, and the
+asset's cached thumbnail is dropped so the dev view re-renders. Replacing a still-referenced asset
+with a *different* type is refused unless you pass `--force`, because every reference to it would
+then resolve to something the engine cannot render. Every entry records
+`production: { method: "uploaded", sourceUrl, sourceName }`.
+
+Uploads are read with symlinks refused and capped at 512 MB: the destination is a permanent public
+URL that nothing can delete, so the command will not follow a link to a file you did not mean to
+publish.
+
+The upload is refused before anything is sent when the project's `gameId` is not one the logged-in
+account owns, and every failure before the write says `world.json is unchanged`. A `.glb` whose bake
+fails after the upload prints where the GLB landed and the exact `--asset-id` to re-run with, so the
+retry replaces that attempt instead of adding a second asset. While it runs, the upload shows in the
+dev view's assets panel like any other job (`.bitmagic/jobs/`).
+
+`bitmagic assets remove` edits `world.json` only — the file stays in storage, exactly as the
+Creator's Remove leaves it (published games keep loading; every upload is immutable). It looks first
+for anything in `world.json` still pointing at the asset — any `assetId`, `<thing>AssetId` or
+`<thing>AssetIds` key, so placed objects, a level's `vwldAssetId`, a map, doors, key items and a
+village's `buildingAssetIds` all count — and refuses while there is, listing where; `--force`
+removes the asset and its placed instances in one write and reports the rest. `assets list` shows
+the same total in its `REFS` column, so the two commands never disagree about what is in use. Game
+code that names the id (`engine.playSound(...)`, `spawnFromAsset(...)`) is not checked, and neither
+is a lookup by *name* — `loadJsonAsset` resolves the first asset with a matching name, so `add`
+warns when a name is already taken.
+
 ## Drivable vehicles
 
 `bitmagic generate vehicle` designs a vehicle and registers it as a **new** asset — unlike
@@ -581,13 +645,14 @@ refused is a bundle that is not a Bitmagic engine build at all (exit 1).
 
 ### Exit codes
 
-`bitmagic publish` uses these to let a script or agent branch without parsing the message:
+`bitmagic publish` and `bitmagic judge` use these to let a script or agent branch without parsing the message:
 
 | Code | Meaning |
 |---|---|
 | 1 | Build failed, or the uploaded bundle was not a Bitmagic engine build (check `vite.publish.config.js`). Not retryable — republishing the same bytes gets the same refusal. |
 | 2 | Not logged in |
 | 3 | Verify missing, stale, or failed |
+| 4 | `bitmagic judge --min-score`: the judge ran, but the overall score is below the bar. The scorecard is in `.bitmagic/judge.json`. |
 | 5 | Not the game's owner, or the account/game is banned |
 | 6 | Upload or finalize failed — usually transient (network/storage), but also covers permanent failures such as an unknown game or a rejected request. Retry once; if it fails identically, stop and report it. |
 | 7 | The game published, but did not render when loaded the way the portal loads it. The game IS live — fix it and publish again rather than retrying the publish. Artifacts in `.bitmagic/smoke/`. |

package/dist/assets/add.d.ts

@@ -0,0 +1,66 @@
+import type { Environment } from '../config/environments.js';
+import type { ProjectContext } from '../project/context.js';
+export interface VoxelizeFlags {
+    minVoxelSize: number;
+    maxVoxelSize: number;
+    /** Metres. Absent = the GLB's own size, as the Creator's dialog leaves it by default. */
+    targetHeight?: number;
+    fillInterior: boolean;
+}
+/** What the headless engine is asked to bake. */
+export interface VoxelizeGlbRequest {
+    context: ProjectContext;
+    environment: Environment;
+    token: string;
+    name: string;
+    glbUrl: string;
+    assetId: string;
+    voxel: VoxelizeFlags;
+    retryHint: string;
+    log: (message: string) => void;
+}
+/** Runs the bake and returns the engine's asset record. Injected in tests, real everywhere else. */
+export type VoxelizeGlb = (request: VoxelizeGlbRequest) => Promise<Record<string, unknown>>;
+export interface AddAssetOptions {
+    context: ProjectContext;
+    environment: Environment;
+    token: string;
+    filePath: string;
+    name?: string;
+    assetId?: string;
+    keepGlb: boolean;
+    /** Replace a still-referenced asset even when the type changes. See the gate in addAssetFile. */
+    force: boolean;
+    voxel: VoxelizeFlags;
+    fetchImpl?: typeof globalThis.fetch;
+    voxelize?: VoxelizeGlb;
+    now?: () => Date;
+    log: (message: string) => void;
+}
+export interface AddAssetResult {
+    assetId: string;
+    name: string;
+    type: string;
+    url: string;
+    size: number;
+    sourceGlbUrl?: string;
+    voxelCount?: number;
+    /** True when an asset with this id already existed and was replaced. */
+    replaced: boolean;
+    /** Anything the creator should know that is not an error — e.g. that audio went up untranscoded. */
+    notes: string[];
+}
+/**
+ * Biggest file this lane will upload. Not a server limit — api-server caps nothing — but a local
+ * one: every byte is held in memory, gzipped in memory for the compressible types, and the object
+ * is immutable once written with no delete endpoint anywhere, so an accidental multi-gigabyte
+ * upload cannot be taken back.
+ */
+export declare const MAX_ASSET_BYTES: number;
+/**
+ * The real bake: the shared headless session, one `CREATE_ASSET_FROM_GLB_URL`, the engine's record
+ * back. Same message and options as `generate prop`, minus `fitBox` (there is no placed instance
+ * to fit) and with the creator's own resolution flags.
+ */
+export declare const voxelizeUploadedGlb: VoxelizeGlb;
+export declare function addAssetFile(options: AddAssetOptions): Promise<AddAssetResult>;

package/dist/assets/add.js

@@ -0,0 +1,274 @@
+/**
+ * `bitmagic assets add <file>` — a creator's own file into the game's asset registry.
+ *
+ * The Creator's Assets tab does this with a file picker; this is the same lane for a project the
+ * creator's agent edits: upload the bytes through api-server's signed-URL route, then write the
+ * entry into `src/work/world.json`. Nothing here costs sparks — the one slow path (a `.glb`, which
+ * the engine has to voxelize in a headless browser) is compute on this machine, not a generation.
+ *
+ * Order of operations, and why:
+ *
+ *   1. Classify the file and validate the name BEFORE reading anything, so a format this lane
+ *      cannot take fails in milliseconds with world.json untouched.
+ *   2. Read world.json BEFORE uploading, so a project that is not a Bitmagic project (or whose
+ *      world.json is unreadable) fails before a file has been pushed to storage for nothing.
+ *   3. Upload. From here on the bytes exist in storage whatever happens next — which is fine: every
+ *      upload is immutable-cached and cheap, and the world.json write below is atomic, so a failure
+ *      after this point still leaves world.json exactly as it was and says so.
+ *   4. For a `.glb` (unless `--keep-glb`): hand the uploaded URL to the engine and let it bake and
+ *      upload the `.vxl` itself, exactly as `generate prop`/`vehicle` do. The engine returns the
+ *      complete asset record; only its provenance is corrected to `uploaded`.
+ *   5. One `upsertRoot` on `assets[]`, matched by id — so `--asset-id` re-runs replace rather than
+ *      duplicate — through the same atomic, schema-gated writer the forge uses.
+ */
+import * as fs from 'fs';
+import { CliError } from '../errors.js';
+import { applyModificationsToWorld } from '../forge/apply-modifications.js';
+import { projectWorldJsonPath } from '../forge/run-pipeline.js';
+import { VOXELIZE_TIMEOUT_MS, withVoxelizeSession } from '../forge/voxelize-session.js';
+import { uploadProjectFile } from '../http/signed-upload.js';
+import { isJsonObject, readWorldJson } from '../project/world-json.js';
+import { audioAssetEntry, glbAssetEntry, imageAssetEntry, jsonAssetEntry, voxelizedGlbAssetEntry, vxlAssetEntry, } from './entry.js';
+import { audioTranscodeNote, classifyAssetFile, defaultAssetName, mintAssetId, uploadFilename, validateAssetName, } from './file-kind.js';
+import { findAssetReferences } from './remove.js';
+import { summarizeVxl } from './vxl-summary.js';
+import { formatSize } from './list.js';
+function errnoCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+/** The errno, or the message when there is none — never an unmapped throw. See readFileBytes. */
+function describeErrno(error) {
+    return errnoCode(error) ?? (error instanceof Error ? error.message : String(error));
+}
+/**
+ * Biggest file this lane will upload. Not a server limit — api-server caps nothing — but a local
+ * one: every byte is held in memory, gzipped in memory for the compressible types, and the object
+ * is immutable once written with no delete endpoint anywhere, so an accidental multi-gigabyte
+ * upload cannot be taken back.
+ */
+export const MAX_ASSET_BYTES = 512 * 1024 * 1024;
+function readFileBytes(filePath) {
+    // Refuse a symlink rather than following it. This command's documented caller is an AI agent
+    // running with a path from a prompt or from a cloned template, and the destination is a public,
+    // immutable, undeletable URL recorded in world.json — so a link pointing at a credentials file
+    // or an .ssh key is an exfiltration with no undo. `lstat` does not follow, unlike `readFileSync`.
+    let stats;
+    try {
+        stats = fs.lstatSync(filePath);
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code === 'ENOENT')
+            throw new CliError(`No such file: ${filePath}. world.json is unchanged.`);
+        throw new CliError(`Cannot read ${filePath}: ${describeErrno(error)}. world.json is unchanged.`);
+    }
+    if (stats.isSymbolicLink()) {
+        throw new CliError(`${filePath} is a symlink, and this command uploads to a permanent public URL. `
+            + 'Pass the real file instead. world.json is unchanged.');
+    }
+    if (stats.isDirectory()) {
+        throw new CliError(`${filePath} is a directory, not a file. world.json is unchanged.`);
+    }
+    if (stats.size === 0)
+        throw new CliError(`${filePath} is empty. world.json is unchanged.`);
+    if (stats.size > MAX_ASSET_BYTES) {
+        throw new CliError(`${filePath} is ${Math.round(stats.size / (1024 * 1024))} MB; this command uploads at most `
+            + `${MAX_ASSET_BYTES / (1024 * 1024)} MB. world.json is unchanged.`);
+    }
+    let bytes;
+    try {
+        bytes = fs.readFileSync(filePath);
+    }
+    catch (error) {
+        // Every failure mode is mapped, so none escapes as a raw stack trace that would break this
+        // lane's "world.json is unchanged" contract (EACCES, ELOOP, EISDIR, ERR_FS_FILE_TOO_LARGE...).
+        throw new CliError(`Cannot read ${filePath}: ${describeErrno(error)}. world.json is unchanged.`);
+    }
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+function vxlEntryBuilder(summary) {
+    return (entryBase) => vxlAssetEntry(entryBase, summary);
+}
+function requireVxlSummary(bytes, filename) {
+    const summary = summarizeVxl(bytes);
+    if (summary === null) {
+        throw new CliError(`${filename} is not a VXL3 file this engine can load. Export it from the Creator or the engine `
+            + '(only the binary VXL3 format, versions 3-9, is supported). world.json is unchanged.');
+    }
+    return summary;
+}
+/**
+ * The real bake: the shared headless session, one `CREATE_ASSET_FROM_GLB_URL`, the engine's record
+ * back. Same message and options as `generate prop`, minus `fitBox` (there is no placed instance
+ * to fit) and with the creator's own resolution flags.
+ */
+export const voxelizeUploadedGlb = async (request) => {
+    const { context, environment, token, name, glbUrl, assetId, voxel, retryHint, log } = request;
+    return withVoxelizeSession({
+        context, environment, token, log, subject: `"${name}"`, retryHint,
+    }, async ({ host, port }) => {
+        log(`Voxelizing "${name}" at ${voxel.minVoxelSize}m…`);
+        const result = await host.transport.sendAndWait({
+            type: 'CREATE_ASSET_FROM_GLB_URL',
+            requestId: `upload-${assetId}-${port}`,
+            name,
+            glbUrl,
+            assetId,
+            options: {
+                minVoxelSize: voxel.minVoxelSize,
+                maxVoxelSize: voxel.maxVoxelSize,
+                ...(voxel.targetHeight !== undefined ? { targetHeight: voxel.targetHeight } : {}),
+                fillInterior: voxel.fillInterior,
+                placeholder: false,
+            },
+        }, 'ASSET_FROM_GLB_URL_RESULT', VOXELIZE_TIMEOUT_MS, { maxRetries: 1 });
+        if (!result) {
+            throw new CliError(`Voxelizing "${name}" timed out. ${retryHint}`);
+        }
+        if (result.success === false || !isJsonObject(result.asset)) {
+            const reason = typeof result.error === 'string' ? result.error : 'unknown error';
+            throw new CliError(`Voxelizing "${name}" failed: ${reason}. ${retryHint}`);
+        }
+        return result.asset;
+    });
+};
+export async function addAssetFile(options) {
+    const { context, environment, token, filePath, log } = options;
+    const now = options.now ?? (() => new Date());
+    // 1. Everything that can be refused for free.
+    const file = classifyAssetFile(filePath, { keepGlb: options.keepGlb });
+    const filename = uploadFilename(filePath);
+    const name = validateAssetName(options.name ?? defaultAssetName(filePath));
+    const assetId = options.assetId ?? mintAssetId();
+    // 2. The world this is going into, before anything leaves the machine.
+    const worldPath = projectWorldJsonPath(context.root);
+    const world = readWorldJson(worldPath);
+    const notes = [];
+    const assets = Array.isArray(world.assets) ? world.assets : [];
+    const existing = assets.find((item) => isJsonObject(item) && item.id === assetId);
+    const replaced = existing !== undefined;
+    // Replacing an id is the most destructive thing this command does, and it used to be the only
+    // one with no gate at all — `assets remove` refuses while anything still points at the asset,
+    // while `add --asset-id` would happily turn a placed prop into an audio clip. Same rule here:
+    // a replacement that CHANGES THE TYPE under live references is refused unless forced, because
+    // every one of those references resolves to something the engine cannot render.
+    if (existing !== undefined && !options.force) {
+        const existingType = typeof existing.type === 'string' ? existing.type : '';
+        const references = findAssetReferences(world, assetId);
+        if (existingType !== file.assetType && references.length > 0) {
+            throw new CliError(`Asset "${assetId}" is a ${existingType} referenced ${references.length === 1 ? 'once' : `${references.length} times`} `
+                + `in world.json, and ${filename} would replace it with ${file.assetType === 'image' ? 'an' : 'a'} `
+                + `${file.assetType}. Those references would resolve to the wrong kind of asset. `
+                + 'Use --force to do it anyway, or omit --asset-id to add a new asset. world.json is unchanged.');
+        }
+    }
+    // A name collision is not fatal, but it is silent and it matters: JSON assets are looked up BY
+    // NAME (`loadJsonAsset` -> `getAssetUrlByName`, first match wins), so a second asset sharing a
+    // name is simply never loaded. Warned rather than refused — duplicate names are legal, and the
+    // creator may well want two `rock`s they address by id.
+    const nameClash = assets.some((item) => isJsonObject(item) && item.name === name && item.id !== assetId);
+    if (nameClash) {
+        notes.push(`Another asset is already named "${name}". Assets addressed by name (JSON config assets, `
+            + 'vehicles spawned by name) resolve to the FIRST match, so give this one a distinct --name '
+            + 'if game code looks it up that way.');
+    }
+    const bytes = readFileBytes(filePath);
+    const size = bytes.byteLength;
+    // A `.vxl` is inspected before the upload so a file that is not one is refused for free. The
+    // parse is carried to the switch below as a builder rather than re-parsed there — `summarizeVxl`
+    // gunzips the whole body, so doing it twice for one add is real work for no answer.
+    const buildVxlEntry = file.kind === 'vxl'
+        ? vxlEntryBuilder(requireVxlSummary(bytes, filename))
+        : null;
+    // 3. Upload.
+    log(`Uploading ${filename} (${formatSize(size)})…`);
+    const upload = await uploadProjectFile(environment, token, { gameId: context.metadata.gameId, filename, contentType: file.contentType, bytes }, { fetch: options.fetchImpl ?? globalThis.fetch });
+    const url = upload.url;
+    log(`Uploaded: ${url}`);
+    const base = { id: assetId, name, url, size, sourceName: filename, at: now().toISOString() };
+    // 4. The record — from the engine for a voxelized GLB, built here for everything else.
+    let entry;
+    switch (file.kind) {
+        case 'image':
+            entry = imageAssetEntry(base);
+            break;
+        case 'audio': {
+            entry = audioAssetEntry(base);
+            const note = audioTranscodeNote(file.extension);
+            if (note !== null)
+                notes.push(note);
+            break;
+        }
+        case 'json':
+            entry = jsonAssetEntry(base);
+            break;
+        case 'vxl':
+            // Non-null for exactly this kind, set above in the same `file.kind` test.
+            entry = buildVxlEntry(base);
+            break;
+        case 'glb-keep':
+            entry = glbAssetEntry(base, options.voxel.targetHeight);
+            break;
+        case 'glb-voxelize': {
+            // Names --asset-id explicitly. Unlike `generate prop`/`vehicle` this command has no
+            // --glb-url, so "run it again" re-uploads the file and, without a pinned id, MINTS A NEW ONE
+            // and leaves the first upload orphaned in storage (uploads are immutable and nothing deletes
+            // them). Re-running under the same id is what makes the retry idempotent.
+            const retryHint = 'Nothing was charged and world.json is unchanged. Re-run with '
+                + `\`--asset-id ${assetId}\` so the retry replaces this attempt instead of adding a second `
+                + `asset (the GLB from this run is already uploaded at ${url}).`;
+            const voxelize = options.voxelize ?? voxelizeUploadedGlb;
+            const engineAsset = await voxelize({
+                context, environment, token, name, glbUrl: url, assetId, voxel: options.voxel, retryHint, log,
+            });
+            // The engine ECHOES the id we asked for — but only since the vendored engine learned to
+            // honour a supplied id for an asset that does not exist yet. An older one mints its own,
+            // and because `entry` spreads the engine's record while the upsert predicate matches OUR
+            // id, the mismatch would silently APPEND under a different id than the one reported: the
+            // command prints an id that is in no world.json entry, `assets remove` cannot find it, and
+            // a `--asset-id` retry adds a second copy instead of replacing. `generate vehicle` reads
+            // the id back for the same reason; this is the same check, made loud.
+            const engineId = typeof engineAsset.id === 'string' ? engineAsset.id : '';
+            if (engineId !== assetId) {
+                throw new CliError(`The engine registered "${name}" under id "${engineId || '(none)'}" instead of "${assetId}", so `
+                    + 'this CLI cannot write it reliably. The project\'s vendored engine is too old for '
+                    + '`bitmagic assets add` — run `bitmagic upgrade`, then retry. world.json is unchanged '
+                    + `(the GLB is already uploaded at ${url}).`);
+            }
+            entry = voxelizedGlbAssetEntry(engineAsset, base);
+            break;
+        }
+    }
+    // 5. One atomic write.
+    //
+    // MERGED over the existing record, not substituted for it. An asset accumulates authored state
+    // the uploader knows nothing about — `fitBox` (without which the dev view's HQ regeneration
+    // refuses outright), `vehicleFitment` (without which a vehicle stops driving), `collision`,
+    // `light`, `flattenTerrain`, `lodVariants` — and writing a fresh record over the top silently
+    // discarded all of it. `editor/server.ts` states the same rule for its own asset write: "An
+    // updater, not a replacement". The new record wins field by field, so everything this upload
+    // actually determined still lands.
+    const value = existing === undefined ? entry : { ...existing, ...entry };
+    const modification = {
+        type: 'upsertRoot',
+        path: ['assets'],
+        predicate: (item) => isJsonObject(item) && item.id === assetId,
+        value,
+    };
+    applyModificationsToWorld(worldPath, [modification], { subject: 'The uploaded asset' });
+    const finalUrl = typeof entry.url === 'string' ? entry.url : url;
+    return {
+        assetId,
+        name,
+        type: typeof entry.type === 'string' ? entry.type : file.assetType,
+        url: finalUrl,
+        size: typeof entry.size === 'number' ? entry.size : size,
+        ...(typeof entry.sourceGlbUrl === 'string' ? { sourceGlbUrl: entry.sourceGlbUrl } : {}),
+        ...(typeof entry.voxelCount === 'number' ? { voxelCount: entry.voxelCount } : {}),
+        replaced,
+        notes,
+    };
+}
+//# sourceMappingURL=add.js.map

package/dist/assets/add.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.js","sourceRoot":"","sources":["../../src/assets/add.ts"],"names":[],"mappings":"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"}

package/dist/assets/entry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The world.json `assets[]` record for a file a creator uploaded, kind by kind.
+ *
+ * Kept pure — inputs in, a plain object out — so the shape each kind writes is unit-tested
+ * without a project on disk, and so `add.ts` stays about the order of operations (classify, read,
+ * upload, bake, write) rather than about which fields go where.
+ *
+ * Every shape mirrors what the Creator's Assets tab writes for the same file
+ * (`useAssetsEditor.ts` `handleFileUpload`, `assetsGlbKeepImport.ts`), including `production`:
+ * `uploaded` is the one provenance only the uploading side can know — the engine's voxelize
+ * handler stamps `generated` because it sees the same GLB whether a person or a generator made it,
+ * and the Creator overwrites that too.
+ */
+import type { VxlSummary } from './vxl-summary.js';
+export interface UploadedAssetBase {
+    id: string;
+    name: string;
+    /** Where the uploaded bytes are served from. */
+    url: string;
+    /** Raw file size in bytes — what the Creator records, not the gzipped transfer size. */
+    size: number;
+    /** The file's basename, kept as provenance. */
+    sourceName: string;
+    /** ISO timestamp for `production.at`. */
+    at: string;
+}
+/** An image: the thumbnail IS the image, as the Creator and the image generator both record. */
+export declare function imageAssetEntry(input: UploadedAssetBase): Record<string, unknown>;
+export declare function audioAssetEntry(input: UploadedAssetBase): Record<string, unknown>;
+export declare function jsonAssetEntry(input: UploadedAssetBase): Record<string, unknown>;
+/**
+ * A `.vxl` uploaded as-is, with the metadata its own header states — the fields the Creator gets
+ * back from `/api/analyze-asset` for the same file.
+ */
+export declare function vxlAssetEntry(input: UploadedAssetBase, summary: VxlSummary): Record<string, unknown>;
+/** The Creator's keep-as-GLB import: `type: 'glb'`, the mesh as its own source, 2 m tall by default. */
+export declare const DEFAULT_GLB_TARGET_HEIGHT = 2;
+export declare function glbAssetEntry(input: UploadedAssetBase, targetHeight: number | undefined): Record<string, unknown>;
+/**
+ * The record the engine returned from `CREATE_ASSET_FROM_GLB_URL`, re-stamped as an upload. The
+ * engine's own `production` says `generated` with the GLB as `sourceUrl`; the method is corrected,
+ * the source URL kept (it is the uploaded GLB), and the creator's filename added.
+ */
+export declare function voxelizedGlbAssetEntry(engineAsset: Record<string, unknown>, input: Pick<UploadedAssetBase, 'url' | 'sourceName' | 'at'>): Record<string, unknown>;

package/dist/assets/entry.js

@@ -0,0 +1,71 @@
+function baseEntry(input, type) {
+    return {
+        id: input.id,
+        name: input.name,
+        url: input.url,
+        type,
+        size: input.size,
+        production: {
+            method: 'uploaded',
+            at: input.at,
+            sourceUrl: input.url,
+            sourceName: input.sourceName,
+        },
+    };
+}
+/** An image: the thumbnail IS the image, as the Creator and the image generator both record. */
+export function imageAssetEntry(input) {
+    return { ...baseEntry(input, 'image'), screenshotUrl: input.url };
+}
+export function audioAssetEntry(input) {
+    return baseEntry(input, 'audio');
+}
+export function jsonAssetEntry(input) {
+    return baseEntry(input, 'json');
+}
+/**
+ * A `.vxl` uploaded as-is, with the metadata its own header states — the fields the Creator gets
+ * back from `/api/analyze-asset` for the same file.
+ */
+export function vxlAssetEntry(input, summary) {
+    return {
+        ...baseEntry(input, 'vxl'),
+        boundingBox: summary.boundingBox,
+        // NOT optional beside `voxelSize`. VXL3 stores world-space bounds, but the engine treats
+        // `boundingBox && !boundingBoxInMeters && voxelSize && !sourceGlbUrl` as a pre-1.1 asset whose
+        // box is in VOXEL GRID units and multiplies all six components by `voxelSize`
+        // (EnvironmentObjectSystem's legacy migration) — a silent 10-20x shrink that then mis-sizes
+        // terrain flattening, placement clearance and destruction. Every in-engine writer sets this
+        // flag for the same reason; the Creator's upload dodges it only by never recording a voxelSize.
+        boundingBoxInMeters: true,
+        voxelSize: summary.minVoxelSize,
+        fragmentCount: summary.fragmentCount,
+        ...(summary.voxelCount !== undefined ? { voxelCount: summary.voxelCount } : {}),
+    };
+}
+/** The Creator's keep-as-GLB import: `type: 'glb'`, the mesh as its own source, 2 m tall by default. */
+export const DEFAULT_GLB_TARGET_HEIGHT = 2.0;
+export function glbAssetEntry(input, targetHeight) {
+    return {
+        ...baseEntry(input, 'glb'),
+        sourceGlbUrl: input.url,
+        targetHeight: targetHeight ?? DEFAULT_GLB_TARGET_HEIGHT,
+    };
+}
+/**
+ * The record the engine returned from `CREATE_ASSET_FROM_GLB_URL`, re-stamped as an upload. The
+ * engine's own `production` says `generated` with the GLB as `sourceUrl`; the method is corrected,
+ * the source URL kept (it is the uploaded GLB), and the creator's filename added.
+ */
+export function voxelizedGlbAssetEntry(engineAsset, input) {
+    return {
+        ...engineAsset,
+        production: {
+            method: 'uploaded',
+            at: input.at,
+            sourceUrl: input.url,
+            sourceName: input.sourceName,
+        },
+    };
+}
+//# sourceMappingURL=entry.js.map

package/dist/assets/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/assets/entry.ts"],"names":[],"mappings":"AA4BA,SAAS,SAAS,CAAC,KAAwB,EAAE,IAAY;IACvD,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,IAAI;QACJ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,UAAU,EAAE;YACV,MAAM,EAAE,UAAU;YAClB,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,SAAS,EAAE,KAAK,CAAC,GAAG;YACpB,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B;KACF,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,eAAe,CAAC,KAAwB;IACtD,OAAO,EAAE,GAAG,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAwB;IACtD,OAAO,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAwB;IACrD,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAwB,EAAE,OAAmB;IACzE,OAAO;QACL,GAAG,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC;QAC1B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,yFAAyF;QACzF,+FAA+F;QAC/F,8EAA8E;QAC9E,4FAA4F;QAC5F,4FAA4F;QAC5F,gGAAgG;QAChG,mBAAmB,EAAE,IAAI;QACzB,SAAS,EAAE,OAAO,CAAC,YAAY;QAC/B,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAC;AACJ,CAAC;AAED,wGAAwG;AACxG,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAE7C,MAAM,UAAU,aAAa,CAAC,KAAwB,EAAE,YAAgC;IACtF,OAAO;QACL,GAAG,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC;QAC1B,YAAY,EAAE,KAAK,CAAC,GAAG;QACvB,YAAY,EAAE,YAAY,IAAI,yBAAyB;KACxD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAoC,EACpC,KAA2D;IAE3D,OAAO;QACL,GAAG,WAAW;QACd,UAAU,EAAE;YACV,MAAM,EAAE,UAAU;YAClB,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,SAAS,EAAE,KAAK,CAAC,GAAG;YACpB,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B;KACF,CAAC;AACJ,CAAC"}

package/dist/assets/file-kind.d.ts

@@ -0,0 +1,53 @@
+/** How the file is handled, which decides everything downstream. */
+export type AssetFileKind = 'glb-voxelize' | 'glb-keep' | 'vxl' | 'image' | 'audio' | 'json';
+export interface AssetFileClass {
+    kind: AssetFileKind;
+    /** The `type` recorded on the world.json asset entry. */
+    assetType: 'vxl' | 'glb' | 'image' | 'audio' | 'json';
+    /** What the upload is signed for; the server decides gzip from this. */
+    contentType: string;
+    /** Lower-case extension without the dot. */
+    extension: string;
+}
+/** Every extension `classifyAssetFile` accepts, for help text and the README. */
+export declare const ACCEPTED_EXTENSIONS: string[];
+export declare function fileExtension(filename: string): string;
+export declare function classifyAssetFile(filename: string, options: {
+    keepGlb: boolean;
+}): AssetFileClass;
+/**
+ * The asset's name when `--name` is not given: the file's basename without its extension, which
+ * is what the Creator pre-fills its name prompt with.
+ */
+export declare function defaultAssetName(filename: string): string;
+/**
+ * A name the engine can build a filename from. `CREATE_ASSET_FROM_GLB_URL` uploads its bake as
+ * `<gameId>-<name>-<timestamp>.vxl`, and api-server refuses a filename carrying a separator or
+ * `..` — so a name that would trip that fails HERE, before the file has been uploaded and the
+ * browser launched, instead of as an opaque "Failed to upload VXL file" minutes later.
+ *
+ * The length cap and the URL-unsafe set are part of the same job: both produce a failure that only
+ * appears after the upload (or after a ten-minute bake), which is precisely what this is for.
+ */
+export declare function validateAssetName(name: string): string;
+/**
+ * The upload filename: a bare basename, which is all api-server accepts.
+ *
+ * Mirrors `sanitizeUploadFilename` in full — separators AND `..`, as three independent checks.
+ * `path.basename` strips `/` on POSIX but leaves `\`, so a legal `my\model.glb` used to pass here
+ * and then eat a network round-trip to be refused by the server with a message naming nothing the
+ * creator could act on. The URL-unsafe and length checks are here for the same reason as on the
+ * name above.
+ */
+export declare function uploadFilename(filePath: string): string;
+/**
+ * `asset_<timestamp>_<random>` — byte-compatible with the engine's `ObjectIdService.generateId`
+ * and with what api-server mints for the generators (`cli-assets.ts`), so an id minted here is
+ * indistinguishable from one minted anywhere else in the system.
+ */
+export declare function mintAssetId(now?: () => number, random?: () => number): string;
+/**
+ * Said once per audio upload that the Creator would have transcoded. The engine plays the file
+ * as-is; this is about download size, and it names the exact command rather than a vague "consider".
+ */
+export declare function audioTranscodeNote(extension: string): string | null;