39. Fixing VP Plungers
If you built one of the plunger sensor options for the Pinscape
Controller, or if you bought a commercial plunger kit, you'll
certainly want to use the plunger when playing simulated pinball
tables. Many tables work with plungers automatically, but some don't.
Fortunately, for open systems like Visual Pinball, it's possible to
edit the table files yourself, so you can often fix any games that
don't already work with the plunger. This section shows you how to do
this for Visual Pinball tables.
Plunger support has evolved in Visual Pinball over the years. Most
Visual Pinball 10 tables should work automatically. It's much more
hit-or-miss with Visual Pinball 9, though; many tables, especially
older ones, lack proper support for the plunger.
Commercial game software doesn't usually give you any ability to
modify the software yourself. Your only recourse for a commercial
game that doesn't work is to contact the publisher's technical support
How plungers are supposed to work in Visual Pinball
The "right" way for a Visual Pinball 9 table to implement a plunger is
to use VP's intrinsic plunger object. VP has had built-in support for
plunger devices since early releases of VP 9.
The built-in plunger object in VP automatically takes input from a USB
plunger device, if you have one in your system. This works by reading
the USB joystick interface, using what's called the Z axis (although
you can configure this in VP's settings dialog to use a different
axis, if your physical plunger device uses something different). The
name "Z axis" is taken from mathematics, where it conventionally
refers to the vertical axis in a 3D plot. But PC joysticks use the
term loosely, to refer to "just some random third axis" - third
because the first two, X and Y, are the two degrees of freedom of the
stick itself, left/right and forward/back. Z usually represents some
other control attached to the joystick, such as a slider control or a
throttle. For virtual pinball plungers, we only pretend to be a
joystick, but we still have to use their notation. So we continue the
PC joystick tradition of assigning idiosyncratic meanings to the
mathematical axis names, using X and Y to represent accelerometer
readings for nudging, and using Z to represent the plunger position.
Tables that take advantage of VP's built-in plunger feature usually
"just work", because the built-in plunger itself just works (once you
have it properly configured, at least).
Why plungers don't always work in VP tables
If tables authors would always use VP's built-in plunger object,
plungers would work properly in all tables.
But table authors don't always go along with this plan. A lot of VP
tables, especially older tables written before about 2016,
don't use VP's built-in plunger feature. Instead, a lot of
them reinvent the
wheel plunger by using Visual Basic scripting
(which is another thing built into VP) to create their own completely
new object that's supposed to look and act like a plunger.
To be fair, many of the table authors that scripted their own custom
plunger objects were well-meaning. The early versions of VP's plunger
looked cartoonish and had a rather poor physics simulation. Table
authors working on re-creations of real tables naturally wanted their
tables to look good and work right, so they didn't want to settle
for the poor plunger implementation in early VP 9 releases.
But well-meaning or not, all of this re-inventing created huge hassles
for those of us with physical plunger devices. Many of the table
authors who created their own plungers in VB scripting didn't think to
read the joystick input. If a table doesn't read the joystick input,
it obviously won't work with your physical plunger device, which sends
information via the joystick input.
VP's built-in plunger was overhauled around version 9.9.5 to give it a
photo-realistic appearance and to make its physics work properly, both
for desktop play using keyboard input, and for cabinet play with a
physical plunger device. The new plunger was carried over into VP 10
and has been a part of VP 10 from the beginning. So newer tables -
those written later in VP 9's tenure, and anything written for VP 10 -
mostly use the new plunger object and mostly "just work". The only
exceptions among newer tables are a few written by authors who were
accustomed to the bad old way of doing things and didn't get the memo
about the built-in plunger overhaul. But those should be increasingly
rare as time goes on, and I certainly hope no one is still using the
bad old way for new tables at this point.
How do you fix a table that ignores the joystick input?
Unfortunately, it's not easy - but it can be done. Basically, you
have to rip out all of the scripted plunger code in the table, and
substitute the "real" built-in plunger object instead. The thing that
makes this difficult is that there's not a simple, rote procedure you
can follow, because every table that re-invented the plunger
re-invented it in its own way. You have to look at each table
individually to find its plunger scripting code and the associated
table objects so you can remove all of that. But there are two rays
of sunlight here. The first is that most table authors didn't
actually reinvent their custom plungers from whole cloth - most did a
copy-and-paste job from another table. So once you've fixed a few
tables, you'll start recognizing common patterns, and it'll become
easier each time. The second nice thing is that you don't really have
to write any new code - mostly it's just a matter of deleting all of
the custom plunger code so that the built-in plunger can take over.
The table scripts will end up simpler and cleaner when you're done with them.
At any rate, I'll try to give you the outline of a procedure that
works for many tables, but be warned that it still takes some work on
your part; it's not a simple "recipe" that you can apply mechanically.
Why plungers don't always work, part II
There's actually one more reason that plungers don't always work in
VP. This one's a lot easier to fix than the first one.
Remember how I said that the built-in plunger in older versions of VP
had bad physics? The situation was so bad that the bad physics
actually interfered with ordinary desktop use, even if you didn't have
a joystick attached. So a lot of table authors who used the built-in
plunger as the basis of their scripted re-inventions explicitly
disabled the joystick input so that desktop users wouldn't have to
put up with the bugs.
So for some tables, you'll find that there's already a proper built-in
plunger object present, and that all you have to do is tick a box in
the settings to re-enable joystick input.
How to fix a VP table
Here's my procedure for fixing VP tables with broken plungers. Be warned
that this isn't a simple recipe you can follow mechanically; it's more of
Before starting, save a backup copy of the table! We're going to go
into the table definition and do some major surgery. It's possible to
hopelessly screw up the table this way, and sometimes the easiest way
to get back to a working state is to scrap all of your changes and
start over from the original working version. You'll feel better
about messing around with the table's innards if you have a backup
copy tucked away that you can easily restore if things go haywire.
If you're already adept at using VP, you probably just need a quick
overview of the steps at a high level:
- First, check for a Plunger object in the table. If it's there:
- Make sure Enable mechanical plunger is enabled in its properties
- Make sure it's positioned so that it can hit the ball
- Make sure it's visible
- Set its style to Custom, and set the image to CustomWhiteTip or CustomBlackTip (see Making the
built-in plunger look nice below)
- If there's not already a Plunger object, try adding one, setting it
up to use the new "Custom" visual style and positioning it so that can
hit the ball when fired
- Delete any playfield objects (ramps, walls, lights, EMReels) that
are being used to draw the scripted plunger on-screen
- Go through the table's scripts and delete all of the old
plunger-related scripting code
If you're not a VP power user, read on for a more detailed
Open the table in the VP editor
Fire up VP. Open the table in the editor (not in "playing" mode).
Look for an existing plunger object
The first step is always to find out if there's already a built-in
plunger object. Many (maybe most) of the tables with scripted
plungers also have a built-in plunger object that's used as a
helper for some of the scripted operations.
If there is a built-in plunger, it might be hidden or located
somewhere off the table or in a remove corner of the table where it
can't interact with the ball. So it might not be obvious that it even
exists when you look at the table layout in the editor.
The easiest way to find this object is as follows:
- Edit > Select Element (or Ctrl+Shift+E)
- Look through the list for something called "Plunger" or something
similar, like "Plunger1"
- Click it in the list
- Click Select - a rectangular outline should light up somewhere in
the layout showing where the object is positioned
- Close the dialog
Enable mechanical plunger
If you successfully found a plunger object in the previous step:
- Select the object as described above
- If the properties window isn't already showing, click Options in the
left panel to bring it up
- In the State section, make sure the Visible box is checked
- In the State section, if Park Position is set to 0, change it to 0.16667
- In the State section, make sure the box for Enable mechanical
plunger is checked
- If the Enable mechanical plunger box wasn't already checked,
this might be all you need to do to fix it! This might be one of
those tables where the original author disabled joystick input (this
is the option that does that) because of the old physics bugs it
caused for desktop users. Checking the box re-enables the joystick
input, so the table might suddenly start working. Save the table,
fire it up in "play" mode, and test it out. If the on-screen plunger
tracks your physical plunger and launches the ball properly, you're
done! If it mostly works at this point but the plunger is
too weak or too strong, see "Other physics adjustments" below.
Try moving the plunger object
If you found a plunger object, but "Enable mechanical plunger" didn't
turn out to be a magic one-step fix, there's another simple thing we
can try before we have to dig deeper into the table.
A lot of table authors who "re-invented" the plunger did so by tying
their scripted object to a real plunger, and kept it from getting
involved in the physics by moving it somewhere out of the way where it
couldn't hit the ball. You might be able to see this easily just by
looking at the table layout - the plunger might be obviously off in
left field somewhere. But in some cases, this might not be visually
apparent. Some table authors just move it back a few pixels from the
ball position, so that it gets tantalizingly close but can't actually
hit the ball.
So the thing we can try now is moving it into the proper position.
The first thing to do is to make sure the object is movable. If the
object lights up with a gray rectangle when selected, it's "locked",
meaning VP won't let you move it. But we have the key! Right-click
it and un-check "Locked" in the context menu. If it lights up in blue
when selected, it's already unlocked and movable.
If the object is obviously off in left field somewhere, try moving
it into the shooter lane area. If it's already more or less in the
shooter area, try moving it further up on the playfield (in the
upwards direction on the editor screen).
It can be hard to visually parse VP's editor screen, because
everything is so schematic (just a few black lines showing the rough
outline of each object) and there can be so many things overlapping in
one area. Most games have an arrangement something like shown below,
with a "wall" object shaped like a little wedge that holds the ball in
place at the bottom of the shooter lane, just above where the plunger
strikes. That's the key point for aligning the plunger. It has to
overlap that wedge-shaped wall slightly - by about 1/6 of the plunger
length - in order to hit the ball.
You won't find this exact layout on all tables, so don't be overly
literal about looking for this exact picture. You might not find a
"wedge" wall like this at all. It's a common motif, but every VP
table author does things their own unique way. You might find a
differently shaped wall in roughly the same area, or no wall at all.
There's also usually a bunch of other stuff overlapping in the same
area, so even if the wedge is there, it might be hard to visually
separate from all of the other objects. If you're having trouble
identifying which squiggle belongs to which object, remember that you
can select an object by clicking on it. This will at least highlight
it so that you can see which of the lines belong to this one object,
and it'll show its name and object type in the Properties window,
which can help identify its purpose.
Once you've moved the plunger into what appears to be the proper
position, test again in "play" mode. Again, check if the on-screen
plunger tracks the motion of the physical plunger (it's a great sign
if so), and check if you can launch the ball.
Other physics adjustments
If you can make the plunger work at all with the changes we've
covered so far, you might still need to make some further adjustments
to make it work well. In particular, if the launch speed is too slow
or too fast (for example, the ball doesn't make it all the way up the
lane even when you pull the plunger all the way back and release),
you can adjust that by changing the plunger properties. Here's how:
- Select the plunger object
- Bring up the Properties window
- Adjust the Mech Strength property: increase the number if
the launch is too slow, decrease it if the launch is too strong
Removing a double image
Some tables use their own objects to simulate the visuals of the
plunger, hiding the real plunger by positioning it somewhere out of
sight. Moving it back into its proper position for the sake of the
physics will also make it appear at the proper position visually,
so you might now have two plungers showing up on-screen.
The easiest way to fix this is to make the built-in plunger object
- Select the plunger object
- Bring up the Properties window
- Un-check the Visible box under the State section
That leaves the built-in plunger working as far as the physics go,
but hides its visuals, so you get the custom graphics that the table
Personally, though, I prefer to do the opposite: I prefer to switch
tables to use the built-in visuals instead. This usually looks much
better than the old scripted visuals. The "new" built-in plunger in
VP looks photo-realistic, plus it's very smoothly animated. The
custom scripted graphics in many older tables look okay, and some look
great, but almost all of them have really choppy animation with just
a few "stops" the plunger can appear at.
Getting rid of the old graphics can be a bit of work, so be prepared.
The first step is to change the built-in plunger to use the new visual
style that actually looks nice. Existing plunger objects in older
tables are always set up to use one of the old visual styles, which
all looked crappy. See "Making the built-in plunger look nice" for
The rest is a matter of ripping out the game's custom scripted plunger
graphics. The procedure is exactly the same as "Replacing the
scripts" below, since you want to get rid of the scripts and use
the built-in object instead.
Adding a new plunger
If the table you're working with doesn't have a built-in plunger
object at all, you've got a bigger job ahead of you.
The first step, at least, is easy. You add a new plunger and
move it into position. Adding the object is just a matter of
clicking the "Plunger" button in the left pane in the VP editor,
then clicking on the playfield where you want to position it.
Make sure that the following options are set in the Properties
for the new plunger object:
- Enable mechanical plunger
Repeat the steps above under "Try moving the plunger object" to
get it into the proper position.
Making the built-in plunger look nice
If you had to create a new plunger object, or you're working with a
pre-existing plunger object, chances are that it's using one of the
old visual styles that look cartoonish or bad.
The trick to making the built-in plunger look nice is to switch it
to the "Custom" style. It's a fairly long procedure, but it's all
- Create a new VP table
- On the menu, select Table > Image Manager
- Find CustomWhiteTip in the image list and select it
- Click the Export button
- Save the file somewhere on your local hard disk
- Close the Image Manager dialog and discard the new table
- Go back to the table we were working on
- On the menu, select Table > Image Manager
- Click the Import button
- Find and select the CustomWhiteTip.png file that you saved from the new table above
- Close the Image Manager dialog
- Select the plunger object
- Bring up the Properties window
- In the Color & Formatting section, select PlungerTypeCustom
in the Type drop-list
- In the Image drop list, select CustomWhiteTip
Note that there's also a CustomBlackTip object you can use if you prefer
a plunger with a black rubber tip - this fits some tables better. You
can also create your own original texture if you're familiar with how
3D texture mapping works. That's a bit of an arcane process, though,
which is beyond the scope of this chapter.
Note also that there are a bunch of other properties in the Color
& Formatting section that let you further customize the drawing,
such as setting the diameter of the plunger rod and how many loops of
the spring are shown. You can tweak those to get the visuals just
right for the table.
Removing the old plunger scripts
Now to the hard part: getting rid of the table's custom plunger scripts.
This is only necessary if you weren't able to get the plunger working
by enabling (or creating) and properly positioning a built-in VP
plunger object, as outlined above. It's also necessary if you already
got the plunger working in terms of the physics but you want to get rid
of the old scripted graphics.
Delete fake plunger objects
Start by looking for objects on the playfield around the plunger area
that serve no apparent purpose. These will often be one of the following
The most likely thing will be a big rectangular object (of one of the
types above) covering roughly the same area where the plunger appears.
These will usually be somewhat larger than the plunger.
If you find such an object, check its property list to see if it has
an associated image in the Color & Formatting section. If so,
check what the image looks like in the Image Manager:
- On the menu, select Table & Image Manager
- Find the named image in the list
- Click it and look at the thumbnail
If the image looks like a plunger photo, that clinches it - you've
found exactly what we're looking for.
If there's no image, though, it might still be an object of interest.
The scripts might be assigning an image in Visual Basic land instead
of using the object properties directly. If the object is in the right
area, you can make a guess that it's what we're looking for.
If you don't find anything on the playfield, you might try looking at
the Backdrop. This is an extremely hacky hack that some table authors
use to force an object to appear on top of the table - the "Backdrop"
is a sort of super-layer that gets drawn on top of everything (the
opposite of what you'd guess from its name!). You might find something
called an EM Reel object there:
- Click Backdrop in the left pane
- Note that the Backdrop view is rotated 90 degrees from the regular view,
so the plunger area is at the top right in this view
- Look for one or more rectangular objects of type EM Reel around the plunger area
If you find something matching the description - a ramp, wall, light, or EM Reel
in the right area and possible with the right image type, try deleting it. Just
select it with the mouse and press the Delete key on the keyboard.
Note that might have to "unlock" the object before you can delete it.
If it lights up with a gray rectangle instead of blue, it's locked.
Right-click it and un-check "Locked" from the context menu.
One good sign that you found the right object is that there's
another object right behind it that looks exactly the same. A lot
of table scripts use a big stack of objects piled one on top of the
other as a series of flip-book animation frames. The Visual Basic
scripts will make one of the objects visible at a time to animate the
plunger motion. If you find a stack of 10 or 20 identical objects in
the same spot, you've found an animation flip book. Just keep
selecting and deleting them until they're all gone.
The next (and fortunately last) step is hard to express as a recipe.
You're going to be somewhat on your own here. What you have to do now
is find and delete scripting code that refers to those objects we
If you're good at reading Visual Basic code, you can go through the
script and look for subroutines related to the plunger. When you find
one, you can usually just delete it outright, from the line that says
"Sub name" to the matching "End Sub".
A lot of tables with plunger scripts are actually pretty helpful about
grouping all of the plunger scripts together in one place. You might
find a section marked with comment like this:
' Plunger scripts
If you find something like that, you can try selecting everything
that follows that looks plunger-related (based on the names of the
subroutines, for example) and deleting it.
If you don't want to pore over the script, there's a pretty easy
trial-and-error way of finding the trouble spots. Specifically, you
can rely on the fact that all of the plunger scripts will probably
make reference to the playfield objects we just deleted. Whenever
any of those references are encountered at run-time, Visual Basic
will halt the program and throw up an error message telling you
that the code is referring to a non-existent object. VB is usually
pretty good about showing you exactly where each error occurs,
by highlighting the error line in the editor, so this can be a
quick and reliable way to find each error and remove the code.
- Run the game
- Wait for Visual Basic to throw up an error message
- If you don't get any errors immediately, try pressing and holding the
Enter key on the keyboard to pull back the plunger. Let it pull all
the way back, then release the Enter key to release the plunger. If
there are any scripts that rely on deleted objects, one of them
should trigger an error at some point during this process.
- If you don't get any errors with the keyboard, try again with your
plunger device. Hook up the device, move the plunger around, and see
if any errors occur at any point.
- Find the line of code where the error occurred
- Delete the code:
- If the error location is in a Sub..End Sub section that looks totally
plunger-related, delete the entire Sub..End Sub section
- If the error location isn't in a Sub at all, it's probably
"initialization" code that runs at table startup. Just delete
that one line that contains the error
- If the code is inside a Sub called something like Table_Init, it's
also initialization code. Just delete the one line containing the
- If the code is inside a Sub called something like Table_KeyDown
or Table_KeyUp, it's keyboard handler code. Don't delete the whole
routine; just delete the line that's causing the error.
- Go back and repeat this whole process until the game runs reliably
In most cases, tables with plunger scripting use subroutines that are
fairly self-contained and dedicated to the plunger operations. So
when you find an error, you can usually just delete the entire
subroutine that contains the error line: that is, all lines from the
nearest Sub name that precedes the error line to the
nearest End Sub that follows it.
Something that's likely to happen during this process is that you
might delete one subroutine block that another subroutine
calls. So after you delete the code with the first error, run again,
and you'll probably hit a new error in code that's trying to
call the code you just deleted.
Getting the table working now is usually just a matter of repeating
this seek-and-destroy mission until until you stop getting errors.
If all else fails
In some cases, the "delete code until it starts working" approach can
backfire. Some tables are just too complicated, with Visual Basic
code that's too intertwined, for mere code deletion to work. You
sometimes have to rework the code a bit instead.
If you know VB well enough, you can analyze the code and figure out
what you have to change. If you're not a VB power user, well, it's a
bit beyond scope of this section to turn you into one. My advice
would be to ask nicely for help on the forums - maybe you can find the
original table authors and persuade them to update the table to modern
standards, or enlist help from one of the many Visual Pinball power
users on the forums.