SkoolKit 1.0.6 (2010-02-04)

1 What is SkoolKit?

1.1 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' for the full text of the licence.

2 Installing and using SkoolKit

2.1 Requirements

2.2 Linux/*BSD v. Windows command line

Throughout this document, 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:

On Linux/*BSD, the commands may be entered exactly as they are shown (without the dollar sign, of course). On Windows, the dot-slash (./) prefix should be omitted. (The dot-slash prefix may also be omitted on Linux/*BSD if you have the current working directory in your PATH, but that is not the norm.)

2.3 Generating the HTML disassemblies

To generate the HTML version of the Skool Disassemblies, use the skool2html.py script. Open a terminal window, change to the directory containing SkoolKit, and enter this command:

A few seconds later (or minutes, depending on the speed of your machine), the HTML version of the Skool Disassemblies will be ready in the skool-disassemblies subdirectory (which will have been created if it didn't already exist).

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

So, to write only the disassembly files and memory maps for Skool Daze:

2.4 Generating ASM files

To generate ASM files for Skool Daze or Back to Skool, use the skool2asm.py script. Open a terminal window, change to the directory containing SkoolKit, and enter this command:

A few seconds later, an ASM file for Skool Daze will be ready: sd.asm.

To create an ASM file for Back to Skool:

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

3 Parsing, rendering, and modes

The following subsections explain at a high level the two phases involved in transforming a skool file (and its related ref files) into HTML or ASM format: parsing and rendering. These subsections also introduce some terminology that will be used in later sections.

3.1 Parsing

3.1.1 HTML mode

HTML mode is used when the target output format is HTML (as opposed to ASM). In HTML mode, all skool directives are processed, but most ASM directives are ignored (because they are irrelevant to the purpose of creating the HTML disassemblies). The only ASM directives that are processed in HTML mode are those that introduce two different versions of a section of code or data: one that applies for HTML output, and another that applies for ASM output.

3.1.2 ASM mode

ASM mode is used when the target output format is ASM (as opposed to HTML). In ASM mode, all skool directives and ASM directives are processed.

3.2 Rendering

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

3.2.1 HTML mode

3.2.2 ASM mode

4 Data files

SkoolKit contains several data files. The following subsections describe those files, their purpose, and their format.

4.1 sd.skool

sd.skool contains all the assembly language instructions for the main routines and data blocks in Skool Daze.

4.2 sd.ref

sd.ref contains all the data required to generate the non-code parts of the HTML version of the Skool Daze disassembly, including:

• Bug descriptions
• Trivia entries
• Character buffer documentation

4.3 bts.skool

bts.skool contains all the assembly language instructions for the main routines and data blocks in Back to Skool.

4.4 bts.ref

bts.ref contains all the data required to generate the non-code parts of the HTML version of the Back to Skool disassembly, including:

• Bug descriptions
• Trivia entries
• Character buffer documentation

4.5 skool.ref

skool.ref contains data required to generate the non-code parts of the HTML versions of the disassemblies that are either common to both games or not game-specific, such as the glossary.

4.6 start.skool

start.skool contains the assembly language instructions for the startup routines for both Skool Daze and Back to Skool. They are placed here because they don't really fit in the main skool files (sd.skool and bts.skool).

4.7 load.skool

load.skool contains the assembly language instructions for the tape loader routines for both Skool Daze and Back to Skool.

4.8 save.skool

save.skool contains the assembly language instructions for the tape saver routines for both Skool Daze and Back to Skool.

4.9 changelog.ref

changelog.ref contains the changelog entries.

4.10 Skool file format

The skool files (sd.skool, bts.skool and the others) must be in a certain format to ensure that they are processed correctly by skool2html.py and skool2asm.py. The rules are as follows:

1. Entries (an 'entry' being a routine or data block) must be separated by blank lines, and an entry must not contain any blank lines.

2. Lines in an entry may start with one of ';*!bcgituwz ', where:

• ';' begins a comment line
• '*' denotes an entry point in a routine
• '!' denotes an entry point in a routine
• 'b' denotes the first instruction in a data block
• 'c' denotes the first instruction in a code block (routine)
• 'g' denotes the first instruction in a game status buffer entry
• 'i' denotes an ignored entry
• 't' denotes the first instruction in a data block that contains text
• 'u' denotes the first instruction in an unused code or data block
• 'w' denotes the first instruction in a data block that contains (only) two-byte values (words)
• 'z' denotes the first instruction in a data block that contains (only) zeroes
• ' ' begins a line that does not require any of the markers listed above

If a non-comment line starts with any other character (e.g. 'a' in load.skool), it is to distinguish it from another non-comment line with the same address.

The format of a non-comment line is:

where:

• C is one of the characters listed above ('*!bcgituwz ')
• ##### is an address (e.g. 24576)
• INSTRUCTION is an instruction (e.g. 'LD A,(HL)')
• comment is a comment (which may be blank)

The comment for a single instruction may span multiple lines thus:

A comment may also be associated with more than one instruction by the use of braces ('{' and '}') to indicate the start and end points, thus:

Lines that start with '*' or '!' will have their addresses shown in bold in the HTML versions of the disassemblies, and will have labels generated for them in the ASM versions. '!' is used only in load.skool to distinguish one entry point from another with '*' and the same address.

4.11 Ref file format

The ref files (sd.ref, bts.ref, skool.ref and changelog.ref) are formatted into sections separated by section names inside square brackets, like this:

The contents of each section follow no particular format. They may be parsed as free text, a list of key-value pairs, or something else depending on the context.

5 Ref file macros

Sections in the ref files may contain macros that will be expanded before rendering. The ref file macros recognised by SkoolKit are described in the following subsections.

5.1 ::

The :: macro is used to include the contents of another section in the current section.

For example (in sd.ref and bts.ref):

This will copy the contents of the section named Bug-WaitingForEinstein (defined in skool.ref) into the current section.

5.2 ${bts:}, ${sd:}

The bts: macro is expanded only in Back to Skool mode; in Skool Daze mode it is replaced with an empty string. Conversely, the sd: macro is expanded only in Skool Daze mode; in Back to Skool mode it is replaced with an empty string.

For example (in skool.ref):

In Skool Daze mode, this expands to:

But in Back to Skool mode, it expands to:

5.3 ${f:}

The f: macro expands to a filename path computed from the names of variables in the FileInfo object (defined in skoolhtml.py).

For example (in changelog.ref):

Here, ${f:sd_dir/playarea_tiles} expands to the path of the 'Play area tiles' page in the Skool Daze disassembly, defined by the sd_dir and playarea_tiles variables of the FileInfo object.

The f: macro can also be used to call methods of the FileInfo object. For example (in changelog.ref):

Here, ${f:sd_dir/asm_path/asm_fname(64939)} expands to the path of the file containing the disassembly of the data block at 64939 in the Skool Daze disassembly; that path is defined by the following elements:

• sd_dir (a variable in the FileInfo object)
• asm_path (a variable in the FileInfo object)
• asm_fname(64939) (the result of calling FileInfo.asm_fname() with the argument '64939')

5.4 ${v:}

The v: macro expands to the value of a game variable (defined in the [Game] section of sd.ref or bts.ref).

For example (in skool.ref):

Here, ${v:SRBAddress} expands to the value of the game variable SRBAddress (defined as '32524' in the [Game] section in sd.ref, and as '32512' in the [Game] section in bts.ref).

6 Skool directives

The skool files (sd.skool, bts.skool and the others) contain some directives that are processed during the parsing phase. These 'skool directives' are described in the following subsections.

6.1 !bts+begin, !bts+end, !sd+begin, !sd+end

These directives are used to define a section of a skool file that should be parsed in Back to Skool mode but ignored in Skool Daze mode (!bts+begin, !bts+end), or vice versa (!sd+begin, !sd+end).

For example (in load.skool):

The result here is that in Skool Daze mode only these lines are processed:

whereas in Back to Skool mode only these lines are processed:

6.2 !defb

The !defb directive defines bytes to be inserted into the memory snapshot for the skool file being parsed. This is used in sd.skool to define the bytes for the routines that occupy the space for the unused animatory states 104-126 and 232-254, so that those animatory states will not appear blank on the 'Animatory states' page.

For example:

The !defb directive is required here because the parser (in skoolparser.py) will only convert the 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).

6.3 !refs

The !refs directive is used to define empty entries that will not appear in the memory map for the skool file being parsed, but which JR/JP/CALL instructions should be hyperlinked to (because they are defined in some other skool file).

For example (in start.skool):

This defines an empty entry for the routine at 26880 in Skool Daze, so that any JR/JP/CALL instruction with 26880 as the operand can be hyperlinked to the entry for that routine (which is defined in sd.skool). Further down in start.skool we see:

which defines empty entries for the routines at 20709, 21746 and 21920 in Back to Skool.

7 Skool macros

The skool files (sd.skool, bts.skool and the others) and the ref files (sd.ref, bts.ref and skool.ref) contain some macros that are either 'expanded' to an appropriate piece of HTML markup (when rendering in HTML mode), or 'reduced' to an appropriate piece of plain text (when rendering in ASM mode). The skool macros recognised by SkoolKit are described in the following subsections.

7.1 #AS (Animatory State)

In HTML mode, the #AS macro expands to a hyperlink (<a> element) to an image on the 'Animatory states' page.

• state is the animatory state number
• link text is the link text to use (default is state)

In ASM mode, the #AS macro reduces to the link text.

For example (from sd.skool):

In HTML mode, this instance of the #AS macro expands to a hyperlink to the image of animatory state 16 (EINSTEIN standing/walking, phase 1) on the 'Animatory states' page.

In ASM mode, this instance of the #AS macro reduces to '16'.

7.2 #ASIMG (Animatory State IMaGe)

In HTML mode, the #ASIMG macro expands to an <img> element for the image of an animatory state.

• num is the animatory state number (0-255)
• scale is the required scale of the image (default=2)
• mask is 1 if the image should show the mask (by displaying the transparent background in green), or 0 if not (default=1)
• attribute is the required attribute byte for the image (default=120)

The #ASIMG macro is not supported in ASM mode.

If an image file matching the required properties doesn't already exist, it will be created.

For example (from bts.ref):

In HTML mode, this instance of the #ASIMG macro expands to an <img> element for the image for animatory state 21 (BOY WANDER sitting on the floor) at 4 times the original size.

7.3 #ASM

In HTML mode, the #ASM macro expands to a hyperlink (<a> element) to the disassembly page for a routine or data block. The routine or data block need not exist in the current skool file.

• address is the address of the routine or data block
• #anchor is the named anchor to link to on the disassembly page
• (link text) is the link text to use (default=address)

In ASM mode, the #ASM macro reduces to the link text.

For example (from the entry at 58144 in bts.skool):

In HTML mode, this instance of the #ASM macro expands to a hyperlink to the disassembly page for the startup routine at 33204 for Back to Skool (which is defined in start.skool), with 'startup routine' as the link text.

In ASM mode, this instance of the #ASM macro reduces to 'startup routine'.

7.4 #ASTILE (Animatory State TILE)

In HTML mode, the #ASTILE macro expands to an HTML <img> element for the image of an animatory state tile.

• state is the animatory state number (0-255)
• row is the row number (0-3) of the tile in the 4x3 matrix of tiles that make up the animatory state
• col is the column number (0-2) of the tile
• attr is the required attribute byte for the image (default=120)
• mask is 1 if the image should show the mask (by displaying the transparent background in green), or 0 if not (default=1)
• scale is the required scale of the image (default=4)

The #ASTILE macro is not supported in ASM mode.

If an image file matching the required properties doesn't already exist, it will be created.

7.5 #BOX

In HTML mode, the #BOX macro expands to an <img> element for the image of a box graphic (such as the game logo or the score box, which are 64x24 pixels).

• address is the address of the attribute and graphic data for the box
• scale is the required scale of the image (default=2)
• attribute is the required attribute byte for the image (default is to use the attribute bytes at address)

The #BOX macro is not supported in ASM mode.

If an image file matching the required properties doesn't already exist, it will be created.

For example (from sd.skool):

In HTML mode, this instance of the #BOX macro expands to an <img> element for the image of the Skool Daze score box.

7.6 #BUG

In HTML mode, the #BUG macro expands to a hyperlink (<a> element) to the 'Bugs' page, or to a specific entry on that page.

• #name is the named anchor of a bug (if linking to a specific one)
• link text is the link text to use (default is 'bug')

In ASM mode, the #BUG macro reduces to the link text.

For example (from sd.skool):

In HTML mode, this instance of the #BUG macro expands to a hyperlink to the entry for 'MR CREAK and the empty class' on the 'Bugs' page for Skool Daze.

In ASM mode, this instance of the #BUG macro reduces to 'bug'.

7.7 #C (Copyright)

In HTML mode, the #C macro expands to the HTML entity reference for the copyright symbol (©).

In ASM mode, the #C macro reduces to '(c)'.

For example (from sd.skool):

7.8 #CBUF (Character BUFfer)

In HTML mode, the #CBUF macro expands to a hyperlink (<a> element) to the character buffer documentation page, or to a specific entry on that page.

• #name is the named anchor of a character buffer entry description (if linking to a specific one)
• link text is the link text to use (default is name if given, or 'buffer')

In ASM mode, the #CBUF macro reduces to the link text.

For example (in sd.skool):

In HTML mode, this instance of the #CBUF macro expands to a hyperlink to the character buffer documentation page with the link text 'character buffer documentation'.

In ASM mode, this instance of the #CBUF macro reduces to 'character buffer documentation'.

7.9 #D (Description)

In HTML mode, the #D macro expands to the title of an entry (a routine or data block) in the memory map.

• address is the address of the entry.

In ASM mode, the #D macro reduces to the title of the entry.

For example (in sd.skool):

In HTML mode, this instance of the #D macro (in the last line) expands to the title of the routine at 27126 in Skool Daze.

In ASM mode, this instance of the #D macro reduces to the title of the routine at 27126 in Skool Daze.

7.10 #EREFS (Entry point REFerences)

In HTML mode, the #EREFS macro expands to a comma-separated sequence of hyperlinks (<a> elements) to the disassembly pages for the routines that jump to or call a given address.

• address is the address to search for references to

The #EREFS macro is not supported in ASM mode.

The #EREFS macro is not used in any of the stock SkoolKit data files, but it was used while the Skool Disassemblies were under development.

7.11 #FACT

In HTML mode, the #FACT macro expands to a hyperlink (<a> element) to the 'Trivia' page, or to a specific entry on that page.

• #name is the named anchor of a trivia entry (if linking to a specific one)
• link text is the link text to use (default is 'fact')

The #FACT macro is not supported in ASM mode.

7.12 #FONT

In HTML mode, the #FONT macro expands to an <img> element for the image of the skool font (as used on the 'Other graphics' page).

The #FONT macro is not supported in ASM mode.

The image of the skool font will be created if it doesn't already exist.

7.13 #GBUF (Game status BUFfer)

In HTML mode, the #GBUF macro expands to a hyperlink (<a> element) to the 'Game status buffer' page, or to a specific entry on that page.

• address is the address of the entry to link to (if any)
• link text is the link text to use (default is address if given, or 'game status buffer')

In ASM mode, the #GBUF macro reduces to the link text.

For example (from bts.skool):

7.14 #KEYTABLE

In HTML mode, the #KEYTABLE macro expands to a hyperlink (<a> element) to the 'Keypress table' page, or to a specific entry on that page.

• #name is the named anchor of the entry on the keypress table page to link to (if any)
• link text is the link text to use (default is 'keypress table')

In ASM mode, the #KEYTABLE macro reduces to 'keypress table documentation'.

For example (from sd.skool):

7.15 #LESSON

In HTML mode, the #LESSON macro expands to a hyperlink (<a> element) to the page for a lesson.

• num is the lesson number

In ASM mode, the #LESSON macro reduces to the lesson number.

For example (from sd.skool):

In HTML mode, this instance of the #LESSON macro (in the last line) expands to a hyperlink to the page for lesson 224.

In ASM mode, this instance of the #LESSON macro reduces to '224'.

7.16 #LOAD

In HTML mode, the #LOAD macro expands to a hyperlink (<a> element) to the disassembly page for one of the tape loading routines.

• address is the address of the tape loading routine (23831, 32768 or 32815)
• #name is the named anchor of an item on the disassembly page to link to (if any)
• link text is the link text to use (default is address)

In ASM mode, the #LOAD macro reduces to the link text.

For example (from save.skool):

In HTML mode, this instance of the #LOAD macro expands to a hyperlink to the disassembly page for the tape loading routine at 32815 with link text 'load routine'.

In ASM mode, this instance of the #LOAD macro reduces to 'load routine'.

7.17 #MSG

In HTML mode, the #MSG macro expands to a hyperlink (<a> element) to the disassembly page for the data block containing a specific message.

or

• num is the message number (applicable only in Back to Skool)
• address is the address of the message
• link text is the link text to use (default is num or address)

In ASM mode, the #MSG macro reduces to the link text.

For example (from bts.skool):

In HTML mode, this instance of the #MSG macro expands to a hyperlink to the disassembly page for the data block containing message 21 (at 61267).

In ASM mode, this instance of the #MSG macro reduces to '21'.

7.18 #MUTABLE

In HTML mode, the #MUTABLE macro expands to an <img> element for the image of a mutable object in Back to Skool (i.e. a door, a window, a cup, or the spot on the tree where the bike is chained).

• address is the address of the mutable object's UDG reference table
• padding is the amount of padding (number of tiles) to use around the matrix of UDGs for the mutable object (default=0)

The #MUTABLE macro is not supported in ASM mode.

If an image file matching the required properties doesn't already exist, it will be created.

For example (from bts.skool):

In HTML mode, this instance of the #MUTABLE macro expands to an <img> element for the image of the top-floor window when shut (with no padding).

7.19 #NAME

In HTML mode, the #NAME macro expands to an anchor (<a>) element with a given name.

• name is the name of the anchor

In ASM mode, the #NAME macro reduces to an empty string.

For example (from bts.skool):

In HTML mode, this instance of the #NAME macro expands to an anchor element named 'staircaseMatrix'.

In ASM mode, this instance of the #NAME macro reduces to an empty string.

7.20 #P (Paragraph)

In HTML mode, the #P macro expands to two adjacent br elements: <br /><br />.

In ASM mode, the #P macro reduces to an empty string.

For example (from bts.skool):

In HTML mode, this instance of the #P macro, along with the others in the entry for the routine at 24684 in Back to Skool, is used to separate the (long) description into paragraphs.

In ASM mode, this instance of the #P macro, along with the others, is reduced to an empty string.

7.21 #PATILE (Play Area TILE)

In HTML mode, the #PATILE macro expands to an <img> element for the image of a play area tile.

• x is the x-coordinate of the tile
• y is the y-coordinate of the tile
• scale is the required scale of the image (default=4)

The #PATILE macro is not supported in ASM mode.

If an image with the required properties doesn't already exist, it will be created.

7.22 #POKE

In HTML mode, the #POKE macro expands to a hyperlink (<a> element) to the 'Pokes' page, or to a specific entry on that page.

• #name is the named anchor of a poke (if linking to a specific one)
• link text is the link text to use (default is 'poke')

The #POKE macro is not supported in ASM mode.

For example (from bts.ref):

In HTML mode, this instance of the #POKE macro expands to a hyperlink to the entry for 'Ring the bell' on the 'Pokes' page for Back to Skool, with link text 'ring the bell'.

7.23 #POKES (POKE Snapshot)

In HTML mode, the #POKES macro is used to POKE values into the current memory snapshot.

• address is the address to POKE
• byte is the value to POKE address with
• length is the number of addresses to POKE (default=1)
• step is the address increment to use after each POKE (if length>1; default=1)

The #POKES macro is not supported in ASM mode.

For example (in bts.ref):

7.24 #POPS (POP Snapshot)

In HTML mode, the #POPS macro removes the current memory snapshot and replaces it with the one that was previously saved by a #PUSHS macro.

The #POPS macro is not supported in ASM mode.

7.25 #PT (Personal Timetable)

In HTML mode, the #PT macro expands to a hyperlink (<a> element) to the disassembly page containing a character's personal timetable.

• num is the number of the character
• link text is the link text to use (default=num)

The #PT macro is not supported in ASM mode.

For example (from sd.ref):

In HTML mode, this instance of the #PT macro expands to a hyperlink to the disassembly page containing the personal timetable for MR ROCKITT (whose character number is 164), with the link text 'personal timetable'.

7.26 #PUSHS (PUSH Snapshot)

7.27 #R (Reference)

In HTML mode, the #R macro expands to a hyperlink (<a> element) to the disassembly page for a routine or data block, or to a line at a given address within that page. The routine or data block being referred to must exist in the skool file.

• address is the address of a routine or data block (or an entry point thereof)
• #name is the named anchor of an item on the disassembly page
• link text is the link text to use (default is address)

In ASM mode, the #R macro reduces to the label for address, or to address if no label is found.

For example (from sd.skool):

In HTML mode, this instance of the #R macro expands to a hyperlink to the disassembly page for the routine at 25820 in Skool Daze.

In ASM mode, this instance of the #R macro reduces to 'LSCROLL8' (the label for the routine at 25820).

7.28 #REFS (REFerenceS)

In HTML mode, the #REFS macro expands to a comma-separated sequence of hyperlinks (<a> elements) to the disassembly pages for the routines that jump to or call a given routine, or jump to or call any entry point within that routine.

• address is the address of the routine to search for references to
• prefix is the text to display before the sequence of hyperlinks if there is at least one reference (default is no text)

If there are no references, the macro expands to the following text:

The #REFS macro is not supported in ASM mode.

The #REFS macro is not used in any of the stock SkoolKit data files, but it was used while the Skool Disassemblies were under development.

7.29 #REG (REGister)

In HTML mode, the #REG macro expands to a styled <span> element containing a register name.

• reg is the name of the register (e.g. 'A', 'BC')

In ASM mode, the #REG macro reduces to the name of the register.

The register name must contain 1, 2 or 3 of the following characters:

For example (from sd.skool):

7.30 #SAVE

In HTML mode, the #SAVE macro expands to a hyperlink (<a> element) to the disassembly page for the tape saver routine.

• #name is the named anchor of an item on the disassembly page
• link text is the link text to use (default='save routine')

In ASM mode, the #SAVE macro reduces to the link text.

For example (from sd.skool):

In HTML mode, this instance of the #SAVE macro expands to a hyperlink to the disassembly page for the tape saver routine with link text 'save routine'.

In ASM mode, this instance of the #SAVE macro reduces to 'save routine'.

7.31 #SCR (SCReenshot)

In HTML mode, the #SCR macro expands to an <img> element for the image constructed from the display file and attribute bytes of the current memory snapshot (in turn constructed from the contents of the skool file).

The #SCR macro is not supported in ASM mode.

The screenshot image will be created if it doesn't already exist.

For example (from save.skool):

7.32 #SKOOL

In HTML mode, the #SKOOL macro expands to an <img> element for an image of the play area (or a portion of the play area).

• x and y are the play area coordinates of the top-left tile
• w and h are the width and height of the portion of the play area
• scale is the required scale of the image (default=2)
• showChars is 1 if the game characters are to be displayed in the image, 0 if not (default=0)
• showX is the size of the interval at which x-coordinates should be displayed at the top and bottom of the image, or 0 if none should be displayed (default=0)

The #SKOOL macro is not supported in ASM mode.

If an image of the play area matching the requirements doesn't already exist, it will be created.

For example (from bts.ref):

In HTML mode, the first instance of the #SKOOL macro here expands to an <img> element for an image of the left half of the play area of Back to Skool, with scale 1, no game characters displayed, and x-coordinates shown at 0, 8, 16, 24 and so on.

7.33 #SPACE

In HTML mode, the #SPACE macro expands to one or more ' ' expressions.

• num is the number of spaces required

In ASM mode, the #SPACE macro reduces to num spaces.

For example (from sd.skool):

In HTML mode, this instance of the #SPACE macro expands to:

In ASM mode, this instance of the #SPACE macro reduces to a string containing 8 spaces.

7.34 #START

In HTML mode, the #START macro expands to a hyperlink (<a> element) to the disassembly page for the startup routine.

• #name is the named anchor of an item on the disassembly page
• link text is the link text to use (default is the address of the startup routine)

The #START macro is not supported in ASM mode.

For example (from load.skool):

In HTML mode, this instance of the #START macro expands to a hyperlink to the disassembly page for the startup routine (24288 in Skool Daze, 33204 in Back to Skool), with the address of that routine as the link text.

7.35 #TABLE

The #TABLE macro marks the beginning of a table; TABLE# is used to mark the end. Between these markers, the rows of the table are defined.

• class is the CSS class to use for the <table> element
• class1, class2 etc. are the CSS classes to use for columns 1, 2 etc.

The rows in a table must start with '{ ' and end with ' }'. The cells in a row must be separated by ' | '.

For example (from the routine at 29052 in bts.skool):

This table has two rows and two columns, and will have the CSS class 'data'.

By default, cells will be rendered as <td> elements. To specify that a <th> element should be used instead, use the =h indicator before the cell contents:

It is also possible to specify colspan and rowspan attributes using the =c and =r indicators:

Finally, the =t indicator specifies that a cell should be transparent (i.e. inherit its parent element's background colour).

If a cell requires more than one indicator, the indicators should be separated by commas:

In ASM mode, tables are rendered as plain text, using dashes (-) and pipes (|) for the borders, and plus signs (+) where a horizontal border meets a vertical border.

ASM mode also supports the :w indicator in the #TABLE macro's arguments. The :w indicator marks a column as a candidate for having its width reduced (by wrapping the text it contains) so that the table will be no more than 79 characters wide when rendered. For example:

7.36 #TAP

In HTML mode, the #TAP macro expands to a hyperlink (<a> element) to the disassembly page for a command list.

• num is the command list number

In ASM mode, the #TAP macro reduces to the command list number.

For example (from sd.skool):

In HTML mode, this instance of the #TAP macro expands to a hyperlink to the disassembly page for command list 206 in Skool Daze.

In ASM mode, this instance of the #TAP macro reduces to '206'.

7.37 #TAPS

In HTML mode, the #TAPS macro expands to a comma-separated list of hyperlinks (<a> elements) to the disassembly pages for the command lists that contain a given routine address.

• address is the routine address

The #TAPS macro is not supported in ASM mode.

The #TAPS macro is not used in any of the stock SkoolKit data files, but it was used while the Skool Disassemblies were under development.

7.38 #TIME

In ASM mode, the #TIME macro expands to the following string:

(with the timestamp replaced by the current time).

The #TIME macro is not supported in HTML mode.

7.39 #UDG

In HTML mode, the #UDG macro expands to an <img> element for the image of a UDG (an 8x8 block of pixels).

• address is the base address of the UDG bytes
• attribute is the attribute byte to use
• scale is the required scale of the image (default=4)
• step is the interval between successive bytes of the UDG (default=1)
• increment will be added to each UDG byte before constructing the image (default=0)

The #UDG macro is not supported in ASM mode.

If an image of the UDG matching the required properties doesn't already exist, it will be created.

For example (from bts.skool):

In HTML mode, this instance of the #UDG macro expands to an <img> element for the image of the safe key UDG, with attribute byte 6 (INK 6: PAPER 0).

7.40 #UDGTABLE

The #UDGTABLE macro is used to mark the beginning of a table that will contain images. It is used instead of the #TABLE macro to indicate up-front that the table should not be rendered in ASM mode.

8 ASM modes and directives

The two main skool files (sd.skool and bts.skool) contain directives that are processed when parsing in ASM mode. Exactly how a directive is processed (and whether it is executed) depends on the 'substitution mode' and 'bugfix mode' in which the skool file is being parsed.

8.1 Substitution modes

There are three substitution modes: @isub, @ssub, and @rsub. These modes are described in the following subsections.

8.1.1 @isub mode

In @isub mode, @isub directives are executed, but @ssub, and @rsub directives are not. The main purpose of @isub mode is to make the minimum number of instruction substitutions necessary to produce an ASM file that assembles.

For example (from sd.skool):

This @isub directive ensures that 'LD A,(m)' is replaced by the valid instruction 'LD A,(32512)'.

@isub mode is invoked by default when running skool2asm.py.

8.1.2 @ssub mode

In @ssub mode, @isub and @ssub directives are executed, but @rsub directives are not. The main purpose of @ssub mode is to replace LSBs, MSBs and full addresses in the operands of instructions with labels, to make the code amenable to some degree of relocation, but without actually removing or inserting any code.

For example (from sd.skool):

This @ssub directive replaces 'LD (27016),A' with 'LD (27015+1),A'; the '27015' will be replaced by the label for that address before rendering. (27016 cannot be replaced by a label, since it is not the address of an instruction.)

@ssub mode is invoked by passing the '-s' option to skool2asm.py.

8.1.3 @rsub mode

In @rsub mode, @isub, @ssub and @rsub directives are executed. The main purpose of @rsub mode is to make code unconditionally relocatable, even if that requires the removal of existing code or the insertion of new code.

For example (from sd.skool):

This @rsub block directive inserts two instructions that ensure that the address in bytes 99 and 100 of the character's buffer has the correct MSB as well as the correct LSB, regardless of where the code originally at 25317 now lives.

@rsub mode is invoked by passing the '-r' option to skool2asm.py. @rsub mode also implies @ofix mode; see below for a description of @ofix mode and the other bugfix modes.

8.2 Bugfix modes

There are three bugfix modes: @ofix, @bfix and @rfix. These modes are described in the following subsections.

8.2.1 @ofix mode

In @ofix mode, @ofix directives are executed, but @bfix and @rfix directives are not. The main purpose of @ofix mode is to fix instructions that have faulty operands.

For example (from sd.skool):

These @ofix block directives fix the faulty operand of the CALL instruction at 27872.

@ofix mode is invoked by passing the '-f1' option to skool2asm.py.

8.2.2 @bfix mode

In @bfix mode, @ofix and @bfix directives are executed, but @rfix directives are not. The main purpose of @bfix mode is to fix bugs by replacing instructions, but without changing the start address of any routines, routine entry points, or data blocks.

For example (from bts.skool):

@bfix mode is invoked by passing the '-f2' option to skool2asm.py.

8.2.3 @rfix mode

In @rfix mode, @ofix, @bfix and @rfix directives are executed. The purpose of @rfix mode is to fix bugs that cannot be fixed without moving code around (to make space for the fix).

For example (from sd.skool):

These @rfix block directives insert some instructions to fix the bug in Skool Daze where ERIC can be hit by BOY WANDER's pellet even when he's sitting on the floor or lying down.

8.3 ASM directives

The ASM directives recognised by SkoolKit are described in the following subsections.

8.3.1 @bfix

The @bfix directive is used to make an instruction substitution in @bfix mode.

• INSTRUCTION is the replacement instruction

For example (from sd.skool):

8.3.2 @bfix block directives

The @bfix block directives are used to define a block of lines that will be inserted or removed in @bfix mode.

The syntax for defining a block that will be inserted in @bfix mode is:

The syntax for defining a block that will be removed in @bfix mode is:

Typically, though, it is desirable to define a block that will be removed in @bfix mode right next to the block that should be inserted in its place. That may be done thus:

which is equivalent to:

For example (from bts.skool):

These @bfix block directives fix the bug where ERIC cannot be pushed out of his seat by changing the instruction at 26211 from 'SET 7,(HL)' to 'LD (HL),128'.

8.3.3 @ignoremrcua

The @ignoremrcua directive is used to suppress any warnings that would otherwise be reported concerning addresses not converted to labels in the mid-routine comment above the next instruction.

For example (from bts.skool):

If the @ignoremrcua directive were not present, warnings would be printed (during the rendering phase) about the comment containing addresses (32522, 32600) that cannot be converted to labels.

8.3.4 @ignoreua

The @ignoreua directive is used to suppress any warnings that would otherwise be reported concerning addresses not converted to labels in the comment for the next instruction.

For example (from sd.skool):

If the @ignoreua directive were not present, a warning would be printed (during the rendering phase) about the comment containing an address (62818) that cannot be converted to a label.

8.3.5 @isub

The @isub directive is used to make an instruction substitution in @isub mode.

• INSTRUCTION is the replacement instruction

For example (in sd.skool):

8.3.6 @isub block directives

The @isub block directives are used to define a block of lines that will be inserted or removed in @isub mode.

8.3.7 @keep

The @keep directive is used to prevent the substitution of a label for the operand in the next instruction (but only when the instruction has not been replaced using an @isub or @ssub directive).

For example (in sd.skool):

If the @keep directive were not present, the operand (24576) of the 'LD BC' instruction would be replaced with a label (because there is a routine at 24576); however, the operand is meant to be a pure data value, not a variable or routine address.

8.3.8 @label

The @label directive sets the label for the next instruction.

• LABEL is the label to apply

For example (from sd.skool):

This sets the label for the routine at 24576 to 'RSCROLL'.

8.3.9 @nolabel

The @nolabel directive is used to prevent the next instruction from having a label automatically generated.

For example (from bts.skool):

The @nolabel directive here prevents the instruction at 31610 from being labelled in @bfix mode (because no label is required; instead, the previous instruction at 31607 will be labelled).

The output from this section of bts.skool in @bfix mode will be:

And the output when not in @bfix mode will be:

8.3.10 @nowarn

The @nowarn directive is used to suppress any warnings that would otherwise be reported for the next instruction concerning:

• a LD operand being replaced with a routine label (if the instruction has not been replaced using @isub or @ssub)
• an operand not being replaced with a label (because the operand address has no label)

For example (from sd.skool):

If this @nowarn directive were not present, a warning would be printed (during the parsing phase) about the operand (25404) being replaced with a routine label (which would be inappropriate if 25404 were intended to be a pure data value).

For another example (also from sd.skool):

If this @nowarn directive were not present, a warning would be printed (during the parsing phase, if not in @ofix mode) about the operand (27633) not being replaced with a label (usually you would want the operand of a CALL instruction to be replaced with a label, but not in this case).

8.3.11 @ofix

The @ofix directive is used to make an instruction substitution in @ofix mode.

• INSTRUCTION is the replacement instruction (with a corrected operand)

8.3.12 @ofix block directives

The @ofix block directives are used to define a block of lines that will be inserted or removed in @ofix mode.

8.3.13 @org

The @org directive inserts an ORG assembler directive.

• ADDRESS is the ORG address

8.3.14 @rem

The @rem directive is used to make an illuminating comment about a nearby section or other ASM directive in a skool file. The directive is ignored by the parser.

• COMMENT is a suitably illuminating comment.

For example (from bts.skool):

If this @rem directive were not present, I might one day be tempted to remove the @org directive that follows, having forgotten why it's actually extremely important.

8.3.15 @rfix block directives

The @rfix block directives are used to define a block of lines that will be inserted or removed in @rfix mode.

8.3.16 @rlabel

The @rlabel directive sets the label for the next instruction, but only when parsing in @rsub mode.

• LABEL is the label to apply

For example (from sd.skool):

This sets the label for the instruction at 31892 to 'DINSTEP', so that the operand of the 'JR Z,31892' instruction (which is included only in @rsub mode) a few lines up can be converted to that label.

8.3.17 @rsub

The @rsub directive is used to make an instruction substitution in @rsub mode.

• INSTRUCTION is the replacement instruction

For example (from sd.skool):

8.3.18 @rsub block directives

The @rsub block directives are used to define a block of lines that will be inserted or removed in @rsub mode.

8.3.19 @ssub

The @ssub directive is used to make an instruction substitution in @ssub mode.

• INSTRUCTION is the replacement instruction

For example (from sd.skool):

8.3.20 @start

The @start directive indicates where to start parsing the skool file for the purpose of generating ASM output. Everything before the @start directive is ignored.

9 Disassembly DIY

9.1 sna2skool.py

SkoolKit includes a utility script called sna2skool.py that can be used to convert a 48K SNA or Z80 snapshot into a skool file. To try it out, copy a Z80 snapshot of Skool Daze (call it skool_daze.z80) to the directory containing SkoolKit, and then run the following command from that directory:

Now take a look at sd-blank.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.

9.2 The control file

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:

• 'b' indicates a data block
• 'c' indicates a code block
• 'g' indicates a game status buffer entry
• 'i' indicates a block that should be ignored
• 't' indicates a block containing text
• 'u' indicates an unused block of memory
• 'w' indicates a block containing words (two-byte values)
• 'z' indicates an unused block containing all zeroes

9.3 A skeleton skool disassembly

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

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

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

9.4 Generating a control file

If you are planning to create a disassembly of some game other than Skool Daze or Back to Skool, 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:

This will do a reasonable job of splitting the snapshot into blocks, but you will need to examine the resultant skool file (game.skool in this case) to see which blocks should be marked as text or data instead of code, and then edit the generated control file (game.ctl) accordingly.

Blocks whose contents resemble text are given a title like this:

Blocks whose contents resemble neither code nor text are given a title like this:

Any other blocks are assumed to contain code and are given a title like this:

9.5 Other disassembly options

If you know that there is nothing of interest in the snapshot before address 24576 (for example), you can tell sna2skool.py to start disassembling from that address (instead of 16384) by using the '-s' option:

To make it easier to find messages (strings) in the snapshot, use the '-t' option:

This will add to the comment field, for each line of the disassembly, the ASCII equivalent of the disassembled bytes.

9.6 Adding pokes, bugs, trivia and a glossary

Adding 'Pokes', 'Bugs', 'Trivia' and 'Glossary' pages to a disassembly is done by adding Poke, Bug, Fact and Glossary 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 sd-blank.ref (or bts-blank.ref if you're playing with the skeleton Back to Skool disassembly):

Now run skool2html.py again:

Open html/sd-blank/index.html and you should see a link to the 'Pokes' page in the 'Reference' section.

The format of a Poke section is:

where:

• anchor is the name of the anchor for the entry on the 'Pokes' page
• Title is the title of the entry

Paragraphs should be separated by blank lines.

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.

One Poke, Bug or Fact section should be added for each poke, bug or trivia item 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.

The format of a Glossary section is slightly different:

The description should be a single paragraph. For example:

9.7 skool v. ASM

If, instead of a skool file, you'd rather create an assembler-ready ASM file from a snapshot, sna2skool.py can do that with the '-a' option:

10 Changelog

10.1 SkoolKit 1.0.6 (2010-02-04)

Above each entry point in a code block, sna2skool.py will insert a comment containing a list of the routines that call or jump to that entry point.

10.2 SkoolKit 1.0.5 (2010-02-03)

Made the following changes to sna2skool.py:

• Added the '-t' option (to show ASCII text in the comment fields)
• Set block titles according to the apparent contents (code/text/data) when using the '-g' option

10.3 SkoolKit 1.0.4 (2010-02-02)

Made the following changes to sna2skool.py:

• Fixed the bug that caused the last instruction before the 64K boundary to be disassembled as a DEFB statement
• Added the '-g' option (to generate a control file using rudimentary static code analysis)
• Added the '-s' option (to specify the disassembly start address)

10.4 SkoolKit 1.0.3 (2010-02-01)

• sna2skool.py copes with instructions that cross the 64K boundary
• skool2html.py writes the 'Game status buffer', 'Glossary', 'Trivia', 'Bugs' and 'Pokes' pages for a skool file specified by the '-f' option (in addition to the disassembly files and memory maps)

10.5 SkoolKit 1.0.2 (2010-01-31)

Modified sna2skool.py so that it:

• recognises instructions that are unchanged by a DD or FD prefix
• recognises instructions with a DDCB or FDCB prefix
• produces a 4-byte DEFB for the ED-prefixed 'LD HL,(nn)' and 'LD (nn),HL' instructions
• produces a 2-byte DEFB for a relative jump across the 64K boundary

10.6 SkoolKit 1.0.1 (2010-01-30)

Fixed the following bugs in sna2skool.py:

• 'X' was replaced by 'Y' instead of 'IX' by 'IY' (leading to nonsense mnemonics such as 'YOR IYh')
• ED72 was disassembled as 'SBC HL,BC' instead of 'SBC HL,SP'
• ED7A was disassembled as 'ADD HL,SP' instead of 'ADC HL,SP'
• ED63 and ED6B were disassembled as 'LD (nn),HL' and 'LD HL,(nn)' (which is correct, but won't assemble back to the same bytes)

10.7 SkoolKit 1.0 (2010-01-28)

Initial public release.

11 Bugs

The following bugs in SkoolKit do not (currently) affect the HTML or ASM rendering, so there is no pressing need to fix them.

1. If the last entry in a skool file has an end comment (i.e. a comment after the last instruction), it is not picked up in the parsing phase, and so will not be rendered.

2. If a table (defined between #TABLE and TABLE# markers) contains a cell with rowspan > 1 and its contents are wrapped, adjacent cells with rowspan = 1 are rendered incorrectly in ASM mode.

3. In verbose ('-v') mode, skool2asm.py does not show lines inserted or removed by the @isub, @rsub, @ofix, @bfix and @rfix block directives.

4. This documentation does not describe the sections in the ref files.