@francisdb/vpin-wasm 0.33.1 → 0.34.0

package/README.md

@@ -66,25 +66,33 @@ const vpxBytes = assemble(files, (message) => {
 
 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.
+or over-long names, storage suggestions, and script checks (missing
+`Option Explicit`, duplicate procedures, unused variables, timers without a
+handler, VPinMAME setup). 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}`);
+  const where = finding.line ? ` (line ${finding.line})` : "";
+  console.log(`${finding.severity} [${finding.code}]${where}: ${finding.message}`);
 }
-// warning: Light "L18": placed on missing surface "!l68"
-// suggestion: image "chrome" is stored as a bitmap, consider converting to webp
+// warning [missing-surface]: Light "L18": placed on missing surface "!l68"
+// suggestion [bmp-image]: image "chrome" is stored as a bitmap, consider converting to webp
+// suggestion [execute-used] (line 812): script uses Execute, which runs runtime-built code and can stutter
 ```
 
+`code` names the check and is stable, so findings can be grouped or
+suppressed by it; `line` and `column` (both from 1) are set for findings
+about one place in the script.
+
 **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
+**Returns:** `{severity: "error" | "warning" | "suggestion" | "info", code: string, message: string, line?: number, column?: number}[]` - empty when the table is clean
 
 ### export_glb(files, options?, callback?)
 
@@ -113,10 +121,14 @@ down on sound-heavy tables. A map without them works too.
 **Parameters:**
 
 - `files: VpxFileMap` (`Record<string, Uint8Array>`) - file paths to contents
-- `options?: GlbExportOptions` - `{ exportInvisibleItems?: boolean }`;
-  when `true`, invisible items are exported with the
-  `KHR_node_visibility` extension instead of skipped (needs viewer
-  support; leave off for Blender). Default `false`.
+- `options?: GlbExportOptions` - `{ exportInvisibleItems?: boolean, itemFilter?: "everything" | "vpinball", skipEditorHiddenItems?: boolean, onlyItems?: string[], excludeItems?: string[] }`;
+  `exportInvisibleItems: true` exports invisible items with the
+  `KHR_node_visibility` extension instead of skipping them (needs viewer
+  support; leave off for Blender). `itemFilter` picks the item selection:
+  `"everything"` (default) or `"vpinball"`, what vpinball's own OBJ export
+  writes. `skipEditorHiddenItems` leaves out the items on hidden editor
+  layers, and `onlyItems` / `excludeItems` select items by name. The same
+  four filter options exist on `export_obj`.
 - `callback?: (message: string) => void` - Optional progress callback
 
 **Returns:** `Uint8Array` - GLB file bytes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@francisdb/vpin-wasm",
-  "version": "0.33.1",
+  "version": "0.34.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

@@ -18,8 +18,15 @@ export type ProgressCallback = (message: string) => void;
  * One table consistency finding reported by `audit`.
  */
 export type AuditFinding = {
-    severity: "error" | "warning" | "suggestion";
+    severity: "error" | "warning" | "suggestion" | "info";
+    /** The check that produced the finding, in kebab case, e.g. "missing-image" */
+    code: string;
+    /** What is wrong, without the location */
     message: string;
+    /** Script line the finding is about, from 1, when it points at one */
+    line?: number;
+    /** Script column of the first character, from 1, when known */
+    column?: number;
 };
 
 
@@ -37,6 +44,29 @@ export interface GlbExportOptions {
      * engines); leave off for Blender. Default: `false`.
      */
     exportInvisibleItems?: boolean;
+    /**
+     * Which items the export includes. `"everything"`: every item type
+     * with geometry, skipping the ones invisible at play time.
+     * `"vpinball"`: what vpinball's own `File -> Export -> OBJ Mesh`
+     * writes (no lights, flashers, decals, plungers or balls). Default:
+     * `"everything"`.
+     */
+    itemFilter?: "everything" | "vpinball";
+    /**
+     * Skip the items whose editor layer is hidden (the `LVIS` record),
+     * like vpinball's own OBJ export does. Opt-in: the record holds the
+     * layer panel state of the last save, and released tables often
+     * have most layers hidden. Default: `false`.
+     */
+    skipEditorHiddenItems?: boolean;
+    /**
+     * Only export the items with these names (case insensitive).
+     */
+    onlyItems?: string[];
+    /**
+     * Skip the items with these names (case insensitive).
+     */
+    excludeItems?: string[];
 }
 
 
@@ -68,9 +98,28 @@ export interface ObjExportOptions {
      */
     extractTextures?: boolean;
     /**
-     * Include the plunger mesh. Default: `true`.
+     * Which items the export includes. `"everything"`: every item type
+     * with geometry, skipping the ones invisible at play time.
+     * `"vpinball"`: what vpinball's own `File -> Export -> OBJ Mesh`
+     * writes (no lights, flashers, decals, plungers or balls). Default:
+     * `"everything"`.
+     */
+    itemFilter?: "everything" | "vpinball";
+    /**
+     * Skip the items whose editor layer is hidden (the `LVIS` record),
+     * like vpinball's own OBJ export does. Opt-in: the record holds the
+     * layer panel state of the last save, and released tables often
+     * have most layers hidden. Default: `false`.
      */
-    includePlunger?: boolean;
+    skipEditorHiddenItems?: boolean;
+    /**
+     * Only export the items with these names (case insensitive).
+     */
+    onlyItems?: string[];
+    /**
+     * Skip the items with these names (case insensitive).
+     */
+    excludeItems?: string[];
 }
 
 /**
@@ -214,6 +263,11 @@ export class PrimitiveMesh {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Triangle corner indices, three per triangle, as 0-based offsets
+     * into the aligned vertex arrays. Each access copies the data out of
+     * wasm memory.
+     */
     readonly indices: Uint32Array;
     /**
      * Bounding-box midpoint of the mesh's positions, in the same
@@ -229,19 +283,57 @@ export class PrimitiveMesh {
      * Returns `[0, 0, 0]` for an empty mesh.
      */
     readonly midpoint: Float32Array;
+    /**
+     * The mesh name: the `o` name of the OBJ it was read from, or
+     * `primitive` for a generated mesh.
+     */
     readonly name: string;
+    /**
+     * Vertex normals as a flat `x, y, z` array, three values per corner,
+     * aligned with `positions`. Each access copies the data out of wasm
+     * memory.
+     */
     readonly normals: Float32Array;
+    /**
+     * Vertex positions as a flat `x, y, z` array, three values per
+     * corner. Each access copies the data out of wasm memory.
+     */
     readonly positions: Float32Array;
+    /**
+     * Texture coordinates as a flat `u, v` array, two values per corner,
+     * aligned with `positions`. Exposed to JavaScript as `texCoords`.
+     * Each access copies the data out of wasm memory.
+     */
     readonly texCoords: Float32Array;
 }
 
+/**
+ * Packs an expanded table back into a `.vpx` file.
+ *
+ * `files` is the `VpxFileMap` produced by [`extract`], with whatever
+ * edits the caller made to its entries; the table is read from the
+ * entries under `/vpx`. The result is the bytes of the `.vpx` file, as
+ * a `Uint8Array`.
+ * Assembling an unmodified map writes a file that holds the same table
+ * as the one that was extracted.
+ *
+ * `callback`, when given, receives a status message at every stage of
+ * the assembly.
+ *
+ * # Errors
+ *
+ * Throws a `JsError` whose message names the problem when a map value is
+ * not a byte array, a required file is missing or malformed, or the
+ * table cannot be written.
+ */
 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.
+ * duplicate or over-long names, storage suggestions and script checks.
+ * Returns an array of `{severity, code, message, line?, column?}` objects,
+ * empty when the table is clean.
  */
 export function audit(files: VpxFileMap, callback?: ProgressCallback | null): AuditFinding[];
 
@@ -276,6 +368,25 @@ export function export_glb(files: VpxFileMap, options?: GlbExportOptions | null,
  */
 export function export_obj(files: VpxFileMap, options?: ObjExportOptions | null, callback?: ProgressCallback | null): ObjExportFileMap;
 
+/**
+ * Unpacks a `.vpx` file into the expanded directory format as a file map.
+ *
+ * `data` holds the bytes of the `.vpx` file, as a `Uint8Array`. The
+ * result is a `VpxFileMap`: a plain object from absolute path under
+ * `/vpx` to a `Uint8Array`, for example `/vpx/images/ball.png` or
+ * `/vpx/gameitems/Wall1.json`. Primitive meshes come out as `.obj`
+ * files; the derived meshes vpinball generates for other items are not
+ * included. The map is what [`assemble`], [`audit`], [`export_glb`] and
+ * [`export_obj`] take.
+ *
+ * `callback`, when given, receives a status message at every stage of
+ * the extraction.
+ *
+ * # Errors
+ *
+ * Throws a `JsError` whose message names the problem when the bytes are
+ * not a readable `.vpx` file or the expansion fails.
+ */
 export function extract(data: Uint8Array, callback?: ProgressCallback | null): VpxFileMap;
 
 /**
@@ -299,6 +410,11 @@ export function extract(data: Uint8Array, callback?: ProgressCallback | null): V
  */
 export function generate_builtin_primitive(sides: number, draw_textures_inside: boolean): PrimitiveMesh;
 
+/**
+ * Runs once when the wasm module is instantiated; installs the panic
+ * hook that forwards Rust panics to the browser console. JavaScript
+ * callers never call this themselves.
+ */
 export function init(): void;
 
 /**

package/vpin.js

@@ -112,6 +112,9 @@ export class PrimitiveMesh {
         wasm.__wbg_primitivemesh_free(ptr, 0);
     }
     /**
+     * Triangle corner indices, three per triangle, as 0-based offsets
+     * into the aligned vertex arrays. Each access copies the data out of
+     * wasm memory.
      * @returns {Uint32Array}
      */
     get indices() {
@@ -137,6 +140,8 @@ export class PrimitiveMesh {
         return ret;
     }
     /**
+     * The mesh name: the `o` name of the OBJ it was read from, or
+     * `primitive` for a generated mesh.
      * @returns {string}
      */
     get name() {
@@ -152,6 +157,9 @@ export class PrimitiveMesh {
         }
     }
     /**
+     * Vertex normals as a flat `x, y, z` array, three values per corner,
+     * aligned with `positions`. Each access copies the data out of wasm
+     * memory.
      * @returns {Float32Array}
      */
     get normals() {
@@ -159,6 +167,8 @@ export class PrimitiveMesh {
         return ret;
     }
     /**
+     * Vertex positions as a flat `x, y, z` array, three values per
+     * corner. Each access copies the data out of wasm memory.
      * @returns {Float32Array}
      */
     get positions() {
@@ -166,6 +176,9 @@ export class PrimitiveMesh {
         return ret;
     }
     /**
+     * Texture coordinates as a flat `u, v` array, two values per corner,
+     * aligned with `positions`. Exposed to JavaScript as `texCoords`.
+     * Each access copies the data out of wasm memory.
      * @returns {Float32Array}
      */
     get texCoords() {
@@ -176,6 +189,23 @@ export class PrimitiveMesh {
 if (Symbol.dispose) PrimitiveMesh.prototype[Symbol.dispose] = PrimitiveMesh.prototype.free;
 
 /**
+ * Packs an expanded table back into a `.vpx` file.
+ *
+ * `files` is the `VpxFileMap` produced by [`extract`], with whatever
+ * edits the caller made to its entries; the table is read from the
+ * entries under `/vpx`. The result is the bytes of the `.vpx` file, as
+ * a `Uint8Array`.
+ * Assembling an unmodified map writes a file that holds the same table
+ * as the one that was extracted.
+ *
+ * `callback`, when given, receives a status message at every stage of
+ * the assembly.
+ *
+ * # Errors
+ *
+ * Throws a `JsError` whose message names the problem when a map value is
+ * not a byte array, a required file is missing or malformed, or the
+ * table cannot be written.
  * @param {VpxFileMap} files
  * @param {ProgressCallback | null} [callback]
  * @returns {Uint8Array}
@@ -193,8 +223,9 @@ export function assemble(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. Returns an array
- * of `{severity, message}` objects, empty when the table is clean.
+ * duplicate or over-long names, storage suggestions and script checks.
+ * Returns an array of `{severity, code, message, line?, column?}` objects,
+ * empty when the table is clean.
  * @param {VpxFileMap} files
  * @param {ProgressCallback | null} [callback]
  * @returns {AuditFinding[]}
@@ -261,6 +292,23 @@ export function export_obj(files, options, callback) {
 }
 
 /**
+ * Unpacks a `.vpx` file into the expanded directory format as a file map.
+ *
+ * `data` holds the bytes of the `.vpx` file, as a `Uint8Array`. The
+ * result is a `VpxFileMap`: a plain object from absolute path under
+ * `/vpx` to a `Uint8Array`, for example `/vpx/images/ball.png` or
+ * `/vpx/gameitems/Wall1.json`. Primitive meshes come out as `.obj`
+ * files; the derived meshes vpinball generates for other items are not
+ * included. The map is what [`assemble`], [`audit`], [`export_glb`] and
+ * [`export_obj`] take.
+ *
+ * `callback`, when given, receives a status message at every stage of
+ * the extraction.
+ *
+ * # Errors
+ *
+ * Throws a `JsError` whose message names the problem when the bytes are
+ * not a readable `.vpx` file or the expansion fails.
  * @param {Uint8Array} data
  * @param {ProgressCallback | null} [callback]
  * @returns {VpxFileMap}
@@ -305,6 +353,11 @@ export function generate_builtin_primitive(sides, draw_textures_inside) {
     return PrimitiveMesh.__wrap(ret[0]);
 }
 
+/**
+ * Runs once when the wasm module is instantiated; installs the panic
+ * hook that forwards Rust panics to the browser console. JavaScript
+ * callers never call this themselves.
+ */
 export function init() {
     wasm.init();
 }
@@ -489,6 +542,10 @@ function __wbg_get_imports() {
             const ret = arg0 in arg1;
             return ret;
         },
+        __wbg___wbindgen_is_function_fcda5e3902d732fe: function(arg0) {
+            const ret = typeof(arg0) === 'function';
+            return ret;
+        },
         __wbg___wbindgen_is_null_5160b3e381865372: function(arg0) {
             const ret = arg0 === null;
             return ret;
@@ -523,10 +580,18 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_5d9e815e6fdf150f: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
+        __wbg_call_269c5566fbede3eb: function() { return handleError(function (arg0, arg1) {
+            const ret = arg0.call(arg1);
+            return ret;
+        }, arguments); },
         __wbg_call_6bcf8d3e20937e46: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = arg0.call(arg1, arg2);
             return ret;
         }, arguments); },
+        __wbg_done_cffed884d87aa22e: function(arg0) {
+            const ret = arg0.done;
+            return ret;
+        },
         __wbg_error_757e9472f8410341: function(arg0, arg1) {
             let deferred0_0;
             let deferred0_1;
@@ -538,6 +603,10 @@ function __wbg_get_imports() {
                 wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
             }
         },
+        __wbg_get_6cf5a4d4d8ad3c5a: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.get(arg0, arg1);
+            return ret;
+        }, arguments); },
         __wbg_get_989d0a1309644f2b: function() { return handleError(function (arg0, arg1) {
             const ret = Reflect.get(arg0, arg1);
             return ret;
@@ -546,6 +615,10 @@ function __wbg_get_imports() {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
+        __wbg_get_unchecked_363572bdd397d473: function(arg0, arg1) {
+            const ret = arg0[arg1 >>> 0];
+            return ret;
+        },
         __wbg_get_with_ref_key_6412cf3094599694: function(arg0, arg1) {
             const ret = arg0[arg1];
             return ret;
@@ -570,10 +643,18 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
+        __wbg_isArray_5674713bb7b79043: function(arg0) {
+            const ret = Array.isArray(arg0);
+            return ret;
+        },
         __wbg_isSafeInteger_8f51c743827d1ec5: function(arg0) {
             const ret = Number.isSafeInteger(arg0);
             return ret;
         },
+        __wbg_iterator_22ddeb808cf55a6f: function() {
+            const ret = Symbol.iterator;
+            return ret;
+        },
         __wbg_keys_6efc298980178da1: function(arg0) {
             const ret = Object.keys(arg0);
             return ret;
@@ -614,6 +695,14 @@ function __wbg_get_imports() {
             const ret = new Uint32Array(getArrayU32FromWasm0(arg0, arg1));
             return ret;
         },
+        __wbg_next_95053e306b1c3aed: function(arg0) {
+            const ret = arg0.next;
+            return ret;
+        },
+        __wbg_next_f31ecb8646d2c605: function() { return handleError(function (arg0) {
+            const ret = arg0.next();
+            return ret;
+        }, arguments); },
         __wbg_now_d1fb6650485d7f3e: function() {
             const ret = Date.now();
             return ret;
@@ -638,11 +727,25 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbindgen_generic_0000000000000001: function(arg0, arg1) {
+        __wbg_value_c227f843d21da141: function(arg0) {
+            const ret = arg0.value;
+            return ret;
+        },
+        __wbindgen_generic_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return ret;
+        },
+        __wbindgen_generic_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return ret;
         },
+        __wbindgen_generic_0000000000000003: function(arg0) {
+            // Cast intrinsic for `U64 -> Externref`.
+            const ret = BigInt.asUintN(64, arg0);
+            return ret;
+        },
         __wbindgen_init_externref_table: function() {
             const table = wasm.__wbindgen_externrefs;
             const offset = table.grow(4);