Data files

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

sd.skool

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

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

bts.skool

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

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

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.

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).

load.skool

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

save.skool

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

changelog.ref

changelog.ref contains the changelog entries.

csc.ref

csc.ref is the ref file for the incomplete Contact Sam Cruise RAM disassembly.

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
• a space 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:

C##### INSTRUCTION ; comment

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:

c24296 CALL 57935    ; Give up right now if the catapult pellet's buffer is
                     ; already in use

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:

*24372 SUB D         ; {Jump if ERIC's y-coordinate does not match HAYLEY's, or
 24373 JR NZ,24378   ; ERIC has used up all his kisses}

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.

3. Tables (grids) have their own markup syntax. See #TABLE for details.
4. Entry headers are a sequence of comment lines broken into three sections:

• Entry title
• Entry description (optional)
• Registers (optional)

The sections are separated by an empty comment line. For example:

; This is the entry title
;
; This is the entry description
;
; A An important parameter
; B Another important parameter

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:

[SectionName]

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.