# 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
```
### 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
Extracts and assembles vpx files
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
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
romname Prints the PinMAME ROM name from a vpx file
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
```
### 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
```
## 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/.vpinball/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.
```toml
[[launch_templates]]
name = "Launch fullscreen"
executable = "/home/myuser/vpinball/VPinballX_BGFX"
arguments = ["-EnableTrueFullscreen"]
[[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"
```
## 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
```