Part One: A quick recap.

In the previous tutorial I guided you through setting up your environment for converting games from the Spectrum to the Enterprise. You would have configured the emulator bundled with MPAGD. You built the simplest game possible (single screen, single sprite) and converted it to the Enterprise using a few commands at the commandline.

What I didn't do is cover adding music. MPAGD, for all its wonderfulness, falls short in the generation of sound and music. But that doesn't matter on the Spectrum as there are a number of programmes available that excel in that area and can export the sounds into a format which can be imported into the Spectrum game. In my opinion it is a better way of doing things. It lets MPAGD focus on building games and leaves the sound development to specialist applications where "sound is all they do".

However, when it comes to the Enterprise, there is a little work required. The Enterprise's sound is generated by it's own sound chip which, unsurprisingly, needs to be accessed in a different manner to the ZX Spectrum's.

Fortunately for those who have used the tool Beepola to create Spectrum tunes, Noel has converted the various Beepola engines to target the Enterprise sound chip, and the code you'll need is found within the SOUND_SRC\Beepengines_EP folder in the SUITE EP directory.

This tutorial will cover adding one or more Beepola Tunes into an Enterprise game. I will be using the Spectrum 48K version of my game, Throbby Heartache, to illustrate this process.

Part Two: A quick introduction to Beepola

Beepola is a free tool available from: https://freestuff.grok.co.uk/beepola/ created by Chris Cowley
It uses a traditional "tracker" style interface to create tunes. As the Spectrum (16/48K) doesn't have a dedicated sound chip, it has to do some technical trickery to make multi-channel tunes. Fortunately a lot of kind people have either created or converted engines for this purpose (12 different ones in the current version), ranging from the simple ROM BEEPER which generates the smallest amount of code, through to the 4 channel qchan fuzzy majesty that wowed many of us in the 1980's.

Now, when I have created a tune in Beepola, my main concern has to get something reasonable with a small code footprint. When it comes to transferring these tunes to the Enterprise, there is more memory available so you may be able to have your tune use a slightly larger code footprint. (I did this with Chump Town where the 48K ZX Spectrum version uses the ROM BEEPER and the Enterprise version uses the Tritone player, and I think gives a better quality sound for a few more bytes).

After designing your tune, you would then compile it (Tools : Compile) and export the song as your engine of choice and the music data as assembly code. This would then form the base of the user.asm code you would add into your MPAGD game (and access it using the USER command within your MPAGD game code).

For this tutorial, you will either take your existing Beepola code and adjust it for the Enterprise, or compile it again to obtain just the song data. There is no right or wrong here. Just make sure you make your changes to a copy of the User.asm code so you don't make changes that stop you rebuilding your original game in the future!

Part Three: Converting Throbby Heartache

For the tutorial today, I will be converting my game, Throbby Heartache, from the ZX Spectrum to the Enterprise. This has a single Beepola Tune for the main menu which uses the Tritone engine. This has been exported as an assembler file combining the Tritone Engine and the song data.

First you will need to get the latest AGD file for your game. Load your game into MPAGD and select File: Export Game.

This will build and generate your game code for the Spectrum. You will need to copy the file it generates from SUITE ZX\AGDsource to SUITE EP\AGDsources

At the command line you would go to the SUITE EP folder and then type:

COPY "..\Suite ZX\AGDsource\throbby_heart48K.agd" AGDsources\THEART.AGD

(Replacing throbby_heart48K.agd and THEART.AGD with the title of your own game. Remember the Enterprise needs files in an 8.3 format so rename the AGD file you're using as your base code on the Enterprise side of things to ensure it will not have problems later).

Once you have done this, it is good practice to check the game works before going any further. Copying the AGD file will not copy any USER.ASM code. Instead a default USER.ASM will be attached to the Enterprise version that simply returns to MPAGD if a USER command is called in your code.

To build your code; while you're still in the SUITE EP folder, type:

build.bat THEARD (and then any parameters your game needs)

Where THEARD is the name of the AGD file, but without the AGD extension, and the parameters will be such things as enabling ULA+, including a loading screen or enabling adventure mode.

This then will load the tutorial. On loading I can see some debug code is being picked up (that doesn't get picked up on the Spectrum Version), but it appears the game plays fine and doesn't have any issues. (Because I write "fancy screen wipes" occasionally my maths has been off and it has written data off screen, which is usually fine on the Spectrum but overwrites game code on the Enterprise; so it is good to confirm that this doesn't appear to be a problem.

Before going any further, I will tidy up the debug code (that is not needed) and change the menu items to reflect Joystick 1 and Joystick 2 rather than Kempton and Sinclair (which are Spectrum specific Joystick terms). It is an ideal opportunity for you to do the same with your game.

As with Tutorial One, you will directly edit the THEART.AGD file you copied over from the Spectrum. This will be the master version of the game for the Enterprise. Ensure you back this up and don't overwrite it if you update the Spectrum game.

Now the base code is ready for the Enterprise, you are ready to look at adding your beepola tunes. In my case, I will go back to beepola and compile the song, exporting the song data only.

As this is a tune for the main menu, it is set to loop back to the LOOP START and to exit when a key is pressed. This is the default for the engines Noel has converted. (The Enterprise Engine looks at the bottom row of key rather than "any key". I tend to put "Press Space to Exit" on screen rather than "press any key" as Space will always work).

If you need an alternative option for your songs (e.g. EXIT at the end of the song) this is easy enough to implement if you know assembler. If you don't, you can export two versions and compare them side-by-side and play "spot the difference" as the core engine will be the same, it'll just be the song control/ flow routines that will have changed.

If you want the tune to play once then exit, for the Tritone Engine you'll be looking for a bit of code that looks like:

ORDER_LOOP: LD E,(HL)
INC HL
LD D,(HL)
EX DE,HL
JR NEXT_POS_READ

which will need to be changed to:

ORDER_LOOP: LD E,(HL)
INC HL
LD D,(HL)
EX DE,HL
;JR NEXT_POS_READ
JR STOP_PLAYER ; do not loop when song over

You will usually just use one of the beepola engines in your game. If you need (or want) to use multiple engines, you will need to do some editing of the assembler code for the engines as they tend to share LABELS and having multiple LABELS with the same name will cause the game build to fail with duplicate LABEL errors.

As Noel has provided assembler for the Tritone Beeper engine, I will just be attaching the song data to that code. An alternative would be for you to extract your song data from your existing USER.ASM file for the Spectrum version of the game.

IMPORTANT! IF YOU ARE USING THE USER.ASM FROM YOUR SPECTRUM GAME, ENSURE YOU AREN'T EDITING THE ONLY COPY OF THE USER.ASM FILE FOR YOUR SPECTRUM GAME. ONLY EDIT A COPY.

(Maybe make a backup of your Spectrum game code if you haven't already done so before you start.).

What I do is save the USER.ASM for the game I'm working on in the AGDsources folder along with the AGD file for the game; using a file name of " the game name-USER.ASM". In this instance, I create a file named: THEART-USER.ASM for the beepola tunes.

When you build your game, this file will need to be copied into the SJASM folder with the name USER.ASM.

Part Three. Using batch files to make your life easier.

At this point, I feel it is a good time to talk about making things easier for yourself. When you build your game, you are supplying a bunch of different source files to various parts of the compilation process. As you are only using the command line to do this, it is easy to miss a part of the process, or forget to add a parameter to the build.bat process; or worse, accidentally overwrite something.

What I do is, as mentioned at the end of part two, I give the files the same filename-start (which relates to the game I'm building). I also use the AGDsources folder as my primary source folder. This makes it easy to backup (as I can just right-click the folder in Windows and tell Windows to send it to a compressed folder (a .zip archive) and then save this somewhere safe) and to access for edits etc.

For Throbby Heartache, my batch file will look like this:

cd "C:\dev\v0.7.10-old5\V0.7.10\Suite EP\AGD"
COPY /Y ..\AGDsources\THEART.AGD THEART.AGD
COMPILEREP.EXE THEART -u
COPY /Y THEART.ASM ..\SJASM
CD ..\SJASM
COPY /Y ..\AGDsources\THEART-USER.asm USER.asm
sjasm THEART.ASM THEART.COM
COPY /Y THEART.COM ..\EP128-2.0.11\files\
COPY /Y THEART.PRG ..\EP128-2.0.11\files\
CD ..\EP128-2.0.11

I will save this as theart48k.bat in the SUITE EP folder. When you run this file it will copy your AGD to the AGD folder for the compiler. It then copies the generated ASM code and the USER.ASM code for your game to the SJASM folder to build the game. It then copies the complete game over to the EP128-2.0.11 emulator's files folder so you can access them within the emulator to test.

Note that c:\dev\v0.7.10-old5\V0.7.10\ is where I've installed MPAGD. Change this to where ever you have MPAGD installed. Also change THEART to be the name of your game.

A definite advantage of doing this sort of thing is you always ensure you have the correct USER.ASM for your game. You also build your game with the correct AGD parameters. (Throbby Heartache uses the ULA+ palette defined by the 8 colour DEFINEPALETTE definitions; but other games might need to enable adventure mode (-a) add a loading screen (-l) etc.)

As any coder can tell you. You might not think something simple like this would be useful; but when you come back to the project 3-6 months later and are scratching your head trying to remember what you did to build the game - and inevitably missing something important...

Part Four : Adding the Beepola Engine to your game.

At this point you will have a batch file for building your game. You will have the song you want to add to your game. You just need to grab the engine code to make this all work.

The Beepola Engines can be found in \Suite EP\Sound_SRC\Beepengines_EP .

You will copy the engine code you need (in my case, the Tritone one) in front of the song data you've saved in your AGDsources folder. The easiest way to do this is to copy and paste between two notepad windows.

Open your song data in notepad. The first thing you need to do is remove the ORG 40000 line at the top of the code. In assembler this tells the compiler to put this code at the memory address 40000. However, this will clobber the MPAGD code. Simply delete the line and MPAGD will add this in a memory location after the MPAGD code.

At this point, your song data will start with lines looking like:

MUSICDATA:
; *** Song layout ***
LOOPSTART: DEFW PAT2
DEFW PAT0
DEFW PAT0
DEFW PAT1
DEFW PAT0
DEFW PAT2
DEFW PAT2
DEFW PAT0
DEFW PAT0
DEFW PAT1
DEFW PAT0
DEFW $0000
DEFW LOOPSTART

... etc

If you now open the engine code you need in another notepad window and copy the code from that file in front of the song data.

For me, I would type:

notepad Sound_SRC\Beepengines_EP\tritoneV2_EP.asm

For the time being, you only have a single tune to add, so feel free to delete the first couple of lines. Additionally, the Beepola Engines include an example Tune. (I think it's one of my terrible ones so you won't hurt anyone's feelings by deleting the song data in the engine. Just go to the end of the file where the MUSICDATA label can be found and delete everything (including the MUSICDATA label) onwards.

Then select everything in this file and copy it. Switch to your song data window and paste this data in front of your song data.

At the beginning of the file there will be a label, USER. Add the label user as well. (I think the ZX Spectrum engine looks for USER or is case insensitive, but the Enterprise engine looks for user. It doesn't hurt anything but is a thing to be aware of).

The THEART-USER.ASM will now look like this:

user
USER
or a
ret nz
TRITONE:
; *****************************************************************************
; * Tritone v2 Player (with equal channel volumes)
; *
; * By Shiru (shiru@mail.ru) 03'11
; *
; * Three channels of tone, per-pattern tempo
; * One channel of interrupting drums
; * Feel free to do whatever you want with the code, it is PD
; *
; * Produced by Beepola v1.08.01
; ******************************************************************************

OP_NOP: EQU $00 ; NOP opcode (used for CHECK_KEMPSTON)
OP_SCF: EQU $37 ; SCF opcode (used in CHECK_KEMPSTON)
OP_ORC: EQU $b1 ; OR C opcode (used in CHECK_KEMPSTON)
LD HL,MUSICDATA
CALL TRI_PLAY
RET
TRI_PLAY:
xor a
ld bc,10a0h
clrdave out (c),a
inc c

... etc

Save this file and you can then try and build it.

That looks positive! It built without errors. If you get errors, check you haven't made a typo with your filenames. If you get any errors on the assembler side of things, cross-check your beepola engine code against the default code and make sure you haven't got a duplicate label or deleted a line you need.

Next thing to do is to try and run the code. When you build using build.bat it automatically starts the emulator and loads your game. My batch file doesn't do that because I know I make mistakes and I like to read the errors before trying to run the game.

Start the emulator by typing:

ep128emu.exe -no-opengl

You can then start the game (providing you configured your emulator correctly) by typing

run "gamename.com"

eg.

If all goes well, your game will startup and you'll be greeted by the tune you've exported from the Spectrum. If something goes wrong, or the song sounds different to the Spectrum version, check your engine code and make sure you haven't deleted an xor a or something similar from the USER.ASM code. Also make sure you've picked the correct engine for your song data (as different beepola engines use different amounts of data, for obvious reasons).

In my case, the game starts, the tune plays. But I realise I've forgotten to put a message on screen telling the player to "press space to continue" so I need to return to my AGD code and add a line of text into the intro menu code. What I will do is pop the message in the "press 1, press 2, press 3" options area replacing the options while the tune plays.

I'll then rebuild using my theart48k.bat file and check it works.

Part Five : Adding a second tune to your game.

Now you've added one song, what stops you from adding a second (or third or fourth tune)? Nothing. You just need to do a little careful editing of your USER.ASM (remember, in this case it is the GAMENAME-USER.ASM in the AGDsources folder you'll be editing).

First, compile your second song assembly code from Beepola (or copy it from your Spectrum User.asm file).

For Throbby Heartache I will be adding an additional three tunes. One for "A new high score", one for "Game Over" and one for "Game over, but won the game"

To do this, you'll need to save out the additional assembly code song data from Beepola (or extract it from your existing USER.ASM for the Spectrum game). You'll then need to make a few edits to your GAMENAME-USER.ASM file to allow you to call each individual tune in your code by putting:

For Tune 1 : USER 0
For Tune 2: USER 1
For Tune 3: USER 2
For Tune 4: USER 3

First, open your GAMENAME-USER.ASM file. After your first music data you will add the second music data (for the second tune).

However, you might notice that the labels here are still MUSICDATA, LOOPSTART etc. The same labels you see in your first tune. This will cause a problem; but it's one that is simple to fix. Simply add a 01 to the end of each of the labels. MUSICDATA becomes MUSICDATA01, LOOPSTART becomes LOOPSTART01,  PAT0, PAT1,PAT2,PAT3 etc. become PAT010 PAT011 PAT012 PAT013 etc. Again, if there is an ORG 40000 line, remove it.

Repeat this process with each tune you want to add to your game, making sure all patterns and data labels have unique names. (You probably did this when you made the Spectrum game, but it's always good to be reminded to do something you remember than fail to be reminded to do something you forgot!)

Once your songs are added, you will need to make a few changes to the beginning of the file (so the game knows which tune to play in which situation).

Change the beginning of the GAMENAME-USER.ASM file to say:

user
USER

OP_NOP:         EQU   $00                 ; NOP opcode  (used for CHECK_KEMPSTON)
OP_SCF:         EQU   $37                 ; SCF opcode  (used in CHECK_KEMPSTON)
OP_ORC:         EQU   $b1                 ; OR C opcode (used in CHECK_KEMPSTON)

; those definitions were moved from after the comment in case they are needed as the code
; will ignore them from this point onwards 

cp 0
jr nz, chk1
ld hl,MUSICDATA
jp start0

chk1
   cp 1
   jr nz, chk2
   ld hl,MUSICDATA01
   jp start0

chk2
   cp 2
   jr nz, chk3
   ld hl,MUSICDATA02
   jp start0

chk3
   cp 3
   jr nz, chk4
   ld hl,MUSICDATA03
   jp start0

chk4
  ret

And then, after the Beepola comment and the LD      HL,MUSICDATA but before   call TRI_PLAY (or whichever command follows LD HL,MUSICDATA in the engine you are using), the label:

start0:

If you now save all your code and use your batch file to rebuild the game, it should compile without any issues and you should have multiple tunes attached.

For ref: Your GAMENAME-USER.ASM code should look something like:

user
USER
OP_NOP:         EQU   $00                 ; NOP opcode  (used for CHECK_KEMPSTON)
OP_SCF:         EQU   $37                 ; SCF opcode  (used in CHECK_KEMPSTON)
OP_ORC:         EQU   $b1                 ; OR C opcode (used in CHECK_KEMPSTON)
cp 0
  jr nz, chk1
  ld hl,MUSICDATA
  jp start0

chk1
  cp 1
  jr nz, chk2
  ld hl,MUSICDATA01
  jp start0

chk2
  cp 2
  jr nz, chk3
  ld hl,MUSICDATA02
  jp start0

chk3
  cp 3
  jr nz, chk4
  ld hl,MUSICDATA03
  jp start0

chk4
  ret

TRITONE:

; *****************************************************************************
; * Tritone v2 Player (with equal channel volumes)
; *
; * By Shiru (shiru@mail.ru) 03'11
; *
; * Three channels of tone, per-pattern tempo
; * One channel of interrupting drums
; * Feel free to do whatever you want with the code, it is PD
; *
; * Produced by Beepola v1.08.01
; ******************************************************************************

                LD      HL,MUSICDATA

start0:         CALL    TRI_PLAY
                RET

TRI_PLAY:
        xor     a
        ld      bc,10a0h
clrdave out     (c),a
        inc     c

... etc ...

; ************************************************************************
; * Song data...
; ************************************************************************

BORDER_CLR:          EQU $0
; *** DATA ***
MUSICDATA:
; *** Song layout ***
LOOPSTART:            DEFW      PAT2
                      DEFW      PAT0
                      DEFW      PAT0

... etc ....

                DEFB      $01    ,$01    ,$80,$D2
                DEFB  $FF  ; End of Pattern
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; song 02
MUSICDATA01:

; *** Song layout ***

LOOPSTART01:            DEFW      PAT010
                      DEFW      PAT010
                      DEFW      PAT012

... etc for each of your songs

Part six : Let's add a loading screen.

The final thing you need to do is transfer the Spectrum loading screen to the Enterprise (if you want a loading screen). This is an easy process so long as you have a copy of the screen you want to use in .SCR format. Tools like ZX PAINTBRUSH will save in this format, but you can probably extract the SCREEN$ file from your Spectrum tape image to use here.

Because I do everything with my batch file, I will put the Screens file in the same location as my GAMENAME-USER.ASM and my GAMENAME.AGD code. To be consistent, I'll name it GAMENAME.SCR. In this instance, it will be THEART.SCR

You then need to  edit your batch file to copy the SCR file over to the SJASM folder for when the final game is compiled and built, and you need to add the -l (that's a lowercase L in case the font is confusing) to the COMPILEREP.EXE line.

Your batch file should now look something like this:

cd "C:\dev\v0.7.10-old5\V0.7.10\Suite EP\AGD"
COPY /Y ..\AGDsources\THEART.AGD THEART.AGD
COMPILEREP.EXE THEART -u -l
COPY /Y THEART.ASM ..\SJASM
CD ..\SJASM
COPY /Y ..\AGDsources\THEART-USER.asm USER.asm
COPY /Y ..\AGDsources\THEART.SCR THEART.SCR
SJASM THEART.ASM THEART.COM
COPY /Y THEART.COM ..\EP128-2.0.11\files\
COPY /Y THEART.PRG ..\EP128-2.0.11\files\
CD ..\EP128-2.0.11

Now when you build and load your game, you will be presented with a loading screen and when you press a key, the game will start.

Part Seven : Aftermath

So that gets you a Spectrum game, with music, converted over to the Enterprise.

But what if you want some in-game music, or what to use Spectrum 128K Tunes? My next tutorial will cover adding protracker 3 AY tunes into your Enterprise game.  I hope you find these tutorials useful. If you have any questions, feel free to add a comment.