Features¶

SkoolKit can:

• convert a TAP or TZX file into a ‘pristine’ snapshot (using tap2sna.py)
• disassemble SNA, Z80 and SZX snapshots as well as raw memory files
• distinguish code from data by using a code execution map produced by an emulator
• build still and animated PNG/GIF images from graphic data in the game snapshot (using the #UDG, #UDGARRAY, #FONT and #SCR macros)
• create hyperlinks between routines and data blocks that refer to each other (by use of the #R macro in annotations, and automatically in the operands of CALL and JP instructions)
• neatly render lists of bugs, trivia and POKEs on separate pages (using [Bug:*:*], [Fact:*:*] and [Poke:*:*] sections in a ref file)
• produce ASM files that include bugfixes declared in the skool file (with @ofix, @bfix and other ASM directives)
• produce TAP files from assembled code (using bin2tap.py)

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 and Jet Set Willy. The latest stable releases of the source skool files for these disassemblies can always be obtained from skoolkit.ca; the latest development versions can be found on GitHub.

Licence¶

SkoolKit is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See the file ‘COPYING’ (distributed with SkoolKit) for the full text of the licence.

Requirements¶

SkoolKit requires Python 2.7 or 3.2+. If you’re running Linux or one of the BSDs, you probably already have Python installed. If you’re running Windows, you can get Python here.

Installation¶

There are various ways to install the latest stable release of SkoolKit:

• from the zip archive or tarball available at skoolkit.ca
• from the DEB package or RPM package available at skoolkit.ca
• from PyPI by using easy_install or pip
• from the SkoolKit PPA for Ubuntu

If you choose the zip archive or tarball, note that SkoolKit can be used wherever it is unpacked: it does not need to be installed in any particular location. However, if you would like to install SkoolKit as a Python package, you can do so by using the supplied setup.py script.

> setup.py install

# ./setup.py install

Linux/*BSD v. Windows command line¶

Throughout this documentation, commands that must be entered in a terminal window (‘Command Prompt’ in Windows) are shown on a line beginning with a dollar sign ($), like this:

$ some-script.py some arguments

On Windows, and on Linux/*BSD if SkoolKit has been installed as a Python package (see above), the commands may be entered exactly as they are shown. On Linux/*BSD, use a dot-slash prefix (e.g. ./some-script.py) if the script is being run from the current working directory.

Getting started¶

The first thing to do is select a Spectrum game to disassemble. For the purpose of this discussion, we’ll use Hungry Horace. To build a pristine snapshot of the game, run the following command in the directory where SkoolKit was unpacked:

$ tap2sna.py @examples/hungry_horace.t2s

(If that doesn’t work, or you prefer to make your own snapshot, just grab a copy of the game, load it in an emulator, and save a Z80 snapshot named hungry_horace.z80.)

The next thing to do is create a skool file from this snapshot. Run the following command from the SkoolKit directory:

$ sna2skool.py hungry_horace.z80 > hungry_horace.skool

Note that the ‘.skool’ file name suffix is merely a convention, not a requirement. In general, any suffix besides ‘.ref’ (which is used by skool2html.py to identify ref files) will do. If you are fond of the traditional three-letter suffix, then perhaps ‘.sks’ (for ‘SkoolKit source’) or ‘.kit’ would be more to your liking. However, for the purpose of this particular tutorial, it would be best to stick with ‘.skool’.

Now take a look at hungry_horace.skool. As you can see, by default, sna2skool.py disassembles everything from 16384 to 65535, treating it all as code. Needless to say, this is not particularly useful - unless you have no idea where the code and data blocks are yet, and want to use this disassembly to find out.

Once you have figured out where the code and data blocks are, it would be handy if you could supply sna2skool.py with this information, so that it can disassemble the blocks accordingly. That is where the control file comes in.

The control file¶

In its most basic form, a control file contains a list of start addresses of code and data blocks. Each address is marked with a ‘control directive’, which is a single letter that indicates what the block contains: c for a code block, or b for a data block (for example). A control file may contain annotations too, which will be interpreted as routine titles, descriptions, instruction-level comments or whatever else depending on the control directive they accompany.

A control file for Hungry Horace might start like this:

b 16384 Loading screen
i 23296
c 24576 The game has just loaded
c 25167
...

This control file declares that there is:

• a data block at 16384 titled ‘Loading screen’
• a block at 23296 that should be ignored
• a code block (routine) at 24576 titled ‘The game has just loaded’
• another code block at 25167

For more information on control file directives and their syntax, see Control files.

A skeleton disassembly¶

So if we had a control file for Hungry Horace, we could produce a much more useful skool file. As it happens, SkoolKit includes one: hungry_horace.ctl. You can use it with sna2skool.py thus:

$ sna2skool.py -c examples/hungry_horace.ctl hungry_horace.z80 > hungry_horace.skool

This time, hungry_horace.skool is split up into meaningful blocks, with code as code, data as data (DEFBs), and text as text (DEFMs). Much nicer.

By default, sna2skool.py produces a disassembly with addresses and instruction operands in decimal notation. If you prefer to work in hexadecimal, however, use the -H option:

$ sna2skool.py -H -c examples/hungry_horace.ctl hungry_horace.z80 > hungry_horace.skool

The next step is to create an HTML disassembly from this skool file:

$ skool2html.py hungry_horace.skool

Now open hungry_horace/index.html in a web browser. There’s not much there, but it’s a base from which you can start adding explanatory comments.

In order to replace ‘hungry_horace’ in the page titles and headers with something more appropriate, or add a game logo image, or otherwise customise the disassembly, we need to create a ref file. Again, as it happens, SkoolKit includes an example ref file for Hungry Horace: hungry_horace.ref. To use it with the skool file we’ve just created:

$ skool2html.py examples/hungry_horace.ref

Now the disassembly will sport a game logo image.

See Ref files for more information on how to use a ref file to configure and customise a disassembly.

Generating a control file¶

If you are planning to create a disassembly of some game other than Hungry Horace, you will need to create your own control file. To get started, you can use the -g option with sna2skool.py to perform a rudimentary static code analysis of the snapshot file and generate a corresponding control file:

$ sna2skool.py -g game.ctl game.z80 > game.skool

This will do a reasonable job of splitting the snapshot into blocks, but won’t be 100% accurate (except by accident); you will need to examine the resultant skool file (game.skool in this case) to see which blocks have been incorrectly marked as text, data or code, and then edit the generated control file (game.ctl) accordingly.

To generate a better control file, you could use a code execution map produced by an emulator to tell sna2skool.py where at least some of the code is in the snapshot. sna2skool.py will read a map (otherwise known as a profile or trace) produced by Fuse, SpecEmu, Spud, Zero or Z80 when specified by the -M option:

$ sna2skool.py -M game.map -g game.ctl game.z80 > game.skool

Needless to say, in general, the better the map, the more accurate the resulting control file will be. To create a good map file, you should ideally play the game from start to finish in the emulator, in an attempt to exercise as much code as possible. If that sounds like too much work, and your emulator supports playing back RZX files, you could grab a recording of your chosen game from the RZX Archive, and set the emulator’s profiler or tracer going while the recording plays back.

By default, sna2skool.py generates a control file and a skool file with addresses and instruction operands in decimal notation. If you prefer to work in hexadecimal, however, use the -h option to produce a hexadecimal control file, and the -H option to produce a hexadecimal skool file:

$ sna2skool.py -h -H -g game.ctl game.z80 > game.skool

Developing the skool file¶

When you’re happy that your control file does a decent job of distinguishing the code blocks from the data blocks in your memory snapshot, it’s time to start work on the skool file.

Figuring out what the code blocks do and what the data blocks contain can be a time-consuming job. It’s probably not a good idea to go through each block one by one, in order, and move to the next only when it’s fully documented - unless you’re looking for a nervous breakdown. Instead it’s better to approach the job like this:

1. Skim the code blocks for any code whose purpose is familiar or obvious, such as drawing something on the screen, or producing a sound effect.
2. Document that code (and any related data) as far as possible.
3. Find another code block that calls the code block just documented, and figure out when, why and how it uses it.
4. Document that code (and any related data) as far as possible.
5. If there’s anything left to document, return to step 3.
6. Done!

It also goes without saying that figuring out what a piece of code or data might be used for is easier if you’ve played the game to death already.

Annotating the code and data in a skool file is done by adding comments just as you would in a regular ASM file. For example, you might add a comment to the instruction at 26429 in hungry_horace.skool thus:

 26429 DEC A         ; Decrement the number of lives

See the skool file format reference for a full description of the kinds of annotations that are supported in skool files. Note also that SkoolKit supports many skool macros that can be used in comments and will be converted into hyperlinks and images (for example) in the HTML version of the disassembly.

As you become more familiar with the layout of the code and data blocks in the disassembly, you may find that some blocks need to be split up, joined, or otherwise reorganised. You could do this manually in the skool file itself, or you could regenerate the skool file from a new control file. To ensure that you don’t lose all the annotations you’ve already added to the skool file, though, you should use skool2ctl.py to preserve them.

First, create a control file that keeps your annotations intact:

$ skool2ctl.py game.skool > game-2.ctl

Now edit game-2.ctl to fit your better understanding of the layout of the code and data blocks. Then generate a new skool file:

$ sna2skool.py -c game-2.ctl game.z80 > game-2.skool

This new skool file, game-2.skool, will contain your reorganised code and data blocks, and all the annotations you carefully added to game.skool.

Adding pokes, bugs and trivia¶

Adding ‘Pokes’, ‘Bugs’, and ‘Trivia’ pages to a disassembly is done by adding [Poke:*:*], [Bug:*:*], and [Fact:*:*] sections to the ref file. For any such sections that are present, skool2html.py will add links to the disassembly index page.

For example, let’s add a poke. Add the following lines to hungry_horace.ref:

[Poke:infiniteLives:Infinite lives]
The following POKE gives Horace infinite lives:

POKE 26429,0

Now run skool2html.py again:

$ skool2html.py examples/hungry_horace.ref

Open hungry_horace/index.html and you will see a link to the ‘Pokes’ page in the ‘Reference’ section.

The format of a Bug or Fact section is the same, except that the section name prefix is Bug: or Fact: (instead of Poke:) as appropriate.

Add one Poke, Bug or Fact section for each poke, bug or trivia entry to be documented. Entries will appear on the ‘Pokes’, ‘Bugs’ or ‘Trivia’ page in the same order as the sections appear in the ref file.

See Ref files for more information on the format of the Poke, Bug, and Fact (and other) sections that may appear in a ref file.

Themes¶

In addition to the default theme (defined in skoolkit.css), SkoolKit includes some alternative themes:

• dark (dark colours): skoolkit-dark.css
• green (mostly green): skoolkit-green.css
• plum (mostly purple): skoolkit-plum.css
• wide (wide comment fields on the disassembly pages, and wide boxes on the Changelog, Glossary, Trivia, Bugs and Pokes pages): skoolkit-wide.css

In order to use a theme, run skool2html.py with the -T option; for example, to use the ‘dark’ theme:

$ skool2html.py -T dark game.skool

Themes may be combined; for example, to use both the ‘plum’ and ‘wide’ themes:

$ skool2html.py -T plum -T wide game.skool

pasmo¶

First, create an ASM version of the disassembly:

$ skool2asm.py game.skool > game.asm

Then use pasmo to create a binary file thus:

$ pasmo game.asm game.bin

To create a TAP file from game.bin, use the bin2tap.py utility, included with SkoolKit:

$ bin2tap.py game.bin

The resultant TAP file, game.tap, can then be loaded into an emulator.

SjASMPlus¶

First, create an ASM version of the disassembly:

$ skool2asm.py game.skool > game.asm

Then create a file called game.sjasm with the following contents:

; SjASMPlus source file for game.asm
  device zxspectrum48
  include game.asm
  savebin "game.bin",ORG,LENGTH

replacing ORG and LENGTH with the origin address and the length of the assembled program. Now run sjasmplus on this source file:

$ sjasmplus game.sjasm

and a binary file called game.bin will be created.

To create a TAP file from game.bin, use the bin2tap.py utility, included with SkoolKit:

$ bin2tap.py game.bin

The resultant TAP file, game.tap, can then be loaded into an emulator.

z80asm (z88dk)¶

First, create an ASM version of the disassembly:

$ skool2asm.py game.skool > game.asm

Then use z80asm to create a binary file thus:

$ z80asm -rORG -b game.asm

replacing ORG with the origin address (in hexadecimal notation) of the program.

To create a TAP file from game.bin, use the bin2tap.py utility, included with SkoolKit:

$ bin2tap.py game.bin

The resultant TAP file, game.tap, can then be loaded into an emulator.

[Info]¶

The [Info] section, introduced in SkoolKit 2.0, is not supported in SkoolKit 4. If you have one in your ref file, move its contents to the [Game] section.

[Graphics]¶

The [Graphics] section, introduced in SkoolKit 2.0.5, is not supported in SkoolKit 4. If you have one in your ref file, you can migrate it thus:

• Rename the [Graphics] section [PageContent:Graphics]

• Create a [Paths] section if you don’t already have one, and add a line for the Graphics page:

  [Paths]
  Graphics=graphics/graphics.html
  

• Create an [Index:Graphics:Graphics] section if you don’t already have one, and add the Graphics page ID (to make a link to it appear on the disassembly index page); for example:

  [Index:Graphics:Graphics]
  Graphics
  GraphicGlitches
  

[Page:*]¶

In [Page:*] sections, the following parameters are no longer supported:

• BodyClass
• Link
• Path
• Title

The CSS class for the <body> element of a custom page is now set to the page ID. The path, title, header and link text for a custom page can be defined in the [Paths], [Titles], [PageHeaders] and [Links] sections.

[OtherCode:*]¶

In [OtherCode:*] sections, the following parameters are no longer supported:

• Header
• Index
• IndexPageId
• Link
• Path
• Title

The paths, titles, headers and link text for the pages in a secondary disassembly can be defined in the [Paths], [Titles], [PageHeaders] and [Links] sections; see the documentation on [OtherCode:*] sections for more details.

‘z’ and ‘Z’ directives¶

The ‘z’ and ‘Z’ control directives (and the corresponding ‘z’ blocks in skool files) are not supported in SkoolKit 4; they should be replaced by ‘s’ and ‘S’ directives.

Register table headers¶

Input and output register table headers on disassembly pages are now displayed by default, with header text ‘Input’ and ‘Output’.

To hide the register table headers (as was the default behaviour in SkoolKit 3), use the following CSS rule:

tr.asm-input-header, tr.asm-output-header {display: none;}

CSS selectors¶

The class attributes of many HTML elements have changed in SkoolKit 4.

The following table lists the selectors that appeared in the CSS files in SkoolKit 3, and their replacements (if any) in SkoolKit 4.

The following table lists selectors for the classes that were unstyled (i.e. did not appear in any CSS files) in SkoolKit 3, and their replacements (if any) in SkoolKit 4.

skoolkit3to4.py¶

The skoolkit3to4.py script may be used to convert a skool file, ref file, control file, skool file template or CSS file that is compatible with SkoolKit 3 into a file that will work with SkoolKit 4. For example, to convert game.ref:

$ skoolkit3to4.py game.ref > game4.ref

Note, however, that skoolkit3to4.py converts a CSS file by simply replacing each selector that is used in SkoolKit 3 with its SkoolKit 4 equivalent(s), which means that complex CSS rules may not be converted correctly.

4.3 (2015-02-14)¶

• Added support for block start comments (which appear after the register section and before the first instruction in a routine or data block)
• Added the CodeFiles parameter to the [Paths] section (for specifying the format of a disassembly page filename based on the address of the routine or data block)
• Added the AddressAnchor parameter to the [Game] section (for specifying the format of the anchors attached to instructions on disassembly pages and entries on memory map pages)
• The #FONT, #SCR and #UDG macros now have the ability to create frames for an animated image
• Added the --line-width option to sna2skool.py (for specifying the maximum line width of the skool file)
• Writing an ASM directive in a skool file can now be done by starting a line with @; writing an ASM directive by starting a line with ; @ is deprecated
• Added the @ directive for declaring ASM directives in a control file; the old style of declaring ASM directives (; @directive:address[=value]) is deprecated
• Fixed the flip_udgs() and rotate_udgs() methods on HtmlWriter so that they work with a UDG array that contains the same UDG in more than one place
• Fixed the bug that prevents register descriptions from being HTML-escaped
• Fixed the erroneous substitution of address labels in instructions that have 8-bit numeric operands

4.2 (2014-12-07)¶

• Added support for control directive loops using the L directive
• Added support to control files for preserving the location of @ignoreua directives
• Each image macro now has the ability to specify alt text for the <img> element it produces
• Added support for splitting register descriptions over multiple lines
• skool2asm.py now warns about unconverted addresses in register descriptions, and the @ignoreua directive can be used to suppress such warnings
• Added the table, table_cell, table_header_cell and table_row templates (for formatting tables produced by the #TABLE macro)
• Added the list and list_item templates (for formatting lists produced by the #LIST macro)
• Fixed the bug that prevents the expansion of skool macros in the intro text of a [Changelog:*] section

4.1.1 (2014-09-20)¶

• Updated links to SkoolKit’s new home at skoolkit.ca
• Added example control and ref files for Hungry Horace
• Removed the Manic Miner disassembly from the SkoolKit distribution; it is now being developed separately here

4.1 (2014-08-30)¶

• Added the --search option to skool2html.py (to add a directory to the resource search path)
• Added the --writer option to skool2html.py (for specifying the HTML writer class to use)
• Added the --writer option to skool2asm.py (for specifying the ASM writer class to use)
• Added the LinkInternalOperands parameter to the [Game] section (for specifying whether to hyperlink instruction operands that refer to an address in the same entry)
• Register sections in b, g, s, t, u and w blocks are now included in the output of skool2asm.py and skool2html.py
• Fixed how the address ‘0’ is rendered in HTML output when converted to decimal or hexadecimal
• Fixed the bug that creates a broken hyperlink in a DEFW statement or LD instruction that refers to the address of an ignored entry
• Removed the Jet Set Willy disassembly from the SkoolKit distribution; it is now being developed separately here

4.0 (2014-05-25)¶

• Every HTML page is built from templates defined in [Template:*] sections in the ref file
• Added support for keyword arguments to the #FONT, #SCR, #UDG and #UDGARRAY macros
• Added the mask parameter to the #UDG and #UDGARRAY macros (for specifying the type of mask to apply)
• Added support for defining page headers in the [PageHeaders] section of the ref file
• Added the --ref-file and --ref-sections options to skool2html.py (to show the entire default ref file or individual sections of it)
• Added the EntryDescriptions parameter to the [MemoryMap:*] section (for specifying whether to display entry descriptions on a memory map page)
• Added the LengthColumn parameter to the [MemoryMap:*] section (for specifying whether to display the ‘Length’ column on a memory map page)
• Added documentation on migrating from SkoolKit 3

Older versions¶

bin2tap.py¶

bin2tap.py converts a binary file produced by an assembler (see Supported assemblers) into a TAP file that can be loaded into an emulator. For example:

$ bin2tap.py game.bin

will create a file called game.tap. By default, the origin address (the address of the first byte of code or data), the start address (the first byte of code to run) and the stack pointer are set to 65536 minus the length of game.bin. These defaults can be changed by passing options to bin2tap.py. Run it with no arguments to see the list of available options:

usage: bin2tap.py [options] FILE.bin

Convert a binary snapshot file into a TAP file.

Options:
  -o ORG, --org ORG     Set the origin address (default: 65536 minus the
                        length of FILE.bin)
  -p STACK, --stack STACK
                        Set the stack pointer (default: ORG)
  -s START, --start START
                        Set the start address to JP to (default: ORG)
  -t TAPFILE, --tapfile TAPFILE
                        Set the TAP filename (default: FILE.tap)
  -V, --version         Show SkoolKit version number and exit

Note that the ROM tape loading routine at 1366 ($0556) and the load routine used by bin2tap.py together require 14 bytes for stack operations, and so STACK must be at least 16384+14=16398 ($400E). This means that if ORG is less than 16398, you should use the -p option to set the stack pointer to something appropriate. If the main data block (derived from game.bin) overlaps any of the last four bytes of the stack, bin2tap.py will replace those bytes with the values required by the tape loading routine for correct operation upon returning. Stack operations will overwrite the bytes in the address range STACK-14 to STACK-1 inclusive, so those addresses should not be used to store essential code or data.

skool2asm.py¶

skool2asm.py converts a skool file into an ASM file that can be fed to an assembler (see Supported assemblers). For example:

$ skool2asm.py game.skool > game.asm

skool2asm.py supports many options; run it with no arguments to see a list:

usage: skool2asm.py [options] file

Convert a skool file into an ASM file, written to standard output. FILE may be
a regular file, or '-' for standard input.

Options:
  -c, --create-labels   Create default labels for unlabelled instructions
  -d, --crlf            Use CR+LF to end lines
  -D, --decimal         Write the disassembly in decimal
  -f N, --fixes N       Apply fixes:
                          N=0: None (default)
                          N=1: @ofix only
                          N=2: @ofix and @bfix
                          N=3: @ofix, @bfix and @rfix (implies -r)
  -H, --hex             Write the disassembly in hexadecimal
  -i N, --inst-width N  Set instruction field width (default=23)
  -l, --lower           Write the disassembly in lower case
  -p, --package-dir     Show path to skoolkit package directory and exit
  -q, --quiet           Be quiet
  -r, --rsub            Use relocatability substitutions too (@rsub) (implies
                        '-f 1')
  -s, --ssub            Use safe substitutions (@ssub)
  -t, --tabs            Use tab to indent instructions (default indentation is
                        2 spaces)
  -u, --upper           Write the disassembly in upper case
  -V, --version         Show SkoolKit version number and exit
  -w, --no-warnings     Suppress warnings
  -W CLASS, --writer CLASS
                        Specify the ASM writer class to use

See ASM modes and directives for a description of the @ssub and @rsub substitution modes, and the @ofix, @bfix and @rfix bugfix modes.

skool2ctl.py¶

skool2ctl.py converts a skool file into a control file. For example:

$ skool2ctl.py game.skool > game.ctl

In addition to block types and addresses, game.ctl will contain block titles, block descriptions, registers, mid-block comments, block start and end comments, sub-block types and addresses, instruction-level comments, and some ASM directives.

To list the options supported by skool2ctl.py, run it with no arguments:

usage: skool2ctl.py [options] FILE

Convert a skool file into a control file, written to standard output. FILE may
be a regular file, or '-' for standard input.

Options:
  -a, --no-asm-dirs    Do not write ASM directives
  -b, --preserve-base  Preserve the base of decimal and hexadecimal values in
                       DEFB, DEFM, DEFS and DEFW statements
  -h, --hex            Write addresses in hexadecimal format
  -V, --version        Show SkoolKit version number and exit
  -w X, --write X      Write only these elements, where X is one or more of:
                         b = block types and addresses
                         t = block titles
                         d = block descriptions
                         r = registers
                         m = mid-block comments and block start/end comments
                         s = sub-block types and addresses
                         c = instruction-level comments

If you need to preserve any elements that control files do not support (such as data definition entries and ASM block directives), consider using skool2sft.py to create a skool file template instead.

skool2html.py¶

skool2html.py converts a skool file (and its associated ref files, if any exist) into a browsable disassembly in HTML format.

For example:

$ skool2html.py game.skool

will convert the file game.skool into a bunch of HTML files. If any files named game*.ref (e.g. game.ref, game-bugs.ref, game-pokes.ref and so on) also exist, they will be used to provide further information to the conversion process.

skool2html.py can operate directly on ref files, too. For example:

$ skool2html.py game.ref

In this case, the skool file declared in the [Config] section of game.ref will be used; if no skool file is declared in game.ref, game.skool will be used if it exists. In addition, any existing files besides game.ref that are named game*.ref (e.g. game-bugs.ref, game-pokes.ref and so on) will also be used.

If an input file’s name ends with ‘.ref’, it will be treated as a ref file; otherwise it will be treated as a skool file.

skool2html.py supports several options; run it with no arguments to see a list:

usage: skool2html.py [options] FILE [FILE...]

Convert skool files and ref files to HTML. FILE may be a regular file, or '-'
for standard input.

Options:
  -a, --asm-labels      Use ASM labels
  -c S/L, --config S/L  Add the line 'L' to the ref file section 'S'; this
                        option may be used multiple times
  -C, --create-labels   Create default labels for unlabelled instructions
  -d DIR, --output-dir DIR
                        Write files in this directory (default is '.')
  -D, --decimal         Write the disassembly in decimal
  -H, --hex             Write the disassembly in hexadecimal
  -j NAME, --join-css NAME
                        Concatenate CSS files into a single file with this name
  -l, --lower           Write the disassembly in lower case
  -o, --rebuild-images  Overwrite existing image files
  -p, --package-dir     Show path to skoolkit package directory and exit
  -P PAGES, --pages PAGES
                        Write only these custom pages (when '-w P' is
                        specified); PAGES should be a comma-separated list of
                        IDs of pages defined in [Page:*] sections in the ref
                        file(s)
  -q, --quiet           Be quiet
  -r PREFIX, --ref-sections PREFIX
                        Show default ref file sections whose names start with
                        PREFIX and exit
  -R, --ref-file        Show the entire default ref file and exit
  -s, --search-dirs     Show the locations skool2html.py searches for resources
  -S DIR, --search DIR  Add this directory to the resource search path; this
                        option may be used multiple times
  -t, --time            Show timings
  -T THEME, --theme THEME
                        Use this CSS theme; this option may be used multiple
                        times
  -u, --upper           Write the disassembly in upper case
  -V, --version         Show SkoolKit version number and exit
  -w X, --write X       Write only these files, where X is one or more of:
                          B = Graphic glitches    o = Other code
                          b = Bugs                P = Custom pages
                          c = Changelog           p = Pokes
                          d = Disassembly files   t = Trivia
                          i = Disassembly index   y = Glossary
                          m = Memory maps
  -W CLASS, --writer CLASS
                        Specify the HTML writer class to use; shorthand for
                        '--config Config/HtmlWriterClass=CLASS'

skool2html.py searches the following directories for skool files, ref files, CSS files, JavaScript files, font files, and files listed in the [Resources] section of the ref file:

• The directory that contains the skool or ref file named on the command line
• The current working directory
• ./resources
• ~/.skoolkit
• $PACKAGE_DIR/resources
• Any other directories specified by the -S/--search option

where $PACKAGE_DIR is the directory in which the skoolkit package is installed (as shown by skool2html.py -p). When you need a reminder of these locations, run skool2html.py -s.

The -T option sets the CSS theme. For example, if game.ref specifies the CSS files to use thus:

[Game]
StyleSheet=skoolkit.css;game.css

then:

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

will use the following CSS files, if they exist, in the order listed:

• skoolkit.css
• skoolkit-dark.css
• skoolkit-wide.css
• game.css
• game-dark.css
• game-wide.css

skool2sft.py¶

skool2sft.py converts a skool file into a skool file template. For example:

$ skool2sft.py game.skool > game.sft

To list the options supported by skool2sft.py, run it with no arguments:

usage: skool2sft.py [options] FILE

Convert a skool file into a skool file template, written to standard output.
FILE may be a regular file, or '-' for standard input.

Options:
  -b, --preserve-base  Preserve the base of decimal and hexadecimal values in
                       DEFB, DEFM, DEFS and DEFW statements
  -h, --hex            Write addresses in hexadecimal format
  -V, --version        Show SkoolKit version number and exit

sna2skool.py¶

sna2skool.py converts a binary (raw memory) file or a SNA, SZX or Z80 snapshot into a skool file. For example:

$ sna2skool.py game.z80 > game.skool

Now game.skool can be converted into a browsable HTML disassembly using skool2html.py, or into an assembler-ready ASM file using skool2asm.py.

sna2skool.py supports several options; run it with no arguments to see a list:

usage: sna2skool.py [options] file

Convert a binary (raw memory) file or a SNA, SZX or Z80 snapshot into a skool
file.

Options:
  -c FILE, --ctl FILE   Use FILE as the control file
  -g FILE, --generate-ctl FILE
                        Generate a control file in FILE
  -h, --ctl-hex         Write hexadecimal addresses in the generated control
                        file
  -H, --skool-hex       Write hexadecimal addresses and operands in the
                        disassembly
  -l L, --defm-size L   Set the maximum number of characters per DEFM
                        statement to L (default=66)
  -L, --lower           Write the disassembly in lower case
  -m M, --defb-mod M    Group DEFB blocks by addresses that are divisible by M
  -M FILE, --map FILE   Use FILE as a code execution map when generating a
                        control file
  -n N, --defb-size N   Set the maximum number of bytes per DEFB statement to
                        N (default=8)
  -o ADDR, --org ADDR   Specify the origin address of a binary (.bin) file
                        (default: 65536 - length)
  -p PAGE, --page PAGE  Specify the page (0-7) of a 128K snapshot to map to
                        49152-65535
  -r, --no-erefs        Don't add comments that list entry point referrers
  -R, --erefs           Always add comments that list entry point referrers
  -s ADDR, --start ADDR
                        Specify the address at which to start disassembling
                        (default=16384)
  -t, --text            Show ASCII text in the comment fields
  -T FILE, --sft FILE   Use FILE as the skool file template
  -V, --version         Show SkoolKit version number and exit
  -w W, --line-width W  Set the maximum line width of the skool file (default:
                        79)
  -z, --defb-zfill      Pad decimal values in DEFB statements with leading
                        zeroes

If the input filename does not end with ‘.sna’, ‘.szx’ or ‘.z80’, it is assumed to be a binary file.

By default, any control file or skool file template whose name (minus the ‘.ctl’ or ‘.sft’ suffix) matches the input filename (minus the ‘.bin’, ‘.sna’, ‘.szx’ or ‘.z80’ suffix, if any) will be used, if present.

The -M option may be used (in conjunction with the -g option) to specify a code execution map to use when generating a control file. The supported file formats are:

• Profiles created by the Fuse emulator
• Code execution logs created by the SpecEmu, Spud and Zero emulators
• Map files created by the Z80 emulator

If the file specified by the -M option is 8192 bytes long, it is assumed to be a Z80 map file; otherwise it is assumed to be in one of the other supported formats.

tap2sna.py¶

tap2sna.py converts a TAP or TZX file (which may be inside a zip archive) into a Z80 snapshot. For example:

$ tap2sna.py game.tap game.z80

To list the options supported by tap2sna.py, run it with no arguments:

usage:
  tap2sna.py [options] INPUT snapshot.z80
  tap2sna.py @FILE

Convert a TAP or TZX file (which may be inside a zip archive) into a Z80
snapshot. INPUT may be the full URL to a remote zip archive or TAP/TZX file,
or the path to a local file. Arguments may be read from FILE instead of (or as
well as) being given on the command line.

Options:
  -d DIR, --output-dir DIR
                        Write the snapshot file in this directory.
  -f, --force           Overwrite an existing snapshot.
  --ram OPERATION       Perform a load, move or poke operation on the memory
                        snapshot being built. Do '--ram help' for more
                        information. This option may be used multiple times.
  --reg name=value      Set the value of a register. Do '--reg help' for more
                        information. This option may be used multiple times.
  --state name=value    Set a hardware state attribute. Do '--state help' for
                        more information. This option may be used multiple
                        times.
  -V, --version         Show SkoolKit version number and exit.

Note that support for TZX files is limited to block types 0x10 (Standard Speed Data Block) and 0x11 (Turbo Speed Data Block).

By default, tap2sna.py loads bytes from every data block on the tape, using the start address given in the corresponding header. For tapes that contain headerless data blocks, headers with incorrect start addresses, or irrelevant blocks, the --ram option can be used to load bytes from specific blocks at the appropriate addresses. For example:

$ tap2sna.py --ram load=3,30000 game.tzx game.z80

loads the third block on the tape at address 30000, and ignores all other blocks. The --ram option can also be used to move blocks of bytes from one location to another, and POKE values into individual addresses or address ranges before the snapshot is saved. For more information on the operations that the --ram option can perform, run:

$ tap2sna.py --ram help

For complex snapshots that require many --ram, --reg or --state options to build, it may be more convenient to store the arguments to tap2sna.py in a file. For example, if the file game.t2s has the following contents:

;
; tap2sna.py file for GAME
;
http://example.com/pub/games/GAME.zip
game.z80
--ram load=4,32768         # Load the fourth block at 32768
--ram move=40960,512,43520 # Move 40960-41471 to 43520-44031
--reg pc=34816             # Start at 34816
--reg sp=32768             # Stack at 32768
--state iff=0              # Disable interrupts

then:

$ tap2sna.py @game.t2s

will create game.z80 as if the arguments specified in game.t2s had been given on the command line.

Parsing¶

In the first phase, the skool file is parsed. Parsing a skool file entails reading each line of the file, and processing any relevant ASM directives that are found along the way.

After an ASM directive has been processed, it is discarded, so that it cannot be ‘seen’ during the rendering phase. The purpose of the ASM directives is to transform the skool file into something suitable for rendering (in either HTML or ASM format) later on.

Whether a particular ASM directive is processed depends on the mode in which the parsing is being done: HTML mode or ASM mode.

@bfix-begin
 32459 CP 26  ; This is a bug; it should be 'CP 27'
@bfix+else
       CP 27  ;
@bfix+end

Rendering¶

In the second phase, the skool file (stripped of all its ASM directives during the parsing phase) is ‘rendered’ - as either HTML or ASM, depending on the mode.

Block descriptions¶

To provide a description for a code block at 24576 (for example), use the D directive thus:

c 24576 This is the title of the routine at 24576
D 24576 This is the description of the routine at 24576.

If the description consists of two or more paragraphs, declare each one with a separate D directive:

D 24576 This is the first paragraph of the description of the routine at 24576.
D 24576 This is the second paragraph of the description of the routine at 24576.

Register values¶

To declare the values of the registers upon entry to the routine at 24576, add one line per register with the R directive thus:

R 24576 A An important value in the accumulator
R 24576 DE Display file address

Block start comments¶

To declare a block start comment that will appear above the instruction at 24576, use the N directive thus:

N 24576 And so this routine begins.

If the start comment consists of two or more paragraphs, declare each one with a separate N directive:

N 24576 This is the first paragraph of the start comment.
N 24576 This is the second paragraph of the start comment.

Mid-block comments¶

To declare a mid-block comment that will appear above the instruction at 24592, use the N directive thus:

N 24592 The next section of code does something really important.

If the mid-block comment consists of two or more paragraphs, declare each one with a separate N directive:

N 24592 This is the first paragraph of the mid-block comment.
N 24592 This is the second paragraph of the mid-block comment.

Block end comments¶

To declare a comment that will appear at the end of the routine at 24576, use the E directive thus:

E 24576 And so the work of this routine is done.

If the block end comment consists of two or more paragraphs, declare each one with a separate E directive:

E 24576 This is the first paragraph of the end comment for the routine at 24576.
E 24576 This is the second paragraph of the end comment for the routine at 24576.

Sub-block syntax¶

Sometimes a block marked as one type (code, data, text, or whatever) may contain instructions or statements of another type. For example, a word (w) block may contain the odd non-word here and there. To declare such sub-blocks whose type does not match that of the containing block, use the following syntax:

w 32768 A block containing mostly words
B 32800,3 But here's a sub-block of 3 bytes at 32800
T 32809,8 And an 8-byte text string at 32809
C 32821,10 And 10 bytes of code at 32821
S 32831,17 Followed by 17 zeroes at 32831

The directives (B, T, C and S) used here to mark the sub-blocks are the upper case equivalents of the directives used to mark top-level blocks (b, t, c and s). The comments at the end of these sub-block declarations are taken as instruction-level comments and will appear as such in the resultant skool file.

If an instruction-level comment spans a group of two or more sub-blocks of different types, it must be declared with an M directive:

M 40000,21 This comment covers the following 3 sub-blocks
B 40000,3
W 40003,10
T 40013,8

If the length parameter is omitted from an M directive, the comment is assumed to cover all sub-blocks from the given start address to the end of the top-level block.

Three bits of sub-block syntax left. First, the blank sub-block directive:

c 24576 A great routine
  24580,11 A great section of code at 24580

This is equivalent to:

c 24576 A great routine
C 24580,11 A great section of code at 24580

That is, the the type of a blank sub-block directive is taken to be the same as that of the parent block.

Next, the address range:

c 24576 A great routine
  24580-24590 A great section of code at 24580

This is equivalent to:

c 24576 A great routine
  24580,11 A great section of code at 24580

That is, you can specify the extent of a sub-block using either an address range, or an address and a length.

Finally, the implicit sub-block extent:

c 24576 A great routine
  24580 A great section of code at 24580
  24588,10 Another great section of code at 24590

This is equivalent to:

c 24576 A great routine
  24580,8 A great section of code at 24580
  24588,10 Another great section of code at 24588

But the declaration of the length (8) of the sub-block at 24580 is redundant, because the sub-block is implicitly terminated by the declaration of the sub-block at 24588 that follows. This is exactly how top-level block declarations work: each top-level block is implicitly terminated by the declaration of the next one.

Sub-block lengths¶

Normally, a B sub-block declared thus:

B 24580,12 Interesting data

would result in something like this in the corresponding skool file:

24580 DEFB 1,2,3,4,5,6,7,8 ; {Interesting data
24588 DEFB 9,10,11,12      ; }

But what if you wanted to split the data in this sub-block into groups of 3 bytes each? That can be achieved with:

B 24580,12,3 Interesting data

which would give:

24580 DEFB 1,2,3    ; {Interesting data
24583 DEFB 4,5,6
24586 DEFB 7,8,9
24589 DEFB 10,11,12 ; }

That is, in a B directive, the desired DEFB statement lengths may be given as a comma-separated list of numbers following the sub-block length parameter, and the final number in the list is used for all remaining data in the block. So, for example:

B 24580,12,1,2,3 Interesting data

would give:

24580 DEFB 1        ; {Interesting data
24581 DEFB 2,3
24583 DEFB 4,5,6
24586 DEFB 7,8,9
24589 DEFB 10,11,12 ; }

If the statement length list contains sequences of two or more identical lengths, as in:

B 24580,21,2,2,2,2,2,2,1,1,1,3

then it may be abbreviated thus:

B 24580,21,2*6,1*3,3

The same syntax can be used for S, T, W sub-blocks too. For example:

S 32768,100,25 Four 25-byte chunks of zeroes

would give:

32768 DEFS 25 ; {Four 25-byte chunks of zeroes
32793 DEFS 25
32818 DEFS 25
32843 DEFS 25 ; }

DEFB and DEFM statements may contain both bytes and strings; for example:

40000 DEFM "Hi ",5
40004 DEFB 4,"go"

Such statements can be encoded in a control file thus:

T 40000,4,3:B1
B 40004,3,1:T2

That is, the length of a string in a DEFB statement is prefixed by T, the length of a sequence of bytes in a DEFM statement is prefixed by B, and the lengths of all strings and byte sequences are separated by colons. This notation can also be combined with the ‘*’ notation; for example:

T 50000,8,2:B2*2

which is equivalent to:

T 50000,8,2:B2,2:B2

DEFS statements may specify a byte value other than zero; for example:

60000 DEFS 20,170
60020 DEFS 40,85

These statements can be encoded in a control file thus:

S 60000,60,20:170,40:85

Loops¶

Sometimes the instructions and statements in a code or data block follow a repeating pattern. For example:

b 30000 Two bytes and one word, times ten
B 30000,2
W 30002
B 30004,2
W 30004
...
B 30036,2
W 30038

Repeating patterns like this can be expressed more succinctly as a loop by using the L directive, which has the following format:

L start,length,count[,blocks]

where:

• start is the loop start address
• length is the length of the loop (the size of the address range to repeat)
• count is the number of times to repeat the loop (only values of 2 or more make sense)
• blocks is 1 to repeat block-level elements, or 0 to repeat only sub-block elements (default: 0)

So using the L directive, the body of the data block above can be expressed in three lines instead of 20:

b 30000 Two bytes and one word, times ten
B 30000,2
W 30002
L 30000,4,10

The L directive can also be used to repeat entire blocks, by setting the blocks argument to 1. For example:

b 40000 A block of five pairs of bytes
B 40000,10,2
L 40000,10,3,1

is equivalent to:

b 40000 A block of five pairs of bytes
B 40000,10,2
b 40010 A block of five pairs of bytes
B 40010,10,2
b 40020 A block of five pairs of bytes
B 40020,10,2

Note that ASM directives in the address range of an L directive loop are not repeated.

Number bases¶

Numeric values in DEFB, DEFM, DEFS and DEFW statements are normally rendered in either decimal or hexadecimal, depending on the options passed to sna2skool.py. To force a numeric value to be rendered in a specific base, attach a b (binary), d (decimal) or h (hexadecimal) prefix to the statement length.

For example:

B 40000,8,b1:d2:h1,d1,b1,h2

will result in something like this in the corresponding skool file:

40000 DEFB %10101010,23,43,$5F
40004 DEFB 56
40005 DEFB %11110000
40006 DEFB $2B,$80

ASM directives¶

To declare an ASM directive for a block or an individual instruction, use the @ directive thus:

@ address directive[=value]

where:

• directive is the directive name
• address is the address of the block or instruction to which the directive applies
• value is the value of the directive (if it requires one)

For example, to declare a @label directive for the instruction at 32768:

@ 32768 label=LOOP

When declaring an @ignoreua directive for anything other than an instruction-level comment, a suffix must be appended to the directive to specify the type of comment it applies to:

@ address ignoreua:X

where X is one of:

• d - entry description
• e - block end comment
• i - instruction-level comment (default)
• m - block start comment or mid-block comment
• r - register description section
• t - entry title

For example, to declare an @ignoreua directive for the description of the routine at 49152:

@ 49152 ignoreua:d
D 49152 This is the description of the routine at 49152.

Note that neither ASM block directives (such as the @bfix block directives) nor the exact location of @org, @writer, @start, @end and @set directives can be preserved in a control file.

Instruction-level comments¶

One limitation of storing instruction-level comments as shown so far is that there is no way to distinguish between a blank comment that spans two or more instructions and no comment at all. For example, both:

30000 DEFB 0 ; {
30001 DEFB 0 ; }

and:

30000 DEFB 0 ;
30001 DEFB 0 ;

would be preserved thus:

B 30000,2,1

To solve this problem, a special syntax is used to preserve blank multi-instruction comments:

B 30000,2,1 .

When restored, this comment is reduced to an empty string.

But how then to preserve a multi-instruction comment consisting of a single dot (.), or a sequence of two or more dots? In that case, another dot is prefixed to the comment. So:

30000 DEFB 0 ; {...
30001 DEFB 0 ; }

is preserved thus:

B 30000,2,1 ....

Note that this scheme does not apply to multi-instruction comments that contain at least one character other than a dot; such comments are preserved verbatim (that is, without a dot prefix).

Control file comments¶

A comment may be added to a control file by starting a line with a hash character (#), a per cent sign (%), or a semicolon - so long as the next non-whitespace character is not @, because ; @ is the deprecated (but still valid) way to declare an ASM directive. For example:

# This is a comment
% This is another comment
; This is yet another comment

Limitations¶

A control file can be useful in the early stages of developing a skool file for reorganising code and data blocks, but it cannot preserve the following:

• ASM block directives
• the exact locations of @org, @writer, @start, @end and @set directives
• data definition entries (‘d’ blocks) and remote entries (‘r’ blocks)
• comments that are not part of a code or data block

Skool file templates, however, can preserve all of these elements, and so may be a better choice for skool files that contain any of them.

Revision history¶

Skool file format¶

A skool file must be in a certain format to ensure that it is processed correctly by skool2html.py, skool2asm.py, skool2ctl.py and skool2sft.py. The rules are as follows:

• entries (an ‘entry’ being a routine or data block) must be separated by blank lines, and an entry must not contain any blank lines
• an entry header is a sequence of comment lines broken into four sections; see Entry header format
• each line in an entry may start with one of the following characters: ;* @bcdgirstuw; see Entry line format
• tables (grids) have their own markup syntax; see #TABLE for details

; This is the entry title
;
; This is the first paragraph of the entry description.
; .
; This is the second paragraph of the entry description.
;
; A An important parameter
; B Another important parameter
;
; This is the start comment above the first instruction in the entry.

; This entry has a start comment but no register section
;
; This is the entry description.
;
; .
;
; This is the start comment above the first instruction in the entry.

; This entry has a register section but no description
;
; .
;
; A An important parameter
; B Another important parameter

;  Input:A An important parameter
;        B Another important parameter
; Output:C The result

; HL The description for this register is quite long, so it is split over two
; .  lines for improved readability

C##### INSTRUCTION[ ; comment]

c24296 CALL 57935    ; This comment is too long to fit on a single line, so
                     ; we use two lines

*24372 SUB D         ; {This comment applies to the two instructions at
 24373 JR NZ,24378   ; 24372 and 24373}

*28975 JR 28902
; This is a mid-block comment between two instructions.
; .
; This is the second paragraph of the comment.
 28977 XOR A

ASM directives¶

To write an ASM directive in a skool file, start a line with @; for example:

; Start the game
@label=START
c24576 XOR A

See ASM modes and directives for more details.

Braces in comments¶

As noted above, opening and closing braces ({, }) are used to mark the start and end points of an instruction-level comment that is associated with more than one instruction, and the braces are removed before the comment is rendered. This means that if the comment requires an opening or closing brace when rendered, some care must be taken to get the syntax correct.

The rules regarding an instruction-level comment that starts with an opening brace are as follows:

• The comment terminates on the line where the total number of closing braces in the comment becomes equal to or greater than the total number of opening braces
• Adjacent opening braces at the start of the comment are removed before rendering
• Adjacent closing braces at the end of the comment are removed before rendering

By these rules, it is possible to craft an instruction-level comment that contains matched or unmatched opening and closing braces when rendered.

For example:

b50000 DEFB 0  ; {{This comment (which spans two instructions) has an
 50001 DEFB 0  ; unmatched closing brace} }

will render in ASM mode as:

DEFB 0                  ; This comment (which spans two instructions) has an
DEFB 0                  ; unmatched closing brace}

And:

b50002 DEFB 0  ; { {{Matched opening and closing braces}} }

will render as:

DEFB 0                  ; {{Matched opening and closing braces}}

Finally:

b50003 DEFB 0  ; { {Unmatched opening brace}}

will render as:

DEFB 0                  ; {Unmatched opening brace

Data definition entries¶

If the first instruction line in an entry starts with d, the entry is regarded as a data definition entry. Such entries do not appear in the memory map generated by skool2html.py, but may contain DEFB, DEFW, DEFM and DEFS assembler directives that will be parsed, and so can be used to insert data into the memory snapshot.

For example:

; The eight bytes of code in this routine are also used as UDG data.
; .
; #HTML(#UDG44919)
c44919 LD DE,46572   ;
 44922 CP 200        ;
 44924 JP 45429      ;

d44919 DEFB 17,236,181,254,200,195,117,177

This data definition entry is required to define the bytes for addresses 44919-44926. If it were not present, the memory snapshot would contain zeroes at those addresses, and the UDG created by skool2html.py would be blank. The reason for this is that the skool file parser will only convert DEFB, DEFW, DEFM and DEFS assembler directives into a sequence of bytes; it does not convert assembly language instructions into the equivalent byte values (it is not a Z80 assembler).

Remote entries¶

If the first instruction line in an entry starts with r, the entry is regarded as a remote entry. Such entries do not appear in the memory map generated by skool2html.py, but they enable JR, JP and CALL instructions to be hyperlinked to entries defined in other skool files.

For example:

r26880 main

This entry, if it were present in a secondary skool file, would enable any JR, JP and CALL instruction with 26880 as the operand to be hyperlinked to that routine in the main disassembly (the entry for which should be defined in the main skool file).

If the desired target of the hyperlink is an entry point within a routine that is defined in another skool file (as opposed to the address of the routine itself), both the routine address and the entry point address should be declared in the remote entry. For example:

r29012 main
 29015

This enables hyperlinks to 29015 in the main disassembly, which is an entry point in the routine at 29012. It also enables the #R macro to create hyperlinks to remote entry points using the short form:

#R29015@main

instead of the longer form (which would be required if the remote entry were not defined):

#R29012@main#29015(29015)

Revision history¶

Skool file template format¶

A skool file template has the same layout as a skool file, except that the lines in ‘b’, ‘c’, ‘g’, ‘s’, ‘t’, ‘u’ and ‘w’ blocks that correspond to Z80 instructions look like this:

xX#####,n[;c[ comment]]

where:

• x is one of the characters * bcgstuw (with the same meaning as in a skool file)
• X is one of the characters BCSTW (with the same meaning as in a control file)
• ##### is the address at which to start disassembling
• n is the number of bytes to disassemble
• c is the index of the column in which the comment marker (;) appears in the line (if it does appear)
• comment, if present, is the instruction-level comment for the line on which the instruction occurs

If a comment for a single instruction spans two or more lines in a skool file, as in:

c24296 CALL 57935    ; This comment is too long to fit on a single line, so
                     ; we use two lines

then it will be rendered in the skool file template thus:

cC24296,3;21 This comment is too long to fit on a single line, so
 ;21 we use two lines

Sub-block syntax¶

The syntax for specifying B, S, T and W sub-blocks is analogous to the syntax used in control files. A brief summary of the syntax is given here.

Sequences of DEFB statements can be declared on a single line thus:

bB40960,8*2,5

which is equivalent to:

bB40960,8
 B40968,8
 B40976,5

The same syntax also applies for declaring sequences of DEFM, DEFS and DEFW statements.

DEFB and DEFM statements may contain both strings and bytes; for example:

b30000 DEFB 1,2,3,4,"Hello!"
 30010 DEFM 5,6
 30012 DEFM "B",7,8

Such statements are preserved in a skool file template thus:

bB30000,4:T6
 T30010,B2,1:B2

DEFB, DEFM, DEFS and DEFW statements may contain numeric values in various bases; for example:

b40000 DEFB %10101010,23,43,$5F
 40004 DEFB 56
 40005 DEFB %11110000
 40006 DEFB $2B,$80

These statements may be preserved in a skool file template thus:

bB40000,b1:d2:h1,d1,b1,h2

Skool file template comments¶

Any line that begins with a hash character (#) is ignored by sna2skool.py, and will not show up in the skool file.

Data definition entries¶

In the same way as skool2html.py uses data definition entries (‘d’ blocks) in a skool file to insert data into the memory snapshot it constructs, sna2skool.py uses data definition entries in a skool file template to replace data in the snapshot given on the command line. This feature can be used to make sure that a ‘volatile’ part of memory is set to a specific value before being disassembled.

For example, if address 32400 holds the number of lives, you could make sure that its contents are set to 0 so that it will disassemble to DEFB 0 (whatever the contents may be in the snapshot itself) thus:

d32400 DEFB 0

; Number of lives
bB32400,1

Note that in order to take effect, a ‘d’ block must appear before the block that it overrides.

Revision history¶

General macros¶

#BUG[#name][(link text)]

 42726 DEFB 130 ; This is a #BUG#bug1; it should be 188

#CALL:methodName(args)

; The byte at address 32768 is #CALL:peek(32768).

#CHRnum

#CHR(num)

 26751 DEFB 127   ; This is the copyright symbol: #CHR169

#Daddr

; Now we make an indirect jump to one of the following routines:
; .
; #TABLE(default,centre)
; { =h Address | =h Description }
; { #R27126    | #D27126 }

#EREFSaddr

#FACT[#name][(link text)]

See the trivia entry #FACT#interestingFact() for details.

#HTML(text)

; #HTML(For more information, go <a href="http://example.com/">here</a>.)

#HTML[text]
#HTML{text}
#HTML@text@

; #HTML[The UDG defined here (32768) looks like this: #UDG32768,4,1]

#LINK:PageId[#name](link text)

; See the #LINK:Glossary(glossary) for a definition of 'chuntey'.

#LIST[(class)]<items>LIST#

; #LIST(data)
; { Item 1 }
; { Item 2 }
; LIST#

#POKE[#name][(link text)]

; Of course, if you feel like cheating, you can always give yourself
; #POKE#infiniteLives(infinite lives).

#Raddr[@code][#name][(link text)]

; Prepare for a new game
;
; Used by the routine at #R25820.

#REFSaddr[(prefix)]

Not used directly by any other routines

#REGreg

abcdefhlirspxy'

 24623 LD C,31       ; #REGbc'=31

#SPACE[num]

#SPACE([num])

; '#SPACE8' (8 spaces)
t56832 DEFM "        "

        

; 'Score:#SPACE(5)0'
t49152 DEFM "Score:     0"

#TABLE[([class[,class1[:w][,class2[:w]...]]])]<rows>TABLE#

; #TABLE(default,centre)
; { 0 | Off }
; { 1 | On }
; TABLE#

; #TABLE
; { =h Header 1  | =h Header 2 }
; { Regular cell | Another one }
; TABLE#

; #TABLE
; { =r2 2 rows  | X | Y }
; { =c2           2 columns }
; TABLE#

; #TABLE
; { =h,c2 Wide header }
; { Column 1 | Column 2 }
; TABLE#

; #TABLE(default,centre,:w)
; { =h X | =h Description }
; { 0    | Text in this column will be wrapped in ASM mode to make the table less than 80 characters wide }
; TABLE#

Image macros¶

The #FONT, #SCR, #UDG and #UDGARRAY macros (described in the following sections) may be used to create images based on graphic data in the memory snapshot. They are not supported in ASM mode.

These macros have several numeric parameters, most of which are optional. This can give rise to a long sequence of commas in a macro parameter string, making it hard to read (and write); for example:

#UDG32768,,,,,,1

To alleviate this problem, the image macros accept keyword arguments at any position in the parameter string; the #UDG macro above could be rewritten as follows:

#UDG32768,rotate=1

#FONT[:(text)]addr[,chars,attr,scale][{CROP}][(fname)]

#FONT:[(0) OK]$3D00
#FONT:{(0) OK}$3D00
#FONT:/(0) OK/$3D00

; Font graphic data
;
; #HTML[#FONT:(0123456789)49152]

#SCR[scale,x,y,w,h,df,af][{CROP}][(fname)]

; #UDGTABLE
; { #SCR(loading) | This is the loading screen. }
; TABLE#

#UDGaddr[,attr,scale,step,inc,flip,rotate,mask][:MASK][{CROP}][(fname)]

addr[,step]

; Safe key UDG
;
; #HTML[#UDG39144,6(safe_key)]

#UDGARRAYwidth[,attr,scale,step,inc,flip,rotate,mask];SPEC1[;SPEC2;...][{CROP}](fname)

addr[,attr,step,inc][:MASK]

addr[,step]

; Base sprite
;
; #HTML[#UDGARRAY4;32768-32888-8(base_sprite.png)]

#SCR(screenshot1|Screenshot 1)

#UDGARRAY*FRAME1[;FRAME2;...](fname)

name[,delay]

; #UDGTABLE {
; #FONT:(hello)$3D00(hello*) |
; #FONT:(there)$3D00(there*) |
; #FONT:(peeps)$3D00(peeps*) |
; #UDGARRAY*hello,50;there;peeps(hello_there_peeps.gif)
; } TABLE#

x,y,width,height

#UDG40000,scale=2{2,2,12,12}

Snapshot macros¶

The #POKES, #POPS and #PUSHS macros (described in the following sections) may be used to manipulate the memory snapshot that is built from the DEFB, DEFM, DEFS and DEFW statements in the skool file. Each macro expands to an empty string.

#POKESaddr,byte[,length,step][;addr,byte[,length,step];...]

The UDG looks like this:

#UDG32768(udg_orig)

But it's supposed to look like this:

#PUSHS
#POKES32772,254;32775,136
#UDG32768(udg_fixed)
#POPS

#POPS

#PUSHS[name]

[Bug:*:*]¶

Each Bug:*:* section defines an entry on the ‘Bugs’ page. The section names and contents take the form:

[Bug:anchor:title]
First paragraph.

Second paragraph.

...

where:

• anchor is the name of the HTML anchor for the entry
• title is the title of the entry

To ensure that an entry can be linked to by the #BUG macro, the anchor name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.

Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.

[Changelog:*]¶

Each Changelog:* section defines an entry on the ‘Changelog’ page. The section names and contents take the form:

[Changelog:title]
Intro text.

First top-level item.
  First subitem.
  Second subitem.
    First subsubitem.

Second top-level item.
...

where title is the title of the entry, and the intro text and top-level items are separated by blank lines. Lower-level items are created by using indentation, as shown.

If the intro text is a single hyphen (-), it will not be included in the final HTML rendering.

The intro text and changelog items may contain HTML markup and skool macros.

[Colours]¶

The Colours section contains colour definitions that will be used when creating images. Each line has the form:

name=R,G,B

or:

name=#RGB

where:

• name is the colour name
• R,G,B is a decimal RGB triplet
• #RGB is a hexadecimal RGB triplet (in the usual 6-digit form, or in the short 3-digit form)

Recognised colour names and their default RGB values are:

• TRANSPARENT: 0,254,0 (#00fe00)
• BLACK: 0,0,0 (#000000)
• BLUE: 0,0,197 (#0000c5)
• RED: 197,0,0 (#c50000)
• MAGENTA: 197,0,197 (#c500c5)
• GREEN: 0,198,0 (#00c600)
• CYAN: 0,198,197 (#00c6c5)
• YELLOW: 197,198,0 (#c5c600)
• WHITE: 205,198,205 (#cdc6cd)
• BRIGHT_BLUE: 0,0,255 (#0000ff)
• BRIGHT_RED: 255,0,0 (#ff0000)
• BRIGHT_MAGENTA: 255,0,255 (#ff00ff)
• BRIGHT_GREEN: 0,255,0 (#00ff00)
• BRIGHT_CYAN: 0,255,255 (#00ffff)
• BRIGHT_YELLOW: 255,255,0 (#ffff00)
• BRIGHT_WHITE: 255,255,255 (#ffffff)

[Config]¶

The Config section contains configuration parameters in the format:

name=value

Recognised parameters are:

• GameDir - the root directory of the game’s HTML disassembly; if not specified, the base name of the skool or ref file given on the skool2html.py command line will be used
• HtmlWriterClass - the name of the Python class to use for writing the HTML disassembly of the game (default: skoolkit.skoolhtml.HtmlWriter); if the class is in a module that is not in the module search path (e.g. a standalone module that is not part of an installed package), the module’s location may be specified thus: /path/to/moduledir:module.classname
• SkoolFile - the name of the main skool file to use if not given on the skool2html.py command line; if not specified, the skool file with the same base name as the ref file will be used

For information on how to create your own Python class for writing an HTML disassembly, see the documentation on extending SkoolKit.

[Fact:*:*]¶

Each Fact:*:* section defines an entry on the ‘Trivia’ page. The section names and contents take the form:

[Fact:anchor:title]
First paragraph.

Second paragraph.

...

where:

• anchor is the name of the HTML anchor for the entry
• title is the title of the entry

To ensure that an entry can be linked to by the #FACT macro, the anchor name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.

Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.

[Game]¶

The Game section contains configuration parameters that control certain aspects of the HTML output. The parameters are in the format:

name=value

Recognised parameters are:

• AddressAnchor - the format of the anchors attached to instructions on disassembly pages and entries on memory map pages (default: {address})
• Copyright - the copyright message that appears in the footer of every page (default: ‘’)
• Created - the message indicating the software used to create the disassembly that appears in the footer of every page (default: ‘Created using SkoolKit $VERSION.’; the string $VERSION is replaced by the version number of SkoolKit)
• Font - the base name of the font file to use (default: None); multiple font files can be declared by separating their names with semicolons
• Game - the name of the game, which appears in the title of every page, and also in the header of every page (if no logo is defined); if not specified, the base name of the skool file is used
• GameStatusBufferIncludes - a comma-separated list of addresses of entries to include on the ‘Game status buffer’ page in addition to those that are marked with a g (see the skool file format reference)
• InputRegisterTableHeader - the text displayed in the header of input register tables on routine disassembly pages (default: ‘Input’)
• JavaScript - the base name of the JavaScript file to include in every page (default: None); multiple JavaScript files can be declared by separating their names with semicolons
• LinkInternalOperands - 1 to hyperlink instruction operands that refer to an address in the same entry as the instruction, or 0 to leave them unlinked (default: 0)
• LinkOperands - a comma-separated list of instruction types whose operands will be hyperlinked when possible (default: CALL,DEFW,DJNZ,JP,JR); add LD to the list to enable the address operands of LD instructions to be hyperlinked as well
• Logo - the text/HTML that will serve as the game logo in the header of every page (typically a skool macro that creates a suitable image); if not specified, LogoImage is used
• LogoImage - the path to the game logo image, which appears in the header of every page; if the specified file does not exist, the name of the game is used in place of an image
• OutputRegisterTableHeader - the text displayed in the header of output register tables on routine disassembly pages (default: ‘Output’)
• Release - the message indicating the release name and version number of the disassembly that appears in the footer of every page (default: ‘’)
• StyleSheet - the base name of the CSS file to use (default: skoolkit.css); multiple CSS files can be declared by separating their names with semicolons
• TitlePrefix - the prefix to use before the game name or logo in the header of the main index page (default: ‘The complete’)
• TitleSuffix - the suffix to use after the game name or logo in the header of the main index page (default: ‘RAM disassembly’)

The AddressAnchor parameter contains a standard Python format string that specifies the format of the anchors attached to instructions on disassembly pages and entries on memory map pages. The default format string is {address}, which produces decimal addresses (e.g. #65280); to produce 4-digit, lower case hexadecimal addresses instead (e.g. #ff00), change AddressAnchor to {address:04x}.

Note that an address anchor that starts with an upper case letter (e.g. #FF00) will be interpreted as a skool macro, and so any template that could produce such an anchor should be avoided.

[Glossary:*]¶

Each Glossary:* section defines an entry on the ‘Glossary’ page. The section names and contents take the form:

[Glossary:term]
First paragraph.

Second paragraph.

...

where term is the term being defined in the entry.

Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.

[GraphicGlitch:*:*]¶

Each GraphicGlitch:*:* section defines an entry on the ‘Graphic glitches’ page. The section names and contents take the form:

[GraphicGlitch:anchor:title]
First paragraph.

Second paragraph.

...

where:

• anchor is the name of the HTML anchor for the entry
• title is the title of the entry

Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.

[ImageWriter]¶

The ImageWriter section contains configuration parameters that control SkoolKit’s image creation library. The parameters are in the format:

name=value

Recognised parameters are:

• DefaultFormat - the default image format; valid values are png (the default) and gif
• GIFEnableAnimation - 1 to create animated GIFs for images that contain flashing cells, or 0 to create plain (unanimated) GIFs for such images (default: 1)
• GIFTransparency - 1 to make the TRANSPARENT colour (see [Colours]) in GIF images transparent, or 0 to make it opaque (default: 0)
• PNGAlpha - the alpha value to use for the TRANSPARENT colour (see [Colours]) in PNG images; valid values are in the range 0-255, where 0 means fully transparent, and 255 means fully opaque (default: 255)
• PNGCompressionLevel - the compression level to use for PNG image data; valid values are in the range 0-9, where 0 means no compression, 1 is the lowest compression level, and 9 is the highest (default: 9)
• PNGEnableAnimation - 1 to create animated PNGs (in APNG format) for images that contain flashing cells, or 0 to create plain (unanimated) PNG files for such images (default: 1)

The image-creating skool macros will create a file in the default image format if the filename is unspecified, or its suffix is omitted, or its suffix is neither .png nor .gif. For example, if DefaultFormat is png, then:

#FONT32768,26

will create an image file named font.png. To create a GIF instead (regardless of the default image format):

#FONT32768,26(font.gif)

For images that contain flashing cells, animated GIFs are recommended over animated PNGs in APNG format, because they are more widely supported in web browsers.

[Index]¶

The Index section contains a list of link group IDs in the order in which the link groups will appear on the disassembly index page. The link groups themselves - with the exception of OtherCode - are defined in [Index:*:*] sections (see below); OtherCode is a special built-in link group that contains links to the index pages of secondary disassemblies defined by [OtherCode:*] sections.

To see the default Index section, run the following command:

$ skool2html.py -r Index$

[Index:*:*]¶

Each Index:*:* section defines a link group (a group of links on the disassembly home page). The section names and contents take the form:

[Index:groupID:text]
Page1ID
Page2ID
...

where:

• groupID is the link group ID (as may be declared in the [Index] section)
• text is the text of the link group header
• Page1ID, Page2ID etc. are the IDs of the pages that will appear in the link group

To see the default link groups and their contents, run the following command:

$ skool2html.py -r Index:

[Links]¶

The Links section defines the link text for the various pages in the HTML disassembly (as displayed on the disassembly index page). Each line has the form:

PageID=text

where:

• PageID is the ID of the page
• text is the link text

Recognised page IDs are:

• Bugs - the ‘Bugs’ page
• Changelog - the ‘Changelog’ page
• DataMap - the ‘Data’ memory map page
• Facts - the ‘Trivia’ page
• GameStatusBuffer - the ‘Game status buffer’ page
• Glossary - the ‘Glossary’ page
• GraphicGlitches - the ‘Graphic glitches’ page
• MemoryMap - the ‘Everything’ memory map page (default: ‘Everything’)
• MessagesMap - the ‘Messages’ memory map page
• Pokes - the ‘Pokes’ page
• RoutinesMap - the ‘Routines’ memory map page
• UnusedMap - the ‘Unused addresses’ memory map page

The default link text for a page is the same as the header defined in the [PageHeaders] section, except where indicated above.

The link text for a page defined by a [MemoryMap:*], [OtherCode:*], [Page:*] or [PageContent:*] section also defaults to the page header text, but can be overridden in this section.

If the link text starts with some text in square brackets, that text alone is used as the link text, and the remaining text is displayed alongside the hyperlink. For example:

MemoryMap=[Everything] (routines, data, text and unused addresses)

This declares that the link text for the ‘Everything’ memory map page will be ‘Everything’, and ‘(routines, data, text and unused addresses)’ will be displayed alongside it.

[MemoryMap:*]¶

Each MemoryMap:* section defines the properties of a memory map page. The section names take the form:

[MemoryMap:PageID]

where PageID is the unique ID of the memory map page.

Each MemoryMap:* section contains parameters in the form:

name=value

Recognised parameters and their default values are:

• EntryDescriptions - 1 to display entry descriptions, or 0 not to (default: 0)
• EntryTypes - the types of entries to show in the map (by default, every type is shown); entry types are identified as follows:
  • b - DEFB blocks
  • c - routines
  • g - game status buffer entries
  • G - entries whose address appears in the GameStatusBufferIncludes parameter in the [Game] section
  • s - blocks containing bytes that are all the same value
  • t - messages
  • u - unused addresses
  • w - DEFW blocks
• Intro - the text (which may contain HTML markup and skool macros) displayed at the top of the memory map page (default: ‘’)
• LengthColumn - 1 to display the ‘Length’ column, or 0 not to (default: 0)
• PageByteColumns - 1 to display ‘Page’ and ‘Byte’ columns, or 0 not to (default: 0)
• Write - 1 to write the memory map page, or 0 not to (default: 1)

To see the default memory map pages and their properties, run the following command:

$ skool2html.py -r MemoryMap

A custom memory map page can be defined by creating a MemoryMap:* section for it. By default, the page will be written to maps/PageID.html; to change this, add a line to the [Paths] section. The title, page header and link text for the custom memory map page can be defined in the [Titles], [PageHeaders] and [Links] sections.

Every memory map page is built using the HTML template whose name matches the page ID, if one exists; otherwise, the stock MemoryMap template is used.

[OtherCode:*]¶

An OtherCode:* section defines a secondary disassembly that will appear under ‘Other code’ on the main disassembly home page. The section name takes the form:

[OtherCode:CodeID]

where CodeID is a unique ID for the secondary disassembly; it must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z. The unique ID may be used by the #R macro when referring to routines or data blocks in the secondary disassembly from another disassembly.

An OtherCode:* section must contain a single parameter named Source in the form:

Source=fname

where fname is the path to the skool file from which to generate the secondary disassembly.

When a secondary disassembly named CodeID is defined, the following page and directory IDs become available for use in the [Paths], [Titles], [PageHeaders] and [Links] sections:

• CodeID-Index - the ID of the index page
• CodeID-Asm-* - the IDs of the disassembly pages (* is one of bcgstuw, depending on the entry type)
• CodeID-CodePath - the ID of the directory in which the disassembly pages are written

By default, the index page is written to CodeID/CodeID.html, and the disassembly pages are written in a directory named CodeID.

Note that the index page is a memory map page, and as such can be configured by creating a [MemoryMap:*] section (MemoryMap:CodeID-Index) for it.

[Page:*]¶

A Page:* section may be used to either declare a page that already exists, or define a custom page in the HTML disassembly (in conjunction with a corresponding [PageContent:*] section). The section name takes the form:

[Page:PageID]

where PageID is a unique ID for the page. The unique ID may be used in an [Index:*:*] section to create a link to the page in the disassembly index.

A Page:* section contains parameters in the form:

name=value

Recognised parameters are:

• Content - the path (directory and filename) of a page that already exists; when this parameter is supplied, no others are required
• JavaScript - the base name of the JavaScript file to use in addition to any declared by the JavaScript parameter in the [Game] section (default: None); multiple JavaScript files can be declared by separating their names with semicolons
• PageContent - the HTML source of the body of the page; this defaults to the contents of the corresponding [PageContent:*] section, but may be specified here if the source can be written on a single line

By default, the custom page is written to a file named PageID.html in the root directory of the disassembly; to change this, add a line to the [Paths] section. The title, page header and link text for the custom page can be defined in the [Titles], [PageHeaders] and [Links] sections.

Every custom page is built using the HTML template whose name matches the page ID, if one exists; otherwise, the stock Page template is used.

Note that a Page:* section may be empty; if so, it may be omitted from the ref file.

[PageContent:*]¶

A PageContent:* section contains the HTML source of the body of a custom page (optionally defined in a [Page:*] section). The section name takes the form:

[PageContent:PageID]

where PageID is the unique ID of the page.

The HTML source may contain skool macros.

[PageHeaders]¶

The PageHeaders section defines the header text for every page in the HTML disassembly. Each line has the form:

PageID=header

where:

• PageID is the ID of the page
• header is the header text

Recognised page IDs are:

• Asm-b - disassembly pages for ‘b’ blocks (default: ‘Data’)
• Asm-c - disassembly pages for ‘c’ blocks (default: ‘Routines’)
• Asm-g - disassembly pages for ‘g’ blocks (default: ‘Game status buffer’)
• Asm-s - disassembly pages for ‘s’ blocks (default: ‘Unused’)
• Asm-t - disassembly pages for ‘t’ blocks (default: ‘Data’)
• Asm-u - disassembly pages for ‘u’ blocks (default: ‘Unused’)
• Asm-w - disassembly pages for ‘w’ blocks (default: ‘Data’)
• Bugs - the ‘Bugs’ page
• Changelog - the ‘Changelog’ page
• DataMap - the ‘Data’ memory map page
• Facts - the ‘Trivia’ page
• GameStatusBuffer - the ‘Game status buffer’ page
• Glossary - the ‘Glossary’ page
• GraphicGlitches - the ‘Graphic glitches’ page
• MemoryMap - the ‘Everything’ memory map page
• MessagesMap - the ‘Messages’ memory map page
• Pokes - the ‘Pokes’ page
• RoutinesMap - the ‘Routines’ memory map page
• UnusedMap - the ‘Unused addresses’ memory map page

The default header text for a page is the same as the title defined in the [Titles] section, except where indicated above.

The header text for a page defined by a [MemoryMap:*], [OtherCode:*], [Page:*] or [PageContent:*] section also defaults to the title, but can be overridden in this section.

Note that the header of the disassembly index page (GameIndex) is not defined in this section; it is composed from the values of the TitlePrefix and TitleSuffix parameters in the [Game] section.

[Paths]¶

The Paths section defines the locations of the files and directories in the HTML disassembly. Each line has the form:

ID=path

where:

• ID is the ID of the file or directory
• path is the path of the file or directory relative to the root directory of the disassembly

Recognised file IDs and their default paths are:

• Bugs - the ‘Bugs’ page (default: reference/bugs.html)
• Changelog - the ‘Changelog’ page (default: reference/changelog.html)
• CodeFiles - the format of the disassembly page filenames (default: {address}.html)
• DataMap - the ‘Data’ memory map page (default: maps/data.html)
• Facts - the ‘Trivia’ page (default: reference/facts.html)
• GameIndex - the home page (default: index.html)
• GameStatusBuffer - the ‘Game status buffer’ page (default: buffers/gbuffer.html)
• Glossary - the ‘Glossary’ page (default: reference/glossary.html)
• GraphicGlitches - the ‘Graphic glitches’ page (default: graphics/glitches.html)
• MemoryMap - the ‘Everything’ memory map page (default: maps/all.html)
• MessagesMap - the ‘Messages’ memory map page (default: maps/messages.html)
• Pokes - the ‘Pokes’ page (default: reference/pokes.html)
• RoutinesMap - the ‘Routines’ memory map page (default: maps/routines.html)
• UnusedMap - the ‘Unused addresses’ memory map page (default: maps/unused.html)

Recognised directory IDs and their default paths are:

• CodePath - the directory in which the disassembly pages are written (default: asm)
• FontImagePath - the directory in which font images (created by the #FONT macro) are placed (default: images/font)
• FontPath - the directory in which font files specified by the Font parameter in the [Game] section are placed (default: .)
• JavaScriptPath - the directory in which JavaScript files specified by the JavaScript parameter in the [Game] section and [Page:*] sections are placed (default: .)
• ScreenshotImagePath - the directory in which screenshot images (created by the #SCR macro) are placed (default: images/scr)
• StyleSheetPath - the directory in which CSS files specified by the StyleSheet parameter in the [Game] section are placed (default: .)
• UDGImagePath - the directory in which UDG images (created by the #UDG or #UDGARRAY macro) are placed (default: images/udgs)

The CodeFiles parameter contains a standard Python format string that specifies the format of a disassembly page filename based on the address of the routine or data block. The default format string is {address}.html, which produces decimal addresses (e.g. 65280.html); to produce 4-digit, upper case hexadecimal addresses instead (e.g. FF00.html), change CodeFiles to {address:04X}.html.

[Poke:*:*]¶

Each Poke:*:* section defines an entry on the ‘Pokes’ page. The section names and contents take the form:

[Poke:anchor:title]
First paragraph.

Second paragraph.

...

where:

• anchor is the name of the HTML anchor for the entry
• title is the title of the entry

To ensure that an entry can be linked to by the #POKE macro, the anchor name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.

Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.

[Resources]¶

The Resources section lists files that will be copied into the disassembly build directory when skool2html.py is run. Each line has the form:

fname=destDir

where:

• fname is the name of the file to copy
• destDir is the destination directory, relative to the root directory of the disassembly; the directory will be created if it doesn’t already exist

The files to be copied must be present in skool2html.py‘s search path in order for it to find them; to see the search path, run skool2html.py -s.

If your disassembly requires pre-built images or other resources that SkoolKit does not build, listing them in this section ensures that they will be copied into place whenever the disassembly is built.

[Template:*]¶

Each Template:* section defines a template used to build an HTML page (or part of one).

To see the contents of the default templates, run the following command:

$ skool2html.py -r Template:

For more information, see HTML templates.

[Titles]¶

The Titles section defines the title (i.e. text used to compose the <title> element) for every page in the HTML disassembly. Each line has the form:

PageID=title

where:

• PageID is the ID of the page
• title is the page title

Recognised page IDs and their default titles are:

• Asm-b - disassembly pages for ‘b’ blocks (default: ‘Data at’)
• Asm-c - disassembly pages for ‘c’ blocks (default: ‘Routine at’)
• Asm-g - disassembly pages for ‘g’ blocks (default: ‘Game status buffer entry at’)
• Asm-s - disassembly pages for ‘s’ blocks (default: ‘Unused RAM at’)
• Asm-t - disassembly pages for ‘t’ blocks (default: ‘Data at’)
• Asm-u - disassembly pages for ‘u’ blocks (default: ‘Unused RAM at’)
• Asm-w - disassembly pages for ‘w’ blocks (default: ‘Data at’)
• Bugs - the ‘Bugs’ page (default: ‘Bugs’)
• Changelog - the ‘Changelog’ page (default: ‘Changelog’)
• DataMap - the ‘Data’ memory map page (default: ‘Data’)
• Facts - the ‘Trivia’ page (default: ‘Trivia’)
• GameIndex - the disassembly index page (default: ‘Index’)
• GameStatusBuffer - the ‘Game status buffer’ page (default: ‘Game status buffer’)
• Glossary - the ‘Glossary’ page (default: ‘Glossary’)
• GraphicGlitches - the ‘Graphic glitches’ page (default: ‘Graphic glitches’)
• MemoryMap - the ‘Everything’ memory map page (default: ‘Memory map’)
• MessagesMap - the ‘Messages’ memory map page (default: ‘Messages’)
• Pokes - the ‘Pokes’ page (default: ‘Pokes’)
• RoutinesMap - the ‘Routines’ memory map page (default: ‘Routines’)
• UnusedMap - the ‘Unused addresses’ memory map page (default: ‘Unused addresses’)

The title of a page defined by a [MemoryMap:*], [OtherCode:*], [Page:*] or [PageContent:*] section defaults to the page ID, but can be overridden in this section.

Ref file comments¶

A comment may be added to a ref file by starting a line with a semicolon. For example:

; This is a comment

If a non-comment line in a ref file section needs to start with a semicolon, it can be escaped by doubling it:

[PageContent:Custom]
<code>
;; This is not a ref file comment
</code>

The content of this section will be rendered thus:

<code>
; This is not a ref file comment
</code>

Square brackets¶

If a ref file section needs to contain a line that looks like a section header (i.e. like [SectionName]), then to prevent that line from being parsed as a section header it can be escaped by doubling the opening square bracket:

[PageContent:Custom]
<code>
[[This is not a section header]
</code>

The content of this section will be rendered thus:

<code>
[This is not a section header]
</code>

In fact, any line that starts with two opening square brackets will be rendered with the first one removed.

Asm¶

The Asm template is the full-page template that is used to build disassembly pages.

It contains the following identifiers (in addition to the universal and page-level identifiers):

• disassembly - replaced by sequences of copies of the asm_instruction subtemplate, punctuated by copies of the asm_comment subtemplate
• entry - a dictionary of parameters corresponding to the current memory map entry (see below)
• next_entry - a dictionary of parameters corresponding to the next memory map entry (see below)
• prev_entry - a dictionary of parameters corresponding to the previous memory map entry (see below)
• registers_input - replaced by any number of copies of the asm_register subtemplate
• registers_output - replaced by any number of copies of the asm_register subtemplate

The parameters in the prev_entry, entry and next_entry dictionaries are:

• address - the address of the entry (may be in decimal or hexadecimal format, depending on how it appears in the skool file, and the options passed to skool2html.py)
• annotated - ‘1’ if any instructions in the entry have a non-empty comment field, ‘0’ otherwise
• byte - the LSB of the entry address
• description - the entry description
• exists - ‘1’ if the entry exists, ‘0’ otherwise
• href - the relative path to the disassembly page for the entry (useful only for prev_entry and next_entry)
• label - the ASM label of the first instruction in the entry
• labels - ‘1’ if any instructions in the entry have an ASM label, ‘0’ otherwise
• location - the address of the entry as a decimal number
• map_href - the relative path to the entry on the ‘Memory Map’ page
• page - the MSB of the entry address
• size - the size of the entry in bytes
• title - the title of the entry
• type - the block type of the entry (‘b’, ‘c’, ‘g’, ‘s’, ‘t’, ‘u’ or ‘w’)

To see the default Asm template, run the following command:

$ skool2html.py -r Template:Asm

GameIndex¶

The GameIndex template is the full-page template that is used to build the disassembly index page.

It contains the following identifier (in addition to the universal and page-level identifiers):

• m_index_section - replaced by any number of copies of the index_section subtemplate

To see the default GameIndex template, run the following command:

$ skool2html.py -r Template:GameIndex

MemoryMap¶

The MemoryMap template is the full-page template that is used to build memory map pages and the ‘Game status buffer’ page.

It contains the following identifiers (in addition to the universal and page-level identifiers):

• MemoryMap - a dictionary of the parameters in the corresponding [MemoryMap:*] section
• m_map_entry - replaced by one or more copies of the map_entry subtemplate

To see the default MemoryMap template, run the following command:

$ skool2html.py -r Template:MemoryMap

Page¶

The Page template is the full-page template that is used to build custom pages defined by [Page:*] and [PageContent:*] sections.

It contains the following identifier (in addition to the universal and page-level identifiers):

• content - replaced by the value of the PageContent parameter in the corresponding [Page:*] section

To see the default Page template, run the following command:

$ skool2html.py -r Template:Page

Reference¶

The Reference template is the full-page template that is used to build the ‘Bugs’, ‘Trivia’, ‘Pokes’, ‘Glossary’, ‘Graphic glitches’ and ‘Changelog’ pages.

It contains the following identifiers (in addition to the universal and page-level identifiers):

• entries - replaced by one or more copies of the changelog_entry subtemplate (on the ‘Changelog’ page), or the reference_entry subtemplate (on the ‘Bugs’, ‘Trivia’, ‘Pokes’, ‘Glossary’ and ‘Graphic glitches’ pages)
• m_contents_list_item - replaced by one or more copies of the contents_list_item subtemplate

To see the default Reference template, run the following command:

$ skool2html.py -r Template:Reference

anchor¶

The anchor template is the subtemplate used to format a page anchor (by default, an <a> element with a name attribute).

It contains the following identifier (in addition to the universal identifiers):

• anchor - the value of the name attribute

To see the default anchor template, run the following command:

$ skool2html.py -r Template:anchor

asm_comment¶

The asm_comment template is the subtemplate used by the Asm full-page template to format mid-block comments and block end comments.

It contains the following identifiers (in addition to the universal identifiers):

• entry - a dictionary of parameters corresponding to the current memory map entry (see Asm)
• m_paragraph - replaced by one or more copies of the paragraph subtemplate
• t_anchor - replaced by a copy of the anchor subtemplate (with the address of the next instruction in decimal format as the anchor name when formatting a mid-block comment), or by an empty string (when formatting a block end comment)

To see the default asm_comment template, run the following command:

$ skool2html.py -r Template:asm_comment

asm_instruction¶

The asm_instruction template is the subtemplate used by the Asm full-page template to format an instruction (including its label, address, operation and comment).

It contains the following identifiers (in addition to the universal identifiers):

• address - the address of the instruction (may be in decimal or hexadecimal format, depending on how it appears in the skool file, and the options passed to skool2html.py)
• annotated - ‘1’ if the instruction has a comment field, ‘0’ otherwise
• called - ‘2’ if the instruction is an entry point, ‘1’ otherwise
• comment - the text of the instruction’s comment field
• comment_rowspan - the number of instructions to which the comment field applies
• entry - a dictionary of parameters corresponding to the memory map entry that contains the instruction (see Asm)
• label - the instruction’s ASM label
• operation - the assembly language operation (e.g. ‘LD A,B’), with operand hyperlinked if appropriate
• t_anchor - replaced by a copy of the anchor subtemplate (with the instruction’s address in decimal format as the anchor name)

To see the default asm_instruction template, run the following command:

$ skool2html.py -r Template:asm_instruction

asm_register¶

The asm_register template is the subtemplate used by the Asm full-page template to format each row in a table of input register values or output register values.

It contains the following identifiers (in addition to the universal identifiers):

• description - the register’s description (as it appears in the register section for the current entry in the skool file)
• entry - a dictionary of parameters corresponding to the current memory map entry (see Asm)
• name - the register’s name (e.g. ‘HL’)

To see the default asm_register template, run the following command:

$ skool2html.py -r Template:asm_register

changelog_entry¶

The changelog_entry is the subtemplate used by the Reference full-page template to format each entry on the ‘Changelog’ page.

It contains the following identifiers (in addition to the universal identifiers):

• description - the changelog entry intro text
• num - ‘1’ or ‘2’, depending on the order of the entry on the page
• t_anchor - replaced by a copy of the anchor subtemplate (with the entry title as the anchor name)
• t_changelog_item_list - replaced by a copy of the changelog_item_list subtemplate
• title - the changelog entry title

To see the default changelog_entry template, run the following command:

$ skool2html.py -r Template:changelog_entry

changelog_item_list¶

The changelog_item_list template is the subtemplate used by the changelog_entry subtemplate to format a list of changelog items, and also by the changelog_item or list_item subtemplate to format a list of subitems or subsubitems etc.

It contains the following identifiers (in addition to the universal identifiers):

• indent - the indentation level of the item list: ‘’ (blank string) for the list of top-level items, ‘1’ for a list of subitems, ‘2’ for a list of subsubitems etc.
• m_changelog_item - replaced by one or more copies of the changelog_item subtemplate if it exists, or the list_item subtemplate otherwise

To see the default changelog_item_list template, run the following command:

$ skool2html.py -r Template:changelog_item_list

contents_list_item¶

The contents_list_item template is the subtemplate used by the Reference full-page template to format each item in the contents list on the ‘Bugs’, ‘Trivia’, ‘Pokes’, ‘Glossary’, ‘Graphic glitches’ and ‘Changelog’ pages.

It contains the following identifiers (in addition to the universal identifiers):

• href - the URL to the entry on the page
• title - the entry title

To see the default contents_list_item template, run the following command:

$ skool2html.py -r Template:contents_list_item

img¶

The img template is the subtemplate used to format <img> elements.

It contains the following identifiers (in addition to the universal identifiers):

• alt - the ‘alt’ text for the image
• src - the relative path to the image file

To see the default img template, run the following command:

$ skool2html.py -r Template:img

index_section¶

The index_section template is the subtemplate used by the GameIndex full-page template to format each group of links on the disassembly index page.

It contains the following identifiers (in addition to the universal identifiers):

• header - the header text for the group of links (as defined in the name of the [Index:*:*] section)
• m_index_section_item - replaced by one or more copies of the index_section_item subtemplate

To see the default index_section template, run the following command:

$ skool2html.py -r Template:index_section$

index_section_item¶

The index_section_item template is the subtemplate used by the index_section subtemplate to format each link in a link group on the disassembly index page.

It contains the following identifiers (in addition to the universal identifiers):

• href - the relative path to the page being linked to
• link_text - the link text for the page (as defined in the [Links] section)
• other_text - the supplementary text displayed alongside the link (as defined in the [Links] section)

To see the default index_section_item template, run the following command:

$ skool2html.py -r Template:index_section_item

javascript¶

The javascript template is the subtemplate used by the full-page templates to format each <script> element in the head of a page.

It contains the following identifier (in addition to the universal identifiers):

• src - the relative path to the JavaScript file

To see the default javascript template, run the following command:

$ skool2html.py -r Template:javascript

link¶

The link template is the subtemplate used to format the hyperlinks created by the #BUG, #FACT, #POKE, #LINK and #R macros, and the hyperlinks in instruction operands on disassembly pages.

It contains the following identifiers (in addition to the universal identifiers):

• href - the relative path to the page being linked to
• link_text - the link text for the page

To see the default link template, run the following command:

$ skool2html.py -r Template:link

list¶

The list template is used by the #LIST macro to format a list.

It contains the following identifiers (in addition to the universal identifiers):

• class - the CSS class name for the list
• m_list_item - replaced by any number of copies of the list_item subtemplate

To see the default list template, run the following command:

$ skool2html.py -r Template:list$

list_item¶

The list_item template is the subtemplate used by the list template to format each item in the list, and also by the changelog_item_list subtemplate to format each item in a changelog item list.

It contains the following identifier (in addition to the universal identifiers):

• item - replaced by the text of the list item

To see the default list_item template, run the following command:

$ skool2html.py -r Template:list_item

map_entry¶

The map_entry template is the subtemplate used by the MemoryMap full-page template to format each entry on the memory map pages and the ‘Game status buffer’ page.

It contains the following identifiers (in addition to the universal identifiers):

• MemoryMap - a dictionary of parameters from the corresponding [MemoryMap:*] section
• entry - a dictionary of parameters corresponding to the current memory map entry