@francisdb/vpin-wasm 0.29.0 → 0.31.0

package/README.md

@@ -62,6 +62,30 @@ const vpxBytes = assemble(files, (message) => {
 
 **Returns:** `Uint8Array` - VPX file bytes
 
+### audit(files, callback?)
+
+Checks the expanded table files for consistency problems: references to
+images, materials, surfaces or collection items that do not exist, duplicate
+or over-long names, and storage suggestions. The checks themselves run in a
+few milliseconds even on very large tables, so it is fine to call this after
+every change; the cost is dominated by reading the files into a table.
+
+```typescript
+const findings = audit(files);
+for (const finding of findings) {
+  console.log(`${finding.severity}: ${finding.message}`);
+}
+// warning: Light "L18": placed on missing surface "!l68"
+// suggestion: image "chrome" is stored as a bitmap, consider converting to webp
+```
+
+**Parameters:**
+
+- `files: VpxFileMap` (`Record<string, Uint8Array>`) - file paths to contents
+- `callback?: (message: string) => void` - Optional progress callback
+
+**Returns:** `{severity: "warning" | "suggestion", message: string}[]` - empty when the table is clean
+
 ### export_glb(files, options?, callback?)
 
 Exports a whole table to a GLB (binary glTF 2.0) file. Takes the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@francisdb/vpin-wasm",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "WASM bindings for vpin, a rust library for the visual/virtual pinball ecosystem.",
   "homepage": "https://github.com/francisdb/vpin",
   "bugs": {

package/vpin.d.ts

@@ -8,6 +8,20 @@
  */
 export type VpxFileMap = Record<string, Uint8Array>;
 
+/**
+ * Progress callback: receives a human readable status message while a
+ * long running operation works through a table.
+ */
+export type ProgressCallback = (message: string) => void;
+
+/**
+ * One table consistency finding reported by `audit`.
+ */
+export type AuditFinding = {
+    severity: "error" | "warning" | "suggestion";
+    message: string;
+};
+
 
 
 /**
@@ -27,6 +41,47 @@ export interface GlbExportOptions {
 
 
 
+/**
+ * Options for `export_obj`. Pass a plain object literal; every field
+ * is optional.
+ */
+export interface ObjExportOptions {
+    /**
+     * Axis convention of the written OBJ. Default:
+     * `AxisConvention.ZDownRightHanded`, vpinball's own OBJ export
+     * layout. Use `AxisConvention.YUpRightHanded` for Blender and most
+     * other tools with default import settings.
+     */
+    axes?: AxisConvention;
+    /**
+     * Unit of the written positions. Default: `ExportUnits.M`.
+     */
+    units?: ExportUnits;
+    /**
+     * Emit one `newmtl` block per distinct (material, texture) pair
+     * instead of one per `usemtl`. Default: `true`.
+     */
+    dedupMtlBlocks?: boolean;
+    /**
+     * Write the referenced textures to `images/` and reference them
+     * from the MTL. Default: `true`.
+     */
+    extractTextures?: boolean;
+    /**
+     * Include the plunger mesh. Default: `true`.
+     */
+    includePlunger?: boolean;
+}
+
+/**
+ * Result of `export_obj`: path relative to the export directory to file
+ * contents, e.g. `{ "table.obj": Uint8Array, "table.mtl": Uint8Array,
+ * "images/playfield.png": Uint8Array }`.
+ */
+export type ObjExportFileMap = Record<string, Uint8Array>;
+
+
+
 /**
  * Options for `mesh_to_glb`. Pass a plain object literal; every field
  * is optional.
@@ -108,6 +163,34 @@ export enum AxisConvention {
     YUpRightHanded = 2,
 }
 
+/**
+ * Output unit for table exports (OBJ, glTF/GLB).
+ *
+ * VPinball internally uses "VP Units" (VPU): 50 VPU = 1.0625 inches
+ * (one pinball diameter), so a standard table around 20 inches wide
+ * is roughly 950 VPU. Loaded straight into a tool that treats
+ * numbers as metres, that becomes a ~950 m table. Pick a metric
+ * variant to scale positions on the way out.
+ */
+export enum ExportUnits {
+    /**
+     * Raw VPinball Units (no scaling).
+     */
+    Vpu = 0,
+    /**
+     * Millimetres.
+     */
+    Mm = 1,
+    /**
+     * Centimetres.
+     */
+    Cm = 2,
+    /**
+     * Metres.
+     */
+    M = 3,
+}
+
 /**
  * Mesh data for a single primitive: positions, texture coordinates,
  * normals and triangle indices, packed as flat typed arrays for direct
@@ -152,7 +235,15 @@ export class PrimitiveMesh {
     readonly texCoords: Float32Array;
 }
 
-export function assemble(files: VpxFileMap, callback?: Function | null): Uint8Array;
+export function assemble(files: VpxFileMap, callback?: ProgressCallback | null): Uint8Array;
+
+/**
+ * Checks the expanded table files for consistency problems: references to
+ * images, materials, surfaces or collection items that do not exist,
+ * duplicate or over-long names, and storage suggestions. Returns an array
+ * of `{severity, message}` objects, empty when the table is clean.
+ */
+export function audit(files: VpxFileMap, callback?: ProgressCallback | null): AuditFinding[];
 
 /**
  * Export a whole table to a GLB (binary glTF 2.0) file.
@@ -173,9 +264,19 @@ export function assemble(files: VpxFileMap, callback?: Function | null): Uint8Ar
  * memory down on sound-heavy tables. Passing a map without them works
  * too.
  */
-export function export_glb(files: VpxFileMap, options?: GlbExportOptions | null, callback?: Function | null): Uint8Array;
+export function export_glb(files: VpxFileMap, options?: GlbExportOptions | null, callback?: ProgressCallback | null): Uint8Array;
 
-export function extract(data: Uint8Array, callback?: Function | null): VpxFileMap;
+/**
+ * Export a whole table as a Wavefront OBJ with its MTL and, by
+ * default, the referenced textures. Takes the file map produced by
+ * `extract` and returns a file map relative to the export directory:
+ * `table.obj`, `table.mtl` and `images/*`.
+ *
+ * Sound entries are ignored like in `export_glb`.
+ */
+export function export_obj(files: VpxFileMap, options?: ObjExportOptions | null, callback?: ProgressCallback | null): ObjExportFileMap;
+
+export function extract(data: Uint8Array, callback?: ProgressCallback | null): VpxFileMap;
 
 /**
  * Generate the procedural mesh used by vpinball primitives that
@@ -292,9 +393,12 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_primitivemesh_free: (a: number, b: number) => void;
     readonly assemble: (a: any, b: number) => [number, number, number, number];
+    readonly audit: (a: any, b: number) => [number, number, number];
     readonly export_glb: (a: any, b: number, c: number) => [number, number, number, number];
+    readonly export_obj: (a: any, b: number, c: number) => [number, number, number];
     readonly extract: (a: number, b: number, c: number) => [number, number, number];
     readonly generate_builtin_primitive: (a: number, b: number) => [number, number, number];
+    readonly init: () => void;
     readonly mesh_to_glb: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number, number, number];
     readonly mesh_to_obj: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number, number, number];
     readonly obj_to_mesh: (a: number, b: number, c: number) => [number, number, number];
@@ -304,7 +408,6 @@ export interface InitOutput {
     readonly primitivemesh_normals: (a: number) => any;
     readonly primitivemesh_positions: (a: number) => any;
     readonly primitivemesh_texCoords: (a: number) => any;
-    readonly init: () => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_exn_store: (a: number) => void;

package/vpin.js

@@ -46,6 +46,35 @@ export const AxisConvention = Object.freeze({
     YUpRightHanded: 2, "2": "YUpRightHanded",
 });
 
+/**
+ * Output unit for table exports (OBJ, glTF/GLB).
+ *
+ * VPinball internally uses "VP Units" (VPU): 50 VPU = 1.0625 inches
+ * (one pinball diameter), so a standard table around 20 inches wide
+ * is roughly 950 VPU. Loaded straight into a tool that treats
+ * numbers as metres, that becomes a ~950 m table. Pick a metric
+ * variant to scale positions on the way out.
+ * @enum {0 | 1 | 2 | 3}
+ */
+export const ExportUnits = Object.freeze({
+    /**
+     * Raw VPinball Units (no scaling).
+     */
+    Vpu: 0, "0": "Vpu",
+    /**
+     * Millimetres.
+     */
+    Mm: 1, "1": "Mm",
+    /**
+     * Centimetres.
+     */
+    Cm: 2, "2": "Cm",
+    /**
+     * Metres.
+     */
+    M: 3, "3": "M",
+});
+
 /**
  * Mesh data for a single primitive: positions, texture coordinates,
  * normals and triangle indices, packed as flat typed arrays for direct
@@ -148,7 +177,7 @@ if (Symbol.dispose) PrimitiveMesh.prototype[Symbol.dispose] = PrimitiveMesh.prot
 
 /**
  * @param {VpxFileMap} files
- * @param {Function | null} [callback]
+ * @param {ProgressCallback | null} [callback]
  * @returns {Uint8Array}
  */
 export function assemble(files, callback) {
@@ -161,6 +190,23 @@ export function assemble(files, callback) {
     return v1;
 }
 
+/**
+ * Checks the expanded table files for consistency problems: references to
+ * images, materials, surfaces or collection items that do not exist,
+ * duplicate or over-long names, and storage suggestions. Returns an array
+ * of `{severity, message}` objects, empty when the table is clean.
+ * @param {VpxFileMap} files
+ * @param {ProgressCallback | null} [callback]
+ * @returns {AuditFinding[]}
+ */
+export function audit(files, callback) {
+    const ret = wasm.audit(files, isLikeNone(callback) ? 0 : addToExternrefTable0(callback));
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Export a whole table to a GLB (binary glTF 2.0) file.
  *
@@ -181,7 +227,7 @@ export function assemble(files, callback) {
  * too.
  * @param {VpxFileMap} files
  * @param {GlbExportOptions | null} [options]
- * @param {Function | null} [callback]
+ * @param {ProgressCallback | null} [callback]
  * @returns {Uint8Array}
  */
 export function export_glb(files, options, callback) {
@@ -194,9 +240,29 @@ export function export_glb(files, options, callback) {
     return v1;
 }
 
+/**
+ * Export a whole table as a Wavefront OBJ with its MTL and, by
+ * default, the referenced textures. Takes the file map produced by
+ * `extract` and returns a file map relative to the export directory:
+ * `table.obj`, `table.mtl` and `images/*`.
+ *
+ * Sound entries are ignored like in `export_glb`.
+ * @param {VpxFileMap} files
+ * @param {ObjExportOptions | null} [options]
+ * @param {ProgressCallback | null} [callback]
+ * @returns {ObjExportFileMap}
+ */
+export function export_obj(files, options, callback) {
+    const ret = wasm.export_obj(files, isLikeNone(options) ? 0 : addToExternrefTable0(options), isLikeNone(callback) ? 0 : addToExternrefTable0(callback));
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * @param {Uint8Array} data
- * @param {Function | null} [callback]
+ * @param {ProgressCallback | null} [callback]
  * @returns {VpxFileMap}
  */
 export function extract(data, callback) {
@@ -392,11 +458,11 @@ export function obj_to_mesh(data, options) {
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg_Error_408e67f47ca7b58b: function(arg0, arg1) {
+        __wbg_Error_67e7344beaa85059: function(arg0, arg1) {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return ret;
         },
-        __wbg_Number_3890faa6d3ff057d: function(arg0) {
+        __wbg_Number_c54e7112a3fa7e3e: function(arg0) {
             const ret = Number(arg0);
             return ret;
         },
@@ -407,46 +473,46 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_boolean_get_c9c83ebd41b34df3: function(arg0) {
+        __wbg___wbindgen_boolean_get_7a12af2b3f899c5a: function(arg0) {
             const v = arg0;
             const ret = typeof(v) === 'boolean' ? v : undefined;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
-        __wbg___wbindgen_debug_string_a57024b9c6e4a48b: function(arg0, arg1) {
+        __wbg___wbindgen_debug_string_0e68cf47c9cbd9b0: function(arg0, arg1) {
             const ret = debugString(arg1);
             const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
             const len1 = WASM_VECTOR_LEN;
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_in_ac983077f137f2e6: function(arg0, arg1) {
+        __wbg___wbindgen_in_50072d4d6e45c193: function(arg0, arg1) {
             const ret = arg0 in arg1;
             return ret;
         },
-        __wbg___wbindgen_is_null_7d13f41e1a2d5140: function(arg0) {
+        __wbg___wbindgen_is_null_5160b3e381865372: function(arg0) {
             const ret = arg0 === null;
             return ret;
         },
-        __wbg___wbindgen_is_object_a2790eb24c211ea0: function(arg0) {
+        __wbg___wbindgen_is_object_edb6b15aa3afe12e: function(arg0) {
             const val = arg0;
             const ret = typeof(val) === 'object' && val !== null;
             return ret;
         },
-        __wbg___wbindgen_is_undefined_6cff064c44e0d823: function(arg0) {
+        __wbg___wbindgen_is_undefined_8c687d0b90d5b524: function(arg0) {
             const ret = arg0 === undefined;
             return ret;
         },
-        __wbg___wbindgen_jsval_loose_eq_acf2776254a8d832: function(arg0, arg1) {
+        __wbg___wbindgen_jsval_loose_eq_3c30021c243b64cd: function(arg0, arg1) {
             const ret = arg0 == arg1;
             return ret;
         },
-        __wbg___wbindgen_number_get_136b9679cab35cfb: function(arg0, arg1) {
+        __wbg___wbindgen_number_get_1dc732b810cb937c: function(arg0, arg1) {
             const obj = arg1;
             const ret = typeof(obj) === 'number' ? obj : undefined;
             getDataViewMemory0().setFloat64(arg0 + 8 * 1, isLikeNone(ret) ? 0 : ret, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
         },
-        __wbg___wbindgen_string_get_d154f1e671052120: function(arg0, arg1) {
+        __wbg___wbindgen_string_get_92ab86bb19cbc12f: function(arg0, arg1) {
             const obj = arg1;
             const ret = typeof(obj) === 'string' ? obj : undefined;
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -454,10 +520,10 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_throw_bb96b2010945f0bc: function(arg0, arg1) {
+        __wbg___wbindgen_throw_5d9e815e6fdf150f: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_call_35dba3c747ad7521: function() { return handleError(function (arg0, arg1, arg2) {
+        __wbg_call_6bcf8d3e20937e46: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = arg0.call(arg1, arg2);
             return ret;
         }, arguments); },
@@ -472,11 +538,11 @@ function __wbg_get_imports() {
                 wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
             }
         },
-        __wbg_get_971a0c45d172643f: function() { return handleError(function (arg0, arg1) {
+        __wbg_get_989d0a1309644f2b: function() { return handleError(function (arg0, arg1) {
             const ret = Reflect.get(arg0, arg1);
             return ret;
         }, arguments); },
-        __wbg_get_c0c8f8d7da0c03dd: function(arg0, arg1) {
+        __wbg_get_b1f0ab13c737f856: function(arg0, arg1) {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
@@ -484,7 +550,7 @@ function __wbg_get_imports() {
             const ret = arg0[arg1];
             return ret;
         },
-        __wbg_instanceof_ArrayBuffer_993d02d2d254cad1: function(arg0) {
+        __wbg_instanceof_ArrayBuffer_d4ff01f8247925ae: function(arg0) {
             let result;
             try {
                 result = arg0 instanceof ArrayBuffer;
@@ -494,7 +560,7 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
-        __wbg_instanceof_Uint8Array_f935dbb0aa7cdeed: function(arg0) {
+        __wbg_instanceof_Uint8Array_598adc0fef426aa8: function(arg0) {
             let result;
             try {
                 result = arg0 instanceof Uint8Array;
@@ -504,54 +570,64 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
-        __wbg_isSafeInteger_f3d6cd19ccfe4512: function(arg0) {
+        __wbg_isSafeInteger_8f51c743827d1ec5: function(arg0) {
             const ret = Number.isSafeInteger(arg0);
             return ret;
         },
-        __wbg_keys_ec7f8c0c2370d91d: function(arg0) {
+        __wbg_keys_6efc298980178da1: function(arg0) {
             const ret = Object.keys(arg0);
             return ret;
         },
-        __wbg_length_36bd29c6848c2144: function(arg0) {
+        __wbg_length_31bdaf014f5fbde2: function(arg0) {
             const ret = arg0.length;
             return ret;
         },
-        __wbg_length_ecfa2c63d3d0d82c: function(arg0) {
+        __wbg_length_4e1adc0d42e23620: function(arg0) {
             const ret = arg0.length;
             return ret;
         },
-        __wbg_new_227d7c05414eb861: function() {
-            const ret = new Error();
+        __wbg_new_1da3429bc3c4541c: function(arg0) {
+            const ret = new Uint8Array(arg0);
             return ret;
         },
-        __wbg_new_77cc4f4f472aeb81: function(arg0) {
-            const ret = new Uint8Array(arg0);
+        __wbg_new_227d7c05414eb861: function() {
+            const ret = new Error();
             return ret;
         },
-        __wbg_new_ebe3e0f6837f0879: function() {
+        __wbg_new_bebc3f4757acf305: function() {
             const ret = new Object();
             return ret;
         },
-        __wbg_new_from_slice_3eea173078478cfe: function(arg0, arg1) {
-            const ret = new Uint8Array(getArrayU8FromWasm0(arg0, arg1));
+        __wbg_new_ffa92086ea89f79c: function() {
+            const ret = new Array();
             return ret;
         },
-        __wbg_new_from_slice_709ab7061ebcc5da: function(arg0, arg1) {
+        __wbg_new_from_slice_2221cabb71753908: function(arg0, arg1) {
             const ret = new Float32Array(getArrayF32FromWasm0(arg0, arg1));
             return ret;
         },
-        __wbg_new_from_slice_8aed4f0384605526: function(arg0, arg1) {
+        __wbg_new_from_slice_4ee02165f9de919e: function(arg0, arg1) {
+            const ret = new Uint8Array(getArrayU8FromWasm0(arg0, arg1));
+            return ret;
+        },
+        __wbg_new_from_slice_a500ec81601be48f: function(arg0, arg1) {
             const ret = new Uint32Array(getArrayU32FromWasm0(arg0, arg1));
             return ret;
         },
-        __wbg_now_8b265300afd5f2b9: function() {
+        __wbg_now_d1fb6650485d7f3e: function() {
             const ret = Date.now();
             return ret;
         },
-        __wbg_prototypesetcall_de8e0d9553586985: function(arg0, arg1, arg2) {
+        __wbg_prototypesetcall_ae9f5e7459250748: function(arg0, arg1, arg2) {
             Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
         },
-        __wbg_set_8155bb79a948541b: function() { return handleError(function (arg0, arg1, arg2) {
+        __wbg_set_13d25b81ab403f5e: function(arg0, arg1, arg2) {
+            arg0[arg1 >>> 0] = arg2;
+        },
+        __wbg_set_6be42768c690e380: function(arg0, arg1, arg2) {
+            arg0[arg1] = arg2;
+        },
+        __wbg_set_a377297433dfea63: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = Reflect.set(arg0, arg1, arg2);
             return ret;
         }, arguments); },
@@ -562,7 +638,7 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
+        __wbindgen_generic_0000000000000001: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return ret;

package/vpin_bg.wasm.d.ts

@@ -3,9 +3,12 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_primitivemesh_free: (a: number, b: number) => void;
 export const assemble: (a: any, b: number) => [number, number, number, number];
+export const audit: (a: any, b: number) => [number, number, number];
 export const export_glb: (a: any, b: number, c: number) => [number, number, number, number];
+export const export_obj: (a: any, b: number, c: number) => [number, number, number];
 export const extract: (a: number, b: number, c: number) => [number, number, number];
 export const generate_builtin_primitive: (a: number, b: number) => [number, number, number];
+export const init: () => void;
 export const mesh_to_glb: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number, number, number];
 export const mesh_to_obj: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number, number, number];
 export const obj_to_mesh: (a: number, b: number, c: number) => [number, number, number];
@@ -15,7 +18,6 @@ export const primitivemesh_name: (a: number) => [number, number];
 export const primitivemesh_normals: (a: number) => any;
 export const primitivemesh_positions: (a: number) => any;
 export const primitivemesh_texCoords: (a: number) => any;
-export const init: () => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_exn_store: (a: number) => void;