vpinball-wasm/package/src/types.ts

/**
 * Public TypeScript surface for vpinball-wasm.
 *
 * This wraps the raw Emscripten-generated module (dist/vpinball.js) so
 * consumers don't need to know about ccall/cwrap/FS internals directly.
 */

export interface LoadPinballOptions {
	/** Canvas the engine renders into via SDL3's WebGL2 backend. */
	canvas: HTMLCanvasElement;
	/**
	 * Raw bytes of a self-contained .vpx table file to play instead of the
	 * bundled default table. Real-world tables that reference an external
	 * .vbs script override or a Music/ folder are not supported this way -
	 * see the README's "Browser file-loading UX" section.
	 */
	tableData?: ArrayBuffer;
	/** Base URL to fetch dist/vpinball.wasm/.data (and vpinball.js) from. */
	baseUrl?: string;
	/**
	 * Called as the wasm binary and preloaded asset package download,
	 * with a 0-1 fraction of bytes received. Not called at all if the
	 * browser doesn't support streaming fetch progress (falls back to
	 * Emscripten's own default loading behavior with no progress callback).
	 */
	onProgress?: (fraction: number) => void;
}

export interface PinballInstance {
	/**
	 * Stage a different self-contained .vpx table to play on the *next*
	 * start() call. Does not affect an already-running session - table
	 * switching mid-session isn't supported; call stop() first (a fresh
	 * loadPinball() call is the supported way to load a genuinely new
	 * session with a different table).
	 */
	loadTable(vpxBytes: ArrayBuffer): void;
	/**
	 * Makes a ROM zip available to PinMAME (VPinMAME.Controller) for a
	 * ROM-based ("SS"/real-hardware) table's Controller.Run() call - written
	 * to /tables/pinmame/roms/<gameName>.zip, the table-relative convention
	 * PinMAME's plugin already looks for before any global settings path.
	 * gameName is the short ROM/game name the table's own script passes to
	 * LoadVPM (e.g. "hvymetal"), not the table's display title. Must be
	 * called before start() (or loadTable(), if switching tables) since
	 * Controller.Run() reads the filesystem synchronously at table-init
	 * time. ROM files are copyrighted - only supply ones you're legally
	 * entitled to use.
	 */
	loadRom(gameName: string, romZipBytes: ArrayBuffer): void;
	/** Start the simulation's main loop. No-op if already running. */
	start(): void;
	/** Stop the simulation; the engine tears down (script Exit event, settings save) on its next step. */
	stop(): void;
	/** Tear down the instance immediately and free its WebAssembly memory. */
	dispose(): void;
	/**
	 * Request fullscreen on the canvas via the standard Fullscreen API.
	 * Must be called from within a user gesture (e.g. a click handler) -
	 * browsers reject fullscreen requests otherwise. Returns the promise
	 * from the underlying requestFullscreen() call.
	 */
	requestFullscreen(): Promise<void>;
	/**
	 * Runs arbitrary VBScript against the running table's script interpreter
	 * (the same entry point the interpreter's own debug console uses).
	 * Returns false if no table is currently running. Intended for debugging
	 * and for exercising script-driven engine APIs (e.g. the DMD pixel API)
	 * from JS - not sandboxed, so only run scripts you trust.
	 */
	evalScript(script: string): boolean;
}