@bitmagic/cli 0.1.52-dev.1 → 0.1.52-dev.10

package/README.md

@@ -190,10 +190,14 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic build` | Bundle the game into one self-contained `.bitmagic/build/index.html`. Rarely needs to be run by hand — `publish` builds automatically when the project changed. |
 | `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 generate <skybox\|background\|block-type\|sound\|image\|character\|animation\|model\|prop\|vehicle> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. `model` mints a **new** 3D object from a prompt, `prop` upgrades an existing placeholder **in place**, `vehicle` adds a new drivable one, `animation` takes a parameter spec rather than a prompt, `block-type` registers a custom voxel block — see below. `skybox` and `background` write the **same** field: pick one. |
+| `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. |
+| `bitmagic levels <list\|add\|rename\|set-start\|remove> ...` | Manage the levels `forge` creates: which one boots, their names, registering a bake you already have, deleting one. Local, no network, no sparks. See **Managing levels** below. |
 
 Every command exits non-zero on failure with a single-line message (no stack trace) and, where a
 distinction is useful to an automated caller, a specific exit code — see **Exit codes** below.
@@ -467,9 +471,15 @@ did without inferring it from a diff:
 
 ```
 {"at":"…","event":"object.moved","objectId":"inst_…","position":{"from":{…},"to":{…}}}
+{"at":"…","event":"terrain.saved","voxelUrl":"https://…/game-terrain-….vxl"}
 {"at":"…","event":"hq.requested","assetId":"asset_…","prompt":"a mossy stone arch","command":"bitmagic generate prop …"}
 ```
 
+Most lines are worked out by comparing `world.json` before and after a save. The sculpting ones are
+not: a terrain save changes one URL that says nothing about what was carved, and a save that
+**failed** changes no file at all — so the editor reports those itself rather than leaving your
+agent to infer a thing that left no trace.
+
 ### Regenerating a placeholder
 
 Forged levels are built from placeholder assets — box-model stand-ins. Select one and the object
@@ -493,10 +503,111 @@ carries the URL: retry with `--glb-url <url>` and you are not charged again.
 Both ports must fall between 3000 and 3199. That is the window the asset CDN allows as an origin;
 outside it the game loads with no terrain and no error.
 
-What it does **not** do yet: terrain and voxel sculpting. Clicking the ground still opens the
-engine's terrain tools, but saving them needs an asset upload this command does not perform, so the
-editor warns you as soon as you change a voxel and offers to discard it. Use the web Creator for
-terrain work.
+### Sculpting the ground
+
+Click the ground and you are in the engine's terrain tools; **Save & Exit** in their toolbar keeps
+the work. The sculpted volume is uploaded and `src/work/world.json` gets the one line that points at
+it, the same surgical write every other edit here makes.
+
+That upload is the only part of `bitmagic dev` that needs an account — everything else runs offline.
+Logged out, the save fails and **says so in the toolbar, leaving your edits where they are**: run
+`bitmagic login`, then press Save & Exit again. Nothing is thrown away without you saying so, and
+`terrain.saveFailed` lands in the journal either way, so your agent knows what happened.
+
+Per-object voxel sculpting works the same way — select a voxel object, edit it, Save & Exit.
+
+## 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.
+
+## Generating a 3D model
+
+`bitmagic generate model` turns a sentence into a new placeable asset: the Asset Forger builds a
+mesh, the engine voxelizes it, and the result lands in `assets[]` under a fresh id.
+
+```bash
+bitmagic generate model --prompt "a mossy stone arch"
+bitmagic generate model --prompt "a market stall" --name marketStall --height 3
+bitmagic generate model --prompt "a cathedral" --height 30        # hollow above 6 m, automatically
+```
+
+Place it from game code by name, or drag it in from the dev view's Add-object palette.
+
+**Which of the three 3D lanes you want** matters, because picking wrong wastes a generation:
+
+| Command | Makes | Existing instances |
+|---|---|---|
+| `generate model --prompt "..."` | a **new** asset from a prompt | none yet — nothing is placed |
+| `generate prop --asset <id> --prompt "..."` | replaces the mesh of an **existing** placeholder | **all of them upgrade at once** |
+| `assets add <file>` | a new asset from a file you already have | none yet |
+
+Like `prop` and `vehicle` it needs Chrome and a free port between 3000 and 3199 — only the engine
+can voxelize, so the CLI drives its own headless browser. `--voxel-size` (default 0.1 m) and
+`--max-voxel-size` (default 0.5 m) set the bake resolution; `--height` scales the model, and
+interiors fill solid at or below 6 m and stay hollow above it (`--hollow` / `--solid` override),
+because a solid-filled building is millions of wasted voxels.
+
+It costs the same sparks as generating the same object in the web editor — both bill the Asset
+Forger call under one price, so the lane you choose never changes what a creator pays.
+
+If the bake fails after the mesh exists, the error prints the exact
+`--glb-url … --asset-id …` command to retry the browser step **without paying again**.
 
 ## Drivable vehicles
 
@@ -527,6 +638,45 @@ exact `--glb-url … --voxel-size …` command to retry the browser step without
 If the finished asset reports that it will not drive, the project's vendored engine predates
 vehicle-fitment derivation: run `bitmagic upgrade`, then regenerate.
 
+## Managing levels
+
+`bitmagic forge` bakes levels but could not manage them: only a game's *first* forge became the
+level it boots into, so fixing a wrong start, renaming, or deleting one meant opening the web
+Creator. These do it from here. They edit `src/work/world.json` directly — no network, no sparks,
+no login — and journal each change to `.bitmagic/edit/events.jsonl` so your agent sees it.
+
+```bash
+bitmagic levels list
+bitmagic levels set-start <levelId>
+bitmagic levels rename <levelId> "Old Town"
+bitmagic levels add <vwldAssetId> [--name "Cavern"] [--make-start]
+bitmagic levels remove <levelId>
+```
+
+`list` shows each level's id, name, which one is the **START**, how many spawn points it owns and
+how many placed objects belong to it — plus a warning when its baked `.vwld` asset has gone missing.
+
+**`set-start` is the one that matters most.** `worldProfileData` keeps three *mirror* fields —
+`voxelUrl`, `spawnPoints` and `playerSpawnPosition` — describing the start level, because published
+games boot from those rather than from the level registry. This moves them together. Doing it by
+hand and forgetting the mirrors gives you a game that renders the new level's objects and lighting
+over the **old** level's terrain, with matching collision from a third place and no error anywhere.
+It refuses when the level's `.vwld` asset is missing, since there would be nothing to boot.
+
+**`add`** registers a `.vwld` that is already in the project (`bitmagic assets list` shows them) —
+from a forge, or from `bitmagic assets add level.vwld`. It follows `forge`'s rule: a game's first
+level becomes the start, later ones do not unless you pass `--make-start`. On a game that has a
+world but no level registry yet, the existing world is registered as level 1 first, so it is not
+stranded by the one you are adding.
+
+**`remove`** takes the level's placed objects, doors and key items with it, and leaves the `.vwld`
+asset alone — it may be large, and nothing here deletes uploaded bytes. It refuses two cases: the
+game's only level, and the **start** level (move the start first, so you never end up with a game
+booting one level's terrain under another's objects).
+
+Runtime level switching is engine API — `engine.loadLevel(levelId)` from game code. These commands
+manage the registry, not gameplay.
+
 ## Publishing
 
 `bitmagic publish` is two gated steps in one command:
@@ -560,6 +710,26 @@ before `--force` has anything to work with.
 stick — and note that writing them into `game.json` yourself would change the fingerprint and
 invalidate the verify you just checked.
 
+### Which platform the game is catalogued as
+
+Publish syncs two indicators from your project files, so bitmagic.ai lists the game as what it
+actually is:
+
+| Indicator | Where you set it | Values |
+|---|---|---|
+| `primaryPlatform` | top level of `src/work/game.json` | `desktop` (templates ship this) or `mobile` |
+| `mobileOrientation` | `worldProfileData` in `src/work/world.json` | `portrait` or `landscape`; absent means no lock |
+
+Those files are the **source of truth**: each publish re-sends what they say, so a value changed
+elsewhere (an admin edit, say) is replaced by your next publish, and removing `mobileOrientation`
+from `world.json` clears the stored lock. A project whose `game.json` declares no
+`primaryPlatform` at all leaves the stored value alone rather than forcing it to `desktop`.
+
+Only the catalogue entry is at stake here — the game itself is playable from a phone either way.
+Making it *good* on a phone is code, and the scaffolded `AGENTS.md` tells your agent how: bind every
+action with `registerCustomAction`/`declareMobileActions` so each desktop key gets a touch button,
+and never with a raw `keydown` listener.
+
 ### The source archive
 
 Every publish also uploads a **source archive** — `.bitmagic/publish/source.zip` — alongside the

package/dist/assets/add.d.ts

@@ -0,0 +1,40 @@
+import type { Environment } from '../config/environments.js';
+import type { ProjectContext } from '../project/context.js';
+import { type VoxelizeFlags, type VoxelizeGlb } from './voxelize-glb.js';
+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;
+export declare function addAssetFile(options: AddAssetOptions): Promise<AddAssetResult>;

package/dist/assets/add.js

@@ -0,0 +1,229 @@
+/**
+ * `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, describeErrno, errnoCode } from '../errors.js';
+import { applyModificationsToWorld } from '../forge/apply-modifications.js';
+import { projectWorldJsonPath } from '../forge/run-pipeline.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 { assertEngineHonouredId, voxelizeGlbIntoAsset, } from './voxelize-glb.js';
+import { isGlb, summarizeVxl } from './vxl-summary.js';
+import { formatSize } from './list.js';
+/**
+ * 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;
+}
+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.');
+    }
+    // `let`, and nulled after the upload: a 300 MB Blender export otherwise stays reachable from this
+    // frame for the whole bake — ten minutes of a headless Chrome doing the voxelization on the same
+    // machine — for bytes that were consumed minutes earlier.
+    let 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.
+    // Same idea as the .vxl parse below: prove the bytes are what the extension claims BEFORE the
+    // upload, so a mislabelled file costs nothing instead of an upload plus a browser launch.
+    if ((file.kind === 'glb-voxelize' || file.kind === 'glb-keep') && !isGlb(bytes)) {
+        throw new CliError(`${filename} is named .glb but does not start with the glTF magic — it is not a binary GLB. `
+            + 'A .gltf renamed, a truncated download and a Git-LFS pointer all look like this. '
+            + 'world.json is unchanged.');
+    }
+    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 });
+    bytes = null;
+    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 ?? voxelizeGlbIntoAsset;
+            const engineAsset = await voxelize({
+                context, environment, token, name, glbUrl: url, assetId, voxel: options.voxel, retryHint,
+                requestPrefix: 'upload', log,
+            });
+            assertEngineHonouredId(engineAsset, assetId, name, `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"}