Spectrum game disassembly toolkit

SkoolKit 10.0 (years)

No, I haven’t become impatient (or lost the ability to count) and skipped straight from version 8.0 to version 10.0. Today is SkoolKit’s 10th birthday! Or, to put it another way, SkoolKit 1.0 was released ten years ago today.

Not surprisingly, SkoolKit has improved a bit since version 1.0 (if I do say so myself). Back then, the documentation was a single HTML page, and contained very little info on how to use ref files. A control file was a plain list of block-level directives and addresses only - block titles, comments, register values etc. were not supported. was designed primarily to build the disassemblies of Skool Daze and Back to Skool, with the ability to process an arbitrary skool file tacked on as an afterthought. was quite buggy - it disassembled several instructions incorrectly. Of the 40 available skool macros, no fewer than 14 were specific to (i.e. useful only in) the Skool games. And if you wanted to work in hexadecimal, you were out of luck.

Since we’re in a nostalgic mood (well I am, anyway), let’s sit back and enjoy some snippets of SkoolKit history that you may not have been aware of.

  • The initially buggy was something of a rush job, added to the SkoolKit source code repository on 2010-01-25, three days before 1.0 was released. Before it was developed, I used a modified version of D52’s Z80 disassembler to create skool files. D52 was also the source of inspiration for SkoolKit’s control files.

  • first appeared in the repository on 2008-07-26, as a consolidation of several scripts previously used to build specific parts of the HTML versions of the Skool Daze and Back to Skool disassemblies. It gained the ability to work with a skool file other than sd.skool or bts.skool on 2010-01-26, two days before 1.0 was released.

  • first appeared in the repository on 2009-07-03, almost a year after I developed it mainly because someone showed interest in modifying the source code for Skool Daze, and (understandably) found it awkward to work with the skool file as opposed to a conventional assembler source file.

  • Of the skool macros that are still around today, the first one to be implemented was #R. It was used for the first time on 2008-07-16 in the Skool Daze disassembly. Before that, the first macro to be implemented was $TAPS (which later became #TAPS), on 2008-07-08.

  • The name ‘SkoolKit’ first appeared in the documentation on 2010-01-20, eight days before 1.0 was released.

So, let’s raise a glass to SkoolKit’s 10th birthday, and wish it well for the next 10 years of Spectrum game disassembly!

Plugging away

SkoolKit 8.0 has been released. At your earliest convenience, please head over to the download page, the Python Package Index, the Ubuntu PPA, or the Fedora copr repo to pick up a copy.

As has become customary with N.0 releases, this one brings changes that cause chaos by breaking compatibility with previous versions. Among the most disruptive of those changes are the eradication of skool file templates (and therefore, the dropping of support for GIF images, and the complete overhaul of HTML templates. On the other hand, if you never cared for skool file templates, have always scoffed at GIF images, and wouldn’t spit on an HTML template if it caught fire, then you’ll probably notice very little difference between this release and 7.2. In any case, for all the details on how SkoolKit 8 might break your disassembly, and some tips on how to fix it, see the migration guide.

As for new features, the aforementioned HTML templates now support three directives for conditionally including and repeating content: foreach, if and include. This means that you now have much finer control over how HTML pages are laid out, should you ever wish to exercise it. The introduction of these directives has also enabled me to reduce the number of HTML templates required to render all your disassembly content. Humour me for a moment while I relay some facts about the history of HTML templates in SkoolKit. I started developing them after 3.7 was released, and at one point there were 75 of them. Realising that 75 was an unmanageably large number, I eventually reduced it to 23 in time for the release of 4.0. Then that number crept back up 31 when 6.0 was released. But now, for the release of 8.0, I can proudly assert that the number has been reined in and reduced to 16. Smaller than 23 or 31, and a power of 2 to boot.

The other big new feature is that SkoolKit now has pluggable components. If you’ve ever been dissatisfied with how SkoolKit disassembles code, assembles skool files, generates control files, reads snapshots, converts the base or case of an instruction, or formats HTML templates, then you’ll be happy to hear that all you have to do to achieve satisfaction is learn Python if you haven’t already, and then plug in your own implementation of one or more of these functions. Sick of the Zilog Z80 and want SkoolKit to tear apart Motorola 6800 code instead? Go for it. Prefer octal to binary, decimal and hexadecimal, and frustrated that SkoolKit doesn’t support it? Now you can fix it. Annoyed that SkoolKit won’t read snapshots produced by your favourite but hopelessly obscure emulator? At this point, I’m sure you get the idea.

Also making the news in this release is the #PC macro - the first new macro since #RAW was introduced back in 6.4 over 18 months ago. Like #VERSION, it takes no arguments, but unlike #VERSION, it expands to the address of the closest instruction instead of the version number of SkoolKit. (I hope that comparison with the #VERSION macro has made its purpose and usage clear.) I expect #PC to be most convenient in instruction-level comments, particularly when used in conjunction with #PEEK, where it could replace addresses that would otherwise have to be hard coded.

Of course, there are several other changes in SkoolKit 8.0, most of which pose no danger at all to your existing disassemblies. Such as the ability to specify the characters used to render table borders in ASM mode, and the ability to specify a header prefix and suffix for every page (not just the home page). For more details on these and the other less attention-worthy changes in this release, I refer you to the changelog. Happy component plugging!

Byte values for everyone

SkoolKit 7.2 has been released. Copies are, as usual, available on demand from the download page, the Python Package Index, the Ubuntu PPA, and the Fedora copr repo.

Making the headlines in this release is the ability of control files to specify comments over multiple lines by means of the new dot directive. This makes long comments much easier to read and write, and also enables #LIST and #TABLE macros to be recorded in the natural way: line by line, as they would typically appear in the skool file. In addition, will restore such comments line by line, giving you much greater control over the layout of a skool file that is built from a control file. And on top of that, the new --keep-lines option of will use dot directives to preserve comments. In light of these new powers, support for skool file templates has been deprecated.

Also vying for attention in this release are ASM templates. Finally, after five years (or thereabouts) of HTML templates, SkoolKit now also provides the ability to tinker with the output of Just point the new Templates configuration parameter of at a file containing your own custom comment, equ, instruction, label, org and register templates, and off you go.

Not to be outdone, HTML templates have struck back with the ability to display the byte values of assembled instructions via the asm_instruction template. Just set the new Bytes parameter in the [Game] section to your desired byte format specification (e.g. Bytes=02X), and make sure instructions are actually assembled by using @assemble=2.

And that’s it for the most conspicuous new features in 7.2. For details on the less conspicuous new features, head over to the changelog, where you can learn about configuration parameters for and how the #LINK and #R macros now work with upper case hexadecimal address anchors (among other things).