Skool files

SkoolKit contains several skool files in the src subdirectory. The bts*.skool files are the source files for the Back to Skool disassembly:

• bts.skool - main routines and data blocks
• bts-load.skool - tape loader routines
• bts-save.skool - tape saver routine
• bts-start.skool - startup routines

The csc*.skool files are the source files for the Contact Sam Cruise disassembly:

• csc.skool - main routines and data blocks
• csc-load.skool - tape loader routines
• csc-save.skool - tape saver routine
• csc-start.skool - startup routines

The sd*.skool files are the source files for the Skool Daze disassembly:

• sd.skool - main routines and data blocks
• sd-load.skool - tape loader routines
• sd-save.skool - tape saver routine
• sd-start.skool - startup routine

Skool file format

The skool files must be in a certain format to ensure that they are processed correctly by skool2html.py, skool2asm.py and skool2ctl.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 ;*! bcdgirtuwz, 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)
• d denotes the first instruction in a data definition entry
• g denotes the first instruction in a game status buffer entry
• i denotes an ignored entry
• r denotes the first instruction in a remote 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 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 sd-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: *! bcdgirtuwz
• ##### is an address (e.g. 24576, or $6000 if you prefer hexadecimal notation)
• 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 in sd-load.skool (for example) 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

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

Data definition entries are 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:

c44919 LD DE,46572   ;
 44922 CP 200        ; Reset the carry flag if the animatory state is >=
                     ; #LINK:AnimatoryStates#200(200) (i.e. if we're dealing
                     ; with a teacher)
 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. The reason for this is that the 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 blocks do not appear in the memory map, but they enable JR, JP and CALL instructions to be hyperlinked to entries in other disassemblies (defined in other skool files).

For example (in sd-start.skool):

r26880 main

This enables any JR, JP and CALL instruction with 26880 as the operand to be hyperlinked to the entry for that routine in the main disassembly (which is defined in sd.skool).

If the desired target of the hyperlink is an entry point within a routine in the other disassembly (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 (in bts-start.skool):

r29012 main
 29015

This enables hyperlinks to 29015 in the main Back to Skool disassembly, which is an entry point in the routine at 29012.