Avengers TV-series PUP-pack

What does it do?
Music mods or sound mods are something that I really enjoy a lot. Ideally, the music adds to the pinball machine's theme and brings back the feeling of the bar where the pinball machine often was located near the jukebox. Especially for EM machines that only had chimes and bells, the added music can be nice. This PUP-pack features songs mostly from the 60s and 70s with video cut scenes from the tv series "The Avengers". The focus is on giving you some background music.

What does it NOT do?
This PUP-pack does NOT deal with the Marvel superhero franchise of the same name. If you expected Thor, Captain America or the Hulk here I'm sorry to disappint you, they are not to be found here. We're talking about the British TV series from the sixties instead that featured John Steed (played by Patrick Macnee) and various female side-kicks. The best-known female character was Emma Peel, played by Diana Rigg.

Tracks:
There are 17 tracks that come with this PUP-pack. Add your own videos as you see fit.  

Tables:
There are several tables that have similar themes. The PUP-pack "Avengers TV-series PUP-pack" is meant to be used with tables that deal with the TV series from the 1960s.
It can be used with the tables

• Avengers,TV Series by stevegooner123 (reskin of @jpsalas' Space Cadet)
• Chapeau Melon et Bottes de Cuir by @VLive and @icepinball (reskin of JP Salas' Space Cadet)
• Avengers TV-Series multilingual by @icepinball (reskin on Road Kings) unreleased as of 2024-01-04

and any other table that you want to use it with (if you are ready to tweak the table code).
You can apply the PUP-pack for all or some of the above tables or just for one of them.

Controls:
To accomplish the PUP-pack as a video jukebox I had to add some controls to the table script. During game play, you can go to another random track with the right magnasave button. Pressing the left magnasave button stops the playback. The gameplay itself doesn't have any impact on video playback.

Patching:
I went through a long approval request communication with some of the table authors with no final result, so I've come up with a dif file for each table that you need to apply using VPU's patching system "VPURemix". This way, the original author's work doesn't get touched; think of the patching systems as an easy way to keep you from adding code snippets to the tables manually.

Manual coding:
If you don't want to use the patching system or if you want to apply the code to another table that isn't listed above, here are the instructions for manually applying the code. All who don't want to apply code manually should skip this section:
At the top of the table code, add:

'****** PuP Variables ******

Dim usePUP: Dim cPuPPack: Dim PuPlayer: Dim PUPStatus: PUPStatus=false ' dont edit this line!!!

'*************************** PuP Settings for this table ********************************

usePUP   = true      ' enable Pinup Player functions for this table. 
cPuPPack = "TheAvengers" ' name of the PuP-Pack / PuPVideos folder within PinUPSystem\PUPVideos for this table


'//////////////////// PINUP PLAYER: STARTUP & CONTROL SECTION //////////////////////////

' This is used for the startup and control of Pinup Player

Sub PuPStart(cPuPPack)
    If PUPStatus=true then Exit Sub
    If usePUP=true then
        Set PuPlayer = CreateObject("PinUpPlayer.PinDisplay")
        If PuPlayer is Nothing Then
            usePUP=false
            PUPStatus=false
        Else
            PuPlayer.B2SInit "",cPuPPack 'start the Pup-Pack
            PUPStatus=true
        End If
    End If
End Sub

Sub pupevent(EventNum)
    if (usePUP=false or PUPStatus=false) then Exit Sub
    PuPlayer.B2SData "E"&EventNum,1  'send event to Pup-Pack
End Sub

' ******* How to use PUPEvent to trigger / control a PuP-Pack *******

' Usage: pupevent(EventNum)
' EventNum = PuP Exxx trigger from the PuP-Pack
' Example: pupevent 102
' This will trigger E102 from the table's PuP-Pack
' DO NOT use any Exxx triggers already used for DOF (if used) to avoid any possible confusion

'************ PuP-Pack Startup **************

PuPStart(cPuPPack) 'Check for PuP - If found, then start Pinup Player / PuP-Pack

'***************************************************************************************

Usually, somewhere between the declaration of constants (lines starting with "Const") and the variable dimensions (lines starting with "Dim") is a good place to add that code.
After doing that, run the table to see if it is playable without throwing errors. The videos should be playing, but you won't be able to pause/skip, as we haven't added yet the corresponding code.
Next, add the Magnasave controls by searching the existing code for the term "magnasave". If it's NOT there, we're fine and can savely add our magnasave button definition into a new line of it's own right within the definition of the function "Sub Table1_KeyDown". Add this code:

    If keycode = LeftMagnaSave Then
        PuPevent 801
    End If

    If keycode = RightMagnaSave Then
        PuPEvent 800
    End If

We're done! Test-play, remember to save the table.

The two tables that are a Space Cadet reskin do contain Magnasave functionality, so I have changed

    If keycode = LeftMagnaSave Then bLutActive = True: Lutbox.text = "level of darkness " & LUTImage + 1
    If keycode = RightMagnaSave Then
        If bLutActive Then
            NextLUT
        End If
    End If

into:

    If keycode = LeftMagnaSave Then
        bLutActive = True
        'SetLUTLine "Color LUT image " & table1.ColorGradeImage
        PuPevent 801
    End If

    If keycode = RightMagnaSave Then
        If bLutActive = True Then 
            NextLUT
        Else
            PuPEvent 800
        End If
    End If

Instructions:

1. Download the package and unblock it if applicable
2. Extract the folder "TheAvengers" into your PUP-pack folder (usually something like C:\vPinball\PinUPSystem\PUPVideos)
3. Extract the dif files into a temporary folder (e.g. C:\temp)
4. If you don't have it, download VPU's patching system "VPURemix" and expand it to any folder on your PC, e.g. C:\vPinball\VPPatch64
5. Download the original tables that you want to apply the patch to. You can follow the .url files in the zip to accompish that or just copy and paste the URLs below into the address bar of your browser: 
   * Avengers,TV Series by stevegooner123 (reskin of JP Salas' Space Cadet). No need to apply the dif patch, as Steve has already added the needed code into his release v1.1 or better. The dif patch just brings minor code changes that mainly result in smaller file size; only apply it if you need bleeding edge code. 
   * Chapeau Melon et Bottes de Cuir by VLive and Iceman (reskin of JP Salas' Space Cadet)
   * Avengers TV-Series multilingual by Iceman (reskin on Road Kings): unreleased as of 2024-01-04. Watch VPU for a release. 
6. Apply the patch for the desired table(s): as a result, you should obtain a modified VPX file. Put those files into your tables folder (e.g. C:\vPinball\VisualPinball\Tables)

PUP-pack options:
The PUP-pack videos can be positioned on topper, backglass or full DMD screen, with or without an overlay. It comes with these options:
1-Video on backglass, no overlay
2a-Video on backglass,overlay-frame
2b-Video on backglass,tv-bigscreen
2c-Video on backglass,tv-mediumscreen
2d-Video on backglass,tv-smallscreen
3-Video on fullDMD, no overlay
4a-Video on fullDMD,overlay-frame
4b-Video on fullDMD,tv-bigscreen
4c-Video on fullDMD,tv-mediumscreen
4d-Video on fullDMD,tv-smallscreen
5-Video on topper, no overlay
6-Video on backglass with B2S (supplied by @Justthebest, thank you)
To apply any of them, execute the corresponding batch file in the PUP-folder (e.g. C:\vPinball\PinUPSystem\PUPVideos\TheAvengers).

Table authors: 
I hope that all table authors are OK with this PUP-pack. I'd be more than happy if you would add the code to your next release as a sort of backport. In fact, Stevegooner123 has already done so in his 1.1 release by adding the core functionality. My dif contains minor code adjustments and removes unneeded extra files.

My edits are trivial and most of it was blatantly taken from @NailBuster's code. Some tables use the Magnasave buttons for LUT, so the interfering code needs to be adapted accordingly.

Known Issues:
If you want the PUP-pack video to play on the fullDMD for one table and on the topper for another table for example, you can't get away with just one folder "TheAvengers" within the PUPVideos folder. Create two instead and name them "TheAvengersFullDMD" and "TheAvengersTopper" or similar and refer to that name in the code section in the variable definition for cPuPPack.

I hope that some will find this PUP-pack fun and apologize for the long read.

Enjoy

Joachim