Welcome to the second and final article on Porting the ZX81 and ZX Spectrum Game Tut-Tut to the Jupiter Ace: This time George Beckett takes us through the gritty details of programming in Forth, leaving few treasures undiscovered in the process.
If you missed Part 1, be sure to read up before continuing below.
 |
| Archaeology is just as fun in the Jupiter Ace version of TuT-TuT |
The Forth Tut-Tut is Ace
Previously, I told you a little about what motivated me to port Tut-tut to the Ace and promised to describe how the game is written. However, before we get on to the game, I should explain a bit about the Forth language, which was developed in the late 1960s for the control system of a telescope. Since then, its scope has grown, being used for a range of scientific and other serious applications in the 1980s and 90s. Even today, Forth lives on and can be found at the heart of various embedded systems.The basis of any Forth system is a dictionary of words that encapsulate the functions of the machine. There are simple words for manipulating data (bytes of memory) or performing rudimentary arithmetic, as well as more complex words for printing on the screen, making sound, and saving or loading files. The programmer combines these words together to make new words, continuing to build up the functionality until the final program is represented by one top-level word. In that way, writing a Forth program is a bottom-up process, starting at the lowest-level elements and working up. In contrast, the design of a Forth program is a top-down process. You iteratively break the program’s function down into smaller and smaller elements until you reach the level of the built-in words.
The overall structure of Tut-tut is relatively simple, with the player completing a sequence of levels, which involves collecting objects, unlocking doors, dodging mummies and finding the exit. The bulk of the logic is in how each level plays: how the player navigates the maze, collects objects and is chased by the mummies.
In Rabbit Run, the core of the game was a loop in which the player first had the opportunity to make their move and then each possible outcome was tested for—in that case, eating carrots, falling down mole holes, or being caught by a fox. At the end of the loop, the fox made their move and it was back to the beginning. The same game loop could be used for Tut-tut, though replacing foxes by mummies, carrots by gems, and so on.
For both Rabbit Run and Tut-tut, the game state is held in the display buffer. For example, to check the location the player wants to move to, you look up what is there in the display buffer. This is useful for saving both memory and time. In Tut-tut (and Rabbit Run) on the ZX Spectrum, objects are distinguished by colour. This makes it very fast to check what an object is by looking up its colour using the ATTRIB function (or PEEK-ing the right location in the display buffer). The Ace has a monochrome display, so this approach does not carry over immediately. However, the Ace display is very simple, formed from a two-dimensional array of characters, just like the attributes on the Spectrum is as two-dimensional array of colour values, and so it should be just as quick to look up the character code in the Ace’s screen memory as it is to look up a colour on the Spectrum. Thus, a crucial word to define in the Forth version of Tut-tut is SCREEN, which retrieves the character at a particular location in the level:
: SCREEN ( X Y -- CHAR )
SWAP 32 * + ( 32 CHARS PER ROW )
9216 + ( START OF SCREEN MEMORY )
C@
;
For player movement, I decided to use the Rabbit Run core as the starting point for Tut-tut, though there were some differences. Surprisingly, Ace Forth does not include a CASE statement (which would allow a number of different program paths to be followed depending on the value of an input field—such as, a key-press or the object at a location). For example:
( X Y -- NEW_X NEW_Y )
INKEY
CASE
ASCII P OF 1+ ENDOF ( RIGHT )
ASCII O OF 1- ENDOF ( LEFT )
ASCII A OF SWAP 1+ SWAP ENDOF ( DOWN )
ASCII Q OF SWAP 1- SWAP ENDOF ( UP )
ENDCASE
Sadly, there is no CASE word in Ace Forth, so the above code would not work. I investigated options to implement a CASE structure (a big selling point of Forth is the ability to add your own commands). However, while I found a few candidates on the Internet and in 1980’s magazines, none of them proved to be very effective nor reliable. I therefore decided to use brute force, writing multiple IF statements. This is an ugly approach though has proved adequate for Tut-tut.
Another weakness of FORTH (and, to a lesser extent, BASIC) is that it is difficult to define large input datasets—in this case, I was thinking about how to get the data for game levels into the game. In the BASIC version, David used DATA statements, RESTORE-ing to the correct line and then READ-ing the data for each level. However, FORTH does not have a DATA statement and the method for entering data described in the Ace manual is very laborious. In the end, I decided to bypass FORTH and to define the level data in binary code blocks to be loaded into memory inside suitable ALLOT’ed arrays. For example:
 |
| Tut-tut UDGs and character codes on the Ace. |
CREATE GAMELEVELS 4000 ALLOT
GAMELEVELS 4000 BLOAD tut-tut.lev
There is a reasonable amount of logic involved in drawing each level in Tut-tut, as a level is stored in a compressed form to save memory. In the original ZX Spectrum version, a technique based on trios of character cells was use to reduce the memory requirements of a level by a factor of three. However, since finishing the BASIC version, David updated the compression strategy to one inspired by the GIF image format and described on his website [link]. This gives better compression and has been used in the ZX81 version to allow more levels to be added. Given that David planned to back-port his new compression algorithm to the ZX Spectrum, I decided to adopt the GIF-inspired approach for the Ace.
On the Ace version of Tut-tut, the logic for drawing a level is encoded in a word called DRAWLEVEL. Using Forth is an advantage here, as it excels at integer arithmetic, which is fundamental to how the encoding works. The only complication, for the Ace version, comes because I needed to remap the character values encoded in the (ZX81) level data onto the correct Ace character codes. For example, in David’s level encoding, the four sliding walls are represented by values 5, 6, 7, and 8. For the Ace version, I need to map these onto inverse-video ASCII characters 177, 178, 179, and 180. The same is true for the keys, gems, bracelets, and so on. This remapping of the character encoding represents the majority of the work of DRAWLEVEL, as you can see if you look at the source code.
As well as level data, Tut-tut also contains a reasonable amount of text for the instructions and splash screen, plus user-defined graphics. I also encoded these into two other binary code blocks, called MESSAGES and CHARSET, respectively. CHARSET includes two sets of graphics. There are stylised versions of capital letters that overwrite the default bitmaps for these letters, the same as on the ZX Spectrum version, and a set of objects, held in character code 1—14 (except character 13, which is reserved for carriage return).
Otherwise, the port to Ace Forth was relatively straightforward (accepting I needed to brush up on my Forth skills). I tried to follow good Forth programming practice and to keep the most important game data (the position of the player plus temporary variables) on the stack. This, and the fact that the state of the level is kept in the display memory, means there are relatively few variables needed: for score, air, keys, mummy locations, and a couple of useful flags to help in quickly exiting from the depths of program loops.
Some words involve a fair amount of stack acrobatics, which is a common trait of Forth programs. A particularly complex stack is required for the word CHECKLOCK (which moves a sliding wall, if possible). At one point, CHECKLOCK has a stack depth of 14 numbers, to hold the various permutations of player moving a sliding wall, not having the right key, and/ or a sliding wall being unable to move because of a blocking object behind it.
The word MOVEMUMMY also descends into some scary stack manipulation when the mummy needs to change direction. What was a relatively simple logic in the BASIC version, to make the mummy follow the player, proved particularly challenging in Forth, because I tried to avoid using variables as much as possible. MOVEMUMMY is the element of the program that I most struggled with, spending a good few hours debugging mummies that wandered off the screen or worse still teleported into other parts of the Ace’s memory, typically causing it to crash.
Talking about debugging, this was one of my bugbears with Ace Forth. The programming environment on the Ace is not typical for Forth. Most contemporary versions of Forth required the programmer to enter program source code into screens, which correspond to space reservation on disk (or tape). Manipulating screens was often a clumsy process, though it did mean the programmer could access and change any part of the program at any time.
Instead, on the Ace, you interactively develop the dictionary using : (colon), EDIT, and REDEFINE, creating the new words that make up your program in the active dictionary. If you need to fix a bug or change a word, you must first EDIT the word, which creates a second copy of the word at the top of the dictionary. Then, to get rid of the old version of the word and update any references to the old definition, you must remember to REDEFINE the word, otherwise you can quickly end up with confused dictionaries with multiple versions of a word in use. Because the dictionary is a stack of words, if you forget to REDEFINE a word after changing it, and then define further words, you end up trapped in a situation where you cannot remove the out-of-date version of the word nor can you update the definition of any other words that link to that out-of-date version. The only work around is to FORGET everything that you did afterwards and then re-enter the lost words. On my first attempt at Tut-tut, I fell into this trap on several occasions, and ended up with a hopelessly corrupted dictionary with stale links that made the game unstable.
Eventually, it became clear I needed to start again, from scratch. This was not all bad, as it gave me the opportunity to fix some wrong decisions I had made in that first attempt. I suspect that when writing a program on the Ace, this was a relatively common requirement. Unless you have a very thorough design, the first attempt at a program was likely to end up as a prototype, because once you had moved on from a word definition, you could not go back.
Debugging is not a strong point for Ace Forth (nor Forth, in general). The common trick from the 1980s (because no one does that now!) of adding print statements at key points in a program is slightly more tricky in Forth, as you have to make sure not to affect the state of the stack. The Ace User Guide has a useful word, named .S, which prints out a full copy of the stack without affecting it. I took .S and extended it a little, so that the stack is printed on the first line of the display (a line that is not used in Tut-tut):
: .S ( -- ) ( PRINT STACK )
15419 @ HERE 12 + ( FIND THE TOP AND BOTTOM OF THE STACK )
OVER OVER – ( IF TOP = BOTTOM, WE ARE DONE )
IF
DO
I @ . 2
+LOOP
ELSE
DROP DROP
THEN
;
: .T ( PRINT STACK ON ROW 0 )
0 0 AT 32 SPACES ( CLEAR ANY PREVIOUS TEXT )
0 0 AT .S
;
Otherwise, debugging typically meant studying the source code and manually tracking the changes to the state of the stack after each line. It was sometimes quite laborious; though I noticed, as the game developed, I tended to make fewer mistakes, so suspect my Forth competence was growing. I also found useful tips by looking at other people’s code, especially some of the old magazine listings archived on www.jupiter-ace.co.uk, as well as the Ace ROM disassembly [link].
The full listing of Tut-tut is available on GitHub [link]. There are four files. The main file, called ‘tut-tut.fs’, is the Forth source for all of the words, including constants, arrays, and a small amount of machine code. The other three files contain the level data ‘tut-tut_levels.asm’, the help text ‘tut-tut_messages.asm’, and the user-defined graphics ‘tut-tut_charset.asm’. These need to be assembled using a Z80 assembler, such as Z80ASM [https://savannah.nongnu.org/projects/z80asm], to create binary files that can then be inserted into the memory on an Ace emulator, such as EightyOne; into arrays called GAMELEVELS, MESSAGES, and CHARSET, respectively, which have been pre-allocated appropriately.
The process for inserting the binary blocks is a little involved, so I outline it here for GAMELEVELS.
1. First, assemble the source file ‘tut-tut_levels.asm’ and make sure to write a label file, so you can work out how big the binary block is. Using Z80ASM, the following command would do the trick:
z80asm –L –o tut-tut_levels.bin tut-tut_levels.asm
The block is assembled to address 0x0000, though this is not significant. If you print the labels, you should see a label END, which is used to work out the length of the block. At the time of writing, my test version has three levels and END is reported as 0x017D (or, decimal 381).
2. In your Ace emulator, with your in-progress Tut-tut dictionary loaded, create some space for the game levels, with:
CREATE GAMELEVELS 381 ALLOT
—substituting the right value for the length of the block.
3. Check where GAMELEVELS is located in memory, using
GAMELEVELS .
—and use the address returned as the start point to which you load the block—for example, using [File] [Load Memory Block] on EightyOne.
4. If necessary, remember to:
REDEFINE GAMELEVELS
—if you have a previous version of the array earlier in the dictionary.
I hope you will agree that the Ace version of Tut-tut is a reasonable tribute to David Stephenson’s original and that you will consider attempting to type in the game. I never found a way to automatically output the program from EightOne, so tut-tut.fs has been transcribed by hand. This means I have almost certainly made some mistakes—just like back in the 1980s!
Having written the game, I have come to like Forth a little more, and I have developed a fondness for the Jupiter Ace. Richard and Steven were right that a micro powered by Forth is better able to run software without the need for machine code and I suspect I would indeed have produced more useful programs if I had discovered Forth in the 1980s. I like to think I would have been happy had I owned a Jupiter Ace rather than a ZX Spectrum, when I was younger. However, I suspect I would have been envious of my Commodore- and Spectrum-owning friends and would have missed classic games like Jet Pac and Manic Miner too much.
