A suite of tools for creating disassemblies of ZX Spectrum games

## Project description

SkoolKit is a collection of utilities that can be used to disassemble a Spectrum game (or indeed any piece of Spectrum software written in machine code) into a format known as a skool file. Then, from this skool file, you can use SkoolKit to create a browsable disassembly in HTML format, or a re-assemblable disassembly in assembly language. So the skool file is - from start to finish as you develop it by organising and annotating the code - the common ‘source’ for both the reader-friendly HTML version of the disassembly, and the developer- and assembler-friendly version of the disassembly.

## Features

With SkoolKit you can:

• use sna2ctl.py to generate a control file (an attempt to identify routines and data blocks by static analysis) from a snapshot (SNA, SZX or Z80) or raw memory file

• enable sna2ctl.py to generate a much better control file that more reliably distinguishes code from data by using a code execution map produced by an emulator

• use sna2skool.py along with this control file to produce a disassembly of a snapshot or raw memory file

• add annotations to this disassembly (or the control file) as you discover the purpose of each routine and data block

• use skool2html.py to convert a disassembly into a bunch of HTML files (with annotations in place, and the operands of CALL and JP instructions converted into hyperlinks)

• use skool2asm.py to convert a disassembly into an assembler source file (also with annotations in place)

• use skool2ctl.py to convert a disassembly back into a control file (with annotations retained)

• use skool2bin.py to convert a disassembly into a raw memory file

• use tap2sna.py to convert a TAP or TZX file into a ‘pristine’ Z80 snapshot

• use snapinfo.py to analyse a snapshot or raw memory file and list the BASIC program it contains, show register values, produce a call graph, find tile graphic data, find text, or find sequences of arbitrary byte values

• use tapinfo.py to analyse the blocks in a TAP or TZX file, and list the BASIC program it contains

• use bin2tap.py to convert a snapshot or raw memory file into a TAP file

• use bin2sna.py to convert a raw memory file into a Z80 snapshot

• use snapmod.py to modify the register values or memory contents in a Z80 snapshot

• use sna2img.py to convert graphic data in a disassembly, SCR file, snapshot or raw memory file into a PNG image

In an HTML disassembly produced by skool2html.py you can also:

• use the image macros to build still and animated PNG images from graphic data

• use the #R macro in annotations to create hyperlinks between routines and data blocks that refer to each other

• use [Bug:*], [Fact:*] and [Poke:*] sections in a ref file to neatly render lists of bugs, trivia and POKEs on separate pages

For a demonstration of SkoolKit’s capabilities, take a look at the complete disassemblies of Skool Daze, Back to Skool, Contact Sam Cruise, Manic Miner, Jet Set Willy and Hungry Horace.

## Quick start guide

SkoolKit includes fairly detailed documentation, but if you want to get up and running quickly, here goes.

To convert a SNA, Z80 or SZX snapshot of a Spectrum game into a skool file (so that it can be converted into HTML or assembly language):

$sna2skool.py game.z80 > game.skool To split the disassembly up into code and data blocks, you’ll need a control file. To turn this skool file into an HTML disassembly: $ skool2html.py game.skool

To turn it into a file that can be fed to an assembler:

\$ skool2asm.py game.skool > game.asm

## Project details

Uploaded source