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

package/dist/assets/entry.js

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

package/dist/assets/entry.js.map

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

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

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

package/dist/assets/file-kind.js

@@ -0,0 +1,195 @@
+/**
+ * What `bitmagic assets add <file>` makes of a filename, decided BEFORE anything is read, uploaded
+ * or written — so a file this lane cannot take costs nothing and leaves world.json untouched.
+ *
+ * The table mirrors the Creator's Assets-tab upload (`creator/src/vue/composables/useAssetsEditor.ts`
+ * `handleFileUpload` + `assetsUploadTypes.ts` `detectAssetType`) where the CLI can do the same
+ * thing, and refuses — by name, with where to go instead — where it cannot:
+ *
+ *  - `.gltf` is refused rather than accepted-and-broken: the engine voxelizes ONE fetched URL, and
+ *    a `.gltf` is a JSON index whose buffers and textures live in files beside it.
+ *  - `.vox`/`.qb` (MagicaVoxel/Qubicle import), `.fbx` (animation import), `.spz`/`.ply`/`.sog`
+ *    (splat transcode) and `.mp4` (video faststart) each need a conversion the Creator runs through
+ *    game-play-agent, which a CLI project cannot reach.
+ *
+ * Audio and raster images are uploaded AS THEY ARE. The Creator transcodes them to `.opus`/`.webp`
+ * for size; the engine decodes mp3/ogg/m4a through Web Audio and draws png/jpg like any browser,
+ * so the difference is bytes, not whether it works. `audioTranscodeNote` says so once.
+ */
+import * as path from 'path';
+import { CliError } from '../errors.js';
+const CREATOR_ONLY = {
+    vox: 'MagicaVoxel import',
+    qb: 'Qubicle import',
+    fbx: 'FBX animation import',
+    spz: 'Gaussian-splat transcode',
+    ply: 'Gaussian-splat transcode',
+    sog: 'Gaussian-splat transcode',
+    mp4: 'video',
+};
+const IMAGE_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+};
+const AUDIO_TYPES = {
+    opus: 'audio/ogg',
+    ogg: 'audio/ogg',
+    m4a: 'audio/mp4',
+    mp3: 'audio/mpeg',
+};
+/** 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'];
+/**
+ * The extension, treating a dotfile as having one.
+ *
+ * `path.extname('.vxl')` is `''` — Node reads a leading dot as the start of the basename, not an
+ * extension — so a file literally named `.vxl` (what an export tool that names by extension alone
+ * produces) fell through to the catch-all and was refused with a message listing `.vxl` among the
+ * types it takes.
+ */
+export function fileExtension(filename) {
+    const base = path.basename(filename);
+    const fromExtname = path.extname(base).slice(1);
+    const extension = fromExtname !== '' ? fromExtname : (base.startsWith('.') ? base.slice(1) : '');
+    return extension.toLowerCase();
+}
+export function classifyAssetFile(filename, options) {
+    const extension = fileExtension(filename);
+    const base = path.basename(filename);
+    if (options.keepGlb && extension !== 'glb') {
+        throw new CliError(`--keep-glb only applies to a .glb file, and ${base} is not one. world.json is unchanged.`);
+    }
+    if (extension === 'glb') {
+        return options.keepGlb
+            ? { kind: 'glb-keep', assetType: 'glb', contentType: 'model/gltf-binary', extension }
+            : { kind: 'glb-voxelize', assetType: 'vxl', contentType: 'model/gltf-binary', extension };
+    }
+    if (extension === 'vxl') {
+        // The same content type the engine uploads its own bakes under (VoxelMessageHandlers.ts).
+        // api-server marks it compressible, so the PUT gzips.
+        return { kind: 'vxl', assetType: 'vxl', contentType: 'application/octet-stream', extension };
+    }
+    const imageType = IMAGE_TYPES[extension];
+    if (imageType !== undefined) {
+        return { kind: 'image', assetType: 'image', contentType: imageType, extension };
+    }
+    const audioType = AUDIO_TYPES[extension];
+    if (audioType !== undefined) {
+        return { kind: 'audio', assetType: 'audio', contentType: audioType, extension };
+    }
+    if (extension === 'json') {
+        return { kind: 'json', assetType: 'json', contentType: 'application/json', extension };
+    }
+    if (extension === 'gltf') {
+        throw new CliError(`${base} is a .gltf, which keeps its buffers and textures in files beside it — the game loads a `
+            + 'single URL. Export it as a self-contained .glb and add that instead. world.json is unchanged.');
+    }
+    const creatorOnly = CREATOR_ONLY[extension];
+    if (creatorOnly !== undefined) {
+        throw new CliError(`.${extension} (${creatorOnly}) needs a conversion this CLI does not run. `
+            + 'Upload it through the Creator\'s Assets tab instead. world.json is unchanged.');
+    }
+    throw new CliError(`Cannot add ${base}: this CLI takes ${ACCEPTED_EXTENSIONS.map((e) => `.${e}`).join(', ')}. `
+        + 'world.json is unchanged.');
+}
+/**
+ * The asset's name when `--name` is not given: the file's basename without its extension, which
+ * is what the Creator pre-fills its name prompt with.
+ */
+export function defaultAssetName(filename) {
+    const base = path.basename(filename);
+    const stripped = base.replace(/\.[^/.]+$/, '');
+    // A file named for its extension alone (`.png`) strips to nothing, and an empty name is refused
+    // downstream — a dead end for a file this lane otherwise accepts. Drop the leading dot instead.
+    return stripped !== '' ? stripped : base.replace(/^\.+/, '');
+}
+/**
+ * Characters that survive a path check but break the URL the object is served from, or the storage
+ * key itself. api-server builds `publicUrl` by concatenating the key onto the portal origin with no
+ * percent-encoding, so a `#` truncates the URL at a fragment and a `?` at a query — the asset then
+ * 404s at game load, long after a successful-looking upload. GCS rejects CR/LF in object names
+ * outright. Refused up front rather than escaped, so the name in world.json is the name on disk.
+ */
+// eslint-disable-next-line no-control-regex -- control characters are exactly what this rejects
+const URL_UNSAFE = /[#?%\u0000-\u001f\u007f]/;
+/** GCS caps an object key at 1024 bytes; the engine prefixes and suffixes the name inside one. */
+const MAX_NAME_LENGTH = 128;
+function describeUnsafe(value) {
+    const bad = URL_UNSAFE.exec(value)?.[0] ?? '';
+    const code = bad.charCodeAt(0);
+    return code < 0x20 || code === 0x7f ? `a control character (0x${code.toString(16)})` : `"${bad}"`;
+}
+/**
+ * A name the engine can build a filename from. `CREATE_ASSET_FROM_GLB_URL` uploads its bake as
+ * `<gameId>-<name>-<timestamp>.vxl`, and api-server refuses a filename carrying a separator or
+ * `..` — so a name that would trip that fails HERE, before the file has been uploaded and the
+ * browser launched, instead of as an opaque "Failed to upload VXL file" minutes later.
+ *
+ * The length cap and the URL-unsafe set are part of the same job: both produce a failure that only
+ * appears after the upload (or after a ten-minute bake), which is precisely what this is for.
+ */
+export function validateAssetName(name) {
+    const trimmed = name.trim();
+    if (trimmed === '')
+        throw new CliError('The asset name cannot be empty. world.json is unchanged.');
+    if (/[/\\]/.test(trimmed) || trimmed.includes('..')) {
+        throw new CliError(`The asset name ${JSON.stringify(name)} cannot contain a path separator or "..". world.json is unchanged.`);
+    }
+    if (URL_UNSAFE.test(trimmed)) {
+        throw new CliError(`The asset name ${JSON.stringify(name)} cannot contain ${describeUnsafe(trimmed)} — it ends up in `
+            + 'the uploaded file\'s URL. world.json is unchanged.');
+    }
+    if (trimmed.length > MAX_NAME_LENGTH) {
+        throw new CliError(`The asset name is ${trimmed.length} characters; keep it under ${MAX_NAME_LENGTH}. world.json is unchanged.`);
+    }
+    return trimmed;
+}
+/**
+ * The upload filename: a bare basename, which is all api-server accepts.
+ *
+ * Mirrors `sanitizeUploadFilename` in full — separators AND `..`, as three independent checks.
+ * `path.basename` strips `/` on POSIX but leaves `\`, so a legal `my\model.glb` used to pass here
+ * and then eat a network round-trip to be refused by the server with a message naming nothing the
+ * creator could act on. The URL-unsafe and length checks are here for the same reason as on the
+ * name above.
+ */
+export function uploadFilename(filePath) {
+    const base = path.basename(filePath);
+    if (base.includes('/') || base.includes('\\')) {
+        throw new CliError(`Rename ${JSON.stringify(base)} first: an upload filename cannot contain a path separator. `
+            + 'world.json is unchanged.');
+    }
+    if (base.includes('..')) {
+        throw new CliError(`Rename ${base} first: an upload filename cannot contain "..". world.json is unchanged.`);
+    }
+    if (URL_UNSAFE.test(base)) {
+        throw new CliError(`Rename ${JSON.stringify(base)} first: a filename cannot contain ${describeUnsafe(base)} — it ends up `
+            + 'in the uploaded file\'s URL. world.json is unchanged.');
+    }
+    if (base.length > MAX_NAME_LENGTH) {
+        throw new CliError(`Rename ${JSON.stringify(base)} first: keep the filename under ${MAX_NAME_LENGTH} characters. `
+            + 'world.json is unchanged.');
+    }
+    return base;
+}
+/**
+ * `asset_<timestamp>_<random>` — byte-compatible with the engine's `ObjectIdService.generateId`
+ * and with what api-server mints for the generators (`cli-assets.ts`), so an id minted here is
+ * indistinguishable from one minted anywhere else in the system.
+ */
+export function mintAssetId(now = Date.now, random = Math.random) {
+    return `asset_${now()}_${random().toString(36).substring(2, 8)}`;
+}
+/**
+ * Said once per audio upload that the Creator would have transcoded. The engine plays the file
+ * as-is; this is about download size, and it names the exact command rather than a vague "consider".
+ */
+export function audioTranscodeNote(extension) {
+    if (extension === 'opus')
+        return null;
+    return `Uploaded as .${extension}. The game plays it as-is; for a smaller download convert it first: `
+        + `ffmpeg -i in.${extension} -c:a libopus -b:a 96k out.opus`;
+}
+//# sourceMappingURL=file-kind.js.map

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

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

package/dist/assets/list.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `bitmagic assets list` — the project's `assets[]`, as the dev view's assets panel sees it
+ * (`editor/server.ts` `GET /api/assets` reads the same array and nothing else).
+ */
+import { type JsonObject } from '../project/world-json.js';
+export interface AssetRow {
+    id: string;
+    name: string;
+    type: string;
+    size?: number;
+    /** Placed instances in `environmentObjects[]`. */
+    placed: number;
+    /**
+     * Every reference anywhere in world.json — placed instances plus levels, maps, doors, key items,
+     * village rosters.
+     *
+     * Reported alongside {@link placed} rather than folded into it because the two answer different
+     * questions, and counting only placed instances was actively misleading: a level asset showed
+     * `0`, an agent read that as "safe to delete", and `assets remove` then refused — or, with
+     * `--force`, removed the asset while leaving the level pointing at nothing.
+     */
+    references: number;
+}
+export declare function summarizeAssets(world: JsonObject): AssetRow[];
+export declare function formatSize(bytes: number | undefined): string;
+/** Fixed-width columns, no dependency, readable in a terminal and greppable by an agent. */
+export declare function formatAssetTable(rows: AssetRow[]): string;

package/dist/assets/list.js

@@ -0,0 +1,50 @@
+/**
+ * `bitmagic assets list` — the project's `assets[]`, as the dev view's assets panel sees it
+ * (`editor/server.ts` `GET /api/assets` reads the same array and nothing else).
+ */
+import { isJsonObject } from '../project/world-json.js';
+import { findAssetReferences } from './remove.js';
+export function summarizeAssets(world) {
+    const assets = Array.isArray(world.assets) ? world.assets : [];
+    return assets.filter(isJsonObject).map((asset) => {
+        const id = typeof asset.id === 'string' ? asset.id : '';
+        // The SAME scan `assets remove` refuses on, so the two commands cannot disagree about what
+        // counts as a reference.
+        const found = id === '' ? [] : findAssetReferences(world, id);
+        return {
+            id,
+            name: typeof asset.name === 'string' ? asset.name : '',
+            type: typeof asset.type === 'string' ? asset.type : '',
+            ...(typeof asset.size === 'number' ? { size: asset.size } : {}),
+            placed: found.filter((ref) => ref.placed).length,
+            references: found.length,
+        };
+    });
+}
+export function formatSize(bytes) {
+    if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
+        return '';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** Fixed-width columns, no dependency, readable in a terminal and greppable by an agent. */
+export function formatAssetTable(rows) {
+    if (rows.length === 0)
+        return 'No assets in world.json yet. `bitmagic assets add <file>` adds one.';
+    const header = { id: 'ID', name: 'NAME', type: 'TYPE', size: 'SIZE', placed: 'PLACED', references: 'REFS' };
+    const cells = rows.map((row) => ({
+        id: row.id, name: row.name, type: row.type, size: formatSize(row.size),
+        placed: String(row.placed), references: String(row.references),
+    }));
+    const width = (key) => Math.max(header[key].length, ...cells.map((cell) => cell[key].length));
+    const w = {
+        id: width('id'), name: width('name'), type: width('type'), size: width('size'), placed: width('placed'),
+    };
+    const line = (cell) => `${cell.id.padEnd(w.id)}  ${cell.name.padEnd(w.name)}  ${cell.type.padEnd(w.type)}  `
+        + `${cell.size.padStart(w.size)}  ${cell.placed.padStart(w.placed)}  ${cell.references}`;
+    return [line(header), ...cells.map(line)].join('\n');
+}
+//# sourceMappingURL=list.js.map

package/dist/assets/list.js.map

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

package/dist/assets/remove.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What `bitmagic assets remove <id>` does to world.json, decided before anything is written.
+ *
+ * Removal is world.json only. The uploaded bytes stay in storage — that is what the Creator's
+ * Remove and game-play-agent's `/api/remove-asset` do too (there is no delete endpoint on either
+ * server, and every upload is immutable-cached), so a published game that still points at the file
+ * keeps working.
+ *
+ * The one thing this does that the Creator's button does not: it looks for what still POINTS at
+ * the asset first. world.json references an asset by id under a handful of keys — placed objects'
+ * `assetId`, a level's `vwldAssetId`, a map's `mapAssetId`, doors, key items, towers — and a
+ * removed asset that any of them still names is a load error the creator finds later, in the
+ * browser, with nothing connecting it back to this command. So the scan is a generic walk for
+ * those keys rather than a list of known containers: a container added to the schema tomorrow is
+ * still caught. What it cannot see is game CODE (`engine.playSound(assetId)`), and the refusal
+ * says so.
+ *
+ * `--force` removes the asset and every placed instance in `environmentObjects[]` in the same
+ * atomic write, and reports the rest as warnings.
+ */
+import type { WorldJsonModification } from '@bitmagic/world-forger/pipeline/index.js';
+import { type JsonObject } from '../project/world-json.js';
+export interface AssetReference {
+    /** JSON-pointer-ish path to the referencing value, e.g. `environmentObjects[3].assetId`. */
+    path: string;
+    /**
+     * True when this is a placed instance in root `environmentObjects[]` — the one kind of reference
+     * `--force` can clean up by removing it alongside the asset.
+     *
+     * Recorded during the walk rather than recovered by re-parsing {@link path}: the path is a
+     * human-readable rendering, and deriving structure back out of it silently returns "no placed
+     * instances" the moment that rendering changes.
+     */
+    placed: boolean;
+}
+export interface RemovalPlan {
+    asset: JsonObject;
+    modifications: WorldJsonModification[];
+    /** Placed instances in `environmentObjects[]` — removed with the asset under `--force`. */
+    placedInstances: number;
+    /** References elsewhere in the document, which `--force` leaves in place and reports. */
+    otherReferences: AssetReference[];
+}
+/**
+ * Every place in the document where one of the reference keys holds `assetId`. The asset's own
+ * `assets[]` entry is skipped — its `id` is not a reference key, but a vehicle asset's own
+ * `vehicleFitment` might one day carry one, so the whole `assets[]` subtree is excluded outright.
+ */
+export declare function findAssetReferences(world: JsonObject, assetId: string): AssetReference[];
+export declare function planAssetRemoval(world: JsonObject, assetId: string, force: boolean): RemovalPlan;

package/dist/assets/remove.js

@@ -0,0 +1,91 @@
+import { CliError } from '../errors.js';
+import { isJsonObject } from '../project/world-json.js';
+/**
+ * Whether a key holds an asset id. Matched by SHAPE rather than by an enumerated list, because an
+ * enumerated list is exactly what went wrong: `buildingAssetIds` (required on every village
+ * hotspot) was missing, so removing a village's building asset reported zero references and left
+ * the world throwing `references unknown assetId(s)` at load.
+ *
+ * The shape covers `assetId` and every `<thing>AssetId` / `<thing>AssetIds` in the GameData types
+ * (`vwldAssetId`, `mapAssetId`, `characterAssetId`, `buildingAssetIds`, `audioAssetIds`, …), so a
+ * container OR a key added to the schema tomorrow is caught without editing this file.
+ */
+function isReferenceKey(key) {
+    return key === 'assetId' || /^[A-Za-z]\w*AssetIds?$/.test(key);
+}
+/**
+ * Does this value name the asset? Plural keys hold an ARRAY of ids, which a bare `===` could never
+ * match — the second half of the same bug.
+ */
+function namesAsset(value, assetId) {
+    if (typeof value === 'string')
+        return value === assetId;
+    return Array.isArray(value) && value.some((item) => item === assetId);
+}
+/** Root array of placed instances — the only references `--force` removes rather than reports. */
+const PLACED_OBJECTS_KEY = 'environmentObjects';
+/**
+ * Every place in the document where one of the reference keys holds `assetId`. The asset's own
+ * `assets[]` entry is skipped — its `id` is not a reference key, but a vehicle asset's own
+ * `vehicleFitment` might one day carry one, so the whole `assets[]` subtree is excluded outright.
+ */
+export function findAssetReferences(world, assetId) {
+    const found = [];
+    const walk = (value, path, inPlacedObjects) => {
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => walk(item, `${path}[${index}]`, inPlacedObjects));
+            return;
+        }
+        if (!isJsonObject(value))
+            return;
+        for (const [key, child] of Object.entries(value)) {
+            const childPath = path === '' ? key : `${path}.${key}`;
+            if (path === '' && key === 'assets')
+                continue;
+            if (isReferenceKey(key) && namesAsset(child, assetId)) {
+                found.push({ path: childPath, placed: inPlacedObjects && key === 'assetId' });
+                continue;
+            }
+            walk(child, childPath, inPlacedObjects || (path === '' && key === PLACED_OBJECTS_KEY));
+        }
+    };
+    walk(world, '', false);
+    return found;
+}
+export function planAssetRemoval(world, assetId, force) {
+    const assets = Array.isArray(world.assets) ? world.assets : [];
+    const asset = assets.find((item) => isJsonObject(item) && item.id === assetId);
+    if (asset === undefined) {
+        throw new CliError(`No asset with id "${assetId}" in this project's world.json. `
+            + '`bitmagic assets list` shows the ids. world.json is unchanged.');
+    }
+    const references = findAssetReferences(world, assetId);
+    const placed = references.filter((ref) => ref.placed);
+    const others = references.filter((ref) => !ref.placed);
+    if (references.length > 0 && !force) {
+        const name = typeof asset.name === 'string' ? asset.name : assetId;
+        const lines = references.slice(0, 8).map((ref) => `  - ${ref.path}`);
+        if (references.length > 8)
+            lines.push(`  - …and ${references.length - 8} more`);
+        throw new CliError(`"${name}" is still referenced ${references.length === 1 ? 'once' : `${references.length} times`} in world.json:\n`
+            + `${lines.join('\n')}\n`
+            + 'Removing it would leave those pointing at nothing. Re-run with --force to remove the asset '
+            + `and its ${placed.length} placed instance${placed.length === 1 ? '' : 's'} together`
+            + (others.length > 0 ? ' (the other references stay and are reported)' : '')
+            + '. Game code that names the id (playSound, spawnFromAsset, …) is not checked. world.json is unchanged.');
+    }
+    const modifications = [{
+            type: 'removeRoot',
+            path: ['assets'],
+            predicate: (item) => isJsonObject(item) && item.id === assetId,
+        }];
+    if (placed.length > 0) {
+        modifications.push({
+            type: 'removeRoot',
+            path: ['environmentObjects'],
+            predicate: (item) => isJsonObject(item) && item.assetId === assetId,
+        });
+    }
+    return { asset, modifications, placedInstances: placed.length, otherReferences: others };
+}
+//# sourceMappingURL=remove.js.map

package/dist/assets/remove.js.map

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

package/dist/assets/voxelize-glb.d.ts

@@ -0,0 +1,37 @@
+import type { Environment } from '../config/environments.js';
+import type { ProjectContext } from '../project/context.js';
+/** Bake resolution and scale. Defaults live with the commands, which document them to creators. */
+export interface VoxelizeFlags {
+    minVoxelSize: number;
+    maxVoxelSize: number;
+    /** Metres. Absent = the GLB's own size, as the Creator's voxelize dialog leaves it by default. */
+    targetHeight?: number;
+    fillInterior: boolean;
+}
+export interface VoxelizeGlbRequest {
+    context: ProjectContext;
+    environment: Environment;
+    token: string;
+    /** Asset name; also what the engine builds its uploaded `.vxl` filename from. */
+    name: string;
+    glbUrl: string;
+    /** The id to register under. The engine echoes it back, and callers must check that it did. */
+    assetId: string;
+    voxel: VoxelizeFlags;
+    /** What the creator should do if this fails — what is kept, and the command that resumes it. */
+    retryHint: string;
+    /** Distinguishes concurrent requests in the page; also names the lane in the transport log. */
+    requestPrefix: string;
+    log: (message: string) => void;
+}
+/** Runs the bake and returns the engine's asset record. Injected in tests, real everywhere else. */
+export type VoxelizeGlb = (request: VoxelizeGlbRequest) => Promise<Record<string, unknown>>;
+export declare const voxelizeGlbIntoAsset: VoxelizeGlb;
+/**
+ * The engine ECHOES the id it was given — but only since it learned to honour a supplied id for an
+ * asset that does not exist yet. An older vendored engine mints its own, and since the caller's
+ * upsert matches on the id it ASKED for, a mismatch would silently append under a different id
+ * than the one reported: the command prints an id absent from world.json, `assets remove` cannot
+ * find it, and a retry adds a second copy instead of replacing.
+ */
+export declare function assertEngineHonouredId(engineAsset: Record<string, unknown>, assetId: string, name: string, keptHint: string): void;