08-09-2011, 09:09 AM
Using Beepola to add tunes to your ZX BASIC projects is actually pretty easy. Beepola is able to export its players and songs as .TAP files, which you can then merge in with your own code and call from ZX BASIC using standard RANDOMIZE USR calls.
Here's a quick how-to:
1. Make your tune. I can't help much with this bit, but I've successfully managed to integrate the Music Box, Phaser1 and Special FX engines into ZX BASIC, so I surmise they will all work. You can download Beepola from here: http://freestuff.grok.co.uk/beepola/
2. Now you need to compile your tune so that it's useful from ZX BASIC. You do this by selecting 'Compile' from Beepola's 'Tools' menu, which pops up a window with some options. The most important thing here is to make sure you set the player and song to use an area of memory which won't interfere with your own program. I tend to set this high in memory (64000 and up), but bear in mind that each player uses a different amount of memory and you'll also need to leave room for your song data. Each player has a different set of options, but basically it's all up to you here - choose whatever's best for your tune and situation.
3. The easiest way to integrate the song and player is to choose to export from Beepola as a .TAP file. I usually choose the 'code block only' option because you're not going to need the BASIC loader. Once that's saved, you need to load your game AND the player into memory at the same time. It's actually pretty easy to automate all of this using batch files (or their equivalent if you're non-Windows), because .TAP files are remarkably easy to join together. During Dex development, I created a BASIC loader which loaded my game code and the music code and saved that as a .TAP file. Then I used a batch 'make' file like this to build and assemble the game into a single .TAP.
e.g. BASIC LOADER (saved as loader.tap)
e.g. BATCH FILE (saved as make.bat)
The first line of the batch file compiles the game. Once done, the 'copy' command takes the loader, game code and tune and merges them all together into one large .TAP file (called Dex.tap) that I can just double-click and run. Don't forget the /b switch on the copy operation, otherwise the files will be copied as text rather than binary and probably won't work.
4. If your game is to have multiple tunes, you only need to have one copy of the player - you don't need a separate copy of the player for each tune. Each Beepola engine has a couple of POKEable memory addresses near the start of the player code which points to the tune to be played. If you make more than one tune, export those from Beepola as 'song data only' .TAP files. Make sure that you choose the same settings as for your main tune and that you place the song data at a memory location that is away from both your game code AND the first tune's code.
5. During all of these steps, remember to keep track of the memory addresses that you have compiled the music data to. This is rather important as without the addresses you won't know what to call from your game. Including the address in your filenames as a reminder might be a good idea!
6. Once you have everything ready to go, all that's left to do is to call the player from within your own ZX BASIC code. This is actually very simple - just a standard RANDOMIZE USR xxxxx call (where xxxxx is the address you compiled the player to) will do the trick. However, if you're making this call from within a ZX BASIC sub or function block, be aware that you need to preserve the IX register or the Spectrum is likely to crash - more details on this below. If you wish to play one of the 'extra' tunes described in point 4, you'll first need to POKE the relevant memory addresses with the location of the new song data - Beepola's documentation will tell you how to calculate what these addresses are for each individual engine.
7. This all sounds a bit complicated, but it really isn't. It's probably easier to show in an example, so I'll show you how I created my music playing subroutine for Dex. See the code fragment below:
This routine is basically all of the stuff I described above squashed into a single sub. The main music player was compiled and loaded to 64000, which I've put into a constant. The three tunes I use also have their memory locations described by constants. To play a tune, I call 'playMusic(TUNEMAIN)' (or whatever) and the SUB does all the rest.
You'll see that the address of the tune is determined by the constant I pass - this address is then POKEd into the player engine as described in Beepola's docs. Because we're calling from a SUB, the IX register needs to be preserved - this is easily done with a simple 'push ix' in an ASM block. Once we've done that, it's safe to call the player with 'RANDOMIZE USR'. Once the player returns control to us, we 'pop' the value of IX to allow us to return safely from the subroutine.
Job done!
I hope this is clear, it seems a lot more complicated to write down than it is in my head. If anyone has further questions, please feel free to ask!
Here's a quick how-to:
1. Make your tune. I can't help much with this bit, but I've successfully managed to integrate the Music Box, Phaser1 and Special FX engines into ZX BASIC, so I surmise they will all work. You can download Beepola from here: http://freestuff.grok.co.uk/beepola/
2. Now you need to compile your tune so that it's useful from ZX BASIC. You do this by selecting 'Compile' from Beepola's 'Tools' menu, which pops up a window with some options. The most important thing here is to make sure you set the player and song to use an area of memory which won't interfere with your own program. I tend to set this high in memory (64000 and up), but bear in mind that each player uses a different amount of memory and you'll also need to leave room for your song data. Each player has a different set of options, but basically it's all up to you here - choose whatever's best for your tune and situation.
3. The easiest way to integrate the song and player is to choose to export from Beepola as a .TAP file. I usually choose the 'code block only' option because you're not going to need the BASIC loader. Once that's saved, you need to load your game AND the player into memory at the same time. It's actually pretty easy to automate all of this using batch files (or their equivalent if you're non-Windows), because .TAP files are remarkably easy to join together. During Dex development, I created a BASIC loader which loaded my game code and the music code and saved that as a .TAP file. Then I used a batch 'make' file like this to build and assemble the game into a single .TAP.
e.g. BASIC LOADER (saved as loader.tap)
Code:
10 CLEAR 29999: LOAD "" CODE: LOAD "" CODE: RANDOMIZE USR 30000e.g. BATCH FILE (saved as make.bat)
Code:
"\program files\zxbasic\zxb.py" dex.bas --output=dexgame.tap --org=30000 -t -Z
copy /b loader.tap + dexgame.tap + DexJingle.tap Dex.tapThe first line of the batch file compiles the game. Once done, the 'copy' command takes the loader, game code and tune and merges them all together into one large .TAP file (called Dex.tap) that I can just double-click and run. Don't forget the /b switch on the copy operation, otherwise the files will be copied as text rather than binary and probably won't work.
4. If your game is to have multiple tunes, you only need to have one copy of the player - you don't need a separate copy of the player for each tune. Each Beepola engine has a couple of POKEable memory addresses near the start of the player code which points to the tune to be played. If you make more than one tune, export those from Beepola as 'song data only' .TAP files. Make sure that you choose the same settings as for your main tune and that you place the song data at a memory location that is away from both your game code AND the first tune's code.
5. During all of these steps, remember to keep track of the memory addresses that you have compiled the music data to. This is rather important as without the addresses you won't know what to call from your game. Including the address in your filenames as a reminder might be a good idea!
6. Once you have everything ready to go, all that's left to do is to call the player from within your own ZX BASIC code. This is actually very simple - just a standard RANDOMIZE USR xxxxx call (where xxxxx is the address you compiled the player to) will do the trick. However, if you're making this call from within a ZX BASIC sub or function block, be aware that you need to preserve the IX register or the Spectrum is likely to crash - more details on this below. If you wish to play one of the 'extra' tunes described in point 4, you'll first need to POKE the relevant memory addresses with the location of the new song data - Beepola's documentation will tell you how to calculate what these addresses are for each individual engine.
7. This all sounds a bit complicated, but it really isn't. It's probably easier to show in an example, so I'll show you how I created my music playing subroutine for Dex. See the code fragment below:
Code:
'some constants
const TUNESON as UBYTE = 1
const TUNEPLAYERADDR as UINTEGER = 64000
const TUNE1 as UINTEGER = 64798
const TUNE2 as UINTEGER = 64850
const TUNE3 as UINTEGER = 64900
const TUNEMAIN as UBYTE = 1
const TUNELEVELSTART as UBYTE = 2
const TUNELEVELEND as UBYTE = 3
const TUNEGAMEOVER as UBYTE = 4
'plays a piece of music
SUB playMusic(tune as UBYTE)
DIM SongAddr as UINTEGER = 0
'select the correct tune
if tune = TUNEMAIN then
SongAddr = TUNE3
elseif tune = TUNELEVELSTART then
SongAddr = TUNE1
elseif tune = TUNELEVELEND then
SongAddr = TUNE3
elseif tune = TUNEGAMEOVER then
SongAddr = TUNE2
end if
'call the music player
if TUNESON = 1 and SongAddr > 0 then
'poke the values for the tune start
poke TUNEPLAYERADDR + 1, SongAddr - 256 * INT(SongAddr / 256)
poke TUNEPLAYERADDR + 2, INT(SongAddr / 256)
'and play the tune (remember to preserve IX register or it'll crash)
asm
push ix
end asm
randomize usr TUNEPLAYERADDR
asm
pop ix
end asm
end if
END SUBThis routine is basically all of the stuff I described above squashed into a single sub. The main music player was compiled and loaded to 64000, which I've put into a constant. The three tunes I use also have their memory locations described by constants. To play a tune, I call 'playMusic(TUNEMAIN)' (or whatever) and the SUB does all the rest.
You'll see that the address of the tune is determined by the constant I pass - this address is then POKEd into the player engine as described in Beepola's docs. Because we're calling from a SUB, the IX register needs to be preserved - this is easily done with a simple 'push ix' in an ASM block. Once we've done that, it's safe to call the player with 'RANDOMIZE USR'. Once the player returns control to us, we 'pop' the value of IX to allow us to return safely from the subroutine.
Job done!
I hope this is clear, it seems a lot more complicated to write down than it is in my head. If anyone has further questions, please feel free to ask!
I've managed to put one song with this method but now that I know that the player can be reused, I can put more that one in a game without loss too much memory.