VPX Scripting — Part 4 (Pet Sounds)

Teacher’s Pet backglass by Itchigo.
Backglass for Teacher’s Pet by the user Itchigo.

19 Apr 2024

Sound Resources

In Part 3 of this series we made significant changes to the script of Teacher’s Pet. We removed code, we added code, and we modified a lot of code. As an example:

Replacing PlaySound with EMSPlayPlungerReleaseBallSound.

The line of code, PlaySound "plungerrelease" was replaced with EMSPlayPlungerReleaseBallSound Plunger.

If you find further down in the script where EMSPlayPlungerReleaseBallSound is implemented, it is a pretty simple subroutine that looks like this:

EMSPlayPlungerReleaseBallSound code.

I want to draw attention to the red code in quotes, "Plunger_Release_Ball".

In the case of the code we removed, the quoted part, "plungerrelease", was the name of a sound file to play. In the case of the new code, "Plunger_Release_Ball" is the name of the replacement sound file we want to play.

The next step in enhancing the sound for Teacher’s Pet is to remove the old sound resources (files), and add new sounds.

Under the Table menu in VPX there is a menu item Sound Manager…. Select that to bring up the Sound Manager panel.

How to open the Sound Manager panel.

You are presented with a scrolling list of all the sound resources in the pinball table. The left column is the name of the sound and it is by name that a sound is played. (I scrolled down for the following screenshot so you can see "plungerrelease".)

Sound Manager panel showing old sounds.

We’re going to get rid of all these sounds. But if you’re cautious like me, I would suggest you first export all of the sounds in order to keep a copy on disk (there is an Export button on the right side of the Sound Manager panel).

After selecting all the files and exporting them, you can delete all of them (using the Delete button also on the right side of the Sound Manager panel).

All sounds deleted.

Teacher’s Pet now has no sounds that it can play.

The next step is to import the new sounds. Like the EM Sound code we pasted in from Part 3, the same GitHub repository has a folder of EM sounds we want to download. I am not aware of a simple way to just grab the sound files, so I am going to instruct you on how to download the entire repository.

The repository you want is VPX_EM_Resources. When you go there look for the Code button and click on it to find the Download ZIP option.

Download button to click on.

When you download the zip file, extract it and you will find it contains a Sound Resources folder and within that folder is one called EMSounds. You will want to import the sounds in the EMSounds folder into Teacher’s Pet.

In the Sound Manager panel click the Import button and select all the sounds from the EMSounds folder.

Import the EMSounds.

We are done now with swapping out the old sounds with the new. Be sure to Save Teacher’s Pet.

EMSounds are loaded.

I’ll mention this now and we’ll return to it, but there are extra sounds we imported that we will not need for Teacher’s Pet. We could leave the extra sounds in, but if you’re going to upload this table to be distributed online it would be considerate to remove any unused bytes. But as I say, we can address this later.


Okay, new code, new sounds — at long last, let’s click Play in VPX and try out our new Teacher’s Pet.

Hopefully the table comes up. If we made any typos we may have caused a problem preventing VPX from starting up the table. I am going to have to rely on you to figure out what mistakes you might have made on your own. I can’t possibly cover all the problems you may encounter. If you run into problems and give up trying to solve them on your own, I have the modified version of Teacher’s Pet on Github without typos for you to use.

When I fired up a new game, I got as far as starting a new pinball game when I got a VPX crash.

Encountering an error.

Click Stop and let’s figure out what caused the crash.

Encountering an error.

The text at the bottom of the Script window is telling us the line number and the problem. It is telling us that Vol is undefined. It turns out that in Part 3 of this series Vol was one of the functions we deleted. That’s okay though, we don’t need to add it back. Instead, we want to remove the entire line of code on Line 3181 (the actual line number may be different for you) and replace it with an EM Sound call, EMSPlayMetalHitSound. Here is what it will look like:

New call to EMSPlayMetalHitSound.

Why did we hit that error? The pinball being launched into the plunger lane appears to have hit a metal object and that triggered the sound to be played. However, because of editing we had done on the script, the code failed and VPX halted.

With that issue hopefully resolved, let’s try to play again and see if we get further.

I run Teacher’s Pet again and this time I am able to launch the pinball. However, as the ball is careening around the playfield, I suddenly encounter another crash:

Encountering another error.

Hit Stop again. Now it appears that Rubbers_Hit is the problem. And like Metals2_Hit before, the actual error is a missing Vol function.

As we did before, we can remove all the code within Rubbers_Hit and replace it with an EM Sound call, EMSPlayRubberHitSound.

New call to EMSPlayRubberHitSound.

Let’s have another go.

This time playing Teacher’s Pet it ran right up until I hit the pinball with the flipper and then another crash:

Encountering another error.

If you look closely at the error message above, there is a "Stack trace" that indicates that the crash was in RandomSoundFlipper (top of the stack), but that it was being called from a routine called RightFlipper_Collide.

In fact it was when I hit the ball with the right flipper that VPX halted, so this makes sense. RandomSoundFlipper is crashing by the way because of the same missing Vol routine. But in this case, I am going to remove the entire RandomSoundFlipper routine because we don’t need it. EM Sounds has EMSPlayRightFlipperCollideSound and that will be our replacement. And while we’re here, might as well fix the left flipper code as well.

Encountering another error.

One thing to note in the fixed code above, both EMSPlayRightFlipperCollideSound and the left flipper version take a parameter, Parm, so we pass that.

Surprisingly, after the above fixes, I fire up Teacher’s Pet and I am able to play through a few balls without seeing any more crashes. We seem to have done it! The fixes that I made at this stage on the script are on Github if you like.


Some things nagging me a little bit: the four routines we fixed up were all in that Object sounds section of the script, but there are a lot of other subroutines in there like Gates_Hit and Posts_Hit. Are we going to fix those? And why did they never get called and halt VPX?

The answer is that many of these routines are not really wired up to the table itself. There is no gate on the playfield that is configured to call Gates_Hit and no posts configured to call Posts_Hit.

As I’ve said before, Loserman76 appears to have kept a kind of “boilerplate” script that he moved from table to table as he created new ones. Logic specific to a table like Teacher’s Pet would have to be added of course, but the general utility of playing a sound when a playfield rubber is hit would be the same on all VPX tables. So likely there are tables out there that Loserman76 wrote that do in fact call Posts_Hit for example.

These orphaned routines left in Teacher’s Pet wouldn’t have normally caused any real problem. It’s only because we broke them by removing the Vol function that we have to be careful to fix up the ones that are still “live”.

Trying to determine which of the routines in Object sounds is wired up for a particular pinball table is tricky to do correctly. It is the reason I have taken this “fix it when it breaks” approach to his tables.

My sense if that coding through crashing is generally frowned upon but I have to admit I have done it more than a few times in my career.

There are potential land mines still in the table however unless we thoroughly test it. Perhaps there is one small area on the table where colliding with the pinball will trigger Metals_Thin_Hit. I think it’s a bad idea to post the table with these potential errors left unaddressed.

My approach though is to leave the possible land mines in for as long as I can — keep playing the table while I make other fixes to it. But before I release the modified table I’ll make sure to change the routines in such a way as to defuse them so that they can never cause VPX to halt for other players.

Next Steps

If this kind of thing was new to you then what we’ve pulled off so far is massive. Not only have we wholesale replaced the sound code for a VPX table, we’ve swapped sound resources as well and did some debugging.

There is still more to do though in the next post. But in my mind, the worst is now behind us. What is left involves a little house-cleaning and some refinements to the table. The house-cleaning will be painless, the refinements kind of fun actually.