Tutorial 3: Converting MPAGD ZX Spectrum Games to the Enterprise: Games with AY Music.

Part One: A quick recap.

In the previous tutorials I covered setting up your environment (Tutorial 1) and adding Beepola music to your MPAGD game (Tutorial 2) that had been converted from the ZX Spectrum to the Enterprise.

I also introduced the idea of using a batch file to ensure all your files are compiled with the correct parameters / compiler flags. This becomes more useful when you look at adding protracker tunes to your game. You will need to copy your music files and an edited piece of assembler for your game.

Part Two: Introducing MPAGDMusicizer (ZX Spectrum) way of doing things

One of the most common ways of adding AY music (128K music) to Spectrum games written in MPAGD is by using MPAGDMusicizer created by David Saphier. This application makes it easy to add up to 4 protracker tunes to your game. You write your code as usual, but use the variable "Z" to control the music.

If you set Z to 1,2,3 or 4 then tune 1, 2, 3 or 4 will start playing.

If you se Z to 32 then the music will stop playing.

After you export your Spectrum game, you run in through the MPAGDMusicizer and your (up to) 4 tunes are added to the game.

To make things easy, the MPAGDMusicizer protracker engine has been ported over to the Enterprise version.

To use it, look in the SOUND_SRC\AY_EP folder.

In this folder you will find a py3play.asm file. You will need to edit this file (or, make a copy specific to your game). If you open the file, the first few lines look like:

VAR     equ     varz                     ;update music variable

;        define  PT3MUS1 "music01.pt3"   ;update name of 1st music if exist

;        define  PT3MUS2 "music02.pt3"   ;update name of 2nd music if exist

;        define  PT3MUS3 "music03.pt3"   ;update name of 3rd music if exist

;        define  PT3MUS4 "music04.pt3"   ;update name of 4zh music if exist

uncomment (remove the ;) from the beginning of each define PT3MUS lines for each song you want to add to your game. Either change the name of the files (music01-04.pt3) to your music file names, or change your music files to music01,02,03 and 04.pt3.

Once that is done you are able to run the build.bat with the -3 parameter and your game will build and include any protracker tunes you've included.

Part Three: Why use batch files?

As you write more and more games, you'll end up having multiple music files and having to make edits to the py3play.asm file. To avoid attaching the wrong music to the wrong game, or accidentally erasing your music files, I add them to the batch file.

What I do is name all the files associated with the game the same. An example being my game, Painter Man!! which consists of the following files:

PAINTEP.AGD - Painter man AGD source

PAINTEPP3.ASM - AGD Musicizer assembler code

PAINTEP01.PT3 - Protracker tune 1 (menu)

PAINTEP02.PT3 - Protracker tune 2 (main game)

PAINTEP03.PT3 - Protracker tune 3 (failure tune)

PAINTEP04.PT3 - Protracker tune 4 (success tune)

PAINTEP.SCR - Painter man loading screen

I then create a file, paint.bat which will copy these over to the relievant places and then builds the game.

The batch file looks like:

cd "Suite EP\AGD"

COPY /Y ..\AGDsources\PAINTEP.AGD PAINTEP.AGD

COPY /Y ..\AGDsources\PAINTEPP3.ASM ..\Sound_SRC\AY_EP\pt3play.asm

COPY /Y ..\AGDsources\PAINTEP01.PT3 ..\Sound_SRC\AY_EP\music01.pt3

COPY /Y ..\AGDsources\PAINTEP02.PT3 ..\Sound_SRC\AY_EP\music02.pt3

COPY /Y ..\AGDsources\PAINTEP03.PT3 ..\Sound_SRC\AY_EP\music03.pt3

COPY /Y ..\AGDsources\PAINTEP04.PT3 ..\Sound_SRC\AY_EP\music04.pt3

COPY /Y ..\AGDsources\PAINTEP.SCR ..\SJASM

COMPILEREP.EXE PAINTEP -u -3 -l

COPY /Y PAINTEP.ASM ..\SJASM

CD ..\SJASM

COPY /Y ..\AGDsources\DEFAULT.asm USER.asm

sjasm PAINTEP.ASM PAINTEP.COM

COPY /Y PAINTEP.COM ..\EP128-2.0.11\files\

COPY /Y PAINTEP.PRG ..\EP128-2.0.11\files\

CD ..\EP128-2.0.11

And that is really all there is to it.

You might get an error if your Spectrum game is too large, and you will get an error if your music files cannot be found (or none are defined). Other than that, it just will work as expected.