Keyboard and Joystick Control
Note: This article was originally written by Jonathan Cauldwell and is reproduced here with permission.
One Key at a Time
Providing that you haven’t disabled or otherwise meddled with the Spectrum’s default interrupt mode the ROM will automatically read the keyboard and update several system variables located at memory location 23552 fifty times per second. The simplest way to check for a keypress is to first load address 23560 with a null value, then interrogate this location until it changes, the result being the ASCII value of the key pressed. This is most useful for those “press any key to continue” situations, for choosing items from a menu and for keyboard input such as high score name entry routines. Such a routine might look like this:
ld hl,23560 ; LAST K system variable. ld (hl),0 ; put null value there. loop ld a,(hl) ; new value of LAST K. cp 0 ; is it still zero? jr z,loop ; yes, so no key pressed. ret ; key was pressed.
Single key-presses are seldom any use for fast action arcade games however, for this we need to detect more than one simultaneous key-press and this is where things get a little trickier. Instead of reading memory addresses we have to read one of eight ports, each of which corresponds to a row of five keys. Of course, most Spectrum models appear to have far more keys than this so where did they all go? Well actually, they don’t. The original Spectrum keyboard layout consisted of just forty keys, arranged in eight groupings or rows of five. In order to access some of the functions it was necessary to press certain combinations of keys together – for example to delete the combination required was CAPS SHIFT and 0 together. Sinclair added these extra keys when the Spectrum Plus came onto the scene in 1985, and they work by simulating the combinations of key-presses required for the original rubber keyed models.
The original keyboard layout was separated into these groupings:
Port Keys 32766 B, N, M, Symbol Shift, Space 49150 H, J, K, L, Enter 57342 Y, U, I, O, P 61438 6, 7, 8, 9, 0 63486 5, 4, 3, 2, 1 64510 T, R, E, W, Q 65022 G, F, D, S, A 65278 V, C, X, Z, Caps Shift
To discover which keys are being pressed we read the appropriate port number, each key in the row being allocated one of the lower five bits d0-d4 (values 1,2,4,8 and 16) where d0 represents the outside key, d4 the innermost. Curiously, each bit is high where it is not pressed, low where it is – the opposite of what you might expect.
To read a row of five keys we simply load the port number into the bc register pair, then perform the instruction in a,(c). As we only need the lowest value bits we can ignore the bits we dont want either with an and 31 or by rotating the bits out of the accumulator into the carry flag using five rra:call c,(address) instructions.
If this is difficult to understand consider the following example:
ld bc,63486 ; keyboard row 1-5/joystick port 2. in a,(c) ; see what keys are pressed. rra ; outermost bit = key 1. push af ; remember the value. call nc,mpl ; it's being pressed, move left. pop af ; restore accumulator. rra ; next bit along (value 2) = key 2. push af ; remember the value. call nc,mpr ; being pressed, so move right. pop af ; restore accumulator. rra ; next bit (value 4) = key 3. push af ; remember the value. call nc,mpd ; being pressed, so move down. pop af ; restore accumulator. rra ; next bit (value 8) reads key 4. call nc,mpu ; it's being pressed, move up.
Sinclair joystick ports 1 and 2 were simply mapped to each of the rows of number keys and you can easily prove this by going into the BASIC editor and using the joystick to type numbers. Port 1 (Interface 2) was mapped to the keys 6,7,8,9 and 0, Port 2 (Interface 1) to keys 1,2,3,4 and 5. To detect joystick input we simply read the port in the same way as reading the keyboard. Sinclair joysticks use ports 63486 (Interface 1/port 2), and 61438 (Interface 2/port 1), bits d0-d4 will give a 0 for pressed, 1 for not pressed.
The popular Kempston joystick format is not mapped to the keyboard and can be read by using port 31 instead. This means we can use a simple in a,(31). Again, bit values d0-d4 are used although this time the bit settings are as you might expect, with a bit set high if the joystick is being applied in a particular direction. The resulting bit values will be 1 for pressed, 0 for not pressed.
; Example joystick control routine. joycon ld bc,31 ; Kempston joystick port. in a,(c) ; read input. and 2 ; check "left" bit. call nz,joyl ; move left. in a,(c) ; read input. and 1 ; test "right" bit. call nz,joyr ; move right. in a,(c) ; read input. and 8 ; check "up" bit. call nz,joyu ; move up. in a,(c) ; read input. and 4 ; check "down" bit. call nz,joyd ; move down. in a,(c) ; read input. and 16 ; try the fire bit. call nz,fire ; fire pressed.
A Simple Game
We can now go one step further and, putting into practice what we have already covered, write the main control section for a basic game. This will form the basis of a simple Centipede variant we will be developing over the next few chapters. We haven’t covered everything needed for such a game yet but we can make a start with a small control loop which allows the player to manipulate a small gun base around the screen. Be warned, this program has no exit to BASIC so make sure you’ve saved a copy of your source code before running it.
; We want a black screen. ld a,71 ; white ink (7) on black paper (0), ; bright (64). ld (23693),a ; set our screen colours. xor a ; quick way to load accumulator with zero. call 8859 ; set permanent border colours. ; Set up the graphics. ld hl,blocks ; address of user-defined graphics data. ld (23675),hl ; make UDGs point to it. ; Okay, let's start the game. call 3503 ; ROM routine - clears screen, opens chan 2. ; Initialise coordinates. ld hl,21+15*256 ; load hl pair with starting coords. ld (plx),hl ; set player coords. call basexy ; set the x and y positions of the player. call splayr ; show player base symbol. ; This is the main loop. mloop equ $ ; Delete the player. call basexy ; set the x and y positions of the player. call wspace ; display space over player. ; Now we've deleted the player we can move him before redisplaying him ; at his new coordinates. ld bc,63486 ; keyboard row 1-5/joystick port 2. in a,(c) ; see what keys are pressed. rra ; outermost bit = key 1. push af ; remember the value. call nc,mpl ; it's being pressed, move left. pop af ; restore accumulator. rra ; next bit along (value 2) = key 2. push af ; remember the value. call nc,mpr ; being pressed, so move right. pop af ; restore accumulator. rra ; next bit (value 4) = key 3. push af ; remember the value. call nc,mpd ; being pressed, so move down. pop af ; restore accumulator. rra ; next bit (value 8) reads key 4. call nc,mpu ; it's being pressed, move up. ; Now he's moved we can redisplay the player. call basexy ; set the x and y positions of the player. call splayr ; show player. halt ; delay. ; Jump back to beginning of main loop. jp mloop ; Move player left. mpl ld hl,ply ; remember, y is the horizontal coord! ld a,(hl) ; what's the current value? and a ; is it zero? ret z ; yes - we can't go any further left. dec (hl) ; subtract 1 from y coordinate. ret ; Move player right. mpr ld hl,ply ; remember, y is the horizontal coord! ld a,(hl) ; what's the current value? cp 31 ; is it at the right edge (31)? ret z ; yes - we can't go any further left. inc (hl) ; add 1 to y coordinate. ret ; Move player up. mpu ld hl,plx ; remember, x is the vertical coord! ld a,(hl) ; what's the current value? cp 4 ; is it at upper limit (4)? ret z ; yes - we can go no further then. dec (hl) ; subtract 1 from x coordinate. ret ; Move player down. mpd ld hl,plx ; remember, x is the vertical coord! ld a,(hl) ; what's the current value? cp 21 ; is it already at the bottom (21)? ret z ; yes - we can't go down any more. inc (hl) ; add 1 to x coordinate. ret ; Set up the x and y coordinates for the player's gunbase position, ; this routine is called prior to display and deletion of gunbase. basexy ld a,22 ; AT code. rst 16 ld a,(plx) ; player vertical coord. rst 16 ; set vertical position of player. ld a,(ply) ; player's horizontal position. rst 16 ; set the horizontal coord. ret ; Show player at current print position. splayr ld a,69 ; cyan ink (5) on black paper (0), ; bright (64). ld (23695),a ; set our temporary screen colours. ld a,144 ; ASCII code for User Defined Graphic 'A'. rst 16 ; draw player. ret wspace ld a,71 ; white ink (7) on black paper (0), ; bright (64). ld (23695),a ; set our temporary screen colours. ld a,32 ; SPACE character. rst 16 ; display space. ret plx defb 0 ; player's x coordinate. ply defb 0 ; player's y coordinate. ; UDG graphics. blocks defb 16,16,56,56,124,124,254,254 ; player base.
Fast, isn’t it? In fact, we’ve slowed the loop down with a halt instruction but it still runs at a speedy 50 frames per second, which is probably a little too fast. Don’t worry, as we add more features to the code it will begin to slow down. If you are feeling confident you might like to try adapting the above program to work with a Kempston joystick. It isn’t difficult, and merely requires changing port 63486 to port 31, and replacing the four subsequent call nc,(address) to call c,(address) (The bits are reversed, remember?)
Redefineable keys are a little more tricky. As you are probably aware, the original Spectrum keyboard was divided into 8 rows of 5 keys each, and by reading the port associated with a particular row of keys, then testing bits d0-d4 we can tell if a particular key is being pressed. If you were to replace ld bc,31 in the code snippet above with ld bc,49150 you could test for the row of keys H to Enter – though that doesn’t make for a convenient redefine keys routine. Thankfully, there is another way of going about it.
We can establish the port required for each row of keys using the formula in the Spectrum manual. Where n is the row number 0-7 the port address will be 254+256*(255-2^n). There’s a ROM routine at address 654 which does a lot of the hard work for us by returning the number of the key pressed in the e register, in the range 0-39. 0-7 correspond to the innermost key of each row in turn (that’s B, H, Y, 6, 5, T, G and V), 8-15 to the next key along in each row up to 39 for the outermost key on the last row – CAPS SHIFT. The shift key status, just for the record, is also returned in d. If no key is pressed then e returns 255.
The ROM routine can only return a single key number which is no good for detecting more than one keypress at a time. To determine whether or not a specific key is being pressed at any time we need to convert the number back into a port and bit, then read that port and check the individual bit for ourselves. There’s a very handy routine I use for the job, and it’s the only routine in my games which I didn’t write myself. Credit for that must go to Stephen Jones, a programmer who used to write excellent articles for the Spectrum Discovery Club many years ago. To use his routine, load the accumulator with the number of the key you wish to test, call ktest, then check the carry flag. If it’s set the key is not being pressed, if there’s no carry then the key is being pressed. If that’s too confusing and seems like the wrong way round, put a ccf instruction just before the ret.
; Mr. Jones' keyboard test routine. ktest ld c,a ; key to test in c. and 7 ; mask bits d0-d2 for row. inc a ; in range 1-8. ld b,a ; place in b. srl c ; divide c by 8, srl c ; to find position within row. srl c ld a,5 ; only 5 keys per row. sub c ; subtract position. ld c,a ; put in c. ld a,254 ; high byte of port to read. ktest0 rrca ; rotate into position. djnz ktest0 ; repeat until we've found relevant row. in a,(254) ; read port (a=high, 254=low). ktest1 rra ; rotate bit out of result. dec c ; loop counter. jp nz,ktest1 ; repeat until bit for position in carry. ret
Simple Text and Graphics
Note: This article was originally written by Jonathan Cauldwell and is reproduced here with permission.
So you’ve read the Z80 documentation, you know how the instructions affect the registers and now you want to put this knowledge to use. Judging by the number of emails I have received asking how to read the keyboard, calculate screen addresses or emit white noise from the beeper it has become clear that there really isn’t much in the way of resources for the new Spectrum programmer. This document, I hope, will grow to fill this void in due course. In its present state it is clearly years from completion, but in publishing the few basic chapters that exist to date I hope it will be of help to other programmers.
The ZX Spectrum was launched in April 1982, and by today’s standards is a primitive machine. In the United Kingdom and a few other countries it was the most popular games machine of the 1980s, and through the joys of emulation many people are enjoying a nostalgic trip back in time with the games of their childhoods. Others are only now discovering the machine for the first time, and some are even taking up the challenge of writing games for this simple little computer. After all, if you can write a decent machine code game for a 1980s computer there probably isn’t much you couldn’t write.
Purists will hate this document, but writing a game isn’t about writing “perfect” Z80 code – as if there were such a thing. A Spectrum game is a substantial undertaking, and you won’t get around to finishing it if you are too obsessed with writing the very best scoring or keyboard reading algorithms. Once you’ve written a routine that works and doesn’t cause problems elsewhere, move on to the next routine. It doesn’t matter if it’s a little messy or inefficient, because the important part is to get the gameplay right. Nobody in his right mind is going to disassemble your code and pick faults with it.
The chapters in this document have been ordered in a way designed to enable the reader to start writing a simple game as soon as possible. Nothing beats the thrill of writing your first full machine-code game, and I have set out this manual in such a way as to cover the very basic minimum requirements for this in the first few chapters. From there we move on to cover more advanced methods which should enable the reader to improve the quality of games he is capable of writing.
Throughout this document a number of assumptions have been made. For a start, it is assumed that the reader is familiar with most Z80 opcodes and what they do. If not there are plenty of guides around which will explain these far better than I could ever do. Learning machine code instructions isn’t difficult, but knowing how to put them together in meaningful ways can be. Familiarity with the load (ld), compare (cp), and conditional jump (jp z / jp c / jp nc) instructions is a good place to start. The rest will fall into place once these are learned.
These days we have the benefit of more sophisticated hardware, and there is no need to develop software on the machine for which it is intended. There are plenty of adequate cross-assemblers around which will allow Spectrum software to be developed on a PC and the binary file produced can then be imported into an emulator – SPIN is a popular emulator which has support for this feature.
For graphics there’s a tool called SevenUp which I use, and can thoroughly recommend. This can convert bitmaps into Spectrum images, and allows the programmer to specify the order in which sprites or other graphics are sorted. Output can be in the form of a binary image, or source code. Another popular program is TommyGun.
Music wise I’d recommend the SoundTracker utility which can be downloaded from the World of Spectrum archives. There’s a separate compiler program you’ll also need. Bear in mind that these are Spectrum programs, not PC tools and need to be run on an emulator.
As editors and cross-compilers go I am not in a position to recommend the best available, because I use an archaic editor and Z80 Macro cross-assembler written in 1985, running in DOS windows. Neither are tools I would recommend to others. If you require advice on which tools might be suitable for you, I suggest you try the World of Spectrum development forums. This friendly community has a wide range of experience and is always willing to help.
Over the many years that I have been writing Spectrum software a number of habits have formed which may seem odd. The way I order my coordinates, for example, does not follow the conventions of mathematics. My machine code programs follow the Sinclair BASIC convention of PRINT AT x,y; where x refers to the number of character cells or pixels from the top of the screen and y is the number of characters or pixels from the left edge. If this seems confusing at first I apologise, but it always seemed a more logical way of ordering things and it just stuck with me. Some of my methodology may seem unusual in places, so where you can devise a better way of doing something by all means go with that instead.
One other thing: commenting your code as you go along is important, if not essential. It can be hellishly difficult trying to find a bug in an uncommented routine you wrote only a few weeks ago. It may seem tedious to have to document every subroutine you write, but it will save development time in the long run. In addition, should you wish to re-use a routine in another game at some point in the future, it will be very easy to rip out the required section and adapt it for your next project.
Other than that, just have fun. If you have any suggestions to make or errors to report, please get in touch.
Jonathan Cauldwell, January 2007.
The first BASIC program that most novice programmers write is usually along these lines:
10 PRINT "Hello World" 20 GOTO 10
Alright, so the text may differ. Your first effort may have said “Dave is ace” or “Rob woz ere”, but let’s face it, displaying text and graphics on screen is probably the most important aspect of writing any computer game and – with the exception of pinball or fruit machines – it is practically impossible to conceive a game without a display. With this in mind let us begin this tutorial with some important display routines in the Spectrum ROM.
So how would we go about converting the above BASIC program to machine code? Well, we can PRINT by using the RST 16 instruction – effectively the same as PRINT CHR$ a – but that merely prints the character held in the accumulator to the current channel. To print a string on screen, we need to call two routines – one to open the upper screen for printing (channel 2), then the second to print the string. The routine at ROM address 5633 will open the channel number we pass in the accumulator, and 8252 will print a string beginning at de with length bc to this channel. Once channel 2 is opened, all printing is sent to the upper screen until we call 5633 with another value to send output elsewhere. Other interesting channels are 1 for the lower screen (like PRINT #1 in BASIC, and we can use this to display on the bottom two lines) and 3 for the ZX Printer.
ld a,2 ; upper screen call 5633 ; open channel loop ld de,string ; address of string ld bc,eostr-string ; length of string to print call 8252 ; print our string jp loop ; repeat until screen is full string defb '(your name) is cool' eostr equ $
Running this listing fills the screen with the text until the scroll? prompt is displayed at the bottom. You will note however, that instead of each line of text appearing on a line of its own as in the BASIC listing, the beginning of each string follows directly on from the end of the previous one which is not exactly what we wanted. To achieve this we need to throw a line ourselves using an ASCII control code. One way of doing this would be to load the accumulator with the code for a new line (13), then use RST 16 to print this code. Another more efficient way is to add this ASCII code to the end of our string thus:
string defb '(your name) is cool' defb 13 eostr equ $
There are a number of ASCII control codes like this which alter the current printing position, colours etc. and experimentation will help you to decide which ones you yourself will find most useful. Here are the main ones I use:
13 NEWLINE sets print position to the beginning of the next line.
16,c INK Sets ink colour to the value of the following byte.
17,c PAPER Sets ink colour to the value of the following byte.
22,x,y AT Sets print x and y coordinates to the values specified in the following two bytes.
Code 22 is particularly handy for setting the coordinates at which a string or graphic character is to be displayed. This example will display an exclamation mark in the bottom right of the screen:
ld a,2 ; upper screen call 5633 ; open channel ld de,string ; address of string ld bc,eostr-string ; length of string to print call 8252 ; print our string ret string defb 22,21,31,'!' eostr equ $
This program goes one step further and animates an asterisk from the bottom to the top of the screen:
ld a,2 ; 2 = upper screen. call 5633 ; open channel. ld a,21 ; row 21 = bottom of screen. ld (xcoord),a ; set initial x coordinate. loop call setxy ; set up our x/y coords. ld a,'*' ; want an asterisk here. rst 16 ; display it. call delay ; want a delay. call setxy ; set up our x/y coords. ld a,32 ; ASCII code for space. rst 16 ; delete old asterisk. call setxy ; set up our x/y coords. ld hl,xcoord ; vertical position. dec (hl) ; move it up one line. ld a,(xcoord) ; where is it now? cp 255 ; past top of screen yet? jr nz,loop ; no, carry on. ret delay ld b,10 ; length of delay. delay0 halt ; wait for an interrupt. djnz delay0 ; loop. ret ; return. setxy ld a,22 ; ASCII control code for AT. rst 16 ; print it. ld a,(xcoord) ; vertical position. rst 16 ; print it. ld a,(ycoord) ; y coordinate. rst 16 ; print it. ret xcoord defb 0 ycoord defb 15
Printing Simple Graphics
Moving asterisks around the screen is all very fine but for even the simplest game we really need to display graphics. Advanced graphics are discussed in later chapters, for now we will only be using simple Space Invader type graphics, and as any BASIC programmer will tell you, the Spectrum has a very simple mechanism for this – the User Defined Graphic, usually abbreviated to UDG.
The Spectrum’s ASCII table contains 21 (19 in 128k mode) user-defined graphics characters, beginning at code 144 and going on up to 164 (162 in 128k mode). In BASIC UDGs are defined by poking data into the UDG area at the top of RAM, but in machine code it makes more sense to change the system variable which points to the memory location at which the UDGs are stored, which is done by changing the two-byte value at address 23675.
We can now modify our moving asterisk program to display a graphic instead with a few changes which are underlined.
ld hl,udgs ; UDGs. ld (23675),hl ; set up UDG system variable. ld a,2 ; 2 = upper screen. call 5633 ; open channel. ld a,21 ; row 21 = bottom of screen. ld (xcoord),a ; set initial x coordinate. loop call setxy ; set up our x/y coords. ld a,144 ; show UDG instead of asterisk. rst 16 ; display it. call delay ; want a delay. call setxy ; set up our x/y coords. ld a,32 ; ASCII code for space. rst 16 ; delete old asterisk. call setxy ; set up our x/y coords. ld hl,xcoord ; vertical position. dec (hl) ; move it up one line. ld a,(xcoord) ; where is it now? cp 255 ; past top of screen yet? jr nz,loop ; no, carry on. ret delay ld b,10 ; length of delay. delay0 halt ; wait for an interrupt. djnz delay0 ; loop. ret ; return. setxy ld a,22 ; ASCII control code for AT. rst 16 ; print it. ld a,(xcoord) ; vertical position. rst 16 ; print it. ld a,(ycoord) ; y coordinate. rst 16 ; print it. ret xcoord defb 0 ycoord defb 15 udgs defb 60,126,219,153 defb 255,255,219,219
As Rolf Harris used to say: “Can you tell what it is yet?”
Of course, there’s no reason why you couldn’t use more than the 21 UDGs if you wished. Simply set up a number of banks of them in memory and point to each one as you need it.
Alternatively, you could redefine the character set instead. This gives a larger range of ASCII characters from 32 (SPACE) to 127 (the copyright symbol). You could even mix text and graphics, redefining the letters and numbers of your font to the style of your choice, then using up the symbols and lowercase letters for aliens, zombies or whatever your game requires. To point to another set we subtract 256 from the address at which the font is placed and place this in the two byte system variable at address 23606. The default Sinclair font for example is located at ROM address 15616, so the system variable at address 23606 points to 15360 when the Spectrum is first switched on.
This code copies the Sinclair ROM font to RAM making it “bolder” as it goes, then sets the system variable to point to it:
ld hl,15616 ; ROM font. ld de,60000 ; address of our font. ld bc,768 ; 96 chars * 8 rows to alter. font1 ld a,(hl) ; get bitmap. rlca ; rotate it left. or (hl) ; combine 2 images. ld (de),a ; write to new font. inc hl ; next byte of old. inc de ; next byte of new. dec bc ; decrement counter. ld a,b ; high byte. or c ; combine with low byte. jr nz,font1 ; repeat until bc=zero. ld hl,60000-256 ; font minus 32*8. ld (23606),hl ; point to new font. ret
For most games it is better to define the player’s score as a string of ASCII digits, although that does mean more work in the scoring routines and makes high score tables a real pain in the backside for an inexperienced assembly language programmer. We will cover this in a later chapter, but for now we’ll use some handy ROM routines to print numbers for us.
There are two ways of printing a number on the screen, the first of which is to make use of the same routine that the ROM uses to print Sinclair BASIC line numbers. For this we simply load the bc register pair with the number we wish to print, then call 6683:
ld bc,(score) call 6683
However, since BASIC line numbers can go only as high as 9999, this has the disadvantage of only being capable of displaying a four digit number. Once the player’s score reaches 10000 other ASCII characters are displayed in place of numbers. Fortunately, there is another method which goes much higher. Instead of calling the line number display routine we can call the routine to place the contents of the bc registers on the calculator stack, then another routine which displays the number at the top of this stack. Don’t worry about what the calculator stack is and what its function is because it’s of little use to an arcade games programmer, but where we can make use of it we will. Just remember that the following three lines will display a number from 0 to 65535 inclusive:
ld bc,(score) call 11563 ; stack number in bc. call 11747 ; display top of calc. stack.
To set the permanent ink, paper, brightness and flash levels we can write directly to the system variable at 23693, then clear the screen with a call to the ROM:
; We want a yellow screen. ld a,49 ; blue ink (1) on yellow paper (6*8). ld (23693),a ; set our screen colours. call 3503 ; clear the screen.
The quickest and simplest way to set the border colour is to write to port 254. The 3 least significant bits of the byte we send determine the colour, so to set the border to red:
ld a,2 ; 2 is the code for red. out (254),a ; write to port 254.
Port 254 also drives the speaker and Mic socket in bits 3 and 4. However, the border effect will only last until your next call to the beeper sound routine in the ROM (more on that later), so a more permanent solution is required. To do this, we simply need to load the accumulator with the colour required and call the ROM routine at 8859. This will change the colour and set the BORDCR system variable (located at address 23624) accordingly. To set a permanent red border we can do this:
ld a,2 ; 2 is the code for red. call 8859 ; set border colour.