DOC changes

DOC/Changes.md

@@ -5,7 +5,7 @@
 ### New SW Version V1.02
 
 * The default name of music files has been changed from MUSIC.BIN to MUSIC.SND to be consistent with the APC audio files having .SND as a suffix. That means you might have to rename the MUSIC.BIN files of your SD card to MUSIC.SND
-* A new option is available to replace the old (and sometimes annoying) BG sound of old machines by MUSIC.SND. It can be activated with setting 7 in the [game settings](https://github.com/AmokSolderer/APC/blob/master/DOC/Settings.md#game-settings-in-remote-control-mode).
+* A new option is available to replace the old (and sometimes annoying) [BG sound of old machines by MUSIC.SND](https://github.com/AmokSolderer/APC/blob/master/DOC/PinMameSound_3_7.md#Adding background music). It can be activated with setting 7 in the [game settings](https://github.com/AmokSolderer/APC/blob/master/DOC/Settings.md#game-settings-in-remote-control-mode).
 * A general ball saver is available. It can be activated with setting 5 in the [game settings](https://github.com/AmokSolderer/APC/blob/master/DOC/Settings.md#game-settings-in-remote-control-mode). There's [a list](https://github.com/AmokSolderer/APC/blob/master/DOC/PinMame.md#available-sounds) of supported machines. Look [here](https://github.com/AmokSolderer/APC/blob/master/DOC/PinMameExceptions.md#how-to-add-a-ball-saver) if it's not yet available for your machine.
 
 ## June 2024

DOC/PinMameSound_3_7.md

@@ -168,6 +168,33 @@ However, the major difference is that 0x2a is the background sound which can be
 In the APC SW the Aftersound pointer can be used for this. This pointer can be set to a routine which is called automatically when a sound has run out. That's why the name of the current pitch is always stored in the USB_RepeatSound variable. Then QueueNextSound is called which takes the filename USB_RepeatSound points to as an argument. It sets the AfterSound pointer to a routine which will play the filename stored in USB_RepeatSound when the current sound file is running out. This ensures that whenever the background sound is being interrupted by another sound, it is immediately being restarted as soon as this sound has run out.  
 Setting AfterSound = 0 will disable this mechanism.
 
+### Adding background music
+
+Most machines of this era have a quite boring background sound. This can be replaced by a music track of your choice with a simple change in the PinMameExceptions. A general [game setting](https://github.com/AmokSolderer/APC/blob/master/DOC/Settings.md#game-settings-in-remote-control-mode) to activate the ball saver is already present, so you don't have to bother with changing the settings menu.
+
+The code below is for the Alien Poker, but the principle is the same for all System 3-7 machines.  
+In case of the Alien Poker, the command for the background sound is 14. If this command is received, we have to check whether the setting for background music is selected or not. If yes and SoundSeries[2] variable is zero, the file MUSIC.snd is played on the music channel and also queued for looping. The SoundSeries variable is just used to prevent the music file from being restarted every time PinMame requests a new pitch.  
+If background music is not selected in the settings, the normal BG sound is played as described in the section above.
+
+    else if (Command == 14) {                         // 0x0e Background sound series - repeated
+      SoundSeries[0] = 0;
+      SoundSeries[1] = 0;
+      if (game_settings[USB_BGmusic]) {               // use MUSIC.SND instead of BG sound
+        if (!SoundSeries[2]) {                        // don't restart if next pitch is requested
+          PlayMusic(50, "MUSIC.snd");                 // play music track
+          QueueNextMusic("MUSIC.snd");                // and loop it
+          SoundSeries[2] = 1;}}
+      else {
+        if (SoundSeries[2] < 36 )                     // this sound has 36 pitches
+          SoundSeries[2]++;                           // every call of this sound proceeds with next pitch
+        char FileName[13] = "0_0e_000.snd";           // generate base filename
+        FileName[7] = 48 + (SoundSeries[2] % 10);     // change the 7th character of filename according to current pitch
+        FileName[6] = 48 + (SoundSeries[2] % 100) / 10; // the same with the 6th character
+        for (byte i=0; i<12; i++) {                   // store the name of this sound
+          USB_RepeatSound[i] = FileName[i];}
+        QueueNextSound(USB_RepeatSound);              // select this sound to be repeated
+        PlaySound(51, (char*) FileName);}}            // play the sound
+
 ### Defining the basic special commands
 
 At last we have to implement the two basic special commands every system 3 - 7 game has. These are the sound stop command (0x0c for Sys 3 - 6 and 0x2c for Sys 7) and the bus initialization (0x1f for Sys 3 - 6 and 0x7f for Sys 7). 

DOC/PinMameSound_9.md

@@ -234,6 +234,21 @@ As the pre System11 displays cannot show letters, the corresponding sound number
 
 By that you can just play your game and only if the number of a missing sound file pops up on the right side of your display you note it down and add it later.
 
+### Changing the background music
+
+Most machines of this era have a quite basic background music. This can be replaced by a music track of your choice with a simple change in the PinMameExceptions. A general [game setting](https://github.com/AmokSolderer/APC/blob/master/DOC/Settings.md#game-settings-in-remote-control-mode) to activate the ball saver is already present, so you don't have to bother with changing the settings menu.
+
+The code below is for the Comet, but the principle is the same for all System 9 machines.  
+In case of the Comet, the command for the background sound is 47. If this command is received, we have to check whether the setting for background music is selected or not. If yes the file MUSIC.snd is played on the music channel and also queued for looping. If background music is not selected in the settings, the normal BG music is played as usual.
+
+    else if (Command == 47) {                         // play BG music
+      if (game_settings[USB_BGmusic]) {               // use MUSIC.SND instead of BG sound
+        PlayMusic(50, "MUSIC.snd");                   // play music track
+        QueueNextMusic("MUSIC.snd");}                 // and loop it
+      else {
+        PlayMusic(50, "0_2f.snd");
+        QueueNextMusic("0_2f.snd");}}                 // track is looping so queue it also
+        
 ## Sound problems
 
 Most sound problems like lags and stuttering are caused by the performance of the SD card. Take a look at the [If things don't work](https://github.com/AmokSolderer/APC/blob/master/DOC/Problems.md) section for more.

README.md

@@ -35,10 +35,10 @@ There's a table of contents of the available documentation at the end of this pa
 
 Typical examples for the use of PinMameExceptions are:
 
-* Pre System11 games usually use just one audio channel, so you could add a background music track. Wouldn't it be great if your Disco Fever would play old Disco music in the BG?
-* Add HW toys like a shaker motor or flashers and the necessary rules to drive them. If your game has no free solenoid drivers left, then just add the [Solenoid expansion board](https://github.com/AmokSolderer/APC/blob/master/DOC/SolExpBoard.md) to get 8 more. You can also use the [LED expansion board](https://github.com/AmokSolderer/APC/blob/master/DOC/LEDexpBoard.md) to control RGB-LED stripes or just connect your own individual HW.
-* Add a ball saver. There's a general ball saver available which can be easily adapted to your machine. Of course you can also add an individual ball saver - all you have to do is not to tell PinMame that the ball has reached the outhole, but to kick it into the plunger lane instead. Watch my [Comet video](https://youtu.be/JbgMa_pn0Lo) to see how it can be done with just a few lines of code.  
+* Pre System11 games usually use just one audio channel which can even be annoying at times. With PinMameExceptions you can add [a background music track](https://github.com/AmokSolderer/APC/blob/master/DOC/PinMameSound_3_7.md#Adding background music) which replaces the original background sound. The change is easy and for most pre System11 which have PinMameExceptions it's already implemented. Check [this list](https://github.com/AmokSolderer/APC/blob/master/DOC/PinMame.md#available-sounds) for details.
+* Add a ball saver. There's a [general ball saver](https://github.com/AmokSolderer/APC/blob/master/DOC/PinMameExceptions.md#how-to-add-a-ball-saver) available which can be easily adapted to your machine. Of course you can also add an individual ball saver - all you have to do is not to tell PinMame that the ball has reached the outhole, but to kick it into the plunger lane instead. Watch my [Comet video](https://youtu.be/JbgMa_pn0Lo) to see how it can be done with just a few lines of code.  
 Check the [description](https://github.com/AmokSolderer/APC/blob/master/DOC/PinMameExceptions.md#how-to-add-a-ball-saver) to see how both options work.
+* Add HW toys like a shaker motor or flashers and the necessary rules to drive them. If your game has no free solenoid drivers left, then just add the [Solenoid expansion board](https://github.com/AmokSolderer/APC/blob/master/DOC/SolExpBoard.md) to get 8 more. You can also use the [LED expansion board](https://github.com/AmokSolderer/APC/blob/master/DOC/LEDexpBoard.md) to control RGB-LED stripes or just connect your own individual HW.
 
 The picture below shows an APC prototype in my Pinbot.