Skool files — SkoolKit 9.6 documentation (original) (raw)

A skool file contains the list of Z80 instructions that make up the routines and data blocks of the program being disassembled, with accompanying comments (if any).

Skool file format¶

A skool file must be in a certain format to ensure that it is processed correctly by skool2html.py, skool2asm.py and skool2ctl.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:;* @bcgistuw; see Entry line format
• tables (grids) have their own markup syntax; see #TABLE for details

Entry line format¶

Each line in an entry may start with one of ;* @bcgistuw, where:

• ; begins a comment line
• * denotes an entry point in a routine
• @ begins an ASM directive
• 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
• s denotes the first instruction in a data block containing bytes that are all the same value (typically unused zeroes)
• 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)
• a space begins a line that does not require any of the markers listed above

The format of a line containing an instruction is:

C##### INSTRUCTION[ ; comment]

where:

• C is one of the characters listed above: * bcdgirstuw
• ##### 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 ; This comment is too long to fit on a single line, so ; we use two lines

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 ; {This comment applies to the two instructions at 24373 JR NZ,24378 ; 24372 and 24373}

The opening and closing braces are removed before the comment is rendered in ASM or HTML mode. (See Braces in comments.)

Comments may appear between instructions, or after the last instruction in an entry; paragraphs in such comments must be separated by a comment line containing a dot (.) on its own. For example:

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

Lines that start with * will have their addresses shown in bold in the HTML version of the disassembly (generated by skool2html.py), and will have labels generated for them in the ASM version (generated byskool2asm.py).

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.

Escaping characters¶

Backslash (\) and double quote (") characters in string and character operands must be escaped by preceding them with a backslash. For example:

c32768 LD A,""" ; LD A,34 32770 LD B,"\" ; LD B,92

This ensures that SkoolKit or an assembler can parse such operands correctly.

Non-entry blocks¶

In addition to regular entries (routines and data blocks), a skool file may also contain blocks of lines that do not match the format of an entry, such as a header comment that appears before the first entry and contains copyright information. For example:

; Copyright 2018 J Smith

; Start c24576 JP 32768

Non-entry blocks such as this copyright comment are reproduced byskool2asm.py, ignored by skool2html.py, and preserved verbatim byskool2ctl.py.

To qualify as a regular entry, a block must contain at least one line that starts with b, c, g, i, s, t, u or w when parsed in the relevant subtitution mode orbugfix mode (which depends on the command being run).

So, for example:

@isub-begin c24573 JP 32768 @isub-end

is seen as a regular entry (without the @isub block directives) byskool2ctl.py and skool2html.py, but is invisible to skool2asm.py. And:

@isub+begin c24573 JP 32768 @isub+end

is seen as a non-entry block (with the @isub block directives retained) byskool2ctl.py and skool2html.py, but as a regular entry (without the@isub block directives) by skool2asm.py.

Revision history¶