The skool files (sd.skool, bts.skool and the others) and the ref files (sd.ref, bts.ref and the others) 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).
Skool macros have the following general form:
#MACROrparam1,rparam2,...[,oparam1,oparam2,...]
where:
If an optional parameter is left blank or omitted entirely, it assumes its default value. So, for example:
#UDG39144,6
is equivalent to:
#UDG39144,6,4,1,0
and:
#UDG30115,23,,2,1
is equivalent to:
#UDG30115,23,4,2,1
Numeric parameters may be given in decimal notation (as already shown in the examples above), or in hexadecimal notation (prefixed by $):
#UDG$98E8,$06
The skool macros recognised by SkoolKit are described in the following subsections.
In HTML mode, the #BUG macro expands to a hyperlink (<a> element) to the ‘Bugs’ page, or to a specific entry on that page.
#BUG[#name][(link text)]
In ASM mode, the #BUG macro reduces to the link text.
For example (from sd.skool):
42726 DEFB 130 ; Lesson #LINK:Lesson230(230) (REVISION LIBRARY): #R64410(130)
; (Reading Room) (this is a #BUG#emptyClass)
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’.
In HTML mode, the #C (Copyright) macro expands to the HTML entity reference for the copyright symbol (©).
#C
In ASM mode, the #C macro reduces to ‘(c)’.
For example (from sd.skool):
26751 DEFB 0 ; '#C': Unused
In HTML mode, the #CALL macro expands to the return value of a method on the SkoolWriter class or subclass that is being used to create the HTML disassembly (as defined by the SkoolWriterClass parameter in the [Config] section of the ref file).
#CALL:methodName(args)
The #CALL macro is not supported in ASM mode.
For example (from bts.skool):
; UDG reference table for the top-floor window when shut
;
; Used by the routine at #R27672. The UDG reference table for the top-floor
; window when open is at #R55296.
; #UDGTABLE(udgs)
; { #CALL:mutable(55040) }
; TABLE#
In HTML mode, this instance of the #CALL macro expands to an <img> element for the image of the top-floor window when shut (which is the return value of the mutable method on the BackToSkoolWriter class when called with the argument 55040).
In HTML mode, the #D (Description) macro expands to the title of an entry (a routine or data block) in the memory map.
#Daddress
In ASM mode, the #D macro reduces to the title of the entry.
For example (in sd.skool):
; The address of one of the following continual subcommand routines will be
; present in bytes 124 and 125 of a character's buffer:
; #TABLE(data,centre)
; { =h Address | =h Description }
; { #R25247 | RET (do nothing) }
; { #R27126 | #D27126 }
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.
In HTML mode, the #EREFS (Entry point REFerences) 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.
#EREFSaddress
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.
See also #REFS.
In HTML mode, the #FACT macro expands to a hyperlink (<a> element) to the ‘Trivia’ page, or to a specific entry on that page.
#FACT[#name][(link text)]
The #FACT macro is not supported in ASM mode.
In HTML mode, the #FONT macro expands to an <img> element for an image of the game font (as used on the ‘Other graphics’ page in the Skool Disassemblies).
#FONTaddress,chars[,attr,scale,ftype][(fname)]
The #FONT macro is not supported in ASM mode.
If an image with the given filename doesn’t already exist, it will be created. If fname starts with a ‘/’, the filename is taken to be relative to the root of the HTML disassembly; otherwise the filename is taken to be relative to the directory defined by the FontImagePath parameter in the [Paths] section of the ref file.
For example (from the [Graphics] section of sd.ref):
<h3>Font</h3>
<div>#FONT55584,96,,,1</div>
In HTML mode, this instance of the #FONT macro expands to an <img> element for the image of the skool font.
In HTML mode, the #LINK macro expands to a hyperlink (<a> element) to another page.
#LINK:PageId[#name](link text)
In ASM mode, the #LINK macro reduces to the link text.
The page IDs that may be used are the same as the file IDs that may be used in the [Paths] section of a ref file.
For example (from sd.skool):
; See the #LINK:CharacterBuffers(character buffer documentation) for details of
; how the buffer is used.
In HTML mode, this instance of the #LINK macro expands to a hyperlink to the ‘Character buffers’ page, with link text ‘character buffer documentation’.
In ASM mode, this instance of the #LINK macro reduces to ‘character buffer documentation’.
In HTML mode, the #NAME macro expands to an anchor (<a>) element with a given name.
#NAMEname
In ASM mode, the #NAME macro reduces to an empty string.
For example (from bts.skool):
; #NAMEstaircaseMatrix
; The staircase endpoint identifiers are arranged in bytes 60-67 (corresponding
; to the destination) of pages 189-196 (corresponding to the current location)
; as follows:
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.
In HTML mode, the #P (Paragraph) macro expands to two adjacent br elements: <br /><br />.
#P
In ASM mode, the #P macro reduces to an empty string.
For example (from bts.skool):
; Print a tile
;
; Used by the routines at #R25026, #R25080 and #R25248. Copies a tile of the
; play area into the back buffer at #R57712, superimposes character sprite tiles
; as appropriate, and then copies the resultant tile to the screen. Also sets
; the corresponding attribute byte.
; #P
; The play area graphic data is laid out across pages 128 to 181:
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.
In HTML mode, the #POKE macro expands to a hyperlink (<a> element) to the ‘Pokes’ page, or to a specific entry on that page.
#POKE[#name][(link text)]
The #POKE macro is not supported in ASM mode.
For example (from bts.ref):
If you want to check this for yourself but can't bear to wait for playtime to
come, try the POKEs that enable ERIC to #POKE#ringBell(ring the bell).
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’.
In HTML mode, the #POKES (POKE Snapshot) macro is used to POKE values into the current memory snapshot.
#POKESaddress,byte[,length,step]
The #POKES macro is not supported in ASM mode.
For example (in bts.ref):
To make the line transparent:
#PUSHSeh2
#POKES47254,255
#UDGTABLE(gglitch)
{ #CALL:as_img(54,4) }
{ POKE 47254,255 }
UDGTABLE#
#POPS
In HTML mode, this instance of the #POKES macro does POKE 47254,255, which fixes the graphic glitch in the animatory state of EINSTEIN lying down. The #CALL macro further down then expands to an <img> element for the image of the fixed animatory state.
In HTML mode, the #POPS (POP Snapshot) macro removes the current memory snapshot and replaces it with the one that was previously saved by a #PUSHS macro.
#POPS
The #POPS macro is not supported in ASM mode.
As a skool file is being parsed, a memory snapshot is built up from all the DEFB, DEFW, DEFM and DEFS instructions. After the file has been parsed, the memory snapshot is used to build images of the skool graphic elements (animatory states, score box etc.) for the HTML disassemblies.
In HTML mode, the #PUSHS (PUSH Snapshot) macro saves the current snapshot, and replaces it with an identical copy with a given name.
#PUSHSname
The #PUSHS macro is not supported in ASM mode.
The new snapshot may then be modified by using the #POKES macro. The snapshot name is used to indicate that the current snapshot is a modified version of the original (which has no name).
For example (in bts.ref):
To make the line transparent:
#PUSHSeh2
#POKES47254,255
#UDGTABLE(gglitch)
{ #CALL:as_img(54,4) }
{ POKE 47254,255 }
UDGTABLE#
#POPS
In HTML mode, this instance of the #PUSHS macro creates a new snapshot (copied from the original) named ‘eh2’. This snapshot is then modified with a #POKES macro. Further on, the #CALL macro will expand to an <img> element for the image of animatory state 54 (scaled up by a factor of 4) built from the current snapshot (‘eh2’).
In HTML mode, the #R (Reference) 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 (if the routine or data block is defined in the same skool file).
#Raddress[@code][#name][(link text)]
In ASM mode, the #R macro reduces to the link text if it is specified, or to the label for address, or to address if no label is found.
For example (from sd.skool):
; Scroll the screen left one column
;
; Used by the routine at #R25820.
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).
In HTML mode, the #REFS (REFerenceS) 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.
#REFSaddress[(prefix)]
If there are no references, the macro expands to the following text:
Not used directly by any other routines
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.
See also #EREFS.
In HTML mode, the #REG (REGister) macro expands to a styled <span> element containing a register name.
#REGreg
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:
abcdefhlirspxy'
For example (from sd.skool):
24623 LD C,31 ; #REGbc'=31
In HTML mode, the #SCR (SCReenshot) macro expands to an <img> element for an image constructed from the display file and attribute bytes of the current memory snapshot (in turn constructed from the contents of the skool file).
#SCR[scale,x,y,w,h][(fname)]
The #SCR macro is not supported in ASM mode.
If an image with the given filename doesn’t already exist, it will be created. If fname starts with a ‘/’, the filename is taken to be relative to the root of the HTML disassembly; otherwise the filename is taken to be relative to the directory defined by the ScreenshotImagePath parameter in the [Paths] section of the ref file.
For example (from sd-save.skool):
; #TABLE(scr,,scrDesc)
; { #SCR(saver) | This is the program used to save the fast code block for Skool Daze. }
; TABLE#
In HTML mode, the #SPACE macro expands to one or more   expressions.
#SPACE[num]
In ASM mode, the #SPACE macro reduces to num spaces.
For example (from sd.skool):
t56832 DEFM "TAKE 2000 LINES YOU NASTY BOY"
56861 DEFB 3 ; #R55830: '#SPACE8' (8 spaces)
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.
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.
#TABLE[(class[,class1[:w][,class2[:w]...]])]<rows>TABLE#
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):
; And then the action identifier:
; #TABLE(data)
; { 0 | Close it }
; { 1 | Open it }
; TABLE#
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:
; #TABLE
; { =h Header 1 | =h Header 2 }
; { Regular cell | Another one }
; TABLE#
It is also possible to specify colspan and rowspan attributes using the =c and =r indicators:
; #TABLE
; { =r2 2 rows | X | Y }
; { =c2 2 columns }
; TABLE#
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:
; #TABLE
; { =h,c2 Wide header }
; { Column 1 | Column 2 }
; TABLE#
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:
; #TABLE(data,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#
See also #UDGTABLE.
In HTML mode, the #UDG macro expands to an <img> element for the image of a UDG (an 8x8 block of pixels).
#UDGaddr,attr[,scale,step,inc][:maskAddr[,maskStep]][(fname)]
The #UDG macro is not supported in ASM mode.
If an image with the given filename doesn’t already exist, it will be created. If fname starts with a ‘/’, the filename is taken to be relative to the root of the HTML disassembly; otherwise the filename is taken to be relative to the directory defined by the UDGImagePath parameter in the [Paths] section of the ref file.
For example (from bts.skool):
; Safe key UDG
;
; Used by the routine at #R31746.
; #UDGTABLE(udgs)
; { #UDG39144,6(safe_key) }
; TABLE#
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).
In HTML mode, the #UDGARRAY macro expands to an <img> element for the image of an array of UDGs (8x8 blocks of pixels).
#UDGARRAYwidth[,attr,scale,step,inc];addr1[,attr1,step1,inc1];...(fname)
As many sets of UDGs as required may be specified, separated by semicolons; the UDGs will be arranged in a rectangular array with the given width.
The #UDGARRAY macro is not supported in ASM mode.
If an image with the given filename doesn’t already exist, it will be created. If fname starts with a ‘/’, the filename is taken to be relative to the root of the HTML disassembly; otherwise the filename is taken to be relative to the directory defined by the UDGImagePath parameter in the [Paths] section of the ref file.
For example (from the [Graphics] section of sd.ref):
<tr><td>#UDGARRAY8,,,256;33008-33023(bubble)</td>...
In HTML mode, this instance of the #UDGARRAY macro expands to an <img> element for the image of the speech bubble in Skool Daze (which is 8 UDGs wide, and consists of the 16 UDGs with base addresses 33008-33023).
Also (from the [Graphics] section of bts.ref):
<tr><td>#UDGARRAY8;39392;39648x6;39904;40160;40416x6;40672(bubble)</td>...
In HTML mode, this instance of the #UDGARRAY macro expands to an <img> element for the image of the speech bubble in Back to Skool.