@bitmagic/cli 0.1.59-dev.1 → 0.1.59-dev.11

package/README.md

@@ -204,6 +204,7 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `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** (both produce voxels directly; `--mesh` takes the older mesh path), `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 materials <assetId> [--set <file.json>] [--auto] [--clear]` | Show what an asset's voxels look like, or say what they are **made of** — so a sword's steel blade shines and its leather grip does not. With no flag it prints the asset's colour groups; `--set` applies your verdicts; `--auto` lets a model decide (what `generate prop` and `generate model` already do on their own); `--clear` removes them. Free — no sparks, nothing generated. See **Voxel materials** below. |
 | `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 reference <make\|accept\|show\|clear> ...` | Make a concept image of the game's world, iterate until it is right, and `accept` one — the accepted image becomes the default style reference for `generate skybox\|background\|block-type\|image`, `cover` and `forge`. Only `make` costs sparks (priced like an image). See **Reference image** below. |
@@ -251,6 +252,35 @@ Two things the spec will refuse, both before anything is sent:
 `playCustomAnimation("mLimpStride01")` resolves. It is not the minted `asset_…` id — pass that
 as `--asset-id` if you have one.
 
+### From a video (`--video`)
+
+The one exception to "no text-to-motion service": a clip can be made from a **video of a person
+performing the move**, through Uthana's video-to-motion. The creator supplies the motion by doing
+it, not by describing it, so it sits beside the authored forger rather than replacing it.
+
+```bash
+bitmagic generate animation --video ~/wave.mov --name "Wave"
+bitmagic generate animation --video ~/jog.webm --name "Jog" --slot run --loop
+```
+
+- `.mp4`, `.mov`, `.avi` or `.webm`; **2–60 seconds**; under 200 MB. One person, whole body in
+  frame, plain background, good light. Anything else is re-encoded server-side, so a browser's
+  WebM recording is as good as a phone's mp4.
+- `--slot idle|walk|run` pins the clip to that locomotion state for the player **and every NPC**
+  (persisted as `locomotionState` on the asset — no template code to edit). Omit it for a one-shot
+  clip and play it with `playCustomAnimation("<motionId>")`.
+- It costs sparks (15, charged when Uthana accepts the video) and takes minutes: the command
+  uploads the file, submits a job, and polls until the clip lands in `src/work/world.json`.
+- `--auto-trim` cuts the "walking to the camera" frames off both ends before Uthana sees the
+  clip: pose analysis finds where the person stepped back into frame after pressing record and
+  where they came forward to press stop. Use it for clips recorded that way; when the analysis
+  is not confident, nothing is trimmed. The result reports what was removed.
+- `--spec`/`--family` cannot be combined with `--video`.
+
+`bitmagic dev` has the same flow behind its **Record motion** button — record with the webcam
+(auto-trim is applied to those recordings; picked files are sent as they are) or pick a file,
+name it, choose a slot — and runs it through this command in the sidecar.
+
 ## Environments
 
 `--env` accepts `dev`, `prod`, or `local`. Each command resolves its target in this order, most
@@ -586,7 +616,10 @@ reloads. The same cache feeds the editor's right-click **Add object** palette, w
 
 **Click a row to look at the asset properly.** A mesh or a voxel asset opens in a viewer you can
 drag to turn and scroll to zoom, at full detail rather than the coarse version a 46px tile is drawn
-from; an image opens as the image; a sound gets a player. Beside it is everything the row has no
+from; an image opens as the image; a sound gets a player; an animation plays on the engine's block
+character — the same clip preview the Creator has — with play/pause and a speed slider. A clip
+generated from a recording also shows its source video, with the auto-trimmed ends marked on a
+seek bar. Beside it is everything the row has no
 room for — extent in world units, voxel count, triangle count, and the asset id, with a button to
 copy it so you can paste it into a `bitmagic generate prop --asset …`. Escape closes it. The game
 pauses while it is open and resumes when you close it.
@@ -696,7 +729,7 @@ What each file becomes:
 | `.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. |
+| `.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. | (An `.mp4` you want turned into an **animation** goes to `bitmagic generate animation --video` instead.)
 
 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**
@@ -774,6 +807,119 @@ whose vendored engine predates voxel masters takes the mesh path regardless, and
 If the bake fails after the source exists, the error prints the exact command to retry the browser
 step **without paying again** — `--master-url …` for voxels, `--glb-url …` for a mesh.
 
+## Voxel materials
+
+A generated voxel asset carries colours and nothing else, so every voxel shades identically: a
+sword's steel blade responds to light exactly like its leather grip, and both read as flat paint.
+Material classes fix that by saying what each colour is **made of**.
+
+**You usually do not have to do anything.** `bitmagic generate prop` and `bitmagic generate model`
+classify the asset right after the bake: a light model reads the same colour table shown below
+together with the asset's prompt, and its verdicts are written into the `.vxl` before the command
+returns (`Materials: metal, leather` in the output; `materials.classifier: "ai"` on the asset's
+`world.json` entry). Pass `--no-materials` to skip it. A classification that cannot run — no model
+credential, an engine too old to write classes — is a note, never a failed generation; the asset is
+baked and matte, and `bitmagic assets materials <id> --auto` retries it later.
+
+`bitmagic forge` does the same twice over: the level's own terrain gets classes the designer
+authored per colour ("rock on steep slopes" bakes onto the stone tier), and every archetype
+library asset the forge creates is classified right after the bake, in the same session. A matte
+archetype is always retriable with `bitmagic assets materials <id> --auto`.
+
+When the automatic answer is wrong, or for an asset added from a file (which records no prompt, so
+nothing is classified automatically), `bitmagic assets materials` is two steps, and the CLI does not
+guess at the middle one — **you do**, because you are the one who knows what the asset is meant to
+be.
+
+```bash
+bitmagic assets materials sword-01              # what does this asset look like?
+bitmagic assets materials sword-01 --set m.json # here is what those colours are
+bitmagic assets materials sword-01 --auto       # or let the model decide again
+```
+
+The first command prints the asset's colour groups:
+
+```
+"Longsword"  signature 4f2a91cd (version 1)
+
+20 voxels, 5 palette entries, bbox 1x20x1 voxels
+
+id   colour   share  height(min-max)  extent(x,y,z)  radial  shape       parts
+g0   #dddddd   70.0%        0.33-0.98 0.00,0.65,0.00    0.00  thin-long   1
+g1   #998866   20.0%        0.03-0.18 0.00,0.15,0.00    0.00  blob        1
+g2   #eecc66   10.0%        0.23-0.28 0.00,0.05,0.00    0.00  blob        1
+```
+
+Read with the asset's own prompt — printed underneath — that is enough to name the materials: g0 is
+the steel blade (most of the model, upper two thirds, long and thin), g1 the leather grip at the
+bottom, g2 a brass pommel between them. `share` is the fraction of the asset, `height` where it
+sits from floor to top, `extent` its size along each axis relative to the whole, `radial` how far
+from the centre axis, and `parts` how many separate pieces the colour forms — a colour scattered
+across the whole model in many parts is dithering, not a material.
+
+Then write the verdicts:
+
+```json
+{
+  "signatureVersion": 1,
+  "signatureHash": "4f2a91cd",
+  "verdicts": [
+    { "id": "g0", "class": "metal",   "confidence": 0.95 },
+    { "id": "g1", "class": "leather", "confidence": 0.9 },
+    { "id": "g2", "class": "gold",    "confidence": 0.6 }
+  ]
+}
+```
+
+The `signatureHash` binds the answer to the asset it describes: re-bake or re-voxelize the asset
+and the hash changes, so a stale set of verdicts is refused rather than applied to geometry it
+never saw.
+
+**Classes:** `matte` (the default — no special shading), `metal`, `gold`, `chrome`, `gem`, `glass`,
+`wood`, `stone`, `cloth`, `fur`, `leather`, `plastic`, `paint`. The first five reflect the sky; the
+rest get a highlight from the scene's own lights, which keeps their colours exactly as they are.
+`fur` is the odd one out — it reflects nothing, but picks up a soft halo towards its silhouette the
+way a pelt or plush does. Use it for exactly that: a teddy bear, an animal, a fur trim. Anything
+merely soft is `cloth`.
+
+The engine also has three classes that EMIT light — `filament`, `neon`, `lava` — which is why you
+may see one in a `.vxl` that this command never wrote. They are not on the list above and must not
+be used here, deliberately: whether a surface is a light is not answerable from its colour, and a
+wrongly glowing surface is worse than a wrongly shiny one because it also lights everything around
+it. They are picked in the voxel editor, where a person selected the voxels and knows. A verdict
+naming one is refused over a quarter of an asset like any precious material, and arrives with no
+glow even when it is accepted.
+
+**Rules worth following:**
+
+- `matte` is the right answer for most groups, and costs nothing. Leave a group out entirely rather
+  than inventing a material for it.
+- The asset's prompt is the strongest evidence there is — it names the materials, and your job is
+  only to decide which colour group is which.
+- A material the prompt does **not** name needs strong evidence from the geometry. A precious
+  material (`gold`, `gem`, `glass`) claimed over more than a quarter of the asset is refused
+  outright unless the prompt says so: a wooden crate is never 40% gem, and a wrongly shiny surface
+  is what a player notices.
+- Use a low confidence rather than guessing. Below 0.45 a verdict is dropped, which is a better
+  outcome than a surface that shines when it should not.
+- An asset that records no prompt or description has nothing saying what it is. Prefer leaving it
+  alone.
+
+**Budget.** Four materials per asset. Each one is an extra draw call on every placed instance, so
+over budget the smallest is folded into a related class (`gold` into `metal`, `gem` into `glass`)
+rather than dropped — every fold is reported. Very small groups are dropped too, except for the
+precious classes, where a fraction of a per cent is exactly the point.
+
+Materials are written into the `.vxl` under the **same asset id**, so every placed instance changes
+with it. `--clear` puts an asset back to the plain look — it strips the classes and keeps every
+slot's glow, because taking a light away is the one thing this command must never do. A re-bake
+(`bitmagic assets revoxelize`) produces a fresh `.vxl` whose palette the old verdicts no longer
+describe, so it classifies again on its own — `--no-materials` there leaves the re-baked asset
+plain. Nothing here generates anything or costs
+sparks; what it costs is the headless browser bake, since only the engine can read and write a
+`.vxl`. An asset whose base voxels glow (from the older per-colour glow that materials replaced) is
+refused rather than having that glow silently traded for a shine.
+
 ## Drivable vehicles
 
 `bitmagic generate vehicle` designs a vehicle and registers it as a **new** asset — unlike

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

@@ -9,6 +9,14 @@ export interface AssetFileClass {
     /** Lower-case extension without the dot. */
     extension: string;
 }
+/** Extensions `classifyVideoFile` accepts, for help text and the README. */
+export declare const VIDEO_EXTENSIONS: string[];
+export interface VideoFileClass {
+    contentType: string;
+    /** Lower-case extension without the dot. */
+    extension: string;
+}
+export declare function classifyVideoFile(filename: string): VideoFileClass;
 /** Every extension `classifyAssetFile` accepts, for help text and the README. */
 export declare const ACCEPTED_EXTENSIONS: string[];
 /**

package/dist/assets/file-kind.js

@@ -39,6 +39,30 @@ const AUDIO_TYPES = {
     m4a: 'audio/mp4',
     mp3: 'audio/mpeg',
 };
+/**
+ * What `bitmagic generate animation --video <file>` takes. Deliberately NOT part of
+ * `classifyAssetFile`: an `.mp4` handed to `assets add` is still refused (it would be a video
+ * asset needing the Creator's faststart pass), while the same file here is the INPUT to a
+ * video-to-motion job — asset-forger re-encodes whatever it gets, so `.webm` from a browser's
+ * MediaRecorder is as good as an `.mp4` from a phone.
+ */
+const VIDEO_TYPES = {
+    mp4: 'video/mp4',
+    mov: 'video/quicktime',
+    avi: 'video/x-msvideo',
+    webm: 'video/webm',
+};
+/** Extensions `classifyVideoFile` accepts, for help text and the README. */
+export const VIDEO_EXTENSIONS = Object.keys(VIDEO_TYPES);
+export function classifyVideoFile(filename) {
+    const extension = fileExtension(filename);
+    const contentType = VIDEO_TYPES[extension];
+    if (contentType === undefined) {
+        throw new CliError(`--video takes ${VIDEO_EXTENSIONS.map((e) => `.${e}`).join(', ')}; `
+            + `${JSON.stringify(path.basename(filename))} is none of those.`);
+    }
+    return { contentType, extension };
+}
 /** Every extension `classifyAssetFile` accepts, for help text and the README. */
 export const ACCEPTED_EXTENSIONS = ['glb', 'vxl', 'png', 'jpg', 'jpeg', 'webp', 'opus', 'ogg', 'm4a', 'mp3', 'json'];
 /**

package/dist/assets/file-kind.js.map

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

package/dist/assets/materials.d.ts

@@ -0,0 +1,165 @@
+import type { Environment } from '../config/environments.js';
+import { withVoxelizeSession } from '../forge/voxelize-session.js';
+import type { ProjectContext } from '../project/context.js';
+/**
+ * Whether this project's vendored engine can answer these messages at all.
+ *
+ * A capability PROBE, not a version compare, exactly as `engineSupportsVxlMaster`
+ * does and for the reason its own doc gives: an engine with no handler never
+ * replies, so the request would stall for the full ten-minute bake timeout and
+ * then report a timeout, with nothing pointing at the real cause.
+ */
+export declare function engineSupportsMaterialClasses(projectRoot: string): boolean;
+/** One colour group of an asset, as the engine described it. */
+export interface MaterialGroup {
+    id: string;
+    hex: string;
+    share: number;
+    shape: string;
+}
+/** What the engine reports about an asset's materials. */
+export interface MaterialSignatureReply {
+    version: number;
+    hash: string;
+    voxelCount: number;
+    paletteSize: number;
+    groups: MaterialGroup[];
+    existingSlots: string[];
+}
+/** A single group's verdict, as written into a `--set` file. */
+export interface MaterialVerdictInput {
+    id: string;
+    class: string;
+    confidence: number;
+}
+export interface MaterialsBaseOptions {
+    context: ProjectContext;
+    environment: Environment;
+    token: string;
+    assetId: string;
+    log: (message: string) => void;
+    fetchImpl?: typeof globalThis.fetch;
+    /** Injected in tests so the lane runs without Chrome. */
+    session?: typeof withVoxelizeSession;
+}
+export interface ReadMaterialsResult {
+    assetId: string;
+    assetName: string;
+    signature: MaterialSignatureReply;
+    /** The engine's own rendering of the signature — printed verbatim. */
+    table: string;
+    /** The asset's generation prompt or description, when it records one. */
+    promptText?: string;
+}
+/**
+ * The asset to work on, refused before the browser starts if it cannot be.
+ *
+ * Only a `vxl` asset has voxels to classify. A GLB kept as a mesh, an image, a
+ * sound: none of them have a palette, and saying so up front costs nothing while
+ * a browser launch costs seconds.
+ */
+export declare function findVoxelAsset(world: Record<string, unknown>, assetId: string): {
+    asset: Record<string, unknown>;
+    url: string;
+    name: string;
+};
+/**
+ * The text this asset was generated from, if it records any.
+ *
+ * The single most valuable signal a classifier has — it names the materials
+ * outright — and also what the plausibility guard checks a precious-material
+ * claim against. Absent for an asset added from a file, which is exactly the case
+ * where classifying on colour alone would be guessing.
+ */
+export declare function assetPromptText(asset: Record<string, unknown>): string | undefined;
+/**
+ * Ask the engine what the asset is made of.
+ *
+ * Reads only — no upload, no world.json write, nothing spent. Safe to run as often
+ * as you like, which matters because it is the step an agent runs first.
+ */
+export declare function readAssetMaterials(options: MaterialsBaseOptions): Promise<ReadMaterialsResult>;
+export interface SetMaterialsOptions extends MaterialsBaseOptions {
+    /** The verdicts to apply, and the signature hash they were computed against. */
+    signatureVersion: number;
+    signatureHash: string;
+    verdicts: MaterialVerdictInput[];
+}
+export interface ClearMaterialsOptions extends MaterialsBaseOptions {
+    clear: true;
+}
+export interface SetMaterialsResult {
+    assetId: string;
+    assetName: string;
+    /** The material classes now on the asset. Empty after a --clear. */
+    slots: string[];
+    /** Classes that lost a share floor, the slot budget, or the plausibility guard. */
+    dropped: Array<{
+        class: string;
+        reason: string;
+        share: number;
+    }>;
+    /** Fraction of the asset left with the default look. */
+    baseShare: number;
+    /** True when nothing changed, so no upload and no world.json write happened. */
+    unchanged: boolean;
+    assetUrl?: string;
+    instanceCount: number;
+}
+/**
+ * Apply an assignment — or strip every class with `--clear` — and record the
+ * result in world.json.
+ *
+ * The engine hands back BYTES rather than uploading, the same split
+ * `REVOXELIZE_FROM_VXL_MASTER` uses: in a pro project the CLI owns world.json,
+ * and two writers on one asset thrash the reload watcher.
+ */
+export declare function setAssetMaterials(options: SetMaterialsOptions | ClearMaterialsOptions): Promise<SetMaterialsResult>;
+/** What api-server answers `POST /api/cli/v1/assets/materials/classify` with. */
+export interface ClassifyReply {
+    signatureHash?: unknown;
+    verdicts?: unknown;
+    model?: unknown;
+}
+/** The model step, injectable so the lane is testable without api-server. */
+export type ClassifyMaterials = (request: {
+    gameId: string;
+    assetName: string;
+    table: string;
+    signatureHash: string;
+    promptText?: string;
+}) => Promise<ClassifyReply>;
+export interface ClassifyMaterialsOptions extends MaterialsBaseOptions {
+    /** Test seam; the default posts to api-server. */
+    classify?: ClassifyMaterials;
+}
+export interface ClassifyMaterialsResult extends SetMaterialsResult {
+    /** The model that answered, for provenance. Absent when no verdicts came back. */
+    model?: string;
+}
+/**
+ * Read, classify and apply in ONE browser session: what `generate prop|model` run
+ * on the asset they just baked, and what `assets materials --auto` runs on demand.
+ *
+ * The middle step is api-server's light model rather than the creator's coding
+ * agent — the same prompt that agent would be shown, answered without a round
+ * trip through it, so a generated sword shines before anyone has looked at it.
+ * `assets materials --set` still overrides whatever this decided.
+ *
+ * An empty verdict list skips the APPLY entirely: the engine would leave the
+ * file byte-identical anyway, and not asking is one fewer thing to time out.
+ */
+export declare function classifyAssetMaterials(options: ClassifyMaterialsOptions): Promise<ClassifyMaterialsResult>;
+/**
+ * The tail of `generate prop|model` and `assets revoxelize`: classify the asset
+ * just baked, and say what happened.
+ *
+ * **Never throws.** The asset is baked, uploaded and in world.json by the time
+ * this runs, and a generation is paid for; a classification that fails —
+ * api-server without a model credential, a browser that would not come up a
+ * second time, a vendored engine too old to write classes — costs a note, never
+ * the asset. `bitmagic assets materials <id> --auto` re-runs it on demand.
+ */
+export declare function classifyAssetMaterialsQuietly(options: ClassifyMaterialsOptions): Promise<{
+    slots: string[];
+} | null>;