Z80 player compatibility

Still compiling on a real CPC? Scroll at the bottom if you use Orgams.

From version a4, Arkos Tracker 2 Z80 players target Rasm, an efficient and powerful cross-platform assembler by Roudoudou.

This may be a problem for those working with other assemblers and are unable/unwilling to make a switch. This is particularly true when using an embedded assembler, such as the one from Winape.

There is a simple solution, but it has one drawback: it will impose you to force your music and player address.

Wrapper for Rasm

First of all, have a small Z80 code, called “wrapper.asm”, which we will compile with Rasm. It will embed the player and music:

  org #1000     ;This is the fixed address of the player/music
PlayerAndMusicBinary_Start
  include "resources/mysong.bin"
  include "resources/mysong_playerconfig.asm"

  include "playerAkg.asm"  ;It works for any other player.
PlayerAndMusicBinary_End

Note: if you’re wondering what is that “player config” file, please check this page. This is optional, but don’t be afraid to use this great feature!

Now, when compiling this, we’ll ask Rasm to export the symbols as Z80 code. This requires Rasm >=0.101, so check your version first:

rasm wrapper.asm -o wrapper -sc "%s equ %d"

This command will compile our “wrapper.asm”, generating “wrapper.bin” (the binary), and a symbol file called “wrapper.sym“. However, thanks to the magic “sc” command, the latter has been generated as a Z80 file. Indeed, the symbols have this structure:

PLAYERANDMUSICBINARY_START equ 4096
MYSONG_START equ 4096
...
PLY_AKG_INIT equ 5123
PLY_AKG_PLAY equ 5126 PLY_AKG_STOP equ 5129
...
PLAYERANDMUSICBINARY_END equ 6780

There are many labels present, but we don’t care about them. Please note that Rasm generates upper-case labels.

So now, in your real code using your favorite assembler (Vasm, Winape, SJAsmPlus, etc.), simply do this:

  ;Loads the symbols for the music and player.
include "wrapper.sym"

;Includes the music and player binary.
org PLAYERANDMUSICBINARY_START
include "wrapper.bin"

org #4000
;This is my super game.
...
;Initializes the song.
ld hl,MYSONG_START
xor a ;Subsong 0.
call PLY_AKG_INIT
...
;This is the main loop.
call PLY_AKG_PLAY

That’s it! The PLY_AKG_INIT/PLAY labels can be conveniently used because they are declared in “wrapper.sym”. You don’t have to compile “wrapper.asm” again, unless the music changed, or you want to change its compilation address (from #1000 to anything else).

Please don’t hesitate to contact me if you have any trouble making this work.

Orgams

People wanting to use Orgams on their beloved CPC are not left behind: a raw converter will make the import less painful. This converter is written in Python (download Python >=3 here), and is in the package here: players/sourceToOrgams.py.

Use the -h option to get the options, but the main usage is:

python sourceToOrgams.py -i <Z80 input file> -o <Orgasm output file> [-rc] [-oe <address>]

Use the -rc option to Remove the Comments, which can come in handy to limit the memory consumption.

Use the -oe option to add the ORG <address> / ENT $ mnemonics at the beginning of the source.

Warning, the current version of Orgams produces a “DOS error” at the end of the import. Fortunately, the import still works anyway. The AKY source has been successfully imported. The Lightweight produces some errors, because of Orgams inability to use forward declaration for IX/IY. This can be changed by modifying the source, but I will not do it as it would reduce the code readability.