@bitmagic/cli 0.1.21 → 0.1.24

package/README.md

@@ -20,7 +20,7 @@ bitmagic init my-game      # scaffold a new project into ./my-game
 cd my-game
 bitmagic cover              # generate cover art from GAME-DESIGN.md
 bitmagic check              # typecheck against the vendored engine
-bitmagic dev                 # build, then serve with live rebuilds
+bitmagic dev                 # build, then serve the game + editor, and leave it running
 bitmagic verify              # boot the game in a real browser and report what broke
 bitmagic publish              # verify-gate, build, and ship — private by default
 ```
@@ -34,13 +34,13 @@ bitmagic publish              # verify-gate, build, and ship — private by defa
 | `bitmagic whoami [--env <env>]` | Show the identity the CLI is authenticated as. |
 | `bitmagic init [dir] [--template <id>] [--name <name>] [--idea "<pitch>"] [--env <env>] [--force]` | Scaffold a new project: mints a game, downloads the vendored engine, writes `AGENTS.md`, `GAME-DESIGN.md` and templates. `--idea` seeds the design doc's pitch. |
 | `bitmagic check` | Typecheck (`tsc --noEmit`) against the vendored engine. Fast; does not prove the game runs. |
-| `bitmagic dev [--port <port>]` | Build, then serve with `tsc --watch` + `vite`, default port 3010. |
-| `bitmagic edit [--port <port>] [--editor-port <port>]` | Everything `dev` does, plus a visual scene editor at `http://localhost:3011/`: click an object, drag the gizmo, and the new transform is written to `src/work/world.json`. See **Editing the scene visually** below. |
+| `bitmagic dev [--port <port>] [--editor-port <port>]` | Build, then serve everything and keep it running: `tsc --watch`, `vite` on 3010, and a **Game / Editor** view on 3011 that reloads itself when the project changes. The one command to leave open. See **The dev view** below. |
+| `bitmagic reload [--port <port>]` | Tell a running `bitmagic dev` to reload the browser now. For agents: run it when you finish a round of edits. Exits 0 and does nothing when no dev server is running. |
 | `bitmagic verify [--timeout <ms>]` | Build, boot the game in a headless browser, click the engine's Play button like a player would, and report what broke. A game without the button passes as long as gameplay starts by itself (auto-starting genres, custom start UIs); a run where gameplay never starts fails. `--timeout` is settle time in ms measured after gameplay starts, so the screenshot captures gameplay. Writes the artifacts the publish gate reads (see below). |
 | `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`. |
-| `bitmagic generate <skybox\|sound\|image\|character\|animation\|prop> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. `prop` upgrades an existing placeholder asset in place — see below. |
+| `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 — see below. |
 | `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 forge --prompt "..." [--city\|--dungeon\|--platformer\|--freeform] [--name <name>] [--resume <jobId>]` | Design and bake a whole playable level into `world.json`. Slow and expensive; supports `--resume`. |
 
@@ -60,10 +60,14 @@ my-game/
   engine/             # vendored engine, read-only, replaced wholesale by `bitmagic upgrade`
   AGENTS.md            # guidance for the agent editing this project
   GAME-DESIGN.md        # what the game is — yours to write; bitmagic cover reads it
+  .claude/
+    settings.json          # yours; seeded with a Stop hook that runs `bitmagic reload`
+    skills/                 # generating-assets is shipped by the CLI; your own are untouched
   .bitmagic/
     cover.webp           # bitmagic cover's artwork — the publish thumbnail when present
     cover.json            # its URL and the design hash it was generated from
     AGENTS.md.latest       # the current AGENTS.md template, when upgrade kept your edited one
+    dev.json                # the running `bitmagic dev`'s ports, so `bitmagic reload` finds it
     build/
       index.html            # bitmagic build's output bundle
       manifest.json          # engineVersion, fingerprint, bytes, sha256, builtAt
@@ -89,33 +93,59 @@ Re-running on an unchanged design generates nothing and costs nothing — it rep
 cover. Edit the design and run again, or pass `--force`, to replace it. Because it writes
 `world.json`, it invalidates a passing verify: run it before `bitmagic verify`, not after.
 
-## Editing the scene visually
+## The dev view
 
-Some things are faster with a mouse. `bitmagic edit` runs everything `bitmagic dev` runs and adds a
-local editor on a second port:
+`bitmagic dev` is meant to be started once and left running, beside your agent:
 
 ```bash
-bitmagic edit
-#   Serving the game at http://localhost:3010/
-#   Editor ready at      http://localhost:3011/
+bitmagic dev
+#   Open   http://localhost:3011/   ← game + editor
+#
+#   Game only        http://localhost:3010/
+#   Editor actions   .bitmagic/edit/events.jsonl
 ```
 
-Open the editor URL in your normal browser. The game loads paused, with a free-flying camera, the
-scene hierarchy and the transform gizmo — the same editor the web Creator uses, which already ships
-inside `engine/`. Click an object to select it, then move, rotate, scale, snap it to the ground,
-edit its numbers in the inspector, delete it, or right-click to add one from the project's assets.
+Open the 3011 URL in your normal browser and put it beside your agent's window. It is one page with
+two tabs over the same running game, so switching costs nothing and does not restart anything:
 
-**Every change is saved to `src/work/world.json` as you make it.** There is no Save button and no
-unsaved state: your agent reads the same file, and `git diff` is the record of what you moved.
-Saves are surgical — one entry per object touched, nothing else in the file is rewritten.
+- **Game** — your game, playing. Click into it to capture the mouse, exactly as a player would.
+- **Editor** — the same world, paused, with a free-flying camera, the scene hierarchy and the
+  transform gizmo. This is the editor the web Creator uses, which already ships inside `engine/`.
+  Click an object to select it, then move, rotate, scale, snap it to the ground, edit its numbers in
+  the inspector, delete it, or right-click to add one from the project's assets.
 
-If your agent edits `world.json` while the editor is open, the editor says so and offers a reload
-rather than silently reloading over work in progress.
+3010 still serves the game on its own, for a second window or a bookmark. Both ports must stay
+inside 3000–3199: the asset CDN allowlists only those origins, and outside that window the world
+loads with no terrain.
+
+**Every change in the Editor tab is saved to `src/work/world.json` as you make it.** There is no
+Save button and no unsaved state: your agent reads the same file, and `git diff` is the record of
+what you moved. Saves are surgical — one entry per object touched, nothing else in the file is
+rewritten.
+
+### Auto-reload
+
+The browser reloads itself when the project changes, so you watch your agent's work appear instead
+of reaching for F5. Three things drive it:
+
+- **The file watcher.** `src/` and `dist/` are watched, and a reload fires once the writes go quiet.
+- **The build gate.** A reload waits for `tsc --watch` to finish and land clean. If the build fails
+  the reload is dropped and the page says so — reloading would show you the previous build's code
+  running against your new source, which is the most confusing outcome available.
+- **`bitmagic reload`.** The watcher has to guess when an agent is finished, because an agent pauses
+  to think. This command replaces the guess. `bitmagic init` wires it to Claude Code's `Stop` hook in
+  `.claude/settings.json`, so Claude fires it at the end of every turn; any other agent can run it
+  directly. `bitmagic upgrade` adds the hook to an existing project without touching anything else in
+  that file.
+
+Turn it off with the **Auto-reload** checkbox in the top bar — the setting sticks, and you get the
+old "changed on disk, click to reload" banner instead. It also falls back to the banner on its own
+while you are mid-edit in the Editor tab, rather than reloading a drag away.
 
 ### What your agent sees
 
 Every editor action is appended to `.bitmagic/edit/events.jsonl`, one JSON object per line, and
-printed to the command's own output — so the agent that launched `bitmagic edit` can tell what you
+printed to the command's own output — so the agent that launched `bitmagic dev` can tell what you
 did without inferring it from a diff:
 
 ```
@@ -151,6 +181,35 @@ 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.
 
+## Drivable vehicles
+
+`bitmagic generate vehicle` designs a vehicle and registers it as a **new** asset — unlike
+`generate prop`, which upgrades an existing placeholder in place. An AI designer authors the shape,
+paint and wrap art (including generated side art like "a poodle mural on a grooming van"); a
+parametric builder produces the model; the engine voxelizes it and derives its physics fitment.
+
+```bash
+bitmagic generate vehicle --prompt "a rusty orange pickup with flame decals"
+bitmagic generate vehicle --preset VAN            # a standard vehicle: skips the designer, free
+```
+
+Then spawn it from game code by name:
+
+```js
+engine.getVehicleSpawner().spawnAndEnterFromAsset({ x: 0, z: 0 }, '<assetName>', playerController);
+```
+
+Like `prop` it needs Chrome and a free port between 3000 and 3199 — only the engine can voxelize,
+so the CLI drives its own headless browser. Headlights, taillights and emergency beacons are built
+and lit automatically; there is no need to ask for them.
+
+Costs sparks based on what the designer actually spends, so a retrying design costs more than a
+clean one and `--preset` costs nothing. If it fails after the model exists, the error prints the
+exact `--glb-url … --voxel-size …` command to retry the browser step without paying again.
+
+If the finished asset reports that it will not drive, the project's vendored engine predates
+vehicle-fitment derivation: run `bitmagic upgrade`, then regenerate.
+
 ## Publishing
 
 `bitmagic publish` is two gated steps in one command:
@@ -209,6 +268,10 @@ its own reviewable diff.
 What is yours and never touched: `src/`, `world.json`, `game.json`, `package.json`, `CLAUDE.md`,
 `GAME-DESIGN.md`, `.gitignore`, and any skill you wrote yourself.
 
+`.claude/settings.json` is merged rather than rewritten — it is where your permissions and your own
+hooks live. An upgrade adds the `bitmagic reload` Stop hook if it is missing and changes nothing
+else; if it cannot parse the file it leaves it entirely alone and says so.
+
 `AGENTS.md` is the one conditional case, and it can never lose your work. The CLI records a hash of
 the `AGENTS.md` it writes. On a later upgrade:
 

package/dist/cli.d.ts

@@ -92,17 +92,21 @@ declare const rawCommands: {
     dev: CommandDef<{
         readonly port: {
             readonly type: "string";
-            readonly description: "Port to serve on (default 3010).";
+            readonly description: "Port to serve the game on (default 3010).";
+        };
+        readonly 'editor-port': {
+            readonly type: "string";
+            readonly description: "Port to serve the Game/Editor view on (default 3011).";
         };
     }>;
-    edit: CommandDef<{
+    reload: CommandDef<{
         readonly port: {
             readonly type: "string";
-            readonly description: "Port to serve the game on (default 3010).";
+            readonly description: "Port the dev view is on. Defaults to the running server, then 3011.";
         };
-        readonly 'editor-port': {
-            readonly type: "string";
-            readonly description: "Port to serve the editor on (default 3011).";
+        readonly json: {
+            readonly type: "boolean";
+            readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
         };
     }>;
     verify: CommandDef<{

package/dist/cli.js

@@ -8,7 +8,7 @@ import { initCommand } from './commands/init.js';
 import { upgradeCommand } from './commands/upgrade.js';
 import { checkCommand } from './commands/check.js';
 import { devCommand } from './commands/dev.js';
-import { editCommand } from './commands/edit.js';
+import { reloadCommand } from './commands/reload.js';
 import { verifyCommand } from './commands/verify.js';
 import { buildCommand } from './commands/build.js';
 import { generateCommand } from './commands/generate.js';
@@ -103,7 +103,7 @@ const rawCommands = {
     upgrade: upgradeCommand,
     check: checkCommand,
     dev: devCommand,
-    edit: editCommand,
+    reload: reloadCommand,
     verify: verifyCommand,
     build: buildCommand,
     generate: generateCommand,

package/dist/cli.js.map

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

package/dist/commands/dev.d.ts

@@ -1,6 +1,10 @@
 export declare const devCommand: import("citty").CommandDef<{
     readonly port: {
         readonly type: "string";
-        readonly description: "Port to serve on (default 3010).";
+        readonly description: "Port to serve the game on (default 3010).";
+    };
+    readonly 'editor-port': {
+        readonly type: "string";
+        readonly description: "Port to serve the Game/Editor view on (default 3011).";
     };
 }>;

package/dist/commands/dev.js

@@ -1,7 +1,29 @@
+/**
+ * `bitmagic dev` — the whole local loop, in one command that stays running.
+ *
+ * It builds, watches, serves the game, serves a shell page with a **Game** tab and an **Editor**
+ * tab, and reloads the browser when the project changes. There is deliberately no second command:
+ * the workflow this exists for is an agent window beside a browser window, and a creator should
+ * never have to stop one server and start another to go from playing their game to nudging an
+ * object in it. (`bitmagic edit` was that second command, and folding it in is why it is gone.)
+ *
+ * Four processes make that up, all owned here:
+ *   tsc --watch   piped, not inherited — its `Found N errors` line is the only signal that tells
+ *                 auto-reload whether the emit in dist/ is worth showing (see editor/watch.ts)
+ *   vite          serves the project at --port
+ *   the sidecar   serves the shell and the scene-save API at --editor-port (see editor/server.ts)
+ *   the watcher   src/ and dist/, debounced, feeding the same coordinator as tsc
+ */
 import { defineCommand } from 'citty';
 import { spawn, spawnSync } from 'child_process';
+import * as path from 'path';
 import { CliError } from '../errors.js';
 import { loadProjectContext, projectBin } from '../project/context.js';
+import { removeDevHandle, writeDevHandle } from '../project/dev-handle.js';
+import { startEditorServer } from '../editor/server.js';
+import { ReloadBus } from '../editor/reload-bus.js';
+import { ReloadCoordinator, pipeTscWatch, watchProject } from '../editor/watch.js';
+import { parseLocalPort } from '../local-port.js';
 import { waitForServer } from '../verify/wait-for-server.js';
 import { engineUpdateNotice } from '../project/engine-update.js';
 /**
@@ -34,17 +56,29 @@ async function notifyIfEngineOutdated(projectEngineVersion, log) {
         // See above: no login, no network, or no manifest all mean "no hint", never "dev failed".
     }
 }
-const DEFAULT_PORT = 3010;
+const DEFAULT_GAME_PORT = 3010;
+const DEFAULT_EDITOR_PORT = 3011;
 export const devCommand = defineCommand({
-    meta: { name: 'dev', description: 'Build the game, then serve it with live rebuilds.' },
+    meta: {
+        name: 'dev',
+        description: 'Build the game, then serve it with live rebuilds, a scene editor and auto-reload.',
+    },
     args: {
-        port: { type: 'string', description: `Port to serve on (default ${DEFAULT_PORT}).` },
+        port: { type: 'string', description: `Port to serve the game on (default ${DEFAULT_GAME_PORT}).` },
+        'editor-port': {
+            type: 'string',
+            description: `Port to serve the Game/Editor view on (default ${DEFAULT_EDITOR_PORT}).`,
+        },
     },
     async run({ args }) {
         const context = loadProjectContext();
         const tsc = projectBin(context.root, 'tsc');
         const vite = projectBin(context.root, 'vite');
-        const port = args.port ?? String(DEFAULT_PORT);
+        const gamePort = parseLocalPort(args.port, DEFAULT_GAME_PORT, '--port');
+        const editorPort = parseLocalPort(args['editor-port'], DEFAULT_EDITOR_PORT, '--editor-port');
+        if (gamePort === editorPort) {
+            throw new CliError('`--port` and `--editor-port` must differ — the game and the shell are two servers.');
+        }
         // Build to completion first. Every alias resolves into dist/, so serving before the first
         // emit 404s every module — a failure that reads as "the engine is broken", not "not built".
         console.log('Building…');
@@ -57,16 +91,33 @@ export const devCommand = defineCommand({
         }
         // Fire and forget: the nudge must never gate or delay the server coming up.
         void notifyIfEngineOutdated(context.metadata.engineVersion, (m) => console.log(m));
+        // Bus first, then the coordinator that feeds it, then the servers that feed the coordinator.
+        const bus = new ReloadBus();
+        const coordinator = new ReloadCoordinator({
+            onReload: (reason) => bus.reload(reason),
+            onBuild: (status, message) => bus.build(status, message),
+        });
+        // Before the children, so a port clash fails fast rather than after vite has claimed its port.
+        const editor = await startEditorServer({
+            root: context.root,
+            metadata: context.metadata,
+            gameId: context.metadata.gameId,
+            gamePort,
+            port: editorPort,
+            bus,
+            coordinator,
+            log: (message) => console.log(message),
+        });
         const children = [
-            {
-                name: 'tsc --watch',
-                process: spawn(tsc, ['--watch', '--preserveWatchOutput'], { cwd: context.root, stdio: 'inherit' }),
-            },
+            // Piped rather than inherited — see the file header and editor/watch.ts.
+            { name: 'tsc --watch', process: pipeTscWatch(tsc, context.root, coordinator) },
             {
                 name: 'vite',
-                process: spawn(vite, ['--port', port, '--strictPort'], { cwd: context.root, stdio: 'inherit' }),
+                process: spawn(vite, ['--port', String(gamePort), '--strictPort'], { cwd: context.root, stdio: 'inherit' }),
             },
         ];
+        const watcher = watchProject(context.root, coordinator, (m) => console.log(m));
+        writeDevHandle(context.root, { editorPort, gamePort, pid: process.pid });
         let shuttingDown = false;
         let requestedByUser = false;
         const shutdown = () => {
@@ -75,6 +126,11 @@ export const devCommand = defineCommand({
             shuttingDown = true;
             for (const child of children)
                 child.process.kill('SIGTERM');
+            coordinator.stop();
+            watcher.close();
+            bus.close();
+            removeDevHandle(context.root);
+            void editor.close();
         };
         process.on('SIGINT', () => {
             requestedByUser = true;
@@ -84,10 +140,20 @@ export const devCommand = defineCommand({
             requestedByUser = true;
             shutdown();
         });
-        // Print the URL ourselves once vite actually answers, rather than relying on vite's own
-        // startup banner — that output is vite's to change, this is ours to keep stable.
-        void waitForServer(Number(port), 30_000)
-            .then(() => console.log(`\nServing at http://localhost:${port}/`))
+        // Print the URLs ourselves once vite actually answers, rather than relying on vite's own
+        // startup banner — that output is vite's to change, this is ours to keep stable. The shell URL
+        // leads because it is the one thing to open: the raw game below it is the same game without
+        // the tabs, kept addressable for a second window or a bookmark.
+        void waitForServer(gamePort, 30_000)
+            .then(() => {
+            console.log(`\n  Open   ${editor.url}   ← game + editor`);
+            console.log(`\n  Game only        http://localhost:${gamePort}/`);
+            // Named on startup so the agent that launched this command knows where to look without
+            // being told — the journal is the only record of intentions the editor cannot carry out
+            // itself, and of who changed what.
+            console.log(`  Editor actions   ${path.relative(context.root, editor.journalPath)}`);
+            console.log('\nThe browser reloads itself when the project changes. `bitmagic reload` forces it.\n');
+        })
             .catch(() => {
             // The child-exit watcher below reports a vite that never comes up; this poll simply has
             // nothing to announce in that case.
@@ -114,6 +180,9 @@ export const devCommand = defineCommand({
                 });
             }
         });
+        // Both children are gone by here — via a signal handler or via the failure path above, each of
+        // which has already run shutdown(). This awaits the close that shutdown() could only start.
+        await editor.close();
         if (failure) {
             throw new CliError(`${failure.name} ${failure.detail}. \`bitmagic dev\` stopped.`);
         }

package/dist/commands/dev.js.map

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

package/dist/commands/generate.d.ts

@@ -1,5 +1,6 @@
 import { type GenerationOutcome } from '../generate/stream.js';
 import { type PropVoxelizeResult } from '../generate/prop.js';
+import { type VehicleInstallResult } from '../generate/vehicle.js';
 export interface SkyboxArgs {
     description: string;
     referenceImageUrl?: string;
@@ -84,4 +85,23 @@ export declare function runPropGeneration(options: {
     json: boolean;
     deps?: GenerateRunDeps;
 }): Promise<PropVoxelizeResult>;
+/**
+ * `generate vehicle`, like `generate prop`, cannot go through {@link runAssetGeneration}: the
+ * generator returns a GLB rather than patches, so there is nothing to apply until the CLI has
+ * voxelized it in a browser.
+ *
+ * Unlike prop there is nothing to validate up front — a vehicle creates a NEW asset, so there is no
+ * existing one to look up. The one thing that would waste a paid design is asking for neither a
+ * prompt nor a preset, which is refused here before anything is spent.
+ */
+export declare function runVehicleGeneration(options: {
+    prompt?: string;
+    presetName?: string;
+    name?: string;
+    /** Skip the paid design and voxelize this GLB instead — how a failed run is retried. */
+    glbUrl?: string;
+    minVoxelSize?: number;
+    json: boolean;
+    deps?: GenerateRunDeps;
+}): Promise<VehicleInstallResult>;
 export declare const generateCommand: import("citty").CommandDef<import("citty").ArgsDef>;

package/dist/commands/generate.js

@@ -10,6 +10,7 @@ import { getAccessToken } from '../auth/session.js';
 import { requestGeneration } from '../generate/stream.js';
 import { applyPatchesToWorld } from '../generate/apply-patches.js';
 import { generateAndInstallProp } from '../generate/prop.js';
+import { generateAndInstallVehicle } from '../generate/vehicle.js';
 function parseNumberFlag(flagName, raw, options = {}) {
     if (raw === undefined)
         return undefined;
@@ -181,7 +182,7 @@ export async function runAssetGeneration(type, label, body, json = false, deps)
     }
     runDeps.log(`world.json updated (${applyResult.applied} patch${applyResult.applied === 1 ? '' : 'es'}).`);
     output.result({ ok: true, kind: label, message: outcome.message, patchesApplied: applyResult.applied });
-    runDeps.log('If `bitmagic dev` is running, reload the browser tab to see the change.');
+    runDeps.log('A running `bitmagic dev` reloads the browser by itself to show the change.');
     return outcome;
 }
 /**
@@ -217,7 +218,60 @@ export async function runPropGeneration(options) {
     // `result` already carries glbUrl, so a retry after a later failure can find the paid-for mesh
     // in the JSON document rather than only in the error text.
     output.result({ ok: true, kind: 'prop', ...result });
-    runDeps.log('If `bitmagic edit` or `bitmagic dev` is running, reload the browser tab to see it.');
+    runDeps.log('A running `bitmagic dev` reloads the browser by itself to show it.');
+    return result;
+}
+/**
+ * `generate vehicle`, like `generate prop`, cannot go through {@link runAssetGeneration}: the
+ * generator returns a GLB rather than patches, so there is nothing to apply until the CLI has
+ * voxelized it in a browser.
+ *
+ * Unlike prop there is nothing to validate up front — a vehicle creates a NEW asset, so there is no
+ * existing one to look up. The one thing that would waste a paid design is asking for neither a
+ * prompt nor a preset, which is refused here before anything is spent.
+ */
+export async function runVehicleGeneration(options) {
+    if (options.prompt === undefined && options.presetName === undefined && options.glbUrl === undefined) {
+        throw new CliError('Provide --prompt to design a vehicle, or --preset to build a standard one. '
+            + 'Run `bitmagic generate vehicle --preset ?` to see the preset names.');
+    }
+    const output = createOutput(options.json);
+    const runDeps = options.deps ?? defaultDeps(options.json);
+    const context = loadProjectContext(runDeps.startDir);
+    const environment = resolveEnvironment({ storedDefault: readDefaultEnvironment(runDeps.baseDir) });
+    const token = await getAccessToken(environment, resolveAuth0ClientId(environment), { fetch: runDeps.fetch, sleep: runDeps.sleep, now: runDeps.now }, runDeps.baseDir);
+    let result;
+    try {
+        result = await generateAndInstallVehicle({
+            context,
+            environment,
+            token,
+            ...(options.prompt !== undefined ? { prompt: options.prompt } : {}),
+            ...(options.presetName !== undefined ? { presetName: options.presetName } : {}),
+            ...(options.name !== undefined ? { name: options.name } : {}),
+            ...(options.glbUrl !== undefined ? { glbUrl: options.glbUrl } : {}),
+            ...(options.minVoxelSize !== undefined ? { minVoxelSize: options.minVoxelSize } : {}),
+            fetchImpl: runDeps.fetch,
+            log: runDeps.log,
+        });
+    }
+    catch (error) {
+        throw decoratedError(error, (message) => message);
+    }
+    for (const note of result.notes)
+        runDeps.log(`note: ${note}`);
+    if (result.drivable) {
+        runDeps.log(`Added "${result.assetName}". Spawn it from game code with:\n`
+            + `  engine.getVehicleSpawner().spawnAndEnterFromAsset({ x: 0, z: 0 }, `
+            + `'${result.assetName}', playerController);`);
+    }
+    else {
+        runDeps.log(`Added "${result.assetName}", but it will not drive — see the note above.`);
+    }
+    // `result` already carries glbUrl, so a retry after a later failure can find the paid-for vehicle
+    // in the JSON document rather than only in the error text.
+    output.result({ ok: true, kind: 'vehicle', ...result });
+    runDeps.log('A running `bitmagic dev` reloads the browser by itself to show it.');
     return result;
 }
 // ============================================================================
@@ -455,6 +509,49 @@ const propCommand = defineCommand({
         });
     },
 });
+const vehicleCommand = defineCommand({
+    meta: {
+        name: 'vehicle',
+        description: 'Design a drivable vehicle and register it as a new asset.',
+    },
+    args: {
+        prompt: {
+            type: 'string',
+            description: 'What to design ("a rusty orange pickup with flame decals"). Required unless --preset is given.',
+        },
+        preset: {
+            type: 'string',
+            description: 'Build a standard vehicle instead of designing one — faster and free. Run without it to see the valid names.',
+        },
+        name: {
+            type: 'string',
+            description: 'Asset name override; defaults to the designed name. This is the name game code spawns by.',
+        },
+        'glb-url': {
+            type: 'string',
+            description: 'Voxelize this existing vehicle instead of designing one — how to retry for free. Needs --voxel-size and --name.',
+        },
+        'voxel-size': {
+            type: 'string',
+            description: 'Bake resolution, only with --glb-url. The failed run prints the exact value to use.',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Print the result as JSON on stdout; all progress goes to stderr.',
+        },
+    },
+    async run({ args }) {
+        const minVoxelSize = parseNumberFlag('voxel-size', args['voxel-size'], { min: 0.01, max: 1 });
+        await runVehicleGeneration({
+            ...(args.prompt ? { prompt: args.prompt } : {}),
+            ...(args.preset ? { presetName: args.preset } : {}),
+            ...(args.name ? { name: args.name } : {}),
+            ...(args['glb-url'] ? { glbUrl: args['glb-url'] } : {}),
+            ...(minVoxelSize !== undefined ? { minVoxelSize } : {}),
+            json: args.json === true,
+        });
+    },
+});
 export const generateCommand = defineCommand({
     meta: {
         name: 'generate',
@@ -467,6 +564,7 @@ export const generateCommand = defineCommand({
         character: characterCommand,
         animation: animationCommand,
         prop: propCommand,
+        vehicle: vehicleCommand,
     },
 });
 //# sourceMappingURL=generate.js.map