@francisdb/vpin-wasm 0.28.2 → 0.30.0

package/README.md

@@ -11,7 +11,7 @@ npm install @francisdb/vpin-wasm
 ## Usage
 
 ```typescript
-import init, { extract, assemble, obj_to_mesh, mesh_to_obj } from '@francisdb/vpin-wasm';
+import init, { extract, assemble, obj_to_mesh, mesh_to_obj, AxisConvention } from '@francisdb/vpin-wasm';
 
 await init();
 ```
@@ -35,7 +35,7 @@ const files = extract(vpxBytes, (message) => {
 - `data: Uint8Array` - VPX file bytes
 - `callback?: (message: string) => void` - Optional progress callback
 
-**Returns:** `Record<string, Uint8Array>` - Object mapping file paths to contents
+**Returns:** `VpxFileMap` (`Record<string, Uint8Array>`) - file paths to contents
 
 ### assemble(files, callback?)
 
@@ -57,12 +57,47 @@ const vpxBytes = assemble(files, (message) => {
 
 **Parameters:**
 
-- `files: Record<string, Uint8Array>` - Object mapping file paths to contents
+- `files: VpxFileMap` (`Record<string, Uint8Array>`) - file paths to contents
 - `callback?: (message: string) => void` - Optional progress callback
 
 **Returns:** `Uint8Array` - VPX file bytes
 
-### obj_to_mesh(data) / mesh_to_obj(name, positions, texCoords, normals, indices)
+### export_glb(files, options?, callback?)
+
+Exports a whole table to a GLB (binary glTF 2.0) file. Takes the same
+extracted-file map `assemble` takes; call `extract` first if you only
+have `.vpx` bytes.
+
+```typescript
+const files = extract(vpxBytes);
+const glb = export_glb(files, { exportInvisibleItems: false }, (message) => {
+  console.log(message);
+});
+// glb is a Uint8Array with model/gltf-binary content
+```
+
+The output follows the glTF conventions - Y-up right-handed axes and
+meters - so it opens correctly in Blender and other viewers with
+default import settings. It contains generated meshes for every part
+type, PBR materials from the table's material list, embedded textures,
+and the three VPX view cameras.
+
+Sound entries (`/vpx/sounds.json`, `/vpx/sounds/*`) are ignored - the
+exporter never reads them, and skipping them keeps peak wasm memory
+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`.
+- `callback?: (message: string) => void` - Optional progress callback
+
+**Returns:** `Uint8Array` - GLB file bytes
+
+### obj_to_mesh(data, options?) / mesh_to_obj(name, positions, texCoords, normals, indices, options?)
 
 Renderer-friendly mesh I/O. `obj_to_mesh` parses any flavor of OBJ
 (n-gons fan-triangulated, mismatched `v/vt/vn` corners deduplicated)
@@ -71,7 +106,9 @@ JS-side OBJ parser needed.
 
 ```typescript
 const objBytes = files['/vpx/gameitems/Primitive.MyMesh.obj'];
-const mesh = obj_to_mesh(objBytes);
+const mesh = obj_to_mesh(objBytes); // defaults: vpinball convention, scale 1.0
+// or e.g. for a Blender-exported OBJ:
+// const mesh = obj_to_mesh(objBytes, { axes: AxisConvention.YUpRightHanded });
 
 // mesh.name: string
 // mesh.positions: Float32Array  (length = 3 * vertCount, x,y,z,...)
@@ -95,20 +132,52 @@ const obj = mesh_to_obj(mesh.name, mesh.positions, mesh.texCoords, mesh.normals,
 files['/vpx/gameitems/Primitive.MyMesh.obj'] = obj;
 ```
 
+### mesh_to_glb(name, positions, texCoords, normals, indices, options?)
+
+The GLB sibling of `mesh_to_obj` - serializes a single mesh as a
+binary glTF 2.0 file, for handing one primitive's mesh to a DCC tool.
+There is no axis option: glTF mandates Y-up right-handed, so the
+vpx-internal input is always converted the same way `export_glb`
+converts the whole table (texture coordinates pass through unchanged -
+glTF's UV origin matches vpx's, unlike OBJ's).
+
+```typescript
+const glb = mesh_to_glb(mesh.name, mesh.positions, mesh.texCoords, mesh.normals, mesh.indices);
+// glb is a Uint8Array with model/gltf-binary content
+```
+
+`options.unitScale` (default `1.0`) multiplies positions. A
+primitive's local mesh coordinates are arbitrary units (the table
+scales them by the primitive's Size at render), so no unit conversion
+is applied by default.
+
 The published wasm bundle is built with `wasm-bindgen --weak-refs`, so
 the Rust-owned memory backing each `mesh` is reclaimed automatically
 via `FinalizationRegistry` when the JS wrapper is garbage-collected.
 You may call `mesh.free()` explicitly for deterministic cleanup of
 large meshes, but it is not required.
 
-**Coordinate convention:** the mesh data is in vpx-internal form -
-`obj_to_mesh` applies the same transforms as `assemble`'s read path
-(vertex Z negated, normal Z negated, V coordinate flipped, per-triangle
-corner order reversed), and `mesh_to_obj` applies the inverse, matching
-`extract`'s write path. Round-trip
-`obj_to_mesh -> edit -> mesh_to_obj -> assemble` preserves vpx data by
-construction. If your renderer uses a different convention than
-vpinball's left-handed +Z up, apply a transform matrix on the JS side.
+**Coordinate convention:** the mesh data is always in vpx-internal
+form; `options.axes` names the convention of the OBJ side:
+
+- `AxisConvention.ZDownRightHanded` (default) - vpinball's exported OBJ
+  convention (vertex/normal Z negated, V coordinate flipped,
+  per-triangle corner order reversed). This is what `extract` writes
+  and `assemble` reads, so it is the right choice for OBJs from the
+  extracted file map. Round-trip
+  `obj_to_mesh -> edit -> mesh_to_obj -> assemble` preserves vpx data
+  by construction.
+- `AxisConvention.YUpRightHanded` - the Blender / DCC default (Y-Z
+  swap, V flip, winding reverse). Use this to hand a Blender-exported
+  OBJ straight to `obj_to_mesh`, or to write an OBJ that opens upright
+  in Blender with default import settings.
+- `AxisConvention.ZUpLeftHanded` - vpx-internal values verbatim, no
+  transforms.
+
+`options.unitScale` (default `1.0`) multiplies positions (on the vpx
+side for `obj_to_mesh`, before the axis mapping for `mesh_to_obj`).
+Normals and texture coordinates are never scaled. An OBJ written with
+scale `k` reads back with scale `1 / k`.
 
 **Animation frames:** primitives with vertex animation extract as
 sibling files `Primitive.MyMesh_00000.obj`, `Primitive.MyMesh_00001.obj`,

package/package.json

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

@@ -1,6 +1,182 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * An extracted table as a file map: absolute path under `/vpx` to file
+ * contents, e.g. `{ "/vpx/images/ball.png": Uint8Array, ... }`.
+ * Produced by `extract`, consumed by `assemble` and `export_glb`.
+ */
+export type VpxFileMap = Record<string, Uint8Array>;
+
+
+
+/**
+ * Options for `export_glb`. Pass a plain object literal; every field
+ * is optional.
+ */
+export interface GlbExportOptions {
+    /**
+     * When `true`, items marked invisible in the table are exported
+     * with the `KHR_node_visibility` extension set to `visible: false`
+     * instead of being skipped. Preserves the full table structure but
+     * requires viewer support for the extension (e.g. some game
+     * engines); leave off for Blender. Default: `false`.
+     */
+    exportInvisibleItems?: boolean;
+}
+
+
+
+/**
+ * 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.
+ */
+export interface MeshGlbOptions {
+    /**
+     * Multiplier applied to positions before the axis mapping. Normals
+     * and texture coordinates are never scaled. Default: `1.0`.
+     */
+    unitScale?: number;
+}
+
+
+
+/**
+ * Options for `obj_to_mesh` / `mesh_to_obj`. Pass a plain object
+ * literal; every field is optional.
+ */
+export interface MeshIoOptions {
+    /**
+     * Axis convention of the OBJ side of the conversion (the mesh side
+     * is always vpx-internal). Default: `AxisConvention.ZDownRightHanded`,
+     * matching what `extract` writes and `assemble` reads.
+     */
+    axes?: AxisConvention;
+    /**
+     * Multiplier applied to positions (on the vpx side for
+     * `obj_to_mesh`, before the axis mapping for `mesh_to_obj`).
+     * Normals and texture coordinates are never scaled. An OBJ written
+     * with scale `k` reads back with `1 / k`. Default: `1.0`.
+     */
+    unitScale?: number;
+}
+
+
+
+/**
+ * Axis convention for 3D mesh interchange (OBJ, glTF/GLB), in either
+ * direction: exporting VPX geometry or importing meshes back in.
+ *
+ * VPX space is left-handed with Z up: X right (across the playfield),
+ * Y towards the player (down the playfield), Z up (towards the glass).
+ * [`Self::ZUpLeftHanded`] is that internal frame verbatim; the other
+ * variants negate or swap exactly one axis pair, so each produces a
+ * right-handed frame from the left-handed one. A conversion between two
+ * frames of different [`Self::handedness`] must pair with a reversed
+ * triangle winding (matching vpinball's `ObjLoader`); one between frames
+ * of equal handedness keeps the winding, since such frames differ only
+ * by a pure rotation (the two right-handed variants: 90 degrees about
+ * X).
+ */
+export enum AxisConvention {
+    /**
+     * VPX's internal coordinate system: left-handed with Z up, inherited
+     * from DirectX. X runs right across the playfield, Y down the
+     * playfield towards the player, Z up towards the glass.
+     *
+     * Converting to or from this convention leaves coordinates untouched
+     * (vertices keep their vpx-internal values). Only meaningful for
+     * tooling that works on the raw vpx data; not what any viewer or DCC
+     * tool expects.
+     */
+    ZUpLeftHanded = 0,
+    /**
+     * VPinball's exported OBJ convention: `(x, y, -z)`.
+     *
+     * Right-handed like [`Self::YUpRightHanded`], but keeping VPX's axis
+     * roles: Y still runs down the playfield and Z, now negated, points
+     * down through the table instead of up. This is what vpinball itself
+     * writes when exporting an OBJ and expects when importing one, so a
+     * table shows up rotated 90 degrees about X in a Y-up viewer.
+     */
+    ZDownRightHanded = 1,
+    /**
+     * Y up, right-handed: `(x, z, y)`. The glTF and Wavefront OBJ
+     * convention, and what Blender / Maya / 3ds Max assume with their
+     * default import settings (`Scale 1.0, Forward -Z, Up Y`).
+     */
+    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
@@ -45,9 +221,40 @@ export class PrimitiveMesh {
     readonly texCoords: Float32Array;
 }
 
-export function assemble(files: object, callback?: Function | null): Uint8Array;
+export function assemble(files: VpxFileMap, callback?: Function | null): Uint8Array;
 
-export function extract(data: Uint8Array, callback?: Function | null): object;
+/**
+ * Export a whole table to a GLB (binary glTF 2.0) file.
+ *
+ * Takes the same extracted-file map `assemble` takes
+ * (`{ "/vpx/...": Uint8Array }`), so consumers holding a table as an
+ * extracted tree skip a full assemble/parse round trip; consumers with
+ * only `.vpx` bytes can call `extract` first.
+ *
+ * The output follows the glTF conventions: Y-up right-handed axes and
+ * meters, so it opens correctly in Blender and other glTF viewers with
+ * default settings. It contains the generated meshes for every part
+ * type, PBR materials from the VPX material list, embedded textures,
+ * and the three VPX view cameras (desktop / fullscreen / FSS).
+ *
+ * Sound entries (`/vpx/sounds.json` and `/vpx/sounds/*`) are ignored -
+ * the exporter never reads them, and skipping them keeps peak wasm
+ * 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 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?: Function | null): ObjExportFileMap;
+
+export function extract(data: Uint8Array, callback?: Function | null): VpxFileMap;
 
 /**
  * Generate the procedural mesh used by vpinball primitives that
@@ -72,6 +279,26 @@ export function generate_builtin_primitive(sides: number, draw_textures_inside:
 
 export function init(): void;
 
+/**
+ * Serialize a single mesh as a GLB (binary glTF 2.0) file.
+ *
+ * The GLB sibling of [`mesh_to_obj`], for exporting one primitive's
+ * mesh to DCC tools. There is no axis option: glTF mandates Y-up
+ * right-handed, so the vpx-internal input is always converted the same
+ * way the whole-table exporter converts it (Y-Z swap, winding
+ * reversed; texture coordinates pass through - glTF's UV origin
+ * matches vpx's, unlike OBJ's).
+ *
+ * `name` becomes the mesh/node name; pass an empty string to use
+ * `"object"`. Array requirements are the same as [`mesh_to_obj`].
+ *
+ * `options.unitScale` (default `1.0`) multiplies positions. A
+ * primitive's local mesh coordinates are arbitrary units (the table
+ * scales them by the primitive's Size at render), so no unit
+ * conversion is applied by default.
+ */
+export function mesh_to_glb(name: string, positions: Float32Array, tex_coords: Float32Array, normals: Float32Array, indices: Uint32Array, options?: MeshGlbOptions | null): Uint8Array;
+
 /**
  * Serialize a mesh as a Wavefront OBJ.
  *
@@ -81,18 +308,29 @@ export function init(): void;
  * normals.len() / 3`); index values must be valid 0-based offsets into
  * that vertex array.
  *
- * `convert_to_left_handed` is the symmetric inverse of the same flag
- * on [`obj_to_mesh`]:
+ * `options.axes` is the symmetric inverse of the same option on
+ * [`obj_to_mesh`]: the input is always vpx-internal data, `axes` names
+ * the convention to write the OBJ in.
  *
- * - `true` (matches `extract`'s write path): the input is treated as
- *   vpx-internal data and converted out: vertex Z is negated, normal Z
- *   is negated, V is flipped (`obj_v = 1 - vpx_tv`), and per-triangle
- *   corner order is reversed. The result is a vpinball-format OBJ
- *   that `assemble` (or `obj_to_mesh(.., true)`) reads back identically.
- * - `false`: the input vpx-internal data is written out verbatim, no
- *   transforms applied. Round-trips with `obj_to_mesh(.., false)`.
+ * - [`AxisConvention::ZDownRightHanded`] (the default; matches
+ *   `extract`'s write path, the old `convert_to_left_handed = true`):
+ *   vertex and normal Z are negated, V is flipped (`obj_v = 1 -
+ *   vpx_tv`) and per-triangle corner order is reversed. The result is a
+ *   vpinball-format OBJ that `assemble` (or `obj_to_mesh` with the same
+ *   convention) reads back identically.
+ * - [`AxisConvention::YUpRightHanded`]: Y and Z are swapped, V is
+ *   flipped and winding is reversed; the OBJ opens upright in Blender
+ *   with default import settings.
+ * - [`AxisConvention::ZUpLeftHanded`] (the old `convert_to_left_handed
+ *   = false`): the vpx-internal data is written out verbatim, no
+ *   transforms applied.
+ *
+ * `options.unitScale` (default `1.0`) multiplies positions before the
+ * axis mapping. Normals and texture coordinates are never scaled.
+ * Round-trips through `obj_to_mesh` with the same convention and scale
+ * `1.0 / unitScale`.
  */
-export function mesh_to_obj(name: string, positions: Float32Array, tex_coords: Float32Array, normals: Float32Array, indices: Uint32Array, convert_to_left_handed: boolean): Uint8Array;
+export function mesh_to_obj(name: string, positions: Float32Array, tex_coords: Float32Array, normals: Float32Array, indices: Uint32Array, options?: MeshIoOptions | null): Uint8Array;
 
 /**
  * Parse a Wavefront OBJ into a [`PrimitiveMesh`].
@@ -101,21 +339,31 @@ export function mesh_to_obj(name: string, positions: Float32Array, tex_coords: F
  * anything in between): n-gons are fan-triangulated and `(position, uv,
  * normal)` corners are deduplicated so the result is renderer-ready.
  *
- * `convert_to_left_handed` mirrors vpinball's `ObjLoader::Load` flag of
- * the same name (the "Convert coordinate system" checkbox in the
- * vpinball mesh-import dialog):
+ * `options.axes` names the convention the OBJ data is in; the returned
+ * mesh is always in vpx-internal convention:
+ *
+ * - [`AxisConvention::ZDownRightHanded`] (the default; matches
+ *   `assemble`'s read path and vpinball's mesh-import dialog with
+ *   "Convert coordinate system" checked, the old `convert_to_left_handed
+ *   = true`): vertex and normal Z are negated, V is flipped (`vpx_tv =
+ *   1 - obj_v`) and the per-triangle corner order is reversed. This path
+ *   also honors the `# vpx <hex>` byte-preservation comments, so
+ *   vpinball-format OBJs from `extract` reproduce the original vpx
+ *   values bit-for-bit.
+ * - [`AxisConvention::YUpRightHanded`] (Blender / DCC default export
+ *   settings): Y and Z are swapped, V is flipped and winding is
+ *   reversed.
+ * - [`AxisConvention::ZUpLeftHanded`] (the old `convert_to_left_handed
+ *   = false`): the input is assumed to already hold vpx-internal values
+ *   (e.g. produced by a previous `mesh_to_obj` with the same
+ *   convention). No transforms; values pass through verbatim.
  *
- * - `true` (matches `assemble`'s read path and vpinball's dialog
- *   default): the input is treated as right-handed (Blender / standard
- *   convention). Vertex Z is negated, normal Z is negated, V is flipped
- *   (`vpx_tv = 1 - obj_v`), and the per-triangle corner order is
- *   reversed. The returned mesh data ends up in vpx-internal,
- *   left-handed convention.
- * - `false`: the input is assumed to already be in vpx-internal
- *   convention (e.g. produced by a previous `mesh_to_obj` with the same
- *   flag). The transforms are skipped and values pass through verbatim.
+ * `options.unitScale` (default `1.0`) multiplies positions after the
+ * axis mapping. Normals and texture coordinates are never scaled. A
+ * mesh exported through `mesh_to_obj` with scale `k` reads back with
+ * scale `1.0 / k`.
  */
-export function obj_to_mesh(data: Uint8Array, convert_to_left_handed: boolean): PrimitiveMesh;
+export function obj_to_mesh(data: Uint8Array, options?: MeshIoOptions | null): PrimitiveMesh;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
@@ -123,8 +371,11 @@ 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 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 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];
     readonly primitivemesh_indices: (a: number) => any;

package/vpin.js

@@ -1,5 +1,80 @@
 /* @ts-self-types="./vpin.d.ts" */
 
+/**
+ * Axis convention for 3D mesh interchange (OBJ, glTF/GLB), in either
+ * direction: exporting VPX geometry or importing meshes back in.
+ *
+ * VPX space is left-handed with Z up: X right (across the playfield),
+ * Y towards the player (down the playfield), Z up (towards the glass).
+ * [`Self::ZUpLeftHanded`] is that internal frame verbatim; the other
+ * variants negate or swap exactly one axis pair, so each produces a
+ * right-handed frame from the left-handed one. A conversion between two
+ * frames of different [`Self::handedness`] must pair with a reversed
+ * triangle winding (matching vpinball's `ObjLoader`); one between frames
+ * of equal handedness keeps the winding, since such frames differ only
+ * by a pure rotation (the two right-handed variants: 90 degrees about
+ * X).
+ * @enum {0 | 1 | 2}
+ */
+export const AxisConvention = Object.freeze({
+    /**
+     * VPX's internal coordinate system: left-handed with Z up, inherited
+     * from DirectX. X runs right across the playfield, Y down the
+     * playfield towards the player, Z up towards the glass.
+     *
+     * Converting to or from this convention leaves coordinates untouched
+     * (vertices keep their vpx-internal values). Only meaningful for
+     * tooling that works on the raw vpx data; not what any viewer or DCC
+     * tool expects.
+     */
+    ZUpLeftHanded: 0, "0": "ZUpLeftHanded",
+    /**
+     * VPinball's exported OBJ convention: `(x, y, -z)`.
+     *
+     * Right-handed like [`Self::YUpRightHanded`], but keeping VPX's axis
+     * roles: Y still runs down the playfield and Z, now negated, points
+     * down through the table instead of up. This is what vpinball itself
+     * writes when exporting an OBJ and expects when importing one, so a
+     * table shows up rotated 90 degrees about X in a Y-up viewer.
+     */
+    ZDownRightHanded: 1, "1": "ZDownRightHanded",
+    /**
+     * Y up, right-handed: `(x, z, y)`. The glTF and Wavefront OBJ
+     * convention, and what Blender / Maya / 3ds Max assume with their
+     * default import settings (`Scale 1.0, Forward -Z, Up Y`).
+     */
+    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
@@ -101,7 +176,7 @@ export class PrimitiveMesh {
 if (Symbol.dispose) PrimitiveMesh.prototype[Symbol.dispose] = PrimitiveMesh.prototype.free;
 
 /**
- * @param {object} files
+ * @param {VpxFileMap} files
  * @param {Function | null} [callback]
  * @returns {Uint8Array}
  */
@@ -115,10 +190,63 @@ export function assemble(files, callback) {
     return v1;
 }
 
+/**
+ * Export a whole table to a GLB (binary glTF 2.0) file.
+ *
+ * Takes the same extracted-file map `assemble` takes
+ * (`{ "/vpx/...": Uint8Array }`), so consumers holding a table as an
+ * extracted tree skip a full assemble/parse round trip; consumers with
+ * only `.vpx` bytes can call `extract` first.
+ *
+ * The output follows the glTF conventions: Y-up right-handed axes and
+ * meters, so it opens correctly in Blender and other glTF viewers with
+ * default settings. It contains the generated meshes for every part
+ * type, PBR materials from the VPX material list, embedded textures,
+ * and the three VPX view cameras (desktop / fullscreen / FSS).
+ *
+ * Sound entries (`/vpx/sounds.json` and `/vpx/sounds/*`) are ignored -
+ * the exporter never reads them, and skipping them keeps peak wasm
+ * memory down on sound-heavy tables. Passing a map without them works
+ * too.
+ * @param {VpxFileMap} files
+ * @param {GlbExportOptions | null} [options]
+ * @param {Function | null} [callback]
+ * @returns {Uint8Array}
+ */
+export function export_glb(files, options, callback) {
+    const ret = wasm.export_glb(files, isLikeNone(options) ? 0 : addToExternrefTable0(options), isLikeNone(callback) ? 0 : addToExternrefTable0(callback));
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v1 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    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 {Function | 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]
- * @returns {object}
+ * @returns {VpxFileMap}
  */
 export function extract(data, callback) {
     const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
@@ -164,6 +292,51 @@ export function init() {
     wasm.init();
 }
 
+/**
+ * Serialize a single mesh as a GLB (binary glTF 2.0) file.
+ *
+ * The GLB sibling of [`mesh_to_obj`], for exporting one primitive's
+ * mesh to DCC tools. There is no axis option: glTF mandates Y-up
+ * right-handed, so the vpx-internal input is always converted the same
+ * way the whole-table exporter converts it (Y-Z swap, winding
+ * reversed; texture coordinates pass through - glTF's UV origin
+ * matches vpx's, unlike OBJ's).
+ *
+ * `name` becomes the mesh/node name; pass an empty string to use
+ * `"object"`. Array requirements are the same as [`mesh_to_obj`].
+ *
+ * `options.unitScale` (default `1.0`) multiplies positions. A
+ * primitive's local mesh coordinates are arbitrary units (the table
+ * scales them by the primitive's Size at render), so no unit
+ * conversion is applied by default.
+ * @param {string} name
+ * @param {Float32Array} positions
+ * @param {Float32Array} tex_coords
+ * @param {Float32Array} normals
+ * @param {Uint32Array} indices
+ * @param {MeshGlbOptions | null} [options]
+ * @returns {Uint8Array}
+ */
+export function mesh_to_glb(name, positions, tex_coords, normals, indices, options) {
+    const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passArrayF32ToWasm0(positions, wasm.__wbindgen_malloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ptr2 = passArrayF32ToWasm0(tex_coords, wasm.__wbindgen_malloc);
+    const len2 = WASM_VECTOR_LEN;
+    const ptr3 = passArrayF32ToWasm0(normals, wasm.__wbindgen_malloc);
+    const len3 = WASM_VECTOR_LEN;
+    const ptr4 = passArray32ToWasm0(indices, wasm.__wbindgen_malloc);
+    const len4 = WASM_VECTOR_LEN;
+    const ret = wasm.mesh_to_glb(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3, ptr4, len4, isLikeNone(options) ? 0 : addToExternrefTable0(options));
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v6 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v6;
+}
+
 /**
  * Serialize a mesh as a Wavefront OBJ.
  *
@@ -173,25 +346,36 @@ export function init() {
  * normals.len() / 3`); index values must be valid 0-based offsets into
  * that vertex array.
  *
- * `convert_to_left_handed` is the symmetric inverse of the same flag
- * on [`obj_to_mesh`]:
+ * `options.axes` is the symmetric inverse of the same option on
+ * [`obj_to_mesh`]: the input is always vpx-internal data, `axes` names
+ * the convention to write the OBJ in.
+ *
+ * - [`AxisConvention::ZDownRightHanded`] (the default; matches
+ *   `extract`'s write path, the old `convert_to_left_handed = true`):
+ *   vertex and normal Z are negated, V is flipped (`obj_v = 1 -
+ *   vpx_tv`) and per-triangle corner order is reversed. The result is a
+ *   vpinball-format OBJ that `assemble` (or `obj_to_mesh` with the same
+ *   convention) reads back identically.
+ * - [`AxisConvention::YUpRightHanded`]: Y and Z are swapped, V is
+ *   flipped and winding is reversed; the OBJ opens upright in Blender
+ *   with default import settings.
+ * - [`AxisConvention::ZUpLeftHanded`] (the old `convert_to_left_handed
+ *   = false`): the vpx-internal data is written out verbatim, no
+ *   transforms applied.
  *
- * - `true` (matches `extract`'s write path): the input is treated as
- *   vpx-internal data and converted out: vertex Z is negated, normal Z
- *   is negated, V is flipped (`obj_v = 1 - vpx_tv`), and per-triangle
- *   corner order is reversed. The result is a vpinball-format OBJ
- *   that `assemble` (or `obj_to_mesh(.., true)`) reads back identically.
- * - `false`: the input vpx-internal data is written out verbatim, no
- *   transforms applied. Round-trips with `obj_to_mesh(.., false)`.
+ * `options.unitScale` (default `1.0`) multiplies positions before the
+ * axis mapping. Normals and texture coordinates are never scaled.
+ * Round-trips through `obj_to_mesh` with the same convention and scale
+ * `1.0 / unitScale`.
  * @param {string} name
  * @param {Float32Array} positions
  * @param {Float32Array} tex_coords
  * @param {Float32Array} normals
  * @param {Uint32Array} indices
- * @param {boolean} convert_to_left_handed
+ * @param {MeshIoOptions | null} [options]
  * @returns {Uint8Array}
  */
-export function mesh_to_obj(name, positions, tex_coords, normals, indices, convert_to_left_handed) {
+export function mesh_to_obj(name, positions, tex_coords, normals, indices, options) {
     const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
     const ptr1 = passArrayF32ToWasm0(positions, wasm.__wbindgen_malloc);
@@ -202,7 +386,7 @@ export function mesh_to_obj(name, positions, tex_coords, normals, indices, conve
     const len3 = WASM_VECTOR_LEN;
     const ptr4 = passArray32ToWasm0(indices, wasm.__wbindgen_malloc);
     const len4 = WASM_VECTOR_LEN;
-    const ret = wasm.mesh_to_obj(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3, ptr4, len4, convert_to_left_handed);
+    const ret = wasm.mesh_to_obj(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3, ptr4, len4, isLikeNone(options) ? 0 : addToExternrefTable0(options));
     if (ret[3]) {
         throw takeFromExternrefTable0(ret[2]);
     }
@@ -218,27 +402,37 @@ export function mesh_to_obj(name, positions, tex_coords, normals, indices, conve
  * anything in between): n-gons are fan-triangulated and `(position, uv,
  * normal)` corners are deduplicated so the result is renderer-ready.
  *
- * `convert_to_left_handed` mirrors vpinball's `ObjLoader::Load` flag of
- * the same name (the "Convert coordinate system" checkbox in the
- * vpinball mesh-import dialog):
+ * `options.axes` names the convention the OBJ data is in; the returned
+ * mesh is always in vpx-internal convention:
  *
- * - `true` (matches `assemble`'s read path and vpinball's dialog
- *   default): the input is treated as right-handed (Blender / standard
- *   convention). Vertex Z is negated, normal Z is negated, V is flipped
- *   (`vpx_tv = 1 - obj_v`), and the per-triangle corner order is
- *   reversed. The returned mesh data ends up in vpx-internal,
- *   left-handed convention.
- * - `false`: the input is assumed to already be in vpx-internal
- *   convention (e.g. produced by a previous `mesh_to_obj` with the same
- *   flag). The transforms are skipped and values pass through verbatim.
+ * - [`AxisConvention::ZDownRightHanded`] (the default; matches
+ *   `assemble`'s read path and vpinball's mesh-import dialog with
+ *   "Convert coordinate system" checked, the old `convert_to_left_handed
+ *   = true`): vertex and normal Z are negated, V is flipped (`vpx_tv =
+ *   1 - obj_v`) and the per-triangle corner order is reversed. This path
+ *   also honors the `# vpx <hex>` byte-preservation comments, so
+ *   vpinball-format OBJs from `extract` reproduce the original vpx
+ *   values bit-for-bit.
+ * - [`AxisConvention::YUpRightHanded`] (Blender / DCC default export
+ *   settings): Y and Z are swapped, V is flipped and winding is
+ *   reversed.
+ * - [`AxisConvention::ZUpLeftHanded`] (the old `convert_to_left_handed
+ *   = false`): the input is assumed to already hold vpx-internal values
+ *   (e.g. produced by a previous `mesh_to_obj` with the same
+ *   convention). No transforms; values pass through verbatim.
+ *
+ * `options.unitScale` (default `1.0`) multiplies positions after the
+ * axis mapping. Normals and texture coordinates are never scaled. A
+ * mesh exported through `mesh_to_obj` with scale `k` reads back with
+ * scale `1.0 / k`.
  * @param {Uint8Array} data
- * @param {boolean} convert_to_left_handed
+ * @param {MeshIoOptions | null} [options]
  * @returns {PrimitiveMesh}
  */
-export function obj_to_mesh(data, convert_to_left_handed) {
+export function obj_to_mesh(data, options) {
     const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.obj_to_mesh(ptr0, len0, convert_to_left_handed);
+    const ret = wasm.obj_to_mesh(ptr0, len0, isLikeNone(options) ? 0 : addToExternrefTable0(options));
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -251,6 +445,22 @@ function __wbg_get_imports() {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return ret;
         },
+        __wbg_Number_3890faa6d3ff057d: function(arg0) {
+            const ret = Number(arg0);
+            return ret;
+        },
+        __wbg_String_8564e559799eccda: function(arg0, arg1) {
+            const ret = String(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_boolean_get_c9c83ebd41b34df3: 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) {
             const ret = debugString(arg1);
             const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -258,6 +468,33 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
+        __wbg___wbindgen_in_ac983077f137f2e6: function(arg0, arg1) {
+            const ret = arg0 in arg1;
+            return ret;
+        },
+        __wbg___wbindgen_is_null_7d13f41e1a2d5140: function(arg0) {
+            const ret = arg0 === null;
+            return ret;
+        },
+        __wbg___wbindgen_is_object_a2790eb24c211ea0: function(arg0) {
+            const val = arg0;
+            const ret = typeof(val) === 'object' && val !== null;
+            return ret;
+        },
+        __wbg___wbindgen_is_undefined_6cff064c44e0d823: function(arg0) {
+            const ret = arg0 === undefined;
+            return ret;
+        },
+        __wbg___wbindgen_jsval_loose_eq_acf2776254a8d832: function(arg0, arg1) {
+            const ret = arg0 == arg1;
+            return ret;
+        },
+        __wbg___wbindgen_number_get_136b9679cab35cfb: 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) {
             const obj = arg1;
             const ret = typeof(obj) === 'string' ? obj : undefined;
@@ -292,6 +529,34 @@ function __wbg_get_imports() {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
+        __wbg_get_with_ref_key_6412cf3094599694: function(arg0, arg1) {
+            const ret = arg0[arg1];
+            return ret;
+        },
+        __wbg_instanceof_ArrayBuffer_993d02d2d254cad1: function(arg0) {
+            let result;
+            try {
+                result = arg0 instanceof ArrayBuffer;
+            } catch (_) {
+                result = false;
+            }
+            const ret = result;
+            return ret;
+        },
+        __wbg_instanceof_Uint8Array_f935dbb0aa7cdeed: function(arg0) {
+            let result;
+            try {
+                result = arg0 instanceof Uint8Array;
+            } catch (_) {
+                result = false;
+            }
+            const ret = result;
+            return ret;
+        },
+        __wbg_isSafeInteger_f3d6cd19ccfe4512: function(arg0) {
+            const ret = Number.isSafeInteger(arg0);
+            return ret;
+        },
         __wbg_keys_ec7f8c0c2370d91d: function(arg0) {
             const ret = Object.keys(arg0);
             return ret;
@@ -308,6 +573,10 @@ function __wbg_get_imports() {
             const ret = new Error();
             return ret;
         },
+        __wbg_new_77cc4f4f472aeb81: function(arg0) {
+            const ret = new Uint8Array(arg0);
+            return ret;
+        },
         __wbg_new_ebe3e0f6837f0879: function() {
             const ret = new Object();
             return ret;

package/vpin_bg.wasm.d.ts

@@ -3,8 +3,11 @@
 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 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 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];
 export const primitivemesh_indices: (a: number) => any;