The skool files (sd.skool, bts.skool and the others) and the ref files (sd.ref, bts.ref and skool.ref) 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). The skool macros recognised by SkoolKit are described in the following subsections.
In HTML mode, the #AS macro expands to a hyperlink (<a> element) to an image on the ‘Animatory states’ page.
#AS[state][(link text)]
In ASM mode, the #AS macro reduces to the link text.
For example (from sd.skool):
56081 DEFB 16 ; #AS16=EINSTEIN
In HTML mode, this instance of the #AS macro expands to a hyperlink to the image of animatory state 16 (EINSTEIN standing/walking, phase 1) on the ‘Animatory states’ page.
In ASM mode, this instance of the #AS macro reduces to ‘16’.
In HTML mode, the #ASIMG macro expands to an <img> element for the image of an animatory state.
#ASIMGnum[,scale[,mask[,attribute[,udgpage]]]]
The #ASIMG macro is not supported in ASM mode.
If an image file matching the required properties doesn’t already exist, it will be created.
For example (from bts.ref):
When BOY WANDER is sitting on the floor, there is a blank line above his head:
#UDGTABLE(gglitch)
{ #ASIMG21,4 }
UDGTABLE#
In HTML mode, this instance of the #ASIMG macro expands to an <img> element for the image for animatory state 21 (BOY WANDER sitting on the floor) at 4 times the original size.
In HTML mode, the #ASM macro expands to a hyperlink (<a> element) to the disassembly page for a routine or data block. The routine or data block need not exist in the current skool file.
#ASMaddress[#anchor][(link text)]
In ASM mode, the #ASM macro reduces to the link text.
For example (from the entry at 58144 in bts.skool):
; The 8 bytes here are skool graphic data that is copied into page 128 by the
; #ASM33204(startup routine) after the game has loaded...
In HTML mode, this instance of the #ASM macro expands to a hyperlink to the disassembly page for the startup routine at 33204 for Back to Skool (which is defined in start.skool), with ‘startup routine’ as the link text.
In ASM mode, this instance of the #ASM macro reduces to ‘startup routine’.
See also #R.
In HTML mode, the #ASTILE macro expands to an HTML <img> element for the image of an animatory state tile.
#ASTILEstate,row,col[,attr[,mask[,scale[,udgpage]]]]
The #ASTILE macro is not supported in ASM mode.
If an image file matching the required properties doesn’t already exist, it will be created.
In HTML mode, the #BOX macro expands to an <img> element for the image of a box graphic (such as the game logo or the score box, which are 64x24 pixels).
#BOXaddress[,scale[,attribute]]
The #BOX macro is not supported in ASM mode.
If an image file matching the required properties doesn’t already exist, it will be created.
For example (from sd.skool):
; 'Score - 0 Lines - 0 Hi-Sc - 0' box graphic
;
; Used by the routine at #R27406.
; #UDGTABLE(udgs)
; { #BOX60928 }
; TABLE#
In HTML mode, this instance of the #BOX macro expands to an <img> element for the image of the Skool Daze score box.
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 #LESSON230 (REVISION LIBRARY): #TAP130 (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 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 #CBUF macro expands to a hyperlink (<a> element) to the character buffer documentation page, or to a specific entry on that page.
#CBUF[#name][(link text)]
In ASM mode, the #CBUF macro reduces to the link text.
For example (in sd.skool):
; Character buffer for little boy no. 1 (152)
;
; See the #CBUF(character buffer documentation) for details of how the buffer is
; used.
In HTML mode, this instance of the #CBUF macro expands to a hyperlink to the character buffer documentation page with the link text ‘character buffer documentation’.
In ASM mode, this instance of the #CBUF macro reduces to ‘character buffer documentation’.
In HTML mode, the #D 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 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.
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 the image of the skool font (as used on the ‘Other graphics’ page).
#FONT
The #FONT macro is not supported in ASM mode.
The image of the skool font will be created if it doesn’t already exist.
In HTML mode, the #GBUF macro expands to a hyperlink (<a> element) to the ‘Game status buffer’ page, or to a specific entry on that page.
#GBUF[address][(link text)]
In ASM mode, the #GBUF macro reduces to the link text.
For example (from bts.skool):
; Next, clear the first 222 bytes of the #GBUF(game status buffer).
In HTML mode, the #KEYTABLE macro expands to a hyperlink (<a> element) to the ‘Keypress table’ page, or to a specific entry on that page.
#KEYTABLE[#name][(link text)]
In ASM mode, the #KEYTABLE macro reduces to ‘keypress table documentation’.
For example (from sd.skool):
; Used by the routine at #R26471. The entries in this table are pointed to by
; the the entries in the keypress offset table at #R26656. Another table of
; ASCII codes and routine addresses can be found at #R26752. For more details,
; see the #KEYTABLE.
In HTML mode, the #LESSON macro expands to a hyperlink (<a> element) to the page for a lesson.
#LESSONnum
In ASM mode, the #LESSON macro reduces to the lesson number.
For example (from sd.skool):
; Personal timetable for little boy no. 1 (152)
;
; Used by the routine at #R26342.
b39136 DEFB 170 ; Lesson #LESSON224 (DINNER (MR WITHIT)): #TAP170 (Dinner)
In HTML mode, this instance of the #LESSON macro (in the last line) expands to a hyperlink to the page for lesson 224.
In ASM mode, this instance of the #LESSON macro reduces to ‘224’.
In HTML mode, the #LOAD macro expands to a hyperlink (<a> element) to the disassembly page for one of the tape loading routines.
#LOADaddress[#name][(link text)]
In ASM mode, the #LOAD macro reduces to the link text.
For example (from save.skool):
; The last 5 bytes of the first group (16384 to 32956) saved make important
; changes to the #LOAD32815(load routine) when the game is being loaded:
In HTML mode, this instance of the #LOAD macro expands to a hyperlink to the disassembly page for the tape loading routine at 32815 with link text ‘load routine’.
In ASM mode, this instance of the #LOAD macro reduces to ‘load routine’.
In HTML mode, the #MSG macro expands to a hyperlink (<a> element) to the disassembly page for the data block containing a specific message.
#MSGnum[(link text)]
or:
#MSGaddress[(link text)]
In ASM mode, the #MSG macro reduces to the link text.
For example (from bts.skool):
c21152 LD A,21 ; Message #MSG21: 'MR WACKER'
In HTML mode, this instance of the #MSG macro expands to a hyperlink to the disassembly page for the data block containing message 21 (at 61267).
In ASM mode, this instance of the #MSG macro reduces to ‘21’.
In HTML mode, the #MUTABLE macro expands to an <img> element for the image of a mutable object in Back to Skool (i.e. a door, a window, a cup, or the spot on the tree where the bike is chained).
#MUTABLEaddress[,padding]
The #MUTABLE macro is not supported in ASM mode.
If an image file matching the required properties doesn’t already exist, it will be created.
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)
; { #MUTABLE55040 }
; TABLE#
In HTML mode, this instance of the #MUTABLE macro expands to an <img> element for the image of the top-floor window when shut (with no padding).
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 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 #PATILE macro expands to an <img> element for the image of a play area tile.
#PATILEx,y[,scale]
The #PATILE macro is not supported in ASM mode.
If an image with the required properties doesn’t already exist, it will be created.
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 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)
{ #ASIMG54,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 #ASIMG macro (see #ASIMG) further down then expands to an <img> element for the image of the fixed animatory state.
In HTML mode, the #POPS 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.
In HTML mode, the #PT macro expands to a hyperlink (<a> element) to the disassembly page containing a character’s personal timetable.
#PTnum[(link text)]
The #PT macro is not supported in ASM mode.
For example (from sd.ref):
MR ROCKITT never teaches in the Map Room. See his #PT164(personal timetable).
In HTML mode, this instance of the #PT macro expands to a hyperlink to the disassembly page containing the personal timetable for MR ROCKITT (whose character number is 164), with the link text ‘personal timetable’.
As a skool file is being parsed, a memory snapshot is built up from all the DEFB, DEFW, DEFM and DEFS instructions, and also any !defb directives (see !defb). 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 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)
{ #ASIMG54,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 #ASIMG macro (see #ASIMG) 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 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. The routine or data block being referred to must exist in the skool file.
#Raddress[#name][(link text)]
In ASM mode, the #R macro reduces 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).
See also #ASM.
In HTML mode, the #REFS 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.
In HTML mode, the #REG 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 #SAVE macro expands to a hyperlink (<a> element) to the disassembly page for the tape saver routine.
#SAVE[#name][(link text)]
In ASM mode, the #SAVE macro reduces to the link text.
For example (from sd.skool):
32494 JP 33024 ; Jump into the #SAVE(save routine)
In HTML mode, this instance of the #SAVE macro expands to a hyperlink to the disassembly page for the tape saver routine with link text ‘save routine’.
In ASM mode, this instance of the #SAVE macro reduces to ‘save routine’.
In HTML mode, the #SCR macro expands to an <img> element for the 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
The #SCR macro is not supported in ASM mode.
The screenshot image will be created if it doesn’t already exist.
For example (from save.skool):
; #TABLE(scr,,scrDesc)
; { #SCR | This is the program used to save the fast code block for Skool Daze. }
; TABLE#
In HTML mode, the #SKOOL macro expands to an <img> element for an image of the play area (or a portion of the play area).
#SKOOLx,y,w,h[,scale[,showChars[,showX]]]
The #SKOOL macro is not supported in ASM mode.
If an image of the play area matching the requirements doesn’t already exist, it will be created.
For example (from bts.ref):
#UDGTABLE(udgs)
{ #SKOOL0,0,96,21,1,0,8 }
{ #SKOOL96,0,96,21,1,0,8 }
UDGTABLE#
In HTML mode, the first instance of the #SKOOL macro here expands to an <img> element for an image of the left half of the play area of Back to Skool, with scale 1, no game characters displayed, and x-coordinates shown at 0, 8, 16, 24 and so on.
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.
In HTML mode, the #START macro expands to a hyperlink (<a> element) to a disassembly page for one of the the startup routines.
#STARTaddress[#name][(link text)]
In ASM mode, the #START macro reduces to the link text.
For example (from load.skool):
a32906 RET ; To (23833)=#START24288
In HTML mode, this instance of the #START macro expands to a hyperlink to the disassembly page for the startup routine at 24288 (for Skool Daze), with the address of that routine as the link text.
In ASM mode, this instance of the #START macro reduces to ‘24288’.
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 #TAP macro expands to a hyperlink (<a> element) to the disassembly page for a command list.
#TAPnum
In ASM mode, the #TAP macro reduces to the command list number.
For example (from sd.skool):
; Make a little boy find and follow little boy no. 1
;
; Used by command list #TAP206 (which is used by little boys 2-11).
In HTML mode, this instance of the #TAP macro expands to a hyperlink to the disassembly page for command list 206 in Skool Daze.
In ASM mode, this instance of the #TAP macro reduces to ‘206’.
In HTML mode, the #TAPS macro expands to a comma-separated list of hyperlinks (<a> elements) to the disassembly pages for the command lists that contain a given routine address.
#TAPSaddress
The #TAPS macro is not supported in ASM mode.
The #TAPS macro is not used in any of the stock SkoolKit data files, but it was used while the Skool Disassemblies were under development.
In ASM mode, the #TIME macro expands to the following string:
Generated by skool2asm on Mon 18 Jan 2010 14:48:56 AST
(with the timestamp replaced by the current time).
#TIME
The #TIME macro is not supported in HTML mode.
In HTML mode, the #UDG macro expands to an <img> element for the image of a UDG (an 8x8 block of pixels).
#UDGaddress,attribute[,scale[,step[,increment]]]
The #UDG macro is not supported in ASM mode.
If an image of the UDG matching the required properties doesn’t already exist, it will be created.
For example (from bts.skool):
; Safe key UDG
;
; Used by the routine at #R31746.
; #UDGTABLE(udgs)
; { #UDG39144,6 }
; 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).