Spectrum game disassembly toolkit

An @if but no @but

Do not expand this macro

SkoolKit 6.4 has been released. To get your copy, pop along to the download page, the Python Package Index, the Ubuntu PPA, or the Fedora copr repo.

Continuing the trend of new ASM directives that was started in 6.3, this release brings us the @if directive. As its name implies, it can be used to conditionally process other ASM directives. The variables it can use are the same as those available to the #IF and #MAP macros: asm, base, case, fix (new in 6.4), html and vars (also new in 6.4). So, for example, if you want to replace ‘foo’ with ‘bar’ in HTML mode, but with ‘baz’ otherwise, you could do this:


As noted above, the fix and vars replacement fields are new in this release. fix indicates the fix mode (0, 1, 2, 3 for none, @ofix, @bfix, @rfix), and vars is a dictionary that holds values defined by the new --var option of and In addition, asm now indicates the exact ASM substitution mode (0, 1, 2, 3 for none, @isub, @ssub, @rsub) instead of just being 0 or 1.

Still on the subject of ASM directives, @isub, @ssub, @rsub, @ofix, @bfix and @rfix can now replace not only the instruction on a given line, but also the comment that goes with it. This capability reduces the need for using ASM block directives (@bfix+begin etc.), which cannot be preserved in a control file.

Moving on to the skool macro department, this release introduces the second and final new macro of the 6.x series: #RAW. If you’ve ever been annoyed by SkoolKit’s inability to render a hexadecimal number higher than 40959 (0x9FFF) in upper case with a ‘#’ prefix (e.g. #ABCD), #RAW will quickly become your new best friend. It prevents any macros or macro-like tokens in its sole string argument from being expanded. So you can now write #RAW(#BEEF), safe in the knowledge that SkoolKit will not complain about ‘#BEEF’ being an unknown macro.

Finally, a word about the venerable #LIST and #TABLE macros. In previous versions, neither of these macros could be used in an instruction-level comment or as a parameter of another macro in ASM mode. That restriction has been lifted in 6.4. Since no one’s ever complained to me about it before, I must conclude that either no one noticed, or no one really cared. But preventing the use of these macros in those locations in that mode made no sense, so there we go.

For details on the other new features in this release, I will point you to the changelog. I would also recommend taking note of all the deprecated features, so that you’ll be ready for 7.0 when it arrives. See you then!

Control freak

@remote control

SkoolKit 6.3 has been released. Copies are, as you read this, rolling off the assembly lines in the usual locations: the download page, the Python Package Index, the Ubuntu PPA, and the Fedora copr repo.

Arriving only 7 weeks after 6.2, but still packing one of the largest changelogs in SkoolKit history, this new version of your favourite Spectrum disassembly toolkit brings 4 new ASM directives, 3 enhancements to existing ASM directives, 2 new command options, 3 bug fixes, and a whole bunch of other stuff. Given this embarrassment of riches, it’s difficult to know where to start.

So let’s start with the new ASM directives. The first three are @defb, @defs and @defw, which mimic DEFB, DEFS and DEFW statements without having to appear anywhere in the memory map, and also override the contents of the memory snapshot. Now just a minute, you may be thinking. Isn’t the purpose of these directives already served by data definition entries? To which I would respond: Yes, but hold on. The @def* directives are no mere cheap imitation of ‘d’ blocks. Unlike ‘d’ blocks, they can be preserved in a control file, and will override the contents of the snapshot when is reading them from a control file.

While you ponder the significance of that nugget of info, let me introduce the fourth new ASM directive: @remote. It creates a remote entry that enables JR, JP and CALL instructions to hyperlink across skool files. By now, you might have guessed the main advantage of using @remote over the traditional ‘r’ block. Yes, it can be preserved in a control file. Clearly, the ability to be preserved in a control file is a big theme in 6.3. (SkoolKit historians may also like to note that @remote is uncannily similar to the !refs directive in SkoolKit 1.x.)

Still on the subject of ASM directives, the @label directive can (and should) now be used to emulate the (now redundant) @nolabel directive by providing a blank label: @label=. Also, the @org directive no longer requires an address: it defaults to the address of the next instruction, as you might expect. And finally, the @assemble directive has picked up two new abilities: it can specify what to convert in HTML mode and ASM mode separately, and switch off conversion entirely. Conversion is also now switched off entirely by default in ASM mode, which means should run a little faster.

Let’s finish up with some commentary on the new command options. First, now has a --poke option, which can be useful for POKEing the system variables in a binary file that doesn’t provide its own. And has a --user-agent option for setting the user agent when making HTTP requests. By default, sends no User-Agent header, but if you run into a website that expects one, --user-agent is your friend.

So there we have it. For details on all the other new features and fixes, I advise you to take a gander at the changelog. After that, I suggest you rip out all the ‘d’ blocks, ‘r’ blocks, @nolabel directives and addressful @org directives from your skool files, and stomp them into the dust before providing the 6.3-style replacements. Good times!

In your 0xFACE

@keep it real

SkoolKit 6.2 has been released. As always, copies are available from the download page, the Python Package Index, the Ubuntu PPA, and the Fedora copr repo.

Back in SkoolKit 2.0.6, you may remember, support for hexadecimal numbers began to appear, with control files being the first to allow numbers in either base 10 or base 16. Since then, hexadecimal has established a firm foothold as a first class number base in SkoolKit’s feature set: 2.1.1 saw and gain the ability to convert a disassembly to hexadecimal, and in 4.3 it became possible to render address anchors and disassembly page filenames in hexadecimal. Today, 6.2 continues that tradition by adding support for hexadecimal numbers to SkoolKit’s command options wherever an address, byte, length, step, offset or range limit value is expected. So, for example, you can now do stuff like this:

$ --start 0x8000 --end 0xf800 game.z80 > game.skool
$ --poke 0x9f43,0xff --reg pc=0xc33f game.z80 hacked.z80

In other command-related news, has picked up the --reg and --state options (for setting the value of a register or hardware state attribute). And can now read a binary (raw memory) file when the --binary option is used, and with a specific origin address when the --org option is used. And, and all now sport the --show-config option (for showing configuration parameter values).

Enough about commands. Among the ASM directives, @nolabel is now processed in HTML mode. (This change should have been made back in SkoolKit 3.4 - when support was added for labels in HTML mode - but better late than never.) And the @keep directive is now also applied to instructions that have been replaced by an @isub, @ssub or @rsub directive. This change could affect the output of on an existing disassembly, preventing the substitution of a label for an address in @isub, @ssub or @rsub mode. For example, in SkoolKit 6.1 and earlier, the instruction at 31898 below would be replaced by LD DE,31861%256*256+62 in @ssub mode, and then ‘31861’ would be replaced by a label (if there is one) because the @keep directive is not applied in @ssub mode:

@ssub=LD DE,31861%256*256+62
31898 LD DE,30014

But in 6.2, this @keep directive (originally intended to prevent a label from being substituted for the value ‘30014’) is applied in @ssub mode, and prevents a label from being substituted for ‘31861’. The fix is to use the @keep directive’s new ability to specify the values to keep:

@ssub=LD DE,31861%256*256+62
31898 LD DE,30014

Now, in @ssub mode, ‘31861’ will be replaced by a label, as desired.

And that’s it for the main new features in this release. For details of all the other changes, the changelog is at your service.