SkoolKit

Spectrum game disassembly toolkit

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, sna2skool.py 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 skool2ctl.py 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 skool2asm.py. Just point the new Templates configuration parameter of skool2asm.py 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 skool2ctl.py and how the #LINK and #R macros now work with upper case hexadecimal address anchors (among other things).

Code > text > data

SkoolKit 7.1 has been released. As usual, copies may be obtained from the download page, the Python Package Index, the Ubuntu PPA, or the Fedora copr repo.

Among the changes worthy of note in this release is the improved control file generation algorithm that sna2ctl.py uses when no code map is provided. The algorithm is now much faster, and strongly prefers to mark a chunk of bytes as code first, text second (if it really doesn’t look like code), and data last (if it really looks like neither code nor text). The main idea behind these preferences is that more code and text will be identified, at the expense of misidentifying more data. But since data that has been marked as code or text is easier to spot and fix than code or text that has been marked as data, the cost is worth it.

In other sna2ctl.py news, that command can now read configuration from skoolkit.ini, and has also gained the --ini option (for setting the value of a configuration parameter) and the --show-config option (for showing all configuration parameter values). So if you want sna2ctl.py to always produce hexadecimal control files, you can add the line Hex=2 to the [sna2ctl] section in skoolkit.ini and forget about having to use the --hex option on the command line all the time.

Speaking of control files, sna2skool.py now has the ability to read multiple control files by default (e.g. both game-1.ctl and game-2.ctl when the input snapshot is game.z80), and to use the --ctl option multiple times (for specifying two or more control files manually). This change makes sna2skool.py easier to use if you prefer to split your large control file into smaller, more manageable chunks.

On the image macro front, #UDGARRAY can now specify attribute address ranges, as an alternative to specifying an attribute value separately for each tile. For example, if you are creating an 8x4 graphic whose attribute values are located at addresses 32000-32031, you can now write a macro like this:

#UDGARRAY8;31744-31992-8@32000-32031(box)

Hopefully we can all agree that this is much nicer than having to specify each of those 32 attribute values individually.

And that’s it for the new features that I can be bothered to spend time explaining in any detail. If you want to know more about the other changes in 7.1, such as the ability to render numeric values in instruction operands as negative numbers (e.g. LD A,-1), or how the @*sub and @*fix directives can insert an instruction after the current one without first specifying a replacement, I suggest heading over to the changelog.

Surviving the round trip

ctl-invariance ftw

SkoolKit 7.0 has been released. I invite you to visit the download page, the Python Package Index, the Ubuntu PPA, or the Fedora copr repo if you would like to collect a copy.

As you might expect with the initial release in a new series, there are some changes that break compatibility with previous versions. The two main ones are that the ability to generate a control file has moved from sna2skool.py to the new sna2ctl.py command, and that skool2html.py now expects a skool file as its first positional argument, and treats any remaining positional arguments as extra ref files. For details on the other ways that SkoolKit 7 might break your disassembly, and how to fix it, see the migration guide.

But enough of that. What new features does this release bring? Well, again, as with the compatibility-breaking changes, there are two main ones, and they both serve a purpose that has long been dear to my heart: preservability in a control file. It has always irked me that some parts of some skool files are not amenable to such preservation, but with the advent of 7.0 those parts (and those skool files) are thankfully smaller in number.

First of all, the @isub, @ssub, @rsub, @ofix, @bfix and @rfix directives have gained some key new abilities. They can now specify a replacement comment over multiple lines, replace labels, and insert, overwrite and remove instructions. Previously, each of these operations would have required the use of a block directive (e.g. @ssub-begin@ssub-end), which cannot be preserved in a control file.

Second of all, non-entry blocks (i.e. blocks that do not match the format of an entry, such as a header comment) are now preserved verbatim by skool2ctl.py, and are reproduced verbatim (minus any ASM directives) by skool2asm.py. This means that comment blocks appearing between entries in a skool file will now survive a round trip through skool2ctl.py and sna2skool.py, even if they contain ASM block directives.

Third of all, although I said there were only two main new features, there is one more that is relevant to the central theme of preservability in a control file, and so deserves a mention here. Inverted characters - meaning character codes with bit 7 set to indicate the end of a string - can now be stored in and restored from a control file. So, for example, the "o"+$80 in DEFM "Hell","o"+$80 will survive the round trip, instead of degrading to $EF.

And that is it, as far as preservability in a control file is concerned. For details on all the other much less important features - which, I warn you, may have nothing to do with either preservability or control files - take a look at the changelog. Happy migrating!