Optimizations for iOS, iPad, and Android

VPinball was written with PC Desktops and real Pinball Cabinets in mind. It is only recently with the advent of VPX Standalone that it became possible to run VPinball on a mobile phone or tablet. They can run VPinball surprisingly well on higher end devices, but they can look and run better when properly optimized. There are three things you can do here:

• DMD Display Tweaking
• Image Resizing
• Fix Leftover Image Artifacts

[!NOTE] This page assumes you have the basics down: how to load a table onto your device, how to deal with the ROMs required by some tables, etc. If you are having problems with that type of thing, you're better off on this page. Those instructions are for iOS but Android is similar. Android-specific instructions will materialize at some point down the road.

Table Packaging and DMD Display Tweaking

The limited screen real estate on phones and tablets often requires tweaks to the Point of View and DMD Settings for the table to look its best. There are five scenarios we'll cover here that should cover how to tweak most of the tables out there.

• Scenario 1: Good To Go
• Scenario 2: Using Predefined Optimized Setups
• Scenario 3: Generating Your Own Optimized Settings
• Intermission: DMD Types and Parameter Adjustments
• Scenario 4: Tweaking Original Tables That Use FlexDMD
• Scenario 5: Using FlexDMD as an UltraDMD Replacement

Along the way, you might find that a table needs to be patched to function at all on the Standalone version of Visual Pinball upon which the phone and tablet versions are based. You might alway want to play around with alternate DMD colorings or sound packages. All that and more will be covered in the three scenarios that follow. Given them all a read to learn all of the tips and tricks.

Scenario 1: Good To Go

Some tables will display their DMD on iOS, iPad or Android more or less "out of the box". Most of the time, these are tables that support a VR or FSS mode. Total Nuclear Annihilation (Spooky 2017) VPW (TNA) is a good example of this. Import the table into Visual Pinball as described here and you're ready to play.

Click here to see it in action!

Just because a table has VR or FSS mode doesn't necessarily mean it will run out of the box. It might need a VBScript patch because of bugs in Wine. It might also need ROM files if the table is based on a real machine. TNA is an original table (meaning it was created from scratch) so it doesn't need ROMs. A table like Harley Davidson does have a VR mode but it also needs ROMs to run, given that it is a recreation of a real table.

The next scenario discusses how to deal with ROM-based tables as part of the process for optimizing the display for phones and tablets.

Scenario 2: Using Predefined Optimized Setups

In this scenario, community members have already done the work of optimizing the table for smaller devices. One primary source is the VP L3SP4UL Settings Page, a collection of settings for over 200 tables. They were generated on an iPhone 15 Pro Max so the table's graphics are perfectly adapted for its display, but they also work on other iPhone/iPad models and Android devices as well. Another source is work done by @gerhard_b and @Fas0 in the #vpx-standalone-mobile channel on Discord.

[!NOTE] The L3SP4UL settings are based on a device featuring a very high resolution display. Additional tweaks like those described in Scenario 3 might be needed for a table to look its best on your particular device.

Lets work through an example for "The Addams Family (Bally 1992)_Bigus(MOD) 2.1" done by L3SP4UL (it assumes the user is on iOS but Android would be similar). From L3SP4UL's site:

• tap on the Hamburger menu in the top left of the window
• tap on the A-B link to display those tables in that alphabetical range

Each table has a picture with an underlined text link below it. The Addams Family table we're interested in is shown outlined in red in the image above. Each entry consists of 2 different links.

• Tapping the underlined text link (shown within the blue box in the image above) will open a new browser tab that takes you to the primary download source for that table. For our example, that is this link on VPForums. Download this file.
• Tapping the image (shown within the green box in the image above) will open another new browser tab that takes you to the optimized settings for that table. For our example, that is this Google Drive link. You'll see a window like that show below displaying a number of files, but these are the contents of a single .zip file The Addams Family (Bally 1992)_Bigus(MOD)2.1.zip that you can get by clicking the icon at the top of the window. Download this file as well.

Now we have two zip files. How do we put them together? First off...

• Extract The Addams Family (Bally 1992)_Bigus(MOD)2.1.vpx.zip into an empty folder of your choice to get a .vpx table that holds all of the table's artwork & sounds, as well as the original VBScript .vbs file that contains the game logic within a single file.
• Extract The Addams Family (Bally 1992)_Bigus(MOD)2.1.zip into the same folder as above to get a patched .vbs file and a .ini file. The .ini file holds the "Point Of View" (PoV) data that optimizes the display of the table for small form-factor devices like phones and tablets.

This Addam's Family table is a recreation of a real one and so requires the original table's ROM files to run properly. Which ROM is needed can be figured out in a couple of ways. The first way is by searching the .vbs file for the text cgamename. If doing so, we'll find Const cGameName = "TAF_L7" as shown below.

...
Dim DayNight

'table init
Const cGameName = "TAF_L7"

Sub Table1_Init()
...

The second way is by importing the table into VPinball and running it. The table will either fail to load or freeze up. You can then view the vpinball.log in Settings to get detailed error information. This will contain the name of the ROM it was looking for and failed to find. Again, the name of that ROM would be TAF_L7 for our example.

So TAF_L7 is the needed ROM. ROMs are protected by copyright and generally aren't distributed with the tables themselves so you'll have to search them out. Google will help you to find what you need. Good places to look include archive.org, VPUniverse.com, VPForums.org, and PinballNirvana.com. The last three of these four sites will require you to set up a free account before you can download anything.

Now we have a ROM .zip file, a .vpx table file, and a .vbs script file. What we also need for any ROM-based table are a couple of empty folders.

[!IMPORTANT]

• Folder names are case sensitive.
• ROMs are generally available in .zip format. Never unzip the ROM files. VPinball expects them to be in .zip format and won't find them otherwise.
• Visual Pinbal expects ROM names to be in lower case. So even if the code expects a ROM file name of TAF_L7, it should be saved to your system as taf_l7.zip.

• Create an empty pinmame folder within the folder that you extracted the .zip files downloaded earlier
• Open the pinmame folder and create one folder named roms and another named nvram
• Copy the ROM taf_l7.zip into pinmame/roms

When you are done, your directory and its contents should look like this

pinmame
  nvram
  roms
    taf_l7.zip
The Addams Family (Bally 1992)_Bigus(MOD)2.1.ini
The Addams Family (Bally 1992)_Bigus(MOD)2.1.vbs
The Addams Family (Bally 1992)_Bigus(MOD)2.1.vpx

[!NOTE] Notice how the .ini, .vbs, and .vpx files above all have the otherwise identical filename, including case and special characters? This is how VPinball associates different files for the same table and so it is critical that this convention be followed exactly.

[!TIP] Some tables support alternate colored DMD displays and alternate sounds. If you might be interested in trying those out at some point, create two additional directories named altcolor and altsound inside the pinmame directory.

Now those files and directories need to be combined into a single file suitable for transferring to your phone or tablet as described here. When the table is run on your phone or tablet, the patched .vbs file will take priority over the one stored within the .vpx file downloaded from VPForums. In addition, the settings in the .ini file will be picked up to optimize the view settings for the device. The end result should look like this.

Senario 3: Generating Your Own Optimized Settings

In this scenario, you'll be extracting the Visual Basic .vbs script that controls how the table looks, sounds, and plays from the rest of its audio and video assets packed into the the .vpx file. It will also cover how to install a colorized version of the DMD graphics. This section assumes you have read over the prior one so it will be a bit less detailed than before.

[!IMPORTANT] Visual Pinball Standalone upon which the mobile and tablet versions of Visual Pinball are based only supports the open-source "Serum" DMD colorization format. All other formats are closed source and unsupported. Serum formats can be distinguished from the others by its .cRZ filename extension.

[!WARNING] There are many different tables out there written over many years by many different authors. This is a generalized workflow that should work for many tables but there are always exceptions. If you have followed these instructions but can't get things to work, feel free to jump in to the #vpx-standalone-mobile channel on Discord to ask for help. If getting Script-Errors or other Errors, you might check if there are already Script-Patches available -> JSM174 Standalone Script-Patches If using JSM174's Scripts, there is no need to extract the VBS-File. Use the downloaded File as base for the described Modifications. But keeping Mind, don't mix Scripts and VPX-File. These Scripts only work with the same VPX-File where they where extracted.

This scenario will use "24 (Stern 2009)_Bigus(MOD) 2.0" as its example.

• Download the table from this link on VPForums
• Create an empty folder in your file manager and extract the zipped 24 (Stern 2009)_Bigus(MOD)2.0.vpx file into it
• Download the required ROM. For this table, you'll need a ROM named twenty4_150.zip. Figuring out the name of the required ROM and why it isn't directly linked here was explained in the previous scenario). As before, you'll need to track the ROM down on your own. Do not unzip this file.
• Download the Serum colorization for this table from VPUniverse. It should be named twenty4_150.cRZ. Like the .vpx file and unlike the ROM .zip file, Serum colorizations are works of the community and may be freely distributed.
• Create the pinmame folder with altcolor, nvram, and roms subfolders as described in Scenario 2 within the same directory you saved the .vpx file to
• Altcolor support requires that any .cRZ file be stored in its own directory of the same name within the altcolor directory. So for an alcolor file named twenty4_150.cRZ, create a directory twenty4_150 within the pinmame/altcolor directory: pinmame/altcolor/twenty4_150
• Save the .cRZ and .zip files to their respective subdirectories. You should now have something that looks like this:

pinmame
  altcolor
    twenty4_150
      twenty4_150.cRZ
  nvram
  roms
    twenty4_150.zip
24 (Stern 2009)_Bigus(MOD)2.0.vpx

Now it is time to get these files on your device.

• Select all files and folders inside the folder you initially created and compress it to a 24 (Stern 2009)_Bigus(MOD) 2.0.zip file
• Change the extension of this file from .zip to .vpxz so that Visual Pinball can automatically recognize it when you transfer it to your device. You should now have a file named 24 (Stern 2009)_Bigus(MOD) 2.0.vpxz
• Start Visual Pinball, tap (+) and install the just generated .vpxz file
• Load the table and verify that it runs. Exit back into the Visual Pinball main screen after playing a bit.
• Do a long press on the "24" table that was just installed. A menu will pop up from which you'll select "Extract Script". Note that if the script has already been extracted, this option will instead read "View Script".

These next steps are where it gets interesting. The extracted .vbs script will be modified to optimize the display of the DMD.

• If you are on an iPhone or iPad...
  • Open the Files App and choose "Sort By Date".
  • Open the first UUID-coded folder (every table gets imported as a UUID to allow multiple installs of the same title)
• If you are on Android...
  • The folders in which the tables are stored are not directly accessible on the device. You will need to access the .vbs file in the table you just uploaded via the web server built into the the Visual Pinball app. It is enabled withing Settings and by default is not enabled.

The following applies for either Apple or Android devices

• Rename the .vbs script to .txt so you can edit it as a text file. You can skip the renaming of the script if you use a text editor that can open files other than .txt directly.
• Open the script in your text editor of choice
• Search the script for a line starting with LoadVPM.
• If you want altcolor support, as we do in this example, then determine if the table script already has support for colored DMD's. Add this line of code if something like it doesn't already exist, putting it before the line starting with LoadVPM.

Dim UseVPMColoredDMD : UseVPMColoredDMD = True

• Immediately following that code, add this snippet to the script file (floating DMD).

Sub ImplicitDMD2_Init
   Me.x = 480         'X-Position of the DMD in pixels
   Me.y = 2150        'Y-Position of the DMD in pixels
   Me.height = 200    'Height of the DMD above the playfield in pixels
   Me.rotX = 0        'X-axis rotation of the DMD in degrees
   Me.rotY = 0        'Y-axis rotation of the DMD in degrees
   Me.rotZ = 0        'Z-axis rotation of the DMD in degrees
   Me.color = RGB(255, 255, 255)   'Color of the DMD, if supported
   Me.intensityScale = 1.5
   Me.visible = true
End Sub 

[!TIP] The text after the ticks in the code above are interpreted as comments by the VBScript interpreter. Use those comments as a guide to tweaking the values to get the DMD in the best position for your display. This will take a bit of experimentation to find the values that look best to you.

[!TIP] Even though Apple users can make these script edits directly on their device, it might be easier to transfer the file to a desktop machine, make the edits, and transfer them back. The same methods that work for transferring the .vpxz file described in Importing Tables will also work for the back and forth transfer of the .vbs file.

• Save the changes you made to the script.
• If you had to change the extension from .vbs to .txt to open it in your editor, change it back to the original .vbs.
• Open the table in Visual Pinball once again. This time you should be able to enjoy playing "24" with a well positioned, colorized DMD display.

Intermission: DMD Types and Parameter Adjustments

There are two DMD types supported by the DMD used in VPinball Standalone: Fixed DMDs and Floating DMDs.

A Fixed DMD has the same alignment and level as the table. With the Me.x and Me.y parameters shown in the snippet below, the position of the DMD relative to the top left edge of the screen can be defined. With Me.width and Me.height, the size of the DMD itself can be defined:

Sub ImplicitDMD_Init
   Me.x = 10
   Me.y = 670
   Me.width = 999
   Me.height = 64
   Me.fontColor = RGB(255, 0, 0)
   Me.visible = true
   Me.intensityScale = 1.5
End Sub

A Floating DMD is "floating" above the table. The size of the DMD itself is "fixed" so there are no Me.width parameter in its initialization subroutine shown in the example snippet below. It does have Me.height, but here that parameter is used to make the DMD appear larger or smaller by adjusting the distance between the DMD and the eye: the higher the DMD above the playfield, the shorter the distance to the eye and the larger the DMD appears.

Sub ImplicitDMD2_Init
   Me.x = 480
   Me.y = 2120
   Me.height = 400
   Me.rotX = 0
   Me.rotY = 0
   Me.rotZ = 0
   Me.color = RGB(255, 0, 0)
   Me.intensityScale = 1.5
   Me.visible = true
End Sub 

Here are some examples that show the effect of changing the size and rotation parameters within the Floating DMD initialization routine.

Floating DMD with Me.rotX = 0, Me.rotY = 0 and Me.rotZ = 0

---

Floating DMD with Me.rotX = -45, Me.rotY = 0 and Me.rotZ = 0. Note that the DMD appears to have depth and gets smaller as it tilts downward toward the playfield.

---

Floating DMD with Me.rotX = 0, Me.rotY = -45 and Me.rotZ = 0

---

Floating DMD with Me.rotX = 0, Me.rotY = 0 and Me.rotZ = -45

---

Floating DMD with Me.height = 500. The height of the DMD above the playfield makes it appear much larger.

---

Floating DMD with Me.height = 50. The DMD is now much closer to the playfield, making it appear much smaller.

Scenario 4: Tweaking Original Tables That Use FlexDMD

This scenario shows how a FlexDMD-based table can be tweaked to adjust the type, position, and size of the DMD. We'll be using "SOTN (Mephisto MOD)" for this example.

• First off, download the table from VPUniverse
• Next you want to set yourself up to edit the .vbs table script. We went over loading the table on your device, extracting the .vbs file, and loading the script into an editor in detail in Scenario 3 and won't repeat those instructions here.
• Once you have the .vbs file loaded into an editor, search through the script for a piece of code that looks like this:

Option Explict
Randomize

[!TIP] Generally speaking, Visual Basic is not case sensitive when it comes to keywords or variable names, so Dim FlexDMD, UseFlexDMD and DIM FLEXDMD, USEFLEXDMD are equivalent. One of the few exceptions is path & file names. That has already come up in earlier discussion on this page.

• Paste in the following code snippet after the two lines above. It enables both a "floating" and a "fixed" FlexDMD. Only one of these is needed, and it is up to you to decide what works and looks the best. The DMD that is not needed should be disabled by setting Me.visible = false within the respective DMD's subroutine.

Dim FlexDMD, UseFlexDMD
Sub ImplicitDMD_Init  ' This code for setting up Fixed FlexDMDs
   Me.x = 200          ' X-Position
   Me.y = 689          ' Y-Position
   Me.width = 600      ' DMD Width
   Me.height = 50      ' DMD Height
   Me.fontColor = RGB(255, 255, 255)
   Me.visible = true   ' Set this to false to disable this Fixed FlexDMD
   Me.intensityScale = 1.5 
   Me.timerenabled = true
End Sub

Sub ImplicitDMD2_Init  ' This code is for setting up Floating FlexDMDs
   Me.x = 476          ' X-Position
   Me.y = 50           ' Y-Position
   Me.height = 300     ' Height above the Playfield
   Me.rotX = -90       ' X-Axis Rotation
   Me.rotY = 0         ' Y-Axis Rotation
   Me.rotZ = 0         ' Z-Axis Rotation
   Me.color = RGB(255, 255, 255) ' If using full color, 255 for RGB is needed
   Me.intensityScale = 1.5
   Me.visible = true   ' Set this to false to disable this Floating FlexDMD
End Sub

Sub ImplicitDMD_Timer
   Dim DMDp: DMDp = FlexDMD.DMDColoredPixels
   If Not IsEmpty(DMDp) Then
      DMDWidth = FlexDMD.Width
      DMDHeight = FlexDMD.Height
      DMDColoredPixels = DMDp
   End If
End Sub

When you are done you should have something that looks like this:

Option Explict
Randomize

Dim FlexDMD, UseFlexDMD
Sub ImplicitDMD_Init   ' This code for setting up Fixed FlexDMDs
   Me.x = 200          ' X-Position
...

• The code pasted in above contains the statement Dim FlexDMD. This can appear once and only once in the script or it will it to crash. Search for a second occurrence of Dim FlexDMD within the script. If it exists, either comment the line out by putting a tick mark (') at the start of the line, or delete the line entirely.

• The code pasted in above also defines UseFlexDMD (Dim FlexDMD, UseFlexDMD is equivalent to Dim FlexDMD on one line and Dim UseFlexDMD on the next line). As is the case with FlexDMD, UseFlexDMD can appear once and only once in the script or it will cause it to crash. Search for a second occurrence of Dim UseFlexDMD within the script. If that exists, either comment the line out by putting a tick mark (') at the start of the line, or delete the line entirely.

• Sometimes a snippet of code like this can be found right after the code discussed above. If it exists, you must change the UseFlexDMD = false to UseFlexDMD = True for things to work.

' Use FlexDMD if in FS mode
Dim UseFlexDMD
If Table1.ShowDT = True then
   UseFlexDMD = false  '<- Must to be changed -> True 
Else
   UseFlexDMD = True
End If

• With all these changes made, transfer the updated table script to your device and test it out.

Scenario 5: Using FlexDMD as an UltraDMD Replacement

UltraDMD is an older method of rendering a DMD for original tables. UltraDMD is "outdated" and no longer under development but is still used for some tables: Diablo, Kiss (Stern 2015), JAWS, and Master of the Universe to mention a few. The UltraDMD files are stored in a separate folder next to the .vpx file. The folder name is also case sensitive: if not written exactly the same as in the script, the folder won't be found e.g.diablo.UltraDMD

Running an UltraDMD table with FlexDMD

The mobile version of VPX Standalone doesn't support UltraDMD, so FlexDMD is needed as a replacement. This part only requires copy & pasting. Then the steps described in Scenario 4 have to be done as well.

[!IMPORTANT] The mobile version of VPX Standalone can't handle the .wmv files for animation often used in UltraDMD animations. These files have to be converted from .WMV to animated .GIF.

Once those conversions are done, search the script for .WMV and replace every occurrence with .GIF.

[!IMPORTANT] Check the Table1_exit Subroutine, UltraDMD is closed propperly, otherwise VPX-Standalone might crash and not close when you exit the Table.

... to be continued ...

Image Resizing

Basic Image Resizing

That phones and tablets can run Visual Pinball at all is really impressive considering their limitations. Many tables run great, but those tables with very high resolution textures and the like can push even top-end devices to their limits.

That is where docker-vpxtool-resize comes in. As its name suggests, it builds a Docker image that will automatically reduce the size of images within a .vpx file. The default reduction shrinks most images to 25% of their original size. In other words, an 8Kx8K texture image as used in some tables by V-Pin Workshop will be shrunken down to 2Kx2K in size.

If you don't want to use Docker, the resizing script can be downloaded as a raw file. You'll need vpxtool and ImageMagick installed as dependencies on your Mac or Linux machine. Just remember to make the script executable before trying to run it:

  chmod +x resize.sh

The script can also be edited if you want to tweak the resizing percentage. Look for this line in the script

  magick "$file" -resize 25% "$file"

and change the percentage as you wish. Values greater than 25% will compress the image less, and vice versa.

Advanced Image Resizing

[!NOTE] The process described here currently requires access to a Windows PC with the Visual Pinball software installed - it requires the Image Manager built into that version's editor. This editor is not available on the Standalone version on which the mobile and tablet versions of VPX are based.

If the table uses FlexDMD (e.g. Daredevil and the Defenders 2.0), the script will shrink the FlexDMD artwork too, breaking how it displays in the process. The script is also limited in that it can only replace compressed artwork of the same filetype as that already inside the .vpx file, meaning that it can't automatically switch to a compressed image format that might give better results for use on phones and tablets. The script can also backfire: some V-Pin Workshop tables can actually increase in size instead of decrease after running it. This might be caused by the original compression of the Blender-generated artwork being somehow lost in the conversion process.

Getting better results is doable but takes more work. Here is a high-level description of one possible workflow for doing so for "Daredevil and the Defenders 2.0".

• Download the file to your Windows PC with Visual Pinball installed and unzip it.
• Load the table into Visual Pinball on Windows
• Open Visual Pinball's Image Manager

• Click on the Raw Size column so that the largest files are shown at the top of the winow.
• Export the largest files by clicking the Export button. You can select multiple files at the same time except for Blender generated EXR-files: these have to be exported one by one. Never resize or compress LUT-Files: they aren't compressible and will render VPinball unable to display the table properly.
• When you've finished exporting the images you want to work on, start GIMP and select Batch Image Manipulation

• BIMP works on the idea of stacking image manipulation steps one after the other. To get started, click on the Add button to choose a function to execute. We'll start by resizing a batch of images so select Resize from the menu that pops up after clicking Add.

• Fill in the horizontal and vertical resize ratios, using the same value for both to keep the aspect ratio the same. A ratio of 50% is shown in the example below. Click OK when done.

• Click Add again and choose the menu option to change the file format and compression type

• Select WebP as the compression/filetype from the drop-down list. The suggested values shown below are a good starting point.

• When done, select the files you want to resize / compress and start the process. Pay attention to where GIMP stores the new output files.
• When GIMP has finished, start replacing the files using the Visual Pinball Image Manager once again. Use the Reimport From button in Image Manager so the path of the new file can be specified. Files have to be reimported one at a time.

[!NOTE] In the image below, the Name given to the image in the first column does not have to be the same as the filename in the Import Path in the second column. The Name is just a quick shorthand way of referring to the image in other parts of the table. In case you are curious, these associations are kept within a file named images.json that you can inspect if you extract the table in a program like vpxtool.

• Once you have reimported all the modified images, save the table and load it on to your device for testing.

Fix Leftover Image Artifacts

Sometimes there are some spurious visual artifacts that show up on tables when played on mobile devices or tablets. Doctor Who (Bally 1992) VPW Mod shows an example of this.

These artifacts are lamps that are used when playing this table in Desktop mode. To hide them, they have to first be identified. Windows users can load the table into Visual Pinball and, within the Editor, switch the view to "Backglass" by clicking the Pinball icon on the left side of the Editor

To identify the Number/Name of the item, just click on the problematic image. When you do, its name will be shown on the right side of the Editor. Going through this process one-by-one will identify the seven lamps on this table that are causing the issue. Note the names of each of them.

To fix this, open the .vbs script and set the identified object's visible property to 0 in the code:

l48bg.visible=0
l36bg.visible=0
l82bg.visible=0
l71bg.visible=0
l72bg.visible=0
l23bg.visible=0
l67bg.visible=0

The result should look like this:

---

Pinball Magic (Capcom) is another example. Depending on who made or modified the table, the artifact will be more or less visible.

To identify this artifact, you can disable the different layers using the VPX Editor on Windows.

When the artifact disappears, enable the last disabled layer and expand it. Then disable one piece after another within that layer until the artifact is identified. This particular artifact was identified as Primitive69. To hide it, just set its visible property to 0 in the .vbs script like the hiding of the lamps in the previous example.

Primitive69.visible=0