SkoolKit

Spectrum game disassembly toolkit

FAQ

FAQ

Trying to do something specific with SkoolKit and can’t figure out how? The first place to look is the user manual, but if you can’t find the answer there, then perhaps you’ll find it below.

Contents

How can I make skool2html.py write labels?

First of all, you need to define some labels by using the @label directive. Then, to make skool2html.py include those labels in the HTML output, use the --asm-labels option.

How can I make skool2html.py write labels in LD instruction operands?

By default when using the --asm-labels option, skool2html.py will replace addresses with labels in the following types of instruction:

  • CALL
  • DEFW
  • DJNZ
  • JP
  • JR

LD instructions are omitted from this list because their operands are often pure data values (e.g. a counter, an addend or a subtrahend) and not addresses, and replacing such a data value that coincidentally equals that of a labelled address would be a mistake.

But if you really want all LD instruction operands to be replaced by labels where possible, just append LD to the value of the LinkOperands parameter in the [Game] section of the ref file:

LinkOperands=CALL,DEFW,DJNZ,JP,JR,LD

Then, if you do find that some LD instruction operands are being incorrectly replaced with labels, you can correct them by using the @keep directive.

My disassembly pages are too narrow

That’s a statement, not a question. Anyway, by default, the HTML tables on disassembly pages are restricted to a width of 800 pixels. If that’s not enough to comfortably accommodate the instructions and annotations in your disassembly, try the ‘wide’ theme:

$ skool2html.py --theme wide game.skool ...

How can I get negative operands in my disassembly?

If you want to see LD A,-1 instead of LD A,255 in your skool file, you need to avail yourself of the ‘m’ (minus) number base indicator. For example, if the LD A,n instruction is at address 32768, then this directive in the control file will make sure its operand is rendered as a negative integer:

C 32768,m2

How can I get numbers in the right base in annotations?

If you publish your disassembly in both hexadecimal and decimal formats, you might want numbers in annotations to be rendered as either hexadecimal or decimal depending on the options (--hex, --decimal, or neither) passed to skool2asm.py or skool2html.py. If that’s the case, the #N macro is your friend.

How do I keep auto-generated 'Used by' comments after I've added my own?

By default, sna2skool.py inserts a “Used by the routine(s) at…” comment at every routine entry point that doesn’t already have a comment defined. To make it do so even for entry points that do already have a comment defined, set the ListRefs configuration parameter to ‘2’, either on the command line:

$ sna2skool.py --ini ListRefs=2 ...

or in the [sna2skool] section of skoolkit.ini:

[sna2skool]
ListRefs=2

How do I repeat a comment N times without having to write it N times?

There are a couple of ways to do that. Let’s say you want to do the equivalent of this:

B 30000,4 Data set 1
B 30004,4 Data set 2
B 30008,4 Data set 3
...
B 30392,4 Data set 99
B 30396,4 Data set 100

but without writing out these 100 directives individually. One approach is to use a control file loop. For example:

B 30000,4 Data set #EVAL((#PC-29996)/4)
L 30000,4,100

The other approach is to use the repeat parameter of the M directive:

M 30000,400,1 Data set #EVAL((#PC-29996)/4)
B 30000,400,4

In each approach, the #EVAL macros will be expanded by skool2html.py or skool2asm.py to ‘1’, ‘2’, ‘3’, and so on up to ‘100’.

My control file is big. Can I split it up?

Yes, you can. The --ctl option of sna2skool.py can be repeated as many times as you like:

$ sna2skool.py --ctl first.ctl --ctl second.ctl ...

Alternatively, you could place all your control files into a subdirectory named ctlfiles (for example) and then do:

$ sna2skool.py --ctl ctlfiles ...

Why does skool2asm.py produce no output?

You’re probably missing a @start directive. Place one at the address of the routine or data block at which you want to start producing output, and you’ll be good to go.

Why does skool2asm.py produce so many warnings?

Probably because you haven’t defined enough (or any) address labels. You can make skool2asm.py nag you a little less by creating default labels for unlabelled instructions:

$ skool2asm.py --create-labels ...

But if that’s not enough, and you still think skool2asm.py is warning you about unimportant things, you can shut it up completely like this:

$ skool2asm.py --no-warnings ...

Why does skool2asm.py abort because of an unsupported macro?

skool2asm.py is just letting you know that it has encountered an #AUDIO macro or an image macro, and doesn’t know what to do with it.

One way to handle this is to hide the offending macro behind either an #HTML macro or a #UDGTABLE macro.

Another way to handle this is to use the @set directive to set the ASM property handle-unsupported-macros to 1. Then skool2asm.py will expand any unsupported macro it encounters to an empty string.

How can I see the BASIC loader in a snapshot or TAP file?

Use the --basic option of snapinfo.py or tapinfo.py. For example:

$ snapinfo.py --basic game.z80

For a TAP/TZX file, you will need to specify the tape block number (which starts at ‘1’ for the first block):

$ tapinfo.py --basic 2 game.tap

How can I create a TAP file from my disassembly?

First, use skool2bin.py to convert your disassembly into a raw memory file (game.bin in this example):

$ skool2bin.py game.skool

Then use bin2tap.py to convert game.bin into game.tap:

$ bin2tap.py game.bin

Note that bin2tap.py defaults to creating a TAP file that loads the contents of game.bin at an origin address equal to 65536 minus the length of the file, and then executes the code at that same address. If that’s incorrect, use the --org option to set the origin address, and the --start option to set the address at which to start executing code (if it’s different from the origin address).

How can I create a Z80 snapshot from my disassembly?

First, use skool2bin.py to convert your disassembly into a raw memory file (game.bin in this example):

$ skool2bin.py game.skool

Then use bin2sna.py to convert game.bin into game.z80:

$ bin2sna.py game.bin

Note that bin2sna.py defaults to creating a Z80 snapshot with the contents of game.bin at an origin address equal to 65536 minus the length of the file, and the program counter set to that same address. If that’s incorrect, use the --org option to set the origin address, and the --start option to set the program counter (if it’s different from the origin address).

Should I edit the control file or the skool file?

Ah yes, the age-old debate. This question is now addressed in the user manual. In short, edit the control file unless you’re really sure you know what you’re doing.

How can I make my own HTML page similar to the Bugs, Pokes and Trivia pages?

So you want to make your own box page. First it needs its own [Page:*] section and an ID (MyThings, say). For example:

[Page:MyThings]
SectionPrefix=MyThings

Then you can add entries (boxes) to the page by adding sections to the ref file named MyThings:title:

[MyThings:First thing]
Fascinating description of the first thing.

[MyThings:Second thing]
Spellbinding account of the second thing.

After that you can add a link to this custom box page on the home page of the disassembly, let’s say at the end of the ‘Reference’ section:

[Index:Reference:Reference]
Changelog
Glossary
Facts
Bugs
Pokes
MyThings

Finally, to change this custom page’s title, page header (if different from the title) and link text (if different from the page header), and the location of the file to which it is written:

[Titles]
MyThings=My things

[PageHeaders]
MyThings=My interesting things

[Links]
MyThings=My fascinating things

[Paths]
MyThings=reference/things.html