Importing Visual Pinball Archives - syd711/vpin-studio GitHub Wiki

Please contact me on my discord if you find issues here or miss something.

Motivation

This article gives a recommendation for table authors on how to name and structure VPin assets in archives so that the VPin Studio is able to analyze and extract all of assets into the desired target directory.

Note that the VPin Studio importer supports the following formats:

  • .rar files
  • .zip files
  • .7z files

Assets Types and Matching

Below you find a list of all table assets that are supported by the VPin Studio and a corresponding documentation where to put and how to name the files when you want to create a bundle from it.

.vpx, .fpt, .directb2s, .ini Files

These are the "basic" files you need for a visual pinball table. It is recommended that all of the have the same base name. Even if the Studio importer will adjust the names, it is a good practice to align the filenames so that they can be used for a manual import too.

Put these files into the root folder of the archive.

DMDs (FlexDMD, UltraDMD, ...)

A lot of tables bring their own DMD media. It is recommended to put these assets into separate folder that is not only named "DMD" but also has a prefix of the DMD type of indicates the table name for the DMD, e.g. SpongebobDMD. This is of course something the table author needs to take care of.

DMD folders should be put into the root folder of an archive. This way, mix-ups with other DMD assets can be avoided.

PUP Packs

To identify a PUP pack inside an archive, one of the following rules must apply:

  • The pup pack folder contains a file screens.pup.
  • The pup pack folder contains a file EditThisPuPPack.bat.
  • The pup pack folder contains a file [...]option[...].bat.
  • The pup pack folder contains a file [...]screen[...].bat.
  • The pup pack folder contains a file scriptonly.text.

In additional to the file structure, it is a well known practice to provide different Option_[...].bat files which generate the corresonding config files, depending on the screen setup. Please use this naming pattern so that Studio can identify thse options.

Music Files

Music files are easy to identify, but they can belong to ALT sound bundles or PUP packs too. The following rules are applied to identify music for the VPX emulator:

  • The files must have the suffix mp3, ogg or wav.
  • The files must not be below a directly that is identified as PUP pack (see PUP packs).

Note that music files are extracted directly into the Music folder of VPX. No subfolder are created or resolved for this.

ALT Sound

ALT sound bundles are usually a large collection of.ogg files, inclusing a CSV files which contains the description of how to use them. Based on this information, ALT sound bundles can be detected easily inside an archive. The folder (named by the matching ROM) can just be put onto the root level of an archive.

A folder is identified as ALT sound bundle if one of the following rules is applied:

  • The folder contains the file g-sound.csv.
  • The folder contains the file altsound.csv.

ALT Color

ALT color files have the advantage that all the files have unique suffix (.vni, .pal, .pac, .cRZ), so the location inside the archive doesn't really matter.

ROMs

ROM are themselves again zip files. So by default every .zip file inside a bundle is seens as ROM. As a result of never put a zip file other than ROMs into a bundle.

nvram Files

Since .nv files have a unique file suffix, the location inside an archive doesn't matter. The filename itself must match the games ROM of course.

Frontend Media Files

Frontend files can be different media files that will be extracted into different screen folders of the frontend (e.g. Popper or PinballX/Y). The rules for frontend media are a bit more complex, so we start with.

Rules used to deny(!) files for frontend screens:

  • Files with the keyword screenshot in the path or filename are ignored.
  • Files that contains the path segment DMD/ are ignored for the DMD or Full DMD screens.
  • Files below the optional PUP pack folder are ignored (obviously).

Rules used to accept(!) files for the frontend screens:

  • Files must have the one of the suffixes: mp3, png, apng, jpg, mp4
  • The filename must match with the target screen. In addition to this rule, the following keywords are resolved.
    • Files with the keywords rule, card or help will be copied to the "GameHelp" screen.
    • Files with the keywords flyer will be copied to the "GameInfo" screen.
    • Files with the keywords apron or fulldmd will be copied to the "Apron" screen.

Screenshots

Although not used by the Studio, it is a good practice to add screenshots of the table as part of the table archive. It is recommended to put the screenshots into a separate screenshots folder or to add the phrase screenshot to the filename.

For table authors: The Studio supports showing table screenshots that are part of the VPX file. So you might consider this as an alternative:

https://github.com/syd711/vpin-studio/wiki/Troubleshooting#how-can-i-select-a-screenshot-in-vpx

README Files

The Studio importer will search for files called README or read me. The lookup is case insensitive. The text content of this file will be shown in the importer dialog. This way additional installation details can be shown to the user during the import.

Patch Files

Patch files (.dif) are ignored for bundles, but are detected by the importer no matter if zipped or not. As a result, the patch dialog will be opened instead of the regular importer dialog.

Examples

This section gives examples of table archives and pros and cons on their internal structure.

Swamp Thing - Original (2024)

The download of the table is a good example on how to structure an archive, because:

  • All table files are located in the root folder and their naming matches. :white_check_mark:
  • All media files contain the name of the target screen. :white_check_mark:
  • The .mp3 audio file contains the keyword "music" which indicates to put the file into the Music folder of VPX. :white_check_mark:
  • The README.txt will be detected by the Studio importer and the text will be shown to the user. :white_check_mark:

Note that the name of the "media" folder ignored here and the importer will solely look at that filename to determine the target.

β”œβ”€β”€ README.txt
β”œβ”€β”€ Swamp Thing 2.1.1 (LTek 2024)_Screenshot.jpg
β”œβ”€β”€ Swamp Thing 2.1.1 Bayou Edition (LTek 2024).directb2s
β”œβ”€β”€ Swamp Thing 2.1.1 Bayou Edition (LTek 2024).ini
β”œβ”€β”€ Swamp Thing 2.1.1 Bayou Edition (LTek 2024).vpx
└── media
    β”œβ”€β”€ Swamp Thing FullDMD.mp4
    β”œβ”€β”€ Swamp Thing_FullDMD_vPinStudio.mp4
    β”œβ”€β”€ Swamp Thing_FullDMD_video.mp4
    β”œβ”€β”€ Swamp Thing_backglass.mp4
    β”œβ”€β”€ Swamp Thing_music.mp3
    └── Swamp Thing_wheel.png

SpongeBob's Bikini Bottom Pinball - Original (2021)

The table comes with a DMD.

  • The DMD has a named prefix (Spongebob) and ends with an upper case DMD suffix. :white_check_mark:
  • The user can select from one of the available backglass files during the import. :white_check_mark:
β”œβ”€β”€ SpongeBob Backglasses
β”‚   β”œβ”€β”€ Alternate_1
β”‚   β”‚   └── SpongeBob's - Bikini Bottom Pinball.directb2s
β”‚   β”œβ”€β”€ Alternate_2
β”‚   β”‚   └── SpongeBob's - Bikini Bottom Pinball.directb2s
β”‚   β”œβ”€β”€ Backglass_Versions.jpg
β”‚   └── Original_VPW
β”‚       └── SpongeBob's - Bikini Bottom Pinball.directb2s
β”œβ”€β”€ SpongeBob's Bikini Bottom Pinball VPW 2.1.vpx
└── SpongebobDMD
    β”œβ”€β”€ 500k1.png
    β”œβ”€β”€ 500k2.png
    β”œβ”€β”€ 500k3.png
    ...

Hellboy Pinball - Original (2024)

  • All table files are located in the root folder and their naming matches. :white_check_mark:
  • All media files contain the name of the target screen. :white_check_mark:
  • The user can select from one of the available backglass files during the import. :white_check_mark:
  • The user can select from one of the available wheel images during the import. :white_check_mark:
  • The HELLBOY.gif files gives no additional information where to put it and will be ignored. :x:
  • The Scorebit folder will be ignored.
β”œβ”€β”€ HELLBOYv1.0.directb2s
β”œβ”€β”€ HELLBOYv1.0.ini
β”œβ”€β”€ Hellboy Media Pack
β”‚   β”œβ”€β”€ DirectB2s 3options
β”‚   β”‚   β”œβ”€β”€ HELLBOY alt1.directb2s
β”‚   β”‚   β”œβ”€β”€ HELLBOY.directb2s
β”‚   β”‚   └── HELLBOYalt.directb2s
β”‚   β”œβ”€β”€ HELLBOY.gif
β”‚   β”œβ”€β”€ HELLBOYRULES.png
β”‚   β”œβ”€β”€ HELLBOY_RULECARD.png
β”‚   β”œβ”€β”€ HellboyAudioFrontend.mp3
β”‚   β”œβ”€β”€ HellboyBackglass.mp4
β”‚   β”œβ”€β”€ HellboyLoading.mp4
β”‚   β”œβ”€β”€ Hellboy_FULLDMD.mp4
β”‚   β”œβ”€β”€ Hellboy_Wheel.png
β”‚   β”œβ”€β”€ Hellboy_Wheel1.png
β”‚   β”œβ”€β”€ Hellboy_Wheel2.png
β”‚   └── Hellboy_Wheel3.png
└── Scorbit
    β”œβ”€β”€ Scorbit SDK Install.docx
    └── ScorbitSDK_2_0.zip

Cyclone - (Williams 1988)

  • All table files are located in the root folder and their naming matches. :white_check_mark:
  • The zip file on the root folder is seen as ROM file, but contains the .ini file. The additional zipping here is superflous. :x:
β”œβ”€β”€ Cyclone (Williams 1988) v.2.2.vpx
└── Cyclone (Williams 1988) v.2.2.zip

Futurama Media Pack - (Original 2024)

  • The PUP pack is inside a separate subfolder which contains the game name "futurama". :white_check_mark:
  • The PUP pack options are named properly with a leading "Option" prefix, so they can be detected by the Studio. :white_check_mark:
  • The DMD has a named prefix (Futurama) and ends with an upper case DMD suffix. :white_check_mark:
  • All media files are in a properly named screen folder AND have the screen name as part of the filename. :white_check_mark:

Only folders are shown in the tree below!

β”œβ”€β”€β”€Animated wheel
β”œβ”€β”€β”€Credits
β”œβ”€β”€β”€Flyer
β”œβ”€β”€β”€Futurama.flexDMD
β”œβ”€β”€β”€Instructions
β”œβ”€β”€β”€Playfield Loading Videos
β”œβ”€β”€β”€puppack
β”‚   └───futurama
β”‚       β”œβ”€β”€β”€AmazoniaProgress
β”‚       β”œβ”€β”€β”€Backglass
β”‚       β”œβ”€β”€β”€...
β”‚       β”œβ”€β”€β”€PuP-Pack_Options
β”‚       β”‚   β”œβ”€β”€β”€Option 1 - Backglass DMD Separate
β”‚       β”‚   β”œβ”€β”€β”€Option 2 - FullDMD on Backglass
β”‚       β”‚   └───Option 3 - Single Screen - Desktop - VR
β”œβ”€β”€β”€Topper
└───Wheel