SkoolKit 4.0 has been released. In keeping with age-old tradition, copies of this major new version are available in various formats from the download page. And in keeping with more recent tradition, you can also obtain this major new version from PyPI or the PPA.

The numerically minded among you might have noticed that 4.0 is a whole major version number up from 3.7, the previous release. (For the benefit of the innumerate among you, I hinted at this with the phrase “major new version” - twice - in the first paragraph. You are welcome.) Why 4.0 instead of 3.8? Mainly because there have been some changes that make SkoolKit 4.0 incompatible with skool files, ref files, control files, skool file templates and CSS files that work with SkoolKit 3.7 and earlier versions. For example: the [Info] section of the ref file is no longer supported; the ‘z’ and ‘Z’ directives, which were deprecated in 3.7, are no longer supported; and the class attributes of many HTML elements have changed, which means your custom CSS files may need some modification to make them work with 4.0. See the documentation on migrating from SkoolKit 3 for a comprehensive list of the compatibility-breaking changes, and for information on the skoolkit3to4.py utility, which might ease some of the pain of switching to SkoolKit 4.

So much for the incompatibilities. What of the new features? The biggest one is the introduction of HTML templates, from which every page in an HTML disassembly is built. No longer is the format of the HTML produced by skool2html.py determined by code buried inside the skoolkit package; now you, the format-conscious user, are in control. Don’t care much for the layout of the disassembly index page? Then create your own [Template:GameIndex], [Template:index_section] and [Template:index_section_item] sections in the ref file. Need HTML5 for some pages instead of the default XHTML 1.0? Simply tweak the relevant [Template:*] sections, and away you go.

The next new feature on the list is support for keyword arguments in the image macros: #FONT, #SCR, #UDG and #UDGARRAY. These macros have several numeric parameters, most of them optional, which means that their parameter strings can be unreadably long. For example:

#UDG32768,,,,,,1

Any idea what parameter the value 1 corresponds to here? If not, take comfort in the fact that this macro can now be written more clearly thus:

#UDG32768,rotate=1

Also new in the realm of image creation is support for AND-OR masks. In previous versions, SkoolKit has assumed that sprite mask data is used as follows: take a background byte, OR on the sprite byte, and then AND on the mask byte. I refer to this masking scheme - which is used by Skool Daze, Back to Skool and Contact Sam Cruise - as OR-AND masking. However, it turns out that some games use mask data the other way round: take a background byte, AND on the mask byte, and then OR on the sprite byte. If you’ve had trouble producing masked images, it may be because AND-OR masking is required instead of OR-AND masking. If so, the new mask parameter of the #UDG and #UDGARRAY macros should fix the problem: use mask=2 to specify AND-OR masks.

That’s about it for the main new features; see the changelog for further details. Be brave and upgrade to SkoolKit 4.0 today, and be sure to report any bugs you find, or incompatibilities I haven’t documented!

SkoolKit 3.7 has been released. As usual, copies of this release are available, in various formats, from the download page. If, however, the idea of downloading SkoolKit from this site repels or offends you, you can install it via PyPI or the PPA instead. The choice is yours.

The last release to get an announcement on this here website was version 3.5 over six months ago, so I should probably go over a few of the changes that have taken place since then. For the image-creating fans among you, the big news is that the #UDGARRAY macro is now capable of building animated images from an arbitrary sequence of frames (each of which is built using a special form of the macro). SkoolKit has had support for building animated images that contain flashing cells since 3.0.1, but the new, enhanced #UDGARRAY macro enables you to be a bit cleverer and produce animated sprite images such as the ones of Miner Willy in the incomplete Manic Miner disassembly.

On the subject of disassemblies, a new one has joined the examples distributed with SkoolKit: the incomplete Spectrum ROM disassembly. It was made possible in part by the (new) support for disassemblies with a start address below 10000, and sits proudly alongside the incomplete Jet Set Willy disassembly and the aforementioned Manic Miner disassembly. In addition, built versions of these example disassemblies are now published online (as you may have gathered).

In the number bases department, SkoolKit now supports binary numbers in DEFB, DEFM, DEFS and DEFW statements. That is, they can be parsed in skool files for the purpose of building a snapshot (as demonstrated by the character set in the incomplete Spectrum ROM disassembly), and can be preserved in and restored from control files and skool file templates. The base of decimal and hexadecimal values can be preserved too by using the new --preserve-base option of skool2ctl.py and skool2sft.py.

Finally, on the control directive front, the ‘z’ and ‘Z’ (zero) directives have been deprecated in favour of the new ‘s’ and ‘S’ (space) directives, which can encode DEFS statements with non-zero byte values (e.g. ‘DEFS 8,255’) - something that was not possible with the old ‘Z’ directive. Now that the ‘s’ and ‘S’ directives are here, I really do wonder how we ever did without them.

As ever, more details on the changes since 3.5 can be found in the changelog. Here’s hoping they keep you going until 3.8 arrives!

Update: The Jet Set Willy disassembly is now here, the Manic Miner disassembly is now here, and the Spectrum ROM disassembly is now here.

SkoolKit 3.5 has been released. Not only that, but copies are available, as you’ve probably come to expect, from the aptly monickered download page. Feel free to pop over there and pick up a tarball, zip archive, RPM package or DEB package. I aim to please with a variety of download formats. Alternatively, you could use easy_install or pip to install SkoolKit from PyPI. So, got your copy? OK then, now sit back while I lay out the main changes since the last version I bothered to write an article about (3.3.2 in May).

First, the bad news. This is something you should pay special attention to if you’ve created (and are using) your own custom CSS file(s) with SkoolKit: the StyleSheet and Font parameters have moved from the [Paths] section of the ref file to the [Game] section. In addition, the Logo parameter has also moved from the [Paths] section to the [Game] section, so take care to update your ref file accordingly if you’re using a custom game logo. And, to add insult to injury, the JavaScript parameter has moved from the [Paths] section to the [Page:*] section. Why all these apparently senseless and inconvenient moves of oft-used parameters from one place to another? Well, truth be told, they should never have lived in the [Paths] section in the first place; that section is supposed to contain parameters specifying where files that don’t yet exist should be written, and the aforementioned parameters do not fit that description. Case closed.

Now, the good (or, at least, not annoying) news. On the subject of CSS files and themes, SkoolKit 3.5 brings support for multiple themes, and includes three new sample themes (in addition to the traditional dark and spectrum): green, plum and wide. As the names suggest, green makes your HTML disassembly mostly green, plum makes it mostly dark purple, and wide makes the tables on disassembly pages and the boxes on the Changelog, Glossary, Trivia, Bugs and Pokes pages stretch to full width. So if you want your disassembly to look green and wide, you can do this:

$ skool2html.py -T green -T wide game.ref

Also note that if you want to use your own custom theme, then for ease of maintenance and portability between SkoolKit versions, it’s a good idea to create a CSS file that contains only the differences required from the stock skoolkit.css, and to use both skoolkit.css and your custom CSS file (in that order) when building a disassembly. All the alternative CSS themes that come with SkoolKit have been written (or rewritten and much reduced!) to work in conjuction with skoolkit.css.

Next up, SkoolKit has a new command in its library: tap2sna.py. This command can convert a TAP or TZX file (remote or local, in a zip archive or not) into a Z80 snapshot. Big deal, I hear you snort. But hang on! The idea is that if you’re still in the control file phase of your disassembly, or you’d rather use a skool file template instead of a skool file, you can provide instructions to other users on how to create the ‘perfect’ snapshot that can be used to build the disassembly (from your control file or skool file template) with every byte having the value it’s supposed to have. See the documentation for all the gory details on how to start creating perfect snapshots today.

And that’s probably it for the most newsworthy changes. If it were a slower news day I could mention that skool2html.py now supports ASM labels in HTML output and can hyperlink the operands of LD instructions, that the #NAME macro is dead (and presumably unmourned), and that you might find the new --erefs option of sna2skool.py somewhat useful; but all that would take up too much space in an already bulging article. The curious SkoolKit user can always check the changelog for details.

Have fun with 3.5!