While creating a disassembly of a game, you may find that SkoolKit’s suite of skool macros is inadequate for certain tasks. For example, the game might have large tile-based sprites that you want to create images of for the HTML disassembly, and composing long #UDGARRAY macros for them would be too tedious. Or you might want to insert a timestamp somewhere in the ASM disassembly so that you (or others) can keep track of when your ASM files were written.
One way to solve these problems is to add custom methods that could be called by a #CALL macro. But where to add the methods? SkoolKit’s core HTML writer and ASM writer classes are skoolkit.skoolhtml.HtmlWriter and skoolkit.skoolasm.AsmWriter, so you could add the methods to those classes. But a better way is to subclass HtmlWriter and AsmWriter in a separate extension module, and add the methods there; then that extension module can be easily used with different versions of SkoolKit, and shared with other people.
A minimal extension module would look like this:
from skoolkit.skoolhtml import HtmlWriter
from skoolkit.skoolasm import AsmWriter
class GameHtmlWriter(HtmlWriter):
pass
class GameAsmWriter(AsmWriter):
pass
The next step is to get SkoolKit to use the extension module for your game. First, place the extension module (let’s call it game.py) in the skoolkit package directory; to locate this directory, run skool2html.py with the -p option:
$ skool2html.py -p
/usr/lib/python2.7/dist-packages/skoolkit
(The package directory may be different on your system.) With game.py in place, add the following line to the [Config] section of your disassembly’s ref file:
HtmlWriterClass=skoolkit.game.GameHtmlWriter
If you don’t have a ref file yet, create one (ideally named game.ref, assuming the skool file is game.skool); if the ref file doesn’t have a [Config] section yet, add one.
Now whenever skool2html.py is run on your skool file (or ref file), SkoolKit will use the GameHtmlWriter class instead of the core HtmlWriter class.
To get skool2asm.py to use GameAsmWriter instead of the core AsmWriter class when it’s run on your skool file, add the following @writer ASM directive somewhere after the @start directive, and before the @end directive (if there is one):
@writer=skoolkit.game.GameAsmWriter
The skoolkit package directory is a reasonable place for an extension module, but it could be placed in another package, or somewhere else as a standalone module. For example, if you wanted to keep a standalone extension module named game.py in ~/.skoolkit, you should set the HtmlWriterClass parameter thus:
HtmlWriterClass=~/.skoolkit:game.GameHtmlWriter
and the @writer directive thus:
@writer=~/.skoolkit:game.GameAsmWriter
The HTML writer or ASM writer class can also be specified on the command line by using the -W/--writer option of skool2html.py or skool2asm.py. For example:
$ skool2html.py -W ~/.skoolkit:game.GameHtmlWriter game.skool
Specifying the writer class this way will override any HtmlWriterClass parameter in the ref file or @writer directive in the skool file.
Implementing a method that can be called by a #CALL macro is done by adding the method to the HtmlWriter or AsmWriter subclass in the extension module.
One thing to be aware of when adding a #CALL method to a subclass of HtmlWriter is that the method must accept an extra parameter in addition to those passed from the #CALL macro itself: cwd. This parameter is set to the current working directory of the file from which the #CALL macro is executed, which may be useful if the method needs to provide a hyperlink to some other part of the disassembly (as in the case where an image is being created).
Let’s say your sprite-image-creating method will accept two parameters (in addition to cwd): sprite_id (the sprite identifier) and fname (the image filename). The method (let’s call it sprite) would look something like this:
from skoolkit.skoolhtml import HtmlWriter
class GameHtmlWriter(HtmlWriter):
def sprite(self, cwd, sprite_id, fname):
img_path = self.image_path(fname)
if self.need_image(img_path):
udgs = self.build_sprite(sprite_id)
self.write_image(img_path, udgs)
return self.img_element(cwd, img_path)
With this method (and an appropriate implementation of the build_sprite method) in place, it’s possible to use a #CALL macro like this:
#UDGTABLE
{ #CALL:sprite(3,jumping) }
{ Sprite 3 (jumping) }
TABLE#
Adding a #CALL method to the AsmWriter subclass is equally simple. The timestamp-creating method (let’s call it timestamp) would look something like this:
import time
from skoolkit.skoolasm import AsmWriter
class GameAsmWriter(AsmWriter):
def timestamp(self):
return time.strftime("%a %d %b %Y %H:%M:%S %Z")
With this method in place, it’s possible to use a #CALL macro like this:
; This ASM file was generated on #CALL:timestamp()
Note that if the return value of a #CALL method contains skool macros, then they will be expanded.
Another way to add a custom method is to implement it as a skool macro. The main differences between a skool macro and a #CALL method are:
In summary: a #CALL method is generally simpler to implement than a skool macro, but skool macros are more flexible.
Implementing a skool macro is done by adding a method named expand_macroname to the HtmlWriter or AsmWriter subclass in the extension module. So, to implement a #SPRITE or #TIMESTAMP macro, we would add a method named expand_sprite or expand_timestamp.
A skool macro method must accept either two or three parameters, depending on whether it is implemented on a subclass of AsmWriter or HtmlWriter:
A skool macro method must return a 2-tuple of the form (end, string), where end is the index of the character after the last character of the macro’s parameter string, and string is the HTML or text to which the macro will be expanded.
The expand_sprite method on GameHtmlWriter may therefore look something like this:
from skoolkit.skoolhtml import HtmlWriter
class GameHtmlWriter(HtmlWriter):
# #SPRITEspriteId[{x,y,width,height}](fname)
def expand_sprite(self, text, index, cwd):
end, img_path, crop_rect, sprite_id = self.parse_image_params(text, index, 1)
if self.need_image(img_path):
udgs = self.build_sprite(sprite_id)
self.write_image(img_path, udgs, crop_rect)
return end, self.img_element(cwd, img_path)
With this method (and an appropriate implementation of the build_sprite method) in place, the #SPRITE macro might be used like this:
#UDGTABLE
{ #SPRITE3(jumping) }
{ Sprite 3 (jumping) }
TABLE#
The expand_timestamp method on GameAsmWriter would look something like this:
import time
from skoolkit.skoolasm import AsmWriter
class GameAsmWriter(AsmWriter):
def expand_timestamp(self, text, index):
return index, time.strftime("%a %d %b %Y %H:%M:%S %Z")
Note that if the string part of the return value of a skool macro method contains skool macros, then they will be expanded.
The skoolkit.skoolmacro module provides some utility functions that may be used to parse the parameters of a skool macro.
Parse a string of comma-separated integer parameters. The string will be parsed until either the end is reached, or an invalid character is encountered. The set of valid characters consists of the comma, ‘$’, the digits 0-9, and the letters A-F and a-f; if names is not empty, the set of valid characters also includes ‘=’ and the letters g-z.
| Parameters: |
|
|---|---|
| Returns: | A list of the form [end, value1, value2...], where:
|
Changed in version 4.0: Added the names parameter and support for keyword arguments; index defaults to 0.
Parse a string of the form params[(p_text)]. The parameter string params will be parsed until either the end is reached, or an invalid character is encountered. The default set of valid characters consists of ‘$’, ‘#’, the digits 0-9, and the letters A-Z and a-z.
| Parameters: |
|
|---|---|
| Returns: | A 3-tuple of the form (end, params, p_text), where:
|
Changed in version 3.6: Added the except_chars and only_chars parameters.
HtmlWriter also provides a method for parsing the parameters of an image-creating skool macro.
Parse a string of the form:
params[{x,y,width,height}][(fname[*frame][|alt])]
The parameter string params may contain comma-separated values and is parsed until either the end is reached, or an invalid character is encountered. The default set of valid characters consists of the comma, ‘$’, the digits 0-9, and the letters A-F and a-f; if names is not empty, the set of valid characters also includes ‘=’ and the letters g-z.
| Parameters: |
|
|---|---|
| Returns: | A list of the form [end, image_path, frame, alt, crop_rect, value1, value2...], where:
|
Changed in version 3.6: If path_id is blank or None, image_path is equal to fname; added the ints parameter.
Changed in version 4.0: Added the names parameter and support for keyword arguments.
Changed in version 4.2: Added the frame and alt parameters.
Both HtmlWriter and AsmWriter provide methods for expanding skool macros. These are useful for basing a #CALL method or custom macro on an existing macro.
Return text with skool macros expanded. cwd is the current working directory, which is required by macros that create images or hyperlinks.
Return text with skool macros expanded.
HtmlWriter provides some convenience methods for extracting text and data from ref files. These methods are described below.
Return the contents of a ref file section.
| Parameters: |
|
|---|
Return a list of 2-tuples of the form (suffix, contents) or 3-tuples of the form (infix, suffix, contents) derived from ref file sections whose names start with section_type followed by a colon. suffix is the part of the section name that follows either the first colon (when there is only one) or the second colon (when there is more than one); infix is the part of the section name between the first and second colons (when there is more than one).
| Parameters: |
|
|---|
Return a dictionary built from the contents of a ref file section. Each line in the section should be of the form X=Y.
Return a list of 2-tuples of the form (suffix, dict) derived from ref file sections whose names start with section_type followed by a colon. suffix is the part of the section name that follows the first colon, and dict is a dictionary built from the contents of that section; each line in the section should be of the form X=Y.
The snapshot attribute on HtmlWriter and AsmWriter is a 65536-element list that represents the 64K of the Spectrum’s memory; it is populated when the skool file is being parsed.
A simple #PEEK macro that expands to the value of the byte at a given address might be implemented by using snapshot like this:
from skoolkit.skoolhtml import HtmlWriter
from skoolkit.skoolasm import AsmWriter
from skoolkit.skoolmacro import parse_ints
class GameHtmlWriter(HtmlWriter):
# #PEEKaddress
def expand_peek(self, text, index, cwd):
end, address = parse_ints(text, index, 1)
return end, str(self.snapshot[address])
class GameAsmWriter(AsmWriter):
# #PEEKaddress
def expand_peek(self, text, index):
end, address = parse_ints(text, index, 1)
return end, str(self.snapshot[address])
HtmlWriter also provides some methods for saving and restoring memory snapshots, which can be useful for temporarily changing graphic data or the contents of data tables. These methods are described below.
Save the current memory snapshot for later retrieval (by pop_snapshot()), and put a copy in its place.
| Parameters: | name – An optional name for the snapshot. |
|---|
Discard the current memory snapshot and replace it with the one that was most recently saved (by push_snapshot()).
Return the name of the current memory snapshot.
If you are going to implement custom image-creating #CALL methods or skool macros, you will need to make use of the skoolkit.skoolhtml.Udg class.
The Udg class represents an 8x8 graphic (8 bytes) with a single attribute byte, and an optional mask.
Initialise the UDG.
| Parameters: |
|
|---|
A simple #INVERSE macro that creates an inverse image of a UDG might be implemented like this:
from skoolkit.skoolhtml import HtmlWriter, Udg
from skoolkit.skoolmacro import parse_ints
class GameHtmlWriter(HtmlWriter):
# #INVERSEaddress,attr
def expand_inverse(self, text, index, cwd):
end, address, attr = parse_ints(text, index, 2)
img_path = self.image_path('inverse{0}_{1}'.format(address, attr))
if self.need_image(img_path):
udg_data = [b ^ 255 for b in self.snapshot[address:address + 8]]
udg = Udg(attr, udg_data)
self.write_image(img_path, [[udg]])
return end, self.img_element(cwd, img_path)
The Udg class provides two methods for manipulating an 8x8 graphic: flip and rotate.
Flip the UDG.
| Parameters: | flip – 1 to flip horizontally, 2 to flip vertically, or 3 to flip horizontally and vertically. |
|---|
Rotate the UDG 90 degrees clockwise.
| Parameters: | rotate – The number of rotations to perform. |
|---|
If you are going to implement #CALL methods or skool macros that create animated images, you will need to make use of the skoolkit.skoolhtml.Frame class.
The Frame class represents a single frame of an animated image.
Create a frame of an animated image.
| Parameters: |
|
|---|
New in version 3.6.
Changed in version 4.0: The mask parameter specifies the type of mask to apply (see Masks).
HtmlWriter provides the following image-related convenience methods.
Return the full path of an image file relative to the root directory of the disassembly. If fname does not end with ‘.png’ or ‘.gif’, an appropriate suffix will be appended (depending on the default image format). If fname starts with a ‘/’, it will be removed and the remainder returned (in which case path_id is ignored). If fname is blank, None is returned.
| Parameters: |
|
|---|
Return whether an image file needs to be created. This will be true only if the file doesn’t already exist, or all images are being rebuilt. Well-behaved image-creating methods will call this to check whether an image file needs to be written, and thus avoid building an image when it is not necessary.
| Parameters: | image_path – The full path of the image file relative to the root directory of the disassembly. |
|---|
Create an image and write it to a file.
| Parameters: |
|
|---|
Changed in version 4.0: The mask parameter specifies the type of mask to apply (see Masks).
Create an animated image and write it to a file.
| Parameters: |
|
|---|
New in version 3.6.
Return an <img .../> element for an image file.
| Parameters: |
|
|---|
Return a two-dimensional array of tiles (instances of Udg) built from the display file and attribute file of the current memory snapshot.
| Parameters: |
|
|---|
If your HtmlWriter subclass needs to perform some initialisation tasks, such as creating instance variables, or parsing ref file sections, the place to do that is the init() method.
Perform post-initialisation operations. This method is called after __init__() has completed. By default the method does nothing, but subclasses may override it.
For example:
from skoolkit.skoolhtml import HtmlWriter
class GameHtmlWriter(HtmlWriter):
def init(self):
# Get character names from the ref file
self.characters = self.get_dictionary('Characters')