skool files and ref files may contain skool 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,0,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:
42726 DEFB 130 ; This is a #BUG#bug1; it should be 188
In HTML mode, this instance of the #BUG macro expands to a hyperlink to an entry on the ‘Bugs’ page.
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:
26751 DEFB 127 ; This is the copyright symbol: #C
In HTML mode, the #CALL macro expands to the return value of a method on the HtmlWriter 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:
; Graphic data for sprite 23
;
; #UDGTABLE(udgs)
; { #CALL:sprite(23) }
; TABLE#
In HTML mode, this instance of the #CALL macro expands to the return value of the sprite method when called with the argument 23.
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:
; Now we make an indirect jump to one of the following routines:
; #TABLE(data,centre)
; { =h Address | =h Description }
; { #R27126 | #D27126 }
In HTML mode, this instance of the #D macro expands to the title of the routine at 27126.
In ASM mode, this instance of the #D macro reduces to the title of the routine at 27126.
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.
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)]
In ASM mode, the #FACT macro reduces to the link text.
For example:
See the trivia entry #FACT#interestingFact() for details.
In HTML mode, this instance of the #FACT macro expands to a hyperlink to an entry on the ‘Trivia’ page, with link text equal to the title of the entry.
In ASM mode, this instance of the #FACT macro reduces to the title of the entry on the ‘Trivia’ page.
In HTML mode, the #FONT macro expands to an <img> element for an image of the game font.
#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:
; Font graphic data
;
; #UDGTABLE(udgs)
; { #FONT49152,32 }
; TABLE#
In HTML mode, this instance of the #FONT macro expands to an <img> element for the image of the 32 characters in the 8*8 font whose graphic data starts at 49152.
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:
; See the #LINK:Glossary(glossary) for a definition of 'chuntey'.
In HTML mode, this instance of the #LINK macro expands to a hyperlink to the ‘Glossary’ page, with link text ‘glossary’.
In ASM mode, this instance of the #LINK macro reduces to ‘glossary’.
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:
; #NAMEspriteData
; The following section contains sprite graphic data.
In HTML mode, this instance of the #NAME macro expands to an anchor element named ‘spriteData’.
In ASM mode, this instance of the #NAME macro reduces 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)]
In ASM mode, the #POKE macro reduces to the link text.
For example:
Of course, if you feel like cheating, you can always give yourself
#POKE#infiniteLives(infinite lives).
In HTML mode, this instance of the #POKE macro expands to a hyperlink to an entry on the ‘Pokes’ page, with link text ‘infinite lives’.
In ASM mode, this instance of the #POKE macro reduces to ‘infinite lives’.
In HTML mode, the #POKES (POKE Snapshot) macro is used to POKE values into the current memory snapshot.
#POKESaddress,byte[,length,step][;address,byte[,length,step];...]
The #POKES macro is not supported in ASM mode.
For example:
; The UDG looks like this:
; #UDGTABLE(udgs)
; { #UDG32768,56 }
; TABLE#
; But it's supposed to look like this:
; #PUSHS
; #POKES32772,254;32776,136
; #UDGTABLE(udgs)
; { #UDG32768,56 }
; TABLE#
; #POPS
In HTML mode, this instance of the #POKES macro does POKE 32772,254 and POKE 32776,136, which fixes a graphic glitch in the UDG at 32768.
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.
#PUSHS[name]
The #PUSHS macro is not supported in ASM mode.
The new snapshot may then be modified by using the #POKES macro.
For example:
; The UDG at 32768 is supposed to look like this:
; #PUSHS
; #POKES32772,254
; #UDGTABLE(udgs)
; { #UDG32768,56 }
; TABLE#
; #POPS
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.
#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:
; Prepare for a new game
;
; 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 ASM mode, this instance of the #R macro reduces to the label for the routine at 25820 (or simply 25820 if that routine has no label).
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.
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:
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:
; #UDGTABLE(scr,,scrDesc)
; { #SCR(loading) | This is the loading screen. }
; 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:
; '#SPACE8' (8 spaces)
t56832 DEFM " "
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:
; #TABLE(data)
; { 0 | Off }
; { 1 | On }
; 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,flip,rotate][: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:
; Safe key UDG
;
; #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 UDG at 39144 (which will be named safe_key.png), 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,flip,rotate];addr1[,attr1,step1,inc1][:maskAddr1[,maskStep1]];...(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:
; Base sprite
;
; #UDGTABLE(udgs)
; { #UDGARRAY4;32768-32888-8(base_sprite) }
; TABLE#
In HTML mode, this instance of the #UDGARRAY macro expands to an <img> element for the image of the 4x4 sprite formed by the 16 UDGs with base addresses 32768, 32776, 32784 and so on up to 32888; the image file will be named base_sprite.png.