It’s time for SkoolKit 3.3. As has become quite the tradition by now, release tarballs, zip archives and whatnot are available from the trusty download page, which has been reliably serving up SkoolKit releases since January 2010. Why not pop by and grab yourself a copy?

The main new feature in 3.3 - which, since we’re all here, I should take a moment to explain - is support for reading code execution logs produced by the Fuse, SpecEmu, Spud, Zero and Z80 emulators. Perhaps that doesn’t sound very exciting, but it actually is. One of the more tedious things about starting to disassemble a Spectrum game is figuring out what’s code and what’s not. SkoolKit will perform a static analysis of the memory snapshot, and do a fair job of finding some of the code, but it cannot get everything right (except by chance); the final decision on whether a chunk of bytes is code or data still requires a human eye (and brain). And given the pressures of daily life in 2013, who really has time for this?

Enter the code execution log. Each of the emulators mentioned in the previous paragraph has the ability to produce a file containing the addresses of the machine code instructions that are executed while a program is running. Some call this file a map, some call it a profile, and others call it a trace; to keep things simple, we’ll call it a code execution log, or log for short. Now SkoolKit has the ability to read such logs, and thus do a much better job of finding the code in a memory snapshot. Of course, this does mean that a bit of work may be required to create the log itself, but playing a Spectrum game while the emulator does the hard work of identifying code should be more fun than trying to find the code by eye. However, if your chosen emulator has the ability to play back RZX recordings, you could take the hands-free approach and just sit back and sip coffee while the emulator does all the work for you. Sorted.

So there it is. Now that SkoolKit has support for reading code execution logs, there’s never been a better time to get started on that Spectrum game disassembly you’ve always wanted to do but were too daunted by the sheer mass of unidentified code and data. Get to it!

SkoolKit 3.2 is upon us, and also happens to be available from the never-absent download page. And as there has been a minor version number bump (from 3.1.x), I feel duty-bound to explain what’s been going on in SkoolKit-land since 3.1 was released back in June. If you’re at all interested to hear, stick around and some will be revealed.

In the skool macro department, we have two new members on the team: #HTML and #LIST. The #HTML macro renders arbitrary text in HTML mode only - and by ‘arbitrary’ I really mean ‘possibly including HTML markup’. So if you’ve ever been frustrated by how every comment in a skool file ends up being HTML-escaped before being rendered, you’ll enjoy using #HTML. The #LIST macro, unsurprisingly, may be used to create lists: <ul> elements in HTML mode, and plain-text bulleted lists in ASM mode. The syntax of the #LIST macro is similar to that of the #TABLE macro, which has been around since SkoolKit 1.0.

In the ASM directive department, the new kid on the block is the @set directive. Its purpose is to set properties on the ASM writer being used to produce ASM output. For now, the properties available for setting are bullet (the bullet character to use for lists created by the #LIST macro), crlf (whether to use CR+LF to terminate lines), and tab (whether to use a tab character to indent instructions); expect more properties to become available in future releases.

In the general SkoolKit department, full support has been added for ‘complex’ DEFB and DEFM statements that contain both strings and bytes (e.g. DEFB 1,"a"). This new feature has been put to use in manic_miner.ctl: run it against a snapshot of Manic Miner (Bug Byte edition) to see the source code remnants at 32768 and 37708 nicely documented, and the format used by Matthew Smith’s assembler revealed.

Finally, and specifically in the disassembling department, SkoolKit now supports SZX snapshots (16K, 48K and 128K) and 128K Z80 snapshots. Yes, the 48K limit on your SkoolKit disassembly aspirations has been lifted. By default, sna2skool.py will disassemble whichever RAM page is currently mapped to 49152 ($C000), but you can change that with the ‘-p’ option to gain access to the other RAM pages. How to organise the disassemblies of those other RAM pages alongside the ‘main’ disassembly is left up to you, but if more automation in this area (such as disassembling every currently unmapped page to its own skool file in one go) would be useful, be sure to let me know.

When SkoolKit 1.0 was released (in January 2010), I hadn’t given much thought to making it useful for producing disassemblies of games other than Skool Daze and Back to Skool. Indeed, in the ‘What is SkoolKit?’ section of the documentation, I described it as ‘The Skool Disassemblies in DIY or kit form’ (hence, in case you ever wondered, the name). And many of the documented skool macros and ref file sections were specific to the Skool games, too. It wasn’t really until version 2.0 (in November 2010) that I started thinking seriously about turning SkoolKit into a generic disassembly-creating tool, and only by version 2.1 (in April 2011) had I finally got rid of all the Skool-specific stuff.

Which brings us to version 3.1, released today and available for download from the aptly named download page. Taking support for non-Skool games to the next step, SkoolKit now has a public API that can be used to extend its functionality, thus enabling you - the potential producers of Stonkers, Infection and Laser Squad disassemblies out there - to implement your own skool macros (yes, they’re still called skool macros, for old times’ sake), and read your own custom ref file sections with custom names (made up by you) for custom purposes. For more details on what’s possible and how, see the documentation on extending SkoolKit.

In other news, support for the #CALL, #REFS, #EREFS, #PUSHS, #POKES and #POPS macros in ASM mode has been added, which means that skool2asm.py won’t choke on skool files that contain them. So now the only skool macros not supported in ASM mode are the image-creating ones: #FONT, #SCR, #UDG and #UDGARRAY. Which, I hope you will agree, makes sense: it’s hard to insert an image in a plain text ASM file.

And finally, if you’ve ever considered using SkoolKit to create a Spectrum game disassembly but were put off by the sickly pastel colours in the default CSS file, then be put off no longer. SkoolKit 3.1 includes a dark theme CSS file: skoolkit-dark.css. Quite literally, it is the exact inverse of the traditional skoolkit.css. To try it out with the Manic Miner disassembly (for example), just add the following section to examples/manic_miner.ref (included with SkoolKit):

[Paths]
StyleSheet=skoolkit-dark.css

or leave the ref file as it is and use the handy new ‘-c’ option of skool2html.py when building the disassembly:

skool2html.py -c Paths/StyleSheet=skoolkit-dark.css examples/manic_miner.ref

Either way, you can now revel in the darkness.