KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

vpxtool

★ 53 Open GitHub ↗

Terminal based frontend and utilities for Visual Pinball

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# vpxtool

Cross-platform utility for the vpinball ecosystem

Join [#vpxtool on "Virtual Pinball Chat" discord](https://discord.gg/ugFR9tCf2p) for support and questions.

## Install

Download the latest release for your operating system at https://github.com/francisdb/vpxtool/releases, extract it and
if wanted copy or symlink the binary to `$HOME/bin` to put in on your path

### macOS

After extracting the archive you will have to remove the quarantine flag through
`System Settings / Privacy & Security / Allow Anyway button` or on the command line as shown below.

```
xattr -d com.apple.quarantine vpxtool
```

### Homebrew

@gitfool set up a homebrew tap for vpxtool. Installation instructions on his repo:

https://github.com/gitfool/homebrew-vpinball

### Using cargo

If you have [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) installed you can install
vpxtool with the following command:

```
cargo install vpxtool
```

## Usage

### Command Line Interface (CLI)

Show help

```shell
> vpxtool --help
```

```
Vpxtool v0.16.0

Terminal based frontend and utilities for Visual Pinball

Usage: vpxtool [COMMAND]

Commands:
  info            Vpx table info related commands
  diff            Prints out a diff between the vbs in the vpx and the sidecar vbs
  frontend        Text based frontend for launching vpx files
  simplefrontend  Simple text based frontend for launching vpx files
  index           Indexes a directory of vpx files
  capture         Capture a playfield screenshot using vpinball
  script          Vpx script code related commands
  ls              Show a vpx file content
  extract         Extracts a vpx file
  extractvbs      Extracts the vbs from a vpx file next to it
  importvbs       Imports the vbs next to it into a vpx file
  verify          Verify the structure of a vpx file
  assemble        Assembles a vpx file
  patch           Applies a VPURemix System patch to a table
  new             Creates a minimal empty new vpx file
  config          Vpxtool related config file
  images          Vpx image related commands
  gamedata        Vpx gamedata related commands
  nvram           PinMAME NVRAM related commands
  romname         Prints the PinMAME ROM name from a vpx file
  export          Export a vpx table to obj/gltf/glb or to a vpxz mobile archive
  help            Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
```

Show help for a specific command

```shell
> vpxtool frontend --help`
Acts as a frontend for launching vpx files

Usage: vpxtool frontend [OPTIONS] [VPXROOTPATH]

Arguments:
  [VPXROOTPATH]  The path to the root directory of vpx files [default: /Users/myuser/vpinball/tables]

Options:
  -r, --recursive  Recursively index subdirectories
  -h, --help       Print help
```

### Logging

To get more information about what vpxtool is doing, you can set the `-v` flag to increase verbosity.

```shell
vpxtool -v extract test.vpx
```

You can also set the log level using the RUST_LOG environment variable. For example to get debug output:

```shell
RUST_LOG=debug vpxtool extract test.vpx
```

### High scores

Show the high-score entries stored for a table:

```shell
vpxtool scores show /path/to/table.vpx
```

Works with PinMAME tables (resolved through pinmame-nvram maps) as well as rom-less tables backed by `VPReg.ini`, GLF `<cGameName>_glf.ini` sidecars, or Black's-style `user/*.txt` EM hiscore files. Use `--format tsv` for scripting or `--format pinemhi` for a PINemHi-like layout.

### Text UI Frontend

Vpxtool can act as a frontend for launching vpx files. It will index a directory of vpx files and then present a menu to
launch them.

```
> vpxtool frontend
```

![Frontend](https://raw.githubusercontent.com/francisdb/vpxtool/main/docs/frontend.png)

## Configuration

A configuration file will be written to store among others the Visual Pinball executable location. The config file is
using the [TOML](https://toml.io) format.

When launching the frontend for the first time, it will help you to set up the required settings.

The config file is stored in the default config location for your operating system:

* Linux: `$XDG_CONFIG_HOME/vpxtool/vpxtool.cfg` or `$HOME/.config/vpxtool/vpxtool.cfg`
* macOS: `$HOME/Library/Application Support/vpxtool/vpxtool.cfg`
* Windows: `C:\Users\<user>\AppData\Roaming\vpxtool\vpxtool.cfg`

To show the current config location, use the following command:

```
vpxtool config path
```

To edit the config file using your system default editor, do the following:

```
vpxtool config edit
```

### Configuring vpinball paths

```toml
vpx_executable = "/home/myuser/vpinball/VPinballX_BGFX"

# Optional settings below, only needed if the defaults don't work
tables_folder = "/home/myuser/vpinball/tables"
vpx_config = "/home/myuser/.local/share/VPinballX/10.8/VPinballX.ini"
```

Further settings will be picked up from the Visual Pinball config.

### Launch templates

Sometimes you want to use a different executables, extra arguments or environment variables. This can be done
by setting up launch templates. Each entry will show up on top of the frontend table menu.

To force fullscreen or windowed mode, point a template at a separate vpinball ini file (passed to vpinball as
`-Ini <path>`) with the relevant `FullScreen` / `PlayfieldFullScreen` keys overridden. The previous
`-EnableTrueFullscreen` / `-DisableTrueFullscreen` CLI flags are deprecated upstream and not present in
modern (BGFX) vpinball builds.

```toml
[[launch_templates]]
name = "Launch fullscreen"
executable = "/home/myuser/vpinball/VPinballX_BGFX"
vpinball_config = "/home/myuser/.local/share/VPinballX/10.8/VPinballX.fullscreen.ini"

[[launch_templates]]
name = "Launch GL"
executable = "/home/myuser/vpinball/VPinballX_GL"
[launch_templates.env]
SDL_VIDEODRIVER = "X11"
```

### Configuring a custom diff

When actions are invoked that run diff, the default diff configured for your system will be used. In case you
want to override this with a specific diff, optionally specifying the path, you can add the following line to the config file:

```toml
# use mydiff as default diff
diff = "/path/to/mydiff"
```

### Configuring a custom editor

When actions are invoked that open an editor, the default editor configured for your system will be used. In case you
want to override this with a specific editor, optionally specifying the path, you can add the following line to the config file:

```toml
# use Visual Studio Code as default editor
editor = "code"
```

### Excluding files from `export vpxz`

`vpxtool export vpxz` bundles the chosen vpx and its parent-folder contents into a `.vpxz` archive for the Visual Pinball mobile app. A few classes of files are dropped automatically:

* other `.vpx` files in the tree (the mobile importer rejects archives with more than one vpx) and their stem-keyed sidecars,
* `.directb2s` files whose stem doesn't match the chosen vpx,
* previously generated `.vpxz` archives.

Anything else is included by default. To skip additional patterns, set `vpxz_excludes` in the config file. Patterns are gitignore-ish globs matched against paths relative to the vpx's parent folder; a trailing `/` matches the directory both at the top level and nested anywhere:

```toml
vpxz_excludes = [
    "Downloads/",          # the table author's original archive / install docs
    "downloads/",
    "cache/",              # VPX runtime cache, regenerated on the device
    "**/Thumbs.db",        # Windows folder thumbnails
    "**/.DS_Store",        # macOS folder metadata
    "**/*.bak",            # editor / VPX backups
    "**/*~",               # Emacs-style backups

# Add your own. Examples:
    # "user/",             # also drop desktop save state (high scores, options)
    # "**/*.pov",          # camera POV files (desktop only)
    # "**/*.res",          # legacy B2S Server resolution files (desktop only)
]
```

The list above is the built-in default; if you don't set `vpxz_excludes`, that's what gets applied. Setting it replaces the default in full, so copy the entries you still want.

## Projects using vpxtool

* https://github.com/jsm174/vpx-editor
* https://github.com/syd711/vpin-studio
* https://github.com/jsm174/docker-vpxtool-resize
* https://github.com/mpcarr/aztec-quest
* https://github.com/francisdb/vpinball-example-table-extracted
* https://github.com/surtarso/vpx-gui-tools

## References / Research

Other related projects that read and/or assemble vpx files:

* https://github.com/vpinball/vpinball
* https://github.com/vpdb/vpx-js
* https://github.com/freezy/VisualPinball.Engine
* https://github.com/stojy/ClrVpin
* https://github.com/vbousquet/vpx_lightmapper

An example vpx managed in github with some imagemagick scripts to compose textures

https://github.com/vbousquet/flexdmd/tree/master/FlexDemo

## Building

The project uses the default [rust](https://www.rust-lang.org/) build tool `cargo`. To get going read the docs on
installation and first steps at https://doc.rust-lang.org/cargo/

Some dependencies require extra dependencies. Make sure you install developer tools:

* Fedora: `sudo dnf install @development-tools`
* Ubuntu: `sudo apt install build-essential`

```

cargo build --release

```

vpxtool

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README