Z80 Assembly – Espamática

ZX Spectrum Assembly – Utilities

Juan Antonio Rubio García — Wed, 27 Mar 2024 16:49:44 +0000

This is a compilation of different routines that can be useful to deal with certain aspects of the ZX Spectrum.

The entry will be updated in the future.

Translated with DeepL.

ZX Spectrum model

On more than one occasion we will need to know which model of ZX Spectrum our program is going to run on, 16K, 48K or 128K, and in the latter case if it is in 48K or 128K mode.

The way to get the ZX Spectrum model I’m going to show is based on what Sergio thEpOpE exposed in the Basic ZX Course group on Telegram.

Depending on the value that we find in the memory position 0x4B (75), we can know if it is a 128K model or on the contrary if it is a 16/48K model. If when reading the value of this memory position we get 0x6E (110), the program is running in a 128K model, otherwise it is running in a 16/48K model.

If you are running on a 16/48K ZX Spectrum model, it is interesting to know which one it is, information that can be found at locations 0x5CB4 (23,732) and 0x5CB5 (23,733). In these addresses we will find the total amount of memory: 0x7FFF (32,767) in 16K models or 0xFFFFFF (65,535) in 48K models. As we can see, the second byte (the least significant one) has the same value, changing only the most significant one, which is located at memory location 0x5CB5 (23,733).

If we read the value of this position and get 0x7F (127) we are executing in a 16K model, if we get 0xFF (255) we are executing in a 48K model. For 128K models the value is the same as for 48K models.

If it is running on a 128K ZX Spectrum model, it is possible that it is running in 48K or 128K mode, which we can also find out. First we get the value of the memory location 0x5C3B (23,611), we divide by 16 and the result is divided by 2. If the result of this operation is equal to the integer division of the value of the memory location by 16 and the result is divided by 2, it is running in 48K mode, otherwise in 128K mode.

Pseudocode

IF INT(PEEK(23611)/16)/2 = INT(INT(PEEK(32611)/16/2)
    48K model
ELSE
    128K model
END IF

In other words, if the result of the integer division between the value of memory location 0x5C3B (23,611) and 16 is even, it is in 48K mode, otherwise it is in 128K mode.

In ZX Spectrum assembly we are allowed, with right-hand rotations, to make divisions by powers of 2 (16 = 2^4), so we would have to make four rotations to make the division by 16 and then check if the result is even, bit 0 is zero.

ASM

ld   a, $cc                   ; A = 1100 1100
; We use displacements to perform the division by 16
sra  a                        ; A = A/2 =  0110 0110
sra  a                        ; A = A/4 =  0011 0011
sra  a                        ; A = A/8 =  0001 1001
sra  a                        ; A = A/16 = 0000 1100
; Check if A is even
bit  $00, a
jr   z, isEven                ; If bit 0 is 0, it is even, it skips
isOdd:
; isOdd code
isEven:
; isEven code

If you notice, we have shifted bits 4 to 7 to bits 0 to 3 and bits 4 to 7 have been set to zero, finally checking if bit 0, formerly bit 4, is 0 if it is even or 1 if it is odd. We can save displacements and check bit 4 directly.

Based on what we have seen, the routine to find out on which ZX Spectrum model we are running a program could be the following:

ASM

; ZXModel
;
; Gets the ZX model
;
; Entry:  nothing
;
; Output: BC = ZX model
;              0 = 16K
;              1 = 48K
;              2 = 128K
;              3 = 128K in 48K mode
; Alters the value of the BC and AF registers.
ZXModel:
ld   bc, $00			; BC is used to return the value to BASIC

ld   a, ($4b)           ; A = model address
cp   $6e
jr   z, is128           ; $6E, 128, jump

is16or48:
ld   a, ($5cb5)         ; A = amount of memory, upper part
rla                     ; Rotate to the right to check if it is $BF or $FF
ret  nc                 ; NC = 16K, jump ($BF)
inc  c                  ; C+=1
ret                     ; 48K, jump

is128:
ld   c, $02             ; C = 128K
ld   a, ($5c3b)         ; A = mode address
; IF INT(PEEK 23611/16)/2 = INT(INT(PEEK 23611/16)/2) = 48K.
; Dividing by 16 is like shifting 4 times to the right,
; bit 4 is set to bit 0
; Knowing if it is divisible by two is like knowing if it is even, bit 0 = 0
; It all boils down to evaluating bit 4, if it is 0 it is 48K mode, if it is 1 it is 128K mode
bit  $04, a             ; Bit 4?
ret  nz                 ; !0, 128K mode, exit
inc  c                  ; C+=1
ret                     ; 48K mode

To test this routine, you must compile it and load it, for example, at memory address 0x7D00 (32,000), so that it will run on any ZX Spectrum model or clone. Once the routine is loaded, if you type PRINT USR 32000, the value corresponding to the ZX Spectrum model on which it is running will be printed on the screen.

The value returned by an assembly program to the ZX Spectrum BASIC is done through the BC register.

PAL vs NTSC

Sometimes, we may be interested in knowing if the ZX Spectrum on which our program is running is PAL or NTSC system.

What is the difference?

In PAL system there are 50 interruptions per second, while in NTSC system the number of interruptions per second is 60.

How does it affect us?

It can affect us a lot. If our program relies on interrupts for timing, for example by executing the enemy movement routine every five interrupts, on a PAL system the enemy will move five times per second, while on NTSC it will move six times per second, resulting in faster enemy movement on NTSC than on PAL, which can affect gameplay.

How do we find out the system?

In this case I have relied on Habisoft’s Es.pectrum emulator, which you can download from here.

This wonderful emulator emulates a wide variety of ZX Spectrum models and their clones, so it’s ideal for testing the program I’ve implemented to detect if it’s PAL or NTSC, and it’s also free.

The program is simple, activate the ZX Spectrum interrupts in mode 2 and the first time the interrupt routine is executed it sets swCount to one to indicate that the counter variable in the main loop is being incremented. The second time the interrupt routine is executed it sets swCount to two to indicate that the program should exit. The value of counter is loaded into BC so that it can be obtained from Basic.

In short, the program counts the number of times the main loop is executed between two interrupts. Based on the test results, we could say that NTSC yields values below 100, while PAL yields values above 100.

All this has to be treated with great care, if you look at the results you can see values that are at the limit.

ASM

; Program to find out if it's NTSC or PAL
; Compile: pasmo --name PAL_NTSC --tapbas PAL_NTSC.asm PAL_NTSC.tap
; Once loaded, run PRINT USR 32000 to see the result
; Not compatible with 16K model

; Results of PRINT USR 32768 using emulator Es.pectrum
;
; https://habisoft.com/espectrum/
;
; Sinclair ZX Spectrum:
;       48/48+                  216
;       48 NTSC                  64
;       128                     230
;       48 ar                   ¿?
;       48 se                   215
; Timex:
;       TS 2068                  64
;       TC 2068                 216
;       TC 2048                 216
;       Komputer 2086           216
; Investrónica:
;       48+ es                  215
;       128+ es                 230
;       Inves+                  230
; Amstrad:
;       +2                      230
;       +2 es                   230
;       +2 fr                   230
;       +2 ar                   ¿?
;       +2A 4.0                 230
;       +2A 4.1                 230
;       +2A 4.0 es              230
;       +2A 4.1 es              230
;       +2A ar                  ¿?
;       +3 4.0                  230
;       +3 4.1                  230
;       +3 4.0 es               230
;       +3 4.1 es               230
; Pentagon:
;       Pentagon 128            241
;       Pentagon 512            241
;       Pentagon 1024 SL        227
; ZS Rechearch:
;       Leningrad               184
;       Scorpion ZS-256         151
;       Scorpion ZS-256 Turbo+  215
; Microdigital:
;       Tk90x pt-BR              73
;       Tk90x es-AR             233
;       Tk95  pt-BR              72
;       Tk95  es-AR             233
; ATM:
;       ATM-Turbo               215
;       ATM-Turbo 2+            176
; Otros:
;       Orel BK-08               ¿?
;       Dubna 48K                15
;       HC-91                   230
;       BK-001                  105
;       Foton-Ik03               ¿?
;       Alf TV Game (Elf)        ¿?
;       Vesta IK-30             184
; Mods:
;       +3e                     230
;       +3e es                  230
;       +2e                     230
;       +2e es                  230
;       Pentagon es             241
; Virtuales:
;       Spec256 48K             216
;       Spect256 128K           230
org  $8000

; Input: prepare for interruptions
main:
ld   hl, isr            ; HL = interrupt routine address
ld   ($feff), hl        ; Store in $feff the address
ld   a, $fe             ; of routine isr
ld   i, a               ; I = $fe
im   2                  ; Go to interrupt mode 2

; Loop, waits for swCount to be 1 to start counting
; When swCount is 2, exit loop and end of program
loop:
ld   a, (swCount)       ; A = indicator to know whether to count
or   a                  ; A = 0?
jr   z, loop            ; Z = yes, jump
cp   $02                ; A = 2?
jr   z, exit            ; Z = yes, jump

ld   hl, counter        ; HL = counter address
inc  (hl)               ; Counter+=1

jr   loop               ; Loop

; Exit from the programme
; Sets interrupts to mode 1
; Sets the counter to BC so that it can be retrieved
; from BASIC
exit:
im   1                  ; Go to interrupt mode 1
ld   b, $00
ld   a, (counter)
ld   c, a               ; BC = counter, to return the result
ret                     ; Back to BASIC

; Interruptions routine
; At each interrupt it increments swCount
isr:
push hl                 ; Preserves HL

ld   hl, swCount
inc  (hl)               ; Increases the indicator to know if counting

pop  hl                 ; Retrieves HL

ei                      ; Enables interruptions
ret                     ; Exit

; Vars
swCount:                ; Indicator to know whether to count
db $00
counter:                ; Counter
db $00

Downloads

ZX Spectrum screen

Juan Antonio Rubio García — Wed, 13 Dec 2023 07:19:19 +0000

Screen layout

In this chapter we are going to talk about the screen layout of the ZX Spectrum.

Translated with DeepL.

ZX Spectrum graphic area

The screen of the ZX Spectrum has a resolution of 256*192 pixels, or what is the same 32 columns and 192 scanlines. With each byte we can configure 8 pixels, those at one will have the color of the ink (INK) and those at zero the color of the background (PAPER); 256 pixels / 8 pixels per byte = 32 columns. The graphic area occupies 6,144 bytes ($1800) and starts at memory address 16,384 ($4000).

One of the peculiarities of the ZX Spectrum is the way the graphic area is distributed. Each character consists of 64 pixels, or 8×8 pixels. Each line of the character is called a scanline. If we paint on the first scanline of a character and then add 32 to the memory position, the logic tells us that we are on the next scanline of the character, but it is not so because we are actually on the first scanline of the character just below the one we are on.

If we paint position $4000, the first byte of the screen, and then we want to paint in the first scanline of row 8 of the screen, the logic says that we would only have to add 8 times 32 ($20) to position $4000, so the first scanline of the first character of row 8 would be in position $4100. But this is not the case since position $4100 corresponds to the second scanline of the first character on the screen.

This behavior is due to the fact that the ZX Spectrum screen is divided into thirds. Each of the thirds has 8 rows and each of the rows has 8 scanlines. The first third goes from memory location $4000 to $47FF, the second third from $4800 to $4FFF and the third third third from $5000 to $57FF.

Although this may seem strange at first, when you see the composition that the bytes take when making up a memory location, it all makes sense. The composition of the bytes is as follows:

010T TSSS RRRC CCCC

Where 010 is always fixed, TT represents the third (from 0 to 2), SSS represents the scanline within the character (from 0 to 7), RRR represents the row within the third (from 0 to 7) and CCCCCC represents the column (from 0 to 31).

If we look at the row, from 0 to 23, bits 0, 1 and 3 always indicate the row within the third, and bits 4 and 5 the third, so TTRRR is equivalent to the line in character coordinates (from 0 to 23).

Row 0:  0000 0000 Row 0 of third 0
Row 7:  0000 0111 Row 7 of third 0
Row 8:  0000 1000 Row 0 of third 1
Row 15: 0000 1111 Row 7 of third 1
Row 16: 0001 0000 Row 0 of third 2
Row 23: 0001 0111 Row 7 of third 2

To see all of the above, let’s perform a simple example that fills the bytes of the first column with a simple $AA pattern (1001 1001).

ASM

org  $8000
ld   hl, $4000    ; HL = VideoRAM start address
ld   bc, $20      ; BC = value to be added to move to the next character
ld   a, $08       ; A = to draw the first scanline of the first third of the first third
loop:
ld   (hl), $aa    ; Load on screen the pattern 10011001
add  hl, bc       ; Advances HL to the next row
dec  a            ; Decrease A
jr   nz, loop     ; Loop until A reaches 0
ret               ; Back to Basic
end  $8000

If we run the program, it draws the pattern $AA (10101010) in the first scanline of the first 8 rows.

To see the ZX Spectrum screen layout, just change the LD A line, $08 and load multiples of $08; $08, $10, $18, $20, $28, $30, $38, $40, $40, $48….

Until we reach $48, we will not see how the first scanline of the 8 rows of the second third is painted.

ZX Spectrum attributes area

Following the graphic area (pixels) is the attribute area, which runs from address 22,528 ($5800) to address 23,295 ($5AFF), with a length of 768 ($300) bytes.

Each byte in the attribute area sets the attributes of a character (8×8 pixels), which is the reason for the famous attribute clash.

The format of each byte of the attribute area is as follows:

FBPPPIII

Where F is FLASH, B = BRIGHT, P = PAPER and I = INK.

In the case of the attributes area the distribution is linear, so if we are in the byte of the attributes of column 0, row 0 of the screen and add 32 we are in the attributes of column 0, row 1.

The composition of the memory addresses of the attribute area is as follows:

0101 10TT RRRC CCCC

Where 0101 10 is always fixed, TT represents the third (from 0 to 2), RRR represents the row within the third (from 0 to 7) and CCCCC represents the column (from 0 to 31). Again TTRRR is equivalent to the row in character coordinates (from 0 to 23).

Routines

From here, we are going to see routines that can help you when working with the ZX Spectrum screen. Keep in mind that these routines do not control if the coordinates are outside the screen area.

Memory address from character coordinates

The CharCoord2PointerHR routine takes character coordinates and returns the corresponding memory address.

ASM

; ----------------------------------------------------------------
; CharCoord2PointerHR: Gets the memory address
; corresponding to the specified character coordinates. 
; 
; Entrada: B -> Y-coordinate (0 a 23).
;          C -> X-coordinate (0 a 31).
; 
; Salida: HL -> Memory address corresponding to the
;               coordinates (010T TSSS RRRC CCCC). 
;
; Alters the value of AF and HL registers.
; ----------------------------------------------------------------- 
CharCoord2PointerHR:
ld	a, b      ; A = row. Bits 0, 1 and 2 row. Bits 3 and 4 third.
and $18       ; It stays with the third, 0001 1000. 
              ; Scanline always 0.
or 	$40       ; Add fixed part, 0100 0000.
ld 	h, a      ; H = A. High part of calculated direction.
ld 	a, b      ; A = row.
and $07       ; It stays with the row inside the third.
rrca
rrca
rrca          ; Rotate three times to pass value to bits 5, 6 and 7.Rotate three times to pass value to bits 5, 6 and 7.
or 	c         ; Add column.
ld 	l, a      ; L = A. Lower part of calculated direction.
ret

To test this routine we can pass it positions and then load a pattern at the returned address to see where it draws.

ASM

org $8000

ld b, $10                     ; Load in B the row.
ld c, $10                     ; Load in C the column.
call CharCoord2PointerHR      ; Calculates memory location.
ld (hl), $ff                  ; Activates all pixels in the
                              ; memory location.

inc b                         ; Increases row.
inc c                         ; Increases column.
call CharCoord2PointerHR      ; Calculates memory location.
ld (hl), $ff                  ; Activates all pixels in the
                              ; memory location.

inc b                         ; Increases row.
dec c                         ; Increases column.
call CharCoord2PointerHR      ; Calculates memory location.
ld (hl), $ff                  ; Activates all pixels in the
                              ; memory location.

ret

end	 $8000

Character coordinate from memory address

The PointerHR2CharCoord routine takes a memory address and returns the corresponding character coordinates.

ASM

; ---------------------------------------------------------------- 
; PointerHR2CharCoord: Obtiene las coordenadas de carácter
; correspondientes a la dirección de memoria especificada.
;
; Entrada: HL -> Memory pointer. 010T TSSS RRRC CCCC.
;
; Salida: B -> Y-coordinate (0 a 23).
;         C -> X-coordinate (0 a 31).
;
; Alters the value of AF and BC registers.  
; ---------------------------------------------------------------- 
PointerHR2CharCoord: 
ld a, h     ; A = upper part of memory address. 010T TSSS.
and $18     ; Keeps the third. Bits 4 and 5 of the Y coordinate.
            ; Scanline always at 0, they are character coordinates.
ld b, a     ; B = A.

ld a, l     ; A = lower part of the memory address. RRRC CCCC.
and $e0     ; It stays with the row inside the third.
rrca
rrca
rrca        ; Rotate three times to pass value to bits 0, 1 and 3.
or b        ; Add bits 4 and 5.
ld b, a     ; B = A. Calculated Y-coordinate.

ld a, l     ; A = lower part of the memory address. RRRC CCCC.
and $1f     ; It keeps the column.
ld c, a     ; C = A. Calculated X-coordinate.

ret

Next row memory address

The PointerHRNextLine routine takes a memory address and returns the memory address corresponding to the next row.

ASM

; ----------------------------------------------------------------
; PointerHRNextLine: gets the memory address
; corresponding to the next row.
;
; Entrada: HL -> Current address. 010T TSSS RRRC CCCC.
;
; Salida: HL -> Dirección de la fila siguiente.
;               010T TSSS RRRC CCCC.
;
; Alters the value of AF and HL registers.
; ---------------------------------------------------------------- 
PointerHRNextLine:
ld a, l     ; A = lower part of the address. RRRC CCCC.
add a, $20  ; Add one line (RRRC CCCC + 0010 0000).
ld l, a     ; L = A.
ret nc      ; If there is no carry, the row follows between 0 
            ; and 7, it exits.

; There is carry-over, the third of the screen has to be changed.
ld a, h     ; A = upper part of memory address. 010T TSSS.
add a, $08  ; Add one third (010T TSSS + 0000 1000).
ld h, a     ; H = A.

ret

Previous row memory address

The PointerHRPreviousLine routine takes a memory address and returns the memory address corresponding to the previous row.

ASM

; ----------------------------------------------------------------
; PointerHRPreviousLine: gets the memory address
; corresponding to the previous row.
;
; Entrada: HL -> Current address. 010T TSSS RRRC CCCC.
;
; Salida: HL -> Dirección de la fila anterior.
;               010T TSSS RRRC CCCC.
;
; Alters the value of AF and HL registers.
; ---------------------------------------------------------------- 
PointerHRPreviousLine:
ld a, l     ; A = lower part of the address. RRRC CCCC.
and $e0     ; It keeps the row part (1110 0000).
jr z, PointerHRPreviousLine_continue   ; If line is 0,
                                       ; change of third.

; No change of third.
ld a, l     ; A = lower part of the address, RRRC CCCC.
sub $20     ; Subtract one row (RRRC CCCC - 0010 0000).
ld l, a     ; L = A. Calculated address.

ret

PointerHRPreviousLine_continue:
; It is necessary to change the third party.
ld a, l     ; A = lower part of the address. RRRC CCCC.
or $e0      ; Set the row to 7 (RRRC CCCC or 1110 0000).
ld l, a     ; L = A. Lower part of the calculated address.

ld a, h     ; A = upper part of the address. 010T TSSS.
sub $08     ; Subtract one third (010T TSSS - 0000 1000).
ld h, a     ; H = A. Upper part of the calculated address.

ret

Next scanline

The PointerHRNextScanLine routine takes a memory address and returns the address of the next scanline.

ASM

; ----------------------------------------------------------------
; PointerHRNextScanLine: gets the memory address
; corresponding to the next scanline.
;
; Entrada: HL -> current address. 010T TSSS RRRC CCCC.
;
; Salida: HL -> address of the next scanline.
;               010T TSSS RRRC CCCC.
;
; Alters the value of AF and HL registers.
; ---------------------------------------------------------------- 
PointerHRNextScanLine:
ld a, h     ; A = upper part of the address. 010T TSSS.
and $07     ; Keeps the scanline.
cp $07      ; Check if scanline is 7.
jr z, PointerHRNextScanLine_continue     ; Yes, change of line.

; Scanline is not 7.
inc h       ; Increases the scanline by 1 and exits.

ret

PointerHRNextScanLine_continue:
; The row must be changed.
ld a, l     ; A = lower part of the address. RRRC CCCC.
add a, $20  ; Add one line (RRRC CCCC + 0010 0000).
ld l, a     ; L = A.
ld a, h     ; A = upper part of the address. 010T TSSS.
jr nc, PointerHRNextScanLine_end  ; If there is no carriage, skip
                                  ; to finish the calculation.

; There is carriage, it is necessary to change the third party.
add a, $08  ; Add one to the third (010T TSSS + 0000 1000).

PointerHRNextScanLine_end:
and $f8     ; Keeps the fixed part and the third part.
            ; Set the scanline to 0.
ld h, a     ; H = A. Calculated address.

ret

To test the routine, let’s use a small program to see how it draws. Contrary to what we saw in the first example, now we paint a scanline followed by the one right behind it.

ASM

org $8000

ld hl, $4000    ; HL = VideoRAM start address.
ld b, $08       ; B = to draw 8 scanlines.

loop:
ld (hl), $aa    ; Loads the $AA pattern on screen.
call PointerHRNextScanLine  ; Advances to next scanline.
djnz loop       ; Loop until B reaches 0.

ret

end	 $8000

If we run the program, it draws the $AA pattern on the first character. The first example did it on the first scanline of the first 8 rows.

As we did in the first example, we can load multiples of $08 in B to see how the program is drawing; $08, $10, $18, $20, $28, $30, $38, $40, $48….

Previous Scanline

The PointerHRPreviousScanLine routine takes a memory address and returns the memory address corresponding to the previous scanline.

ASM

; ----------------------------------------------------------------
; PointerHRPreviousScanLine: gets the memory address
; corresponding to the previous scanline.
;
; Entrada: HL -> current address. 010T TSSS RRRC CCCC.
;
; Salida: HL -> address of previous scanline.
;               010T TSSS RRRC CCCC.
;
; Alters the value of AF and HL registers.
; ---------------------------------------------------------------- 
PointerHRPreviousScanLine:
ld a, h     ; A = upper part of the address. 010T TSSS.
and $07     ; Keeps the scanline.
or a        ; Check if it is at 0.
jr z, PointerHRPreviousScanLine_continue  ; Yes, change line.

; No change of line.
dec h       ; Decrements the scanline and exits.

ret

PointerHRPreviousScanLine_continue:
ld a, l     ; A = lower part of the address. RRRC CCCC.
and $e0     ; Keeps the row part.
or a        ; Check if it is at 0.
jr z, PointerHRPreviousScanLine_change  ; Yes, change third.

; No need to change third.
ld a, l     ; A = lower part of the address. RRRC CCCC.
sub $20     ; Subtract one row, (RRRC CCCC - 0010 0000).
ld l, a     ; L = A.
jr PointerHRPreviousScanLine_end  ; Skip to end of calculation.

PointerHRPreviousScanLine_change:
; Need to change third.
ld a, l     ; A = lower part of the address. RRRC CCCC.
or $e0      ; Sets the line to 7.
ld l, a     ; L = A.

ld a, h     ; A = upper part of the address. 010T TSSS.
sub $08     ; Subtract one to the third.
ld h, a     ; H = A.

PointerHRPreviousScanLine_end:
ld a, h     ; A = upper part of the address. 010T TSSS.
and $F8     ; Keeps the fixed part and the third part.
or $07      ; Set the scanline to 7.
ld h, a     ; H = A.

ret

And in order to test the routine, another simple program.

ASM

org $8000

ld hl, $57ff    ; HL = VideoRAM end address.
ld b, $08       ; B = to draw 8 scanlines.

loop:
ld (hl), $aa    ; Loads the $AA pattern on the screen.
call PointerHRPreviousScanLine  ; Back to previous scanline.
djnz loop       ; Loop until B reaches 0.

ret

end	 $8000

Attribute address from character coordinates

The CharCoord2PointerAttr routine takes character coordinates and gets the corresponding attribute memory address.

ASM

; ----------------------------------------------------------------
; CharCoord2PointerAttr: takes character coordinates and obtains
; the memory address of the corresponding attribute.
;
; Entrada: B -> Y-coordinate
;          C -> X-coordinate
;
; Salida: HL -> Attribute memory address.
;               0101 10TT RRRC CCCC.
;
; Alters the value of AF and HL registers.
; ---------------------------------------------------------------- 
CharCoord2PointerAttr:
ld   a, b    ; Load row in A
and  $18     ; Keeps the third bits
rrca
rrca
rrca         ; Pass them to bits 0 and 1
or   $58     ; Adds the fixed bits of the high part of the address
ld   h, a    ; H = 0101 10TT
ld   a, b    ; Load row in A
and  $07     ; Keeps the bits of the row
rrca
rrca
rrca         ; Pass them to bits 5, 6, and 7
or   c       ; Adds the bits of the column
ld   l, a    ; L = RRRC CCCC

ret          ; HL = 0101 10TT RRRC CCCC (attribute address)

Social networks can be wonderful; NathanielSalis made me see that in this routine we can save bytes and clock cycles by dispensing with three rotations. The code would look like this:

ASM

; ----------------------------------------------------------------
; CharCoord2PointerAttr: takes character coordinates and obtains
; the memory address of the corresponding attribute.
;
; Entrada: B -> Y-coordinate
;          C -> X-coordinate
;
; Salida: HL -> Attribute memory address.
;               0101 10TT RRRC CCCC.
;
; Alters the value of AF and HL registers.
; ---------------------------------------------------------------- 
CharCoord2PointerAttr:
ld   a, b    ; Load row in A
; Before keeping the bits of the third, we carry out the rotations
rrca
rrca         ; Passes the bits of the third to bits 0 and 1
rrca         ; and those of the row to bits 5, 6 and 7
ld   l, a    ; Load the result in L
and  $03     ; A = bits of the third
or   $58     ; Adds the fixed bits of the high part of the address
ld   h, a    ; H = 0101 10TT
ld   a, l    ; A = row in bits 5, 6 and 7 and third in bits 0 and 1
and  $e0     ; Keeps the bits of the line
or   c       ; Adds the bits of the column
ld   l, a    ; L = RRRC CCCC

ret          ; HL = 0101 10TT RRRC CCCC (attribute address)

The first version of the routine occupies 18 bytes and takes 75 cycles to execute, while the second occupies 16 bytes and takes 67 cycles to execute, so we save two bytes and 8 cycles.

Character coordinates from attribute address

The PointerAttr2CharCoord routine takes a memory address of an attribute and returns the corresponding character coordinates.

ASM

; ----------------------------------------------------------------
; PointerAttr2CharCoord: takes an attribute memory address 
; and returns the corresponding character coordinates.
;
; Entrada: HL -> Attribute memory address.
;                0101 10TT RRRC CCCC.
;
; Salida:   B -> Y-coordinate
;           C -> X-coordinate
;
; Alters the value of AF and HL registers.
; ---------------------------------------------------------------- 
PointerAttr2CharCoord:
ld   a, h    ; Loads the upper part of the address in A
and  $03     ; Keeps the bits of the third
rlca
rlca
rlca         ; Passes them to bits 3 and 4
ld   b, a    ; B = 000TT000
ld   a, l    ; Load the lower part of the address in A
and  $e0     ; Keeps the bits in the row
rlca
rlca
rlca         ; Passes them to bits 0, 1 and 2
or   b       ; Add the third
ld   b, a    ; B = TTCCC (Y-coordinate)
ld   a, l    ; Load the lower part of the address in A
and  $1f     ; It keeps the bits of the column
ld   c, a    ; C = 000CCCCC (X-coordinate)

ret          ; BC = character coordinates

Attribute address from graphic area address

The PointerHR2PointerAttr routine takes a memory address from the graphic area and returns the corresponding attribute memory address.

ASM

; ----------------------------------------------------------------
; PointerHR2PointerAttr: takes a memory address of the graphic area 
; and returns the memory address of the corresponding attribute.
;
; Entrada: HL -> Memory address of the graphic area.
;                010T TSSS RRRC CCCC.
;
; Salida:  HL -> Attribute memory address.
;                0101 10TT RRRC CCCC.
;
; Alters the value of AF and HL registers.
; ---------------------------------------------------------------- 
PointerHR2PointerAttr:
ld   a, h    ; Loads the upper part of the address in A
and  $18     ; Keeps the bits of the third
rrca
rrca
rrca         ; Passes them to bits 0 and 1
or   $58     ; Add the fixed part
ld   h, a    ; A = 010110TT

ret          ; HL = attribute memory address

Graphic area address from attribute address

The PointerAttr2PointerHR routine takes an attribute memory address and returns the memory address of the graphic area corresponding to scanline 0.

ASM

; ----------------------------------------------------------------
; PointerAttr2PointerHR: takes a memory address of attribute
; and returns the memory address of the corresponding graphic area
; to the first scanline.
;
; Entrada: HL -> Attribute memory address.
;                0101 10TT RRRC CCCC.
;
; Salida:  HL -> Memory address of the graphic area.
;                010T TSSS RRRC CCCC.
;
; Alters the value of AF and HL registers.
; ---------------------------------------------------------------- 
PointerAttr2PointerHR:
ld   a, h    ; Loads the upper part of the address in A
and  $03     ; Keeps the bits of the third
rlca
rlca
rlca         ; Passes them to bits 0 and 1
or   $40     ; Add the fixed part
ld   h, a    ; A = 010TT000

ret          ; HL = address of the first scanline

Conclusion

Everything I have put here, I have learned by following the assembler course found at speccy.org and reading the book Código Máquina del ZX-Spectrum by Jesús Alonso Cano.

The routines shown here are the exercises I have done to practice what I have learned.

You can also visit the rest of tutorials:

And remember, if you use it, don’t just copy it, try to understand it and adapt it to your needs.

Z80 Assembly – BCD numbers

Juan Antonio Rubio García — Tue, 17 Oct 2023 09:28:33 +0000

In this chapter of Z80 Assembly, we will learn how to work with numbers larger than 16 bits.

Translated with DeepL.

What are BCD numbers?

BCD numbers are represented in a natural way, as we would see them; the hexadecimal 99 represents the decimal 99.

To achieve this, a byte can represent numbers from 0 to 99 by dividing the byte into two nibbles (4 bits). Each nibble can represent numbers from 0 to 9.

In this way, the hexadecimal 10, which in decimal is 16, in BCD represents the decimal 10. In other words, we see hexadecimal numbers as if they were decimal numbers.

How to use them?

To represent a 10-digit number, 5 bytes are needed. An extra byte can be used to indicate the position of the decimal point, in order to work with decimals. BCD numbers are used to operate with numbers of more than 16 bits.

When operating with BCD numbers, the DAA (Decimal Adjust Accumulator) instruction must be taken into account. DAA makes adjustments to the results of operations with BCD numbers, and works as follows:

Check bits 0, 1, 2 and 3. If they contain a non-BCD digit (greater than 9) or the H flag is set, add or subtract, depending on the operation, 06h (0000 0110b) to the byte.
Check bits 4, 5, 6 and 7. If they contain a non-BCD digit (greater than 9) or the C flag is set, add or subtract, depending on the operation, 60h (0110 0000b) to the byte.

Thus, if we have $09 and add $01, the result is $0A. After executing DAA, the result is $10. After each arithmetic instruction, increment or decrement, DAA must be executed.

ASM

ld  a, $09    ; A = $09
inc a         ; A = $0A
daa           ; A = $10

dec a         ; A = $0F
daa           ; A = $09

add a, $03    ; A = $0C
daa           ; A = $12

sub $03       ; A = $0F
daa           ; A = $09

How do you paint them?

The way to obtain the ASCII code of each nibble (four bits) is relatively simple.

The routine shown below receives a BCD number in register B and displays it on the screen.

ASM

; -----------------------------------------------------
; Prints a BCD number on the screen.
; Input: B -> BCD number to be printed.
; Alters the value of the AF register.
; ----------------------------------------------------- 
PrintBCD:
ld   a, b   ; Loads in A the number to print
and  $f0    ; Keeps the upper nibble
rrca
rrca
rrca
rrca        ; Rotates it four times to move it to the lower nibble
add  a, '0' ; Adds the ASCII of the 0 to get the ASCII of the number
rst  $10    ; Display the number on the screen (ZX Spectrum)
; call $bb5a  ; Display the number on the screen (Amstrad CPC)

ld   a, b   ; Reloads the number to be printed in A
and  $0f    ; Keeps the bottom nibble
add  a, '0' ; Adds the ASCII of the 0 to get the ASCII of the number
rst  $10    ; Display the number on the screen (ZX Spectrum)
; call $bb5a  ; Displays the number on the screen (Amstrad CPC)
 
ret         ; Exits

RST $10, in ZX Spectrum, prints on screen the character corresponding to the Ascii code loaded in register A. CALL $BB5A does the same in Amstrad CPC.

Conclusion

Working with this type of encoding is relatively simple and allows us to work with large numbers. In exchange, we need more bytes and more processing time.

You can also visit the rest of tutorials:

And remember, if you use it, don’t just copy it, try to understand it and adapt it to your needs.

ZX Spectrum Assembly, Tic-Tac-Toe – 0x06 Final adjustment

Juan Antonio Rubio García — Sat, 07 Oct 2023 06:40:45 +0000

In this chapter of ZX Spectrum Assembly, we will make the final adjustments.

We have reached the last chapter. We are going to make a couple of tweaks that, while not entirely necessary, I think might be of interest.

We will add an option in the menu to allow players to select the maximum number of tables they can have.

As for the tables, currently it is necessary to make all possible moves (occupy all the cells) to complete the point, although sometimes we already know that it is not possible to win and it is a table. We are going to implement the detection of tables to detect when it is no longer possible to win and end the point.

We will propose some modifications that can save some bytes and clock cycles.

We will modify the Spectrum’s moves to make it harder to beat.

Finally, we’ll add the loading screen.

Translation by Felipe Monge Corbalán

Tables menu

Currently, the maximum number of tables is declared in the MAXTIES constant in var.asm; we delete it.

Locate MaxPoints and add the new variable for the tables below it:

ASM

MaxTies:     db $05        ; Maximum tables

Locate TitleEspamatica and add the Tables menu option just above it:

ASM

TitleOptionTies:   db $10, INK7, $16, $10, $08, "4. ", $10, INK6
                   defm "Tables"

To make it more symmetrical, we locate Title3InStripe and replace $16, $02, $09 at the end of the line with $16, $04, $09.

In Main.asm, let’s add the handling of the new menu item. Locate menu_Time and replace JR NZ, menu_op two lines down:

ASM

jr   nz, menu_Ties         ; No, skip

Locate menu_TimeDo and three lines down, after JR menu_op, add the handling of the new menu item:

ASM

menu_Ties:  
cp   KEY4                  ; Pushed 4?
jr   nz, menu_op           ; No, loop
ld   a, (MaxTies)          ; A = tables
add  a, $02                ; A += 2
cp   $0a                   ; A < 10?
jr   c, menu_TiesDo        ; Yes, skip
ld   a, $03                ; A = 3
menu_TiesDo:
ld   (MaxTies), a          ; Update tables
jr   menu_op               ; Loop

If the four key has been pressed, the maximum number of tables is increased by two, if it is greater than nine, it is reduced to three and loaded into memory.

Both this range of values and the difference between one value and the other can be modified as required. You can also change it in points and time.

Once we have the maximum number of tables in memory, we need to use them. Find the loop_reset tag, the LD B, MAXTIES line and replace it with the following:

ASM

ld   a, (MaxTies)          ; A = maximum tables
ld   b, a                  ; B = A

All that remains is to print the selected value. In screen.asm, locate PrintOptions and add the following lines just above JP PrintBCD:

ASM

call PrintBCD              ; Paints it
ld   b, INI_TOP-$10        ; B = coord Y
call AT                    ; Position cursor
ld   hl, MaxTies           ; HL = time value

We compile, load the emulator and check that we can now define the number of tables and that the game ends when the number of tables is reached.

Table detection

Currently, in order for boards to be detected, all cells must be occupied and there must be no tic-tac-toe. In reality, it is possible to know if the point will end in a board before the board is full.

We go to game.asm and implement table detection.

To know if there is a possibility of a move, we just need to know if there is any combination left in which the cells are occupied by only one player or by no player at all.

ASM

; -------------------------------------------------------------------
; Check for tables.
; In order to check if there are tables.
;
; Output: Z  -> No tables.
;         NZ -> There are tables.
;
; Alters the value of the AF, BC, DE, HL and IX registers.
; -------------------------------------------------------------------
CheckTies:
ld   b, $f0                ; B = single-player cell mask
ld   c, $0f                ; B = cell mask another player

We load in B the mask to keep the cells occupied by one player, and in C the mask for the other player.

ASM

checkTies_check123:
ld   hl, Grid              ; HL = grid address
ld   a, (hl)               ; A = cell value 1
inc  hl                    ; HL = cell address 2
add  a, (hl)               ; A+= cell value 2
inc  hl                    ; HL = cell address 3
add  a, (hl)               ; A+= cell value 2
ld   d, a                  ; Preserve A in D
and  b                     ; A = cells occupied by a player
ret  z                     ; None, exits
ld   a, d                  ; Retrieves A from D
and  c                     ; A = cells occupied by another player
ret  z                     ; None, exits

We place HL on the grid, add the value of the three cells in A and increment HL to move from one cell to another. We check if there are any cells occupied by a player, and if not, we leave. If so, we check if there are any cells occupied by the other player, and if not, we leave.

The next two checks have the same structure.

ASM

checkTies_check456:
inc  hl                    ; A = cell address 4
ld   a, (hl)               ; A = cell value 4
inc  hl                    ; HL = cell address 5
add  a, (hl)               ; A+= cell value 5
inc  hl                    ; HL = cell address 6
add  a, (hl)               ; A+= cell value 6
ld   d, a                  ; Preserve A in D
and  b                     ; A = cells occupied by a player
ret  z                     ; None, exits
ld   a, d                  ; Retrieves A from D
and  c                     ; A = cells occupied by another player
ret  z                     ; None, exits

checkTies_check789:
inc  hl                    ; A = cell address 7
ld   a, (hl)               ; A = cell value 7
inc  hl                    ; HL = cell address 8
add  a, (hl)               ; A+= cell value 8
inc  hl                    ; HL = cell address 9
add  a, (hl)               ; A+= cell value 9
ld   d, a                  ; Preserve A in D
and  b                     ; A = cells occupied by a player
ret  z                     ; None, exits
ld   a, d                  ; Retrieves A from D
and  c                     ; A = cells occupied by another player
ret  z                     ; None, exits

Look closely at how we go through the cells with HL, this helps us to save a few bytes in an implementation we did earlier.

The following checks cannot be done by changing cells with HL, as they are not numerically contiguous; we use IX.

ASM

checkTies_check147:
ld   ix, Grid-$01          ; IX = address Grid - 1
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$04)           ; A+= cell value 4
add  a, (ix+$07)           ; A+= cell value 7
ld   d, a                  ; Preserve A in D
and  b                     ; A = cells occupied by a player
ret  z                     ; None, exits
ld   a, d                  ; Retrieves A from D
and  c                     ; A = cells occupied by another player
ret  z                     ; None, exits

The rest of the checks follow the same structure.

ASM

checkTies_check258:
ld   a, (ix+$02)           ; A = cell value 2
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$08)           ; A+= cell value 8
ld   d, a                  ; Preserve A in D
and  b                     ; A = cells occupied by a player
ret  z                     ; None, exits
ld   a, d                  ; Retrieves A from D
and  c                     ; A = cells occupied by another player
ret  z                     ; None, exits

checkTies_check369:
ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$06)           ; A+= cell value 6
add  a, (ix+$09)           ; A+= cell value 9
ld   d, a                  ; Preserve A in D
and  b                     ; A = cells occupied by a player
ret  z                     ; None, exits
ld   a, d                  ; Retrieves A from D
and  c                     ; A = cells occupied by another player
ret  z                     ; None, exits

checkTies_check159:
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$09)           ; A+= cell value 9
ld   d, a                  ; Preserve A in D
and  b                     ; A = cells occupied by a player
ret  z                     ; None, exits
ld   a, d                  ; Retrieves A from D
and  c                     ; A = cells occupied by another player
ret  z                     ; None, exits

checkTies_check357:
ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$07)           ; A+= cell value 7
ld   d, a                  ; Preserve A in D
and  b                     ; A = cells occupied by a player
ret  z                     ; None, exits
ld   a, d                  ; Retrieves A from D
and  c                     ; A = cells occupied by another player
ret                        ; Exits with Z in correct state

With this we now have the prediction of whether there will be tables, all that remains is to go to main.asm and use it.

Find loop_tie and three lines down substitute:

ASM

ld   a, $09                ; A = 9
cp   (hl)                  ; Counter = 9?
jr   nz, loop_cont         ; No, skip

By:

ASM

call CheckTies             ; Any possible movement?
jr   z, loop_cont          ; No, skip

We no longer have to wait until the board is full to know if there are checkers or not. We call CheckTies and if there are no boards we continue with the point.

We compile, load the emulator and see the results.

You may see some behaviour that makes you think something is wrong. You see rows one, two, three free, but you know that the Spectrum will occupy one cell, then you another, and so it should mark tables.

The system is predicting, not guessing. Imagine that there are two free cells in a row and it is the turn of the player whose cell is not occupied to move. Well, he will occupy one of the cells, so we already know it is a draw, but imagine that the player rests on his laurels and loses his turn, the other player occupies another cell and there is only one free cell, and it is still not possible to predict draws, if the other player falls asleep again, he loses his turn again and the first player gets three in a row.

We save bytes and clock cycles

We will implement several modifications to save bytes and clock cycles.

The first of these will be in game.asm, on the set of CheckWinner and ZxMove routines, applying the way we have implemented CheckTies to the horizontal lines, the numerically contiguous ones.

Go to the CheckWinner_check tag and find the following lines:

ASM

ld   a, (ix+1)             ; A = cell 1
add  a, (ix+2)             ; A+= cell 2
add  a, (ix+3)             ; A+= cell 3

And we replace them with:

ASM

ld   hl, Grid              ; HL = cell address 1
ld   a, (hl)               ; A = cell value 1
inc  hl                    ; HL = cell address 2
add  a, (hl)               ; A+= cell value 2
inc  hl                    ; HL = cell address 3
add  a, (hl)               ; A+= cell value 3

We locate the lines:

ASM

ld   a, (ix+4)             ; A = cell 4
add  a, (ix+5)             ; A+= cell 5
add  a, (ix+6)             ; A+= cell 6

And we replace them with:

ASM

inc  hl                    ; HL = cell address 4
ld   a, (hl)               ; A = cell value 4
inc  hl                    ; HL = cell address 5
add  a, (hl)               ; A+= cell value 5
inc  hl                    ; HL = cell address 6
add  a, (hl)               ; A+= cell value 6

We locate the lines:

ASM

ld   a, (ix+7)             ; A = cell 7
add  a, (ix+8)             ; A+= cell 8
add  a, (ix+9)             ; A+= cell 9

And we replace them with:

ASM

inc  hl                    ; HL = cell address 7
ld   a, (hl)               ; A = cell value 7
inc  hl                    ; HL = cell address 8
add  a, (hl)               ; A+= cell value 8
inc  hl                    ; HL = cell address 9
add  a, (hl)               ; A+= cell value 9

This part is ready, add the comments of the routine to HL as the affected register.

This is the comparison between the two versions:

Version	Cycles	Bytes
1	688/641	118
2	638/591	111

ZX Spectrum Assembly, Tic-Tac-Toe

As you can see, we save fifty clock cycles and seven bytes. We compile, load into the emulator and see that it still works.

We continue to modify ZxMove, specifically two parts of this routine set. We locate zxMoveToWin_123 and replace it:

ASM

ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$02)           ; A+= cell value 2
add  a, (ix+$03)           ; A+= cell value 3

By:

ASM

ld   hl, Grid              ; HL = cell address 1
ld   a, (hl)               ; A = cell value 1
inc  hl                    ; HL = cell address 2
add  a, (hl)               ; A+= cell value 2
inc  hl                    ; HL = cell address 3
add  a, (hl)               ; A+= cell value 3

Locate zxMoveToWin_456 and replace it:

ASM

ld   a, (ix+$04)           ; A = cell value 4
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$06)           ; A+= cell value 6

By:

ASM

ld   hl, Grid+$03          ; HL = cell address 4
ld   a, (hl)               ; A = cell value 4
inc  hl                    ; HL = cell address 5
add  a, (hl)               ; A+= cell value 5
inc  hl                    ; HL = cell address 6
add  a, (hl)               ; A+= cell value 6

Locate zxMoveToWin_789 and replace it:

ASM

ld   a, (ix+$07)           ; A = cell value 7
add  a, (ix+$08)           ; A+= cell value 8
add  a, (ix+$09)           ; A+= cell value 9

By:

ASM

ld   hl, Grid+$06          ; HL = cell address 7
ld   a, (hl)               ; A = cell value 7
inc  hl                    ; HL = cell address 8
add  a, (hl)               ; A+= cell value 8
inc  hl                    ; HL = cell address 9
add  a, (hl)               ; A+= cell value 9

We have now completed the first part. The main difference with CheckTies and CheckWinner is that although they are numerically contiguous cells, the move from cell three to cell four and from cell six to cell seven is not with INC HL, as ToMove changes the value of HL.

Locate zxMoveAttack_123 and replace it:

ASM

ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$02)           ; A+= cell value 2
add  a, (ix+$03)           ; A+= cell value 3

By:

ASM

ld   hl, Grid              ; HL = cell address 1
ld   a, (hl)               ; A = cell value 1
inc  hl                    ; HL = cell address 2
add  a, (hl)               ; A+= cell value 2
inc  hl                    ; HL = cell address 3
add  a, (hl)               ; A+= cell value 3

Locate zxMoveAttack_456 and replace it:

ASM

ld   a, (ix+$04)           ; A = cell value 4
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$06)           ; A+= cell value 6

By:

ASM

ld   hl, Grid+$03          ; HL = cell address 4
ld   a, (hl)               ; A = cell value 4
inc  hl                    ; HL = cell address 5
add  a, (hl)               ; A+= cell value 5
inc  hl                    ; HL = cell address 6
add  a, (hl)               ; A+= cell value 6

Locate zxMoveAttack_789 and replace it:

ASM

ld   a, (ix+$07)           ; A = cell value 7
add  a, (ix+$08)           ; A+= cell value 8
add  a, (ix+$09)           ; A+= cell value 9

By:

ASM

ld   hl, Grid+$06          ; HL = cell address 7
ld   a, (hl)               ; A = cell value 7
inc  hl                    ; HL = cell address 8
add  a, (hl)               ; A+= cell value 8
inc  hl                    ; HL = cell address 9
add  a, (hl)               ; A+= cell value 9

We make another modification in zxMoveDefence_cornerBlock34 and zxMoveDefence_cornerBlock67 that saves clock cycles but no bytes.

Replacement in zxMoveDefence_cornerBlock34:

ASM

ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$04)           ; A+= cell value 4

By:

ASM

ld   hl, Grid+$02          ; A = cell address 3
ld   a, (hl)               ; A = cell value 3
inc  hl                    ; HL = cell address 4
add  a, (hl)               ; A+= cell value 4

In zxMoveDefence_cornerBlock67 we replace:

ASM

ld   a, (ix+$06)           ; A = cell value 6
add  a, (ix+$07)           ; A+= cell value 7

By:

ASM

ld   hl, Grid+$05          ; A = cell address 6
ld   a, (hl)               ; A = cell value 6
inc  hl                    ; HL = cell address 7
add  a, (hl)               ; A+= cell value 7

The changes in game.asm are done. As I said, add HL as affected registry in the comments of the routine, we forgot it before because the HL registry was already affected by the zxMoveGeneric routine.

This is the comparison between the two versions of ZxMove:

Version	Cycles	Bytes
1	4632/4079	808
2	4532/3979	802

ZX Spectrum Assembly, Tic-Tac-Toe

Version two occupies six bytes less and takes a hundred cycles less than version one, which seems small when we compare it with the bytes saved by CheckWinner with fewer modifications. Remember that there the transition from cell three to cell four and from cell six to cell seven is done with INC HL, which we cannot do here.

The difference between INC HL and LD HL, Grid is four clock cycles and two bytes, and that limits our savings.

Same tile for both players

If we have capacity problems, which we don’t, we can save another handful of bytes by painting the same tile in a different colour for both players.

We go to sprite.asm, comment out the Sprite_P2 definition and put the Sprite_CROSS, Sprite_SLASH and Sprite_MINUS definitions at the top of the file, like this:

ASM

; -------------------------------------------------------------------
; File: sprite.asm
;
; Definition of graphs.
; -------------------------------------------------------------------
; Crosshead Sprite
Sprite_CROSS:
db $18, $18, $18, $ff, $ff, $18, $18, $18 ; $90

; Sprite of the vertical line
Sprite_SLASH:
db $18, $18, $18, $18, $18, $18, $18, $18 ; $91

; Sprite of the horizontal line
Sprite_MINUS:
db $00, $00, $00, $ff, $ff, $00, $00, $00 ; $92

; Player 1 Sprite
Sprite_P1:
db $c0, $e0, $70, $38, $1c, $0e, $07, $03 ; $93
db $03, $07, $0e, $1c, $38, $70, $e0, $c0 ; $94

; ; Player Sprite 2
; Sprite_P2:
; db $03, $0f, $1c, $30, $60, $60, $c0, $c0 ; $95 Up/Left
; db $c0, $f0, $38, $0c, $06, $06, $03, $03 ; $96 Top/Right
; db $c0, $c0, $60, $60, $30, $1c, $0f, $03 ; $97 Down/Left
; db $03, $03, $06, $06, $0c, $38, $f0, $c0 ; $98 Down/Right

Commenting on player two’s sprite not only forces us to change the routine that paints the tiles, it also forces us to change the routine that paints the board as the UDGs change. We have uploaded the board sprites above so that we can only change the board painting routine once, and so that if we decide to repaint the two tiles later, it won’t be affected.

By commenting out Sprite_P2, we save thirty-two bytes. It doesn’t sound like much, but in certain situations it can save us.

We go to var.asm and change the definition of Board_1 and _2 and leave them as they are:

ASM

; Vertical lines of the board.
Board_1:
db $12, $00, $13, $00        
db $20, $20, $20, $20, $91, $20, $20, $20, $20, $91, $20, $20, $20
db $20, $ff

; Horizontal lines of the board.
Board_2:        
db $92, $92, $92, $92, $90, $92, $92, $92, $92, $90, $92, $92, $92
db $92, $ff

We compile, load into the emulator and see the result, which is the mess we made.

That player two’s tile is painted wrong is to be expected, but what about the board? We have changed the position of the sprite definition, but UDG is still pointing to Sprite_P1.

We go to main.asm and under the Main tag we replace:

ASM

ld   hl, Sprite_P1         ; HL = address Sprite_P1

By:

ASM

ld   hl, Sprite_CROSS      ; HL = address Sprite_CROSS

Also change the comment in the line below.

We compile, load it into the emulator and see that the board looks good, but the parts don’t. Don’t worry, this is to be expected.

We are going to modify the routine that paints the tiles so that it does it well, or not, you can leave it as it is; three in a bloody line.

We locate printOXO_X in screen.asm and the lines where the UDG is loaded in A. We add three to the value it loads:

ld a, $90 becomes ld a, $93
ld a, $91 becomes ld a, $94

We locate printOXO_Y and the lines on which the UDG is loaded in A. We add three to the value it loads:

ld a, $92 becomes ld a, $95
ld a, $93 becomes ld a, $96
ld a, $94 becomes ld a, $97
ld a, $95 becomes ld a, $98

So if we decided to paint two different tiles, the circle would be painted.

As we are now in the situation of painting a single tile, we comment on the lines:

ASM

ld   a, $95                ; A = 1st sprite
ld   a, $98                ; A = 4th sprite

And below that we add the line:

ASM

ld   a, $93                ; A = 1st sprite

We comment on the lines:

ASM

ld   a, $96                ; A = 2nd sprite
ld   a, $97                ; A = 3rd sprite

And below that we add the line:

ASM

ld   a, $94                ; A = 2nd sprite

A bit of a mess, isn’t it? Here’s what it looks like:

ASM

printOXO_X:
ld   a, INKPLAYER1         ; A = ink player 1
call INK                   ; Change ink
ld   a, $93                ; A = 1st sprite
rst  $10                   ; Paints it
ld   a, $94                ; A = 2nd sprite
rst  $10                   ; Paints it
dec  b                     ; B = bottom line
call AT                    ; Position cursor
ld   a, $94                ; A = 2nd sprite
rst  $10                   ; Paints it
ld   a, $93                ; A = 2nd sprite
rst  $10                   ; Paints it
ret                        ; Exits

printOXO_Y:
ld   a, INKPLAYER2         ; A = ink player 2
call INK                   ; Change ink
; ld   a, $95                ; A = 1st sprite
ld   a, $93                ; A = 1st sprite
rst  $10                   ; Paints it
; ld   a, $96                ; A = 2nd sprite
ld   a, $94                ; A = 2nd sprite
rst  $10                   ; Paints it
dec  b                     ; B = bottom line
call AT                    ; Position cursor
; ld   a, $97                ; A = 3rd sprite
ld   a, $94                ; A = 2nd sprite
rst  $10                   ; Paints it
; ld   a, $98                ; A = 4th sprite
ld   a, $93                ; A = 1st sprite
rst  $10                   ; Paints it
ret                        ; Exits

So, if we want to redraw the two pieces, in sprite.asm we uncomment Sprite_P2, and in printOXO_Y we alternate the comments on the LD A, … lines.

This will paint the pieces on the board, but not in the information part of the game.

We go back to var.asm and modify player1_figure to look like this:

ASM

player1_figure:   db $16, $04, $00, $90, $91, $0d, $91, $90

And we leave it at that:

ASM

player1_figure:   db $16, $04, $00, $93, $94, $0d, $94, $93

We modify player2_figure so that it now looks like this:

ASM

player2_figure:   db $16, $04, $1b, $92, $93, $16, $05, $1b
                  db $94, $95, $ff

And we leave it at that:

ASM

player2_figure:   db $16, $04, $1b, $93, $94, $16, $05, $1b
                  db $94, $93, $ff

Finally, we add the annotated definition for painting different tiles.

ASM

; player2_figure:   db $16, $04, $1b, $95, $96, $16, $05, $1b
;                   db $97, $98, $ff

We compile, load in the emulator and see the results.

You can paint the same tile in a different colour for both players, or you can paint a different colour for each player. If we were using a black and white TV, there would be no doubt.

If you keep all the changes, we have saved forty-five bytes and one hundred and fifty clock cycles. If you decide to paint different tiles for each player, the byte saving is thirteen bytes.

Spectrum movement

If you have played several games against the Spectrum, you will have worked out how to beat it every time you start the game, because there is at least one move that the Spectrum does not know how to defend, we have not programmed it.

The specific move is to occupy two corner cells: two and six or six and eight. If we occupy cell two, the Spectrum occupies cell five, we move to cell six and the Spectrum moves to cell seven, we move to cell three and we have two tic-tac-toe moves: cells one, two and three and cells three, six and nine.

In game.asm we locate zxMoveAttack_123 and above it we implement the lines that make it impossible to beat the Spectrum with this move.

ASM

; -------------------------------------------------------------------
; Defensive corner movement.
; -------------------------------------------------------------------
zxMoveDefence_corner24:
ld   a, (ix+$02)           ; A = cell value 2
add  a, (ix+$04)           ; A+= cell value 4
cp   b                     ; A = B?
jr   nz, zxMoveDefence_corner26 ; No, skip
ld   c, KEY1               ; C = key 1
call ToMove                ; Move to cell 1
ret  z                     ; If correct, exits

We check if player one has occupied squares two and four, in which case we move to square one if possible.

The rest of the checks follow the same structure.

ASM

zxMoveDefence_corner26:
ld   a, (ix+$02)           ; A = cell value 2
add  a, (ix+$06)           ; A+= cell value 6
cp   b                     ; A = B?
jr   nz, zxMoveDefence_corner84 ; No, skip
ld   c, KEY3               ; C = key 3
call ToMove                ; Move to cell 3
ret  z                     ; If correct, exits
zxMoveDefence_corner84:
ld   a, (ix+$08)           ; A = cell value 8
add  a, (ix+$04)           ; A+= cell value 4
cp   b                     ; A = B?
jr   nz, zxMoveDefence_corner86 ; No, skip
ld   c, KEY7               ; C = key 7
call ToMove                ; Move to cell 3
ret  z                     ; If correct, exits
zxMoveDefence_corner86:
ld   a, (ix+$08)           ; A = cell value 8
add  a, (ix+$06)           ; A+= cell value 6
cp   b                     ; A = B?
jr   nz, zxMoveAttack_123  ; No, skip
ld   c, KEY9               ; C = key 9
call ToMove                ; Move to cell nine
ret  z                     ; If correct, exits

Although the play is in two corners, we cover all four.

Just above zxMoveDefence_cornerBlock2938Cont is the JR NZ line, zxMoveAttack_123, we modify it and leave it as it is:

ASM

jr   nz, zxMoveDefence_corner24 ; No, no mov cross, skip

If you compile and play some games against Spectrum, you will see that it is no longer possible to beat him with this move, but it is still possible to beat him, there are still moves that he does not know how to defend.

Difficulty

Now it is more difficult to beat the Spectrum, we have to wait for him to start the game and depending on the move he makes, we can beat him.

We will add another option to the menu to be able to choose the level of difficulty: one to not cover the play in the corner, two to cover the play in the corner.

In var.asm, after MaxTies, we add the variable for the level of difficulty:

ASM

Level:       db $02        ; Difficulty level

When a new menu item is added, it is appended to the Spamatica line. We move all the menu items up one line, like this:

ASM

TitleOptionStart:  db $10, INK1, $13, $01, $16, $07, $08, "0. "
                   db $10, INK5
                   defm "Start"
TitleOptionPlayer: db $10, INK7, $13, $01, $16, $09, $08, "1. "
                   db $10, INK6
                   defm "Players"
TitleOptionPoint:  db $10, INK7, $16, $0b, $08, "2. ", $10, INK6
                   defm "Points"
TitleOptionTime:   db $10, INK7, $16, $0d, $08, "3. ", $10, INK6
                   defm "Time"
TitleOptionTies:   db $10, INK7, $16, $0f, $08, "4. ", $10, INK6
                   defm "Tables"

After the definition of TitleOptionTies, we add the definition of Difficulty:

ASM

TitleOptionLevel:  db $10, INK7, $16, $11, $08, "5. ", $10, INK6
                   defm "Difficulty"

In screen.asm we find PrintOptions and subtract one from all Y coordinate assignments:

LD B, INI_TOP-$0A go to LD B,INI_TOP-$09
LD B, INI_TOP-$0C go to LD B,INI_TOP-$0B
LD B, INI_TOP-$0E go to LD B,INI_TOP-$0D
LD B, INI_TOP-$10 go to LD B,INI_TOP-$0F

Above JP PrintBCD we add the following lines:

ASM

call PrintBCD              ; Paints it
ld   b, INI_TOP-$11        ; B = coord Y
call AT                    ; Position cursor
ld   hl, Level             ; HL = difficulty value

The final aspect of the routine is as follows:

ASM

; -------------------------------------------------------------------
; Paint the values of the options.
;
; Alters the value of the AF, BC and HL registers.
; -------------------------------------------------------------------
PrintOptions:
ld   a, INK4               ; A = green ink
call INK                   ; Change ink
ld   b, INI_TOP-$09        ; B = coord Y
ld   c, INI_LEFT-$15       ; C = coord X
call AT                    ; Position cursor
ld   hl, MaxPlayers        ; HL = value players
call PrintBCD              ; Paints it
ld   b, INI_TOP-$0b        ; B = coord Y
call AT                    ; Position cursor
ld   hl, MaxPoints         ; HL = points value
call PrintBCD              ; Paints it
ld   b, INI_TOP-$0d        ; B = coord Y
call AT                    ; Position cursor
ld   hl, seconds           ; HL = time value
call PrintBCD              ; Paints it
ld   b, INI_TOP-$0f        ; B = coord Y
call AT                    ; Position cursor
ld   hl, MaxTies           ; HL = time value
call PrintBCD              ; Paints it
ld   b, INI_TOP-$11        ; B = coord Y
call AT                    ; Position cursor
ld   hl, Level             ; HL = difficulty value
jp   PrintBCD              ; Paints it in and exits

In main.asm find menu_Ties and then the line CP KEY4. After this line, replace JR NZ, menu_op with:

ASM

jr   nz, menu_Level        ; No, skip

After menu_TiesDo, after the JR line menu_op, we add the processing lines of the new menu item:

ASM

menu_Level:
cp   KEY5                  ; Pushed 5?
jr   nz, menu_op           ; No, loop
ld   a, (Level)            ; A = difficulty
xor  $03                   ; Alternates between 1 and 2
ld   (Level), a            ; Refresh in memory
jr   menu_op               ; Loop

Finally, in game.asm we locate zxMoveDefence_corner24, and just below it we add:

ASM

ld   a, (Level)            ; A = difficulty
cp   $01                   ; Difficulty = 1?
jr   z, zxMoveAttack_123   ; Yes, jumps

These lines do not check for corner play when the difficulty level is one. Compile and test.

Loading screen

Finally, we’re going to add the loading screen, but what’s the difference when we’ve already seen how it’s done in ZX-Pong and Space Battle? Well, this time we’re going to do it differently, because we’re not going to load the screen into VideoRAM, we’re going to load it into a different memory address and then make it appear all at once.

This is the loading screen you can download from here.

Please be kind, art has never been my thing. I will be happy if you design your own loading screen, which I am sure will be better than this one; it shouldn’t be difficult.

In order to load the loading screen into a memory area and then dump it all at once into VideoRAM, we need to implement the routine to do this in a separate file and compile it separately.

The loading process will do the following:

Load the loader.
Load the routine that dumps the loading screen into memory address 24200.
Load the loading screen at address 24250.
Runs the routine that dumps the loading screen into VideoRAM.
Load the tic-tac-toe routine at address 24200.
Load the interrupt routine at address 32348.
Run the tic-tac-toe program.

The first thing we are going to look at is the loader we developed in Basic to do all of the above.

 10 CLEAR 24200
 20 INK 0: PAPER 4: BORDER 4: CLS
 30 POKE 23610,255: POKE 23739,111
 40 LOAD ""CODE 24200
 50 LOAD ""CODE 24250
 60 RANDOMIZE USR 24200
 70 LOAD ""CODE 24200
 80 LOAD ""CODE 32348
 90 CLS
100 RANDOMIZE USR 24200

Don’t forget to save it with SAVE «OXO» LINE 10.

The next step is to implement the routine that dumps the loading screen into the VideoRAM. We create the file loadScr.asm and add the following lines:

ASM

; -------------------------------------------------------------------
; LoadScr.asm
;
; The loading screen will be loaded in $5eba, and this routine will 
; be passed by the VideoRAM to appear all at once and will then 
; clear the area.
; Where it was initially loaded.
; The cleaning of this memory area is not necessary, but we do it.
; in case we need to debug, not to find code that actually are 
; remnants of the loading screen.
; -------------------------------------------------------------------
org  $5e88                 ; Loading address

ld   hl, $5eba             ; HL = address where the screen is located
ld   de, $4000             ; DE = VideoRAM address
ld   bc, $1b00             ; Screen length
ldir                       ; Flip the screen

ld   hl, $5eba             ; HL = address where the screen is located
ld   de, $5ebb             ; Next address
ld   bc, $1aff             ; Screen length - 1
ld   (hl), $00             ; Clear the first position
ldir                       ; Clean up the rest

ret

The loading screen is loaded at $5eba. This routine copies $1B00 positions (6912 bytes), the entire area of pixels and attributes, from this address into VideoRAM.

Once copied, we clean up the memory area where the screen was loaded; it is not necessary, but if we have to debug, we will avoid residual code that could confuse us.

Now we just need to modify the script we need to compile and generate the final .tap. The Windows version looks like this:

ShellScript

echo off
cls
echo Compiling oxo
pasmo --name OXO --tap main.asm oxo.tap oxo.log
echo Compiling int
pasmo --name INT --tap int.asm int.tap int.log
echo Compiling loadscr
pasmo --name LoadScr --tap loadScr.asm loadscr.tap loadscr.log
echo Generating Tic-Tac-Toe
copy /b /y loader.tap+loadscr.tap+TresEnRayaScr.tap+oxo.tap+int.tap TicTacToe.tap

The Linux version would look like this:

ShellScript

clear
echo Compiling oxo
pasmo --name OXO --tap main.asm oxo.tap oxo.log
echo Compiling int
pasmo --name INT --tap int.asm int.tap int.log
echo Compiling loadscr
pasmo --name LoadScr --tap loadScr.asm loadscr.tap loadscr.log
echo Generating Tic-Tac-Toe
cat loader.tap loadscr.tap TresEnRayaScr.Tap oxo.tap int.tap > TicTacToe.tap

And that is it.

ZX Spectrum Assembly, Tic-Tac-Toe

Thank you very much for joining me on this journey, I hope this is just the beginning, that it has helped you to learn and become passionate about assembly programming for the ZX Spectrum. I will continue to study and learn, and if I can gather more material in the future, I may write another tutorial.

Download the source code from here.

Useful links

ZX Spectrum Assembly, Tic-Tac-Toe by Juan Antonio Rubio García.
Translation by Felipe Monge Corbalán.
This work is licensed to Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0).
Any comments are always welcome.

ZX Spectrum Assembly, Tic-Tac-Toe – 0x05 Me versus the Spectrum

Juan Antonio Rubio García — Fri, 06 Oct 2023 05:05:34 +0000

In this chapter of ZX Spectrum Assembly, we will implement the possibility to play against the Spectrum.

Translation by Felipe Monge Corbalán

Me versus the Spectrum

Once we can play against friends and family, the possibility remains that we may not have anyone to play with, hence the need to be able to play against the Spectrum.

We wrote the bulk of this implementation in game.asm, starting with a routine that generates semi-random numbers between one and nine, so that when the Spectrum starts the game, it does so in a different way.

ASM

; -------------------------------------------------------------------
; Gets a semi-random number between 1 and 9.
;
; Return: A -> Number obtained.
; -------------------------------------------------------------------
GetRandomN:
ld   a, r                  ; A = R
and  $0f                   ; Leave bits 0 to 3
inc  a                     ; A+=1
cp   $0a                   ; A > 9?
ret  c                     ; No, exit
rra                        ; A/=2, because Carry = 0, otherwise SRL A
ret                        ; Exits

GetRandomN gets a semi-random number between one and nine, using register R. In the RRA line, as seen in the comments, we divide A by two because the carry is zero and because we only do it once, otherwise we would have to do it with SRL A. RRA is one byte and takes four clock cycles, SRL A is only twice as long. It is only divided by two if the number obtained is greater than 9.

The part that carries out the movements of the spectrum is very long, as there are several combinations that are evaluated, so we will see it in blocks. However, as there are many similarities between the different blocks, we will only explain the most important ones.

ASM

; -------------------------------------------------------------------
; Moves ZX Spectrum.
;
; Alters the value of the AF, BC and IX registers.
; -------------------------------------------------------------------
ZxMove:
ld   a, (MoveCounter)      ; A = moves
or   a                     ; Movements = 0?
jr   nz, zxMove_center     ; No, skip
call GetRandomN            ; A = number between 1 and 9
add  a, '0'                ; A = ascii code
ld   c, a                  ; C = A
call ToMove                ; Move to cell
ret                        ; Exits
zxMove_center:
cp   $01                   ; Moves > 1?
jr   nz, zxMove_cont       ; Yes, skip
ld   c, KEY5               ; C = key 5
call ToMove                ; Move to cell 5
ret  z                     ; If correct, exits

In this first part we decide if it is the first move of the game, and if so we take a random number between one and nine and move to that cell. If it is the second move, we try to move to cell five (middle). If these conditions are not met, we continue with the checks to see if the spectrum can win or lose.

ASM

zxMove_cont:
ld   ix, Grid-$01          ; IX = dir Grid-1
ld   b, $20                ; B = Spectrum value can earn
call zxMoveToWin_123       ; Move to gain Spectrum
ret  z                     ; If valid, exits
ld   b, $02                ; B = value player 1 can win
call zxMoveToWin_123       ; Move to avoid it
ret  z                     ; If valid, exits
jp   zxMoveDefence_diagonally ; Defensive movements

Remember that the moves of player two, in this case the Spectrum, are signalled in bit four of the cells, so we load $20 into B, which would be the value if there were two cells occupied by the Spectrum in a row.

We call zxMoveToWin_123 so that if Spectrum wins, it makes the move.

If the Spectrum has not won, we load two into B to check if player one has the move to win. We call zxMoveToWin_123 a second time to prevent it from winning.

If none of the above has happened, we go on the defensive.

ASM

; -------------------------------------------------------------------
; Evaluates whether the Spectrum has the movement to win.
; -------------------------------------------------------------------
zxMoveToWin_123:
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$02)           ; A+= cell value 2
add  a, (ix+$03)           ; A+= cell value 3
cp   b                     ; A = B?
jp   nz, zxMoveToWin_456   ; No, skip
; Spectrum can win
ld   c, KEY1               ; C = key 1
call ToMove                ; Move to cell 1
ret  z                     ; If correct, exits
inc  c                     ; C = key 2
call ToMove                ; Move to cell 2
ret  z                     ; If correct, exits
inc  c                     ; C = key 3
call ToMove                ; Move to cell 3
ret                        ; Exits

If the Spectrum occupies two squares, we try to move to square one, if not, to square two and if not, to square three. To go from one square to the next, we increment C, numerically they are contiguous.

The checks for the combinations four, five, six and seven, eight, nine are the same as above.

ASM

zxMoveToWin_456:
ld   a, (ix+$04)           ; A = cell value 4
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$06)           ; A+= cell value 6
cp   b                     ; A = B?
jr   nz, zxMoveToWin_789   ; No, skip
; Spectrum can win
ld   c, KEY4               ; C = key 4
call ToMove                ; Move to cell 4
ret  z                     ; If correct, exits
inc  c                     ; C = key 5
call ToMove                ; Move to cell 5
ret  z                     ; If correct, exits
inc  c                     ; C = key 6
call ToMove                ; Move to cell 6
ret                        ; Sale

zxMoveToWin_789:
ld   a, (ix+$07)           ; A = cell value 7
add  a, (ix+$08)           ; A+= cell value 8
add  a, (ix+$09)           ; A+= cell value 9
cp   b                     ; A = B?
jr   nz, zxMoveToWin_147   ; No, skip
; Spectrum can win
Ld   c, KEY7               ; C = key 7
call ToMove                ; Move to cell 7
ret  z                     ; If correct, exits
inc  c                     ; C = key 8
call ToMove                ; Move to cell 8
ret  z                     ; If correct, exits
inc  c                     ; C = key 9
call ToMove                ; Move to cell 9
ret                        ; Exits

The rest of the tests change slightly.

ASM

zxMoveToWin_147:
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$04)           ; A+= cell value 4
add  a, (ix+$07)           ; A+= cell value 7
cp   b                     ; A=B?
jr   nz, zxMoveToWin_258   ; No, skip
ld   c, KEY1               ; C = key 1
call ToMove                ; Move to cell 1
ret  z                     ; If correct, exits
ld   c, KEY4               ; C = key 4
call ToMove                ; Move to cell 4
ret  z                     ; If correct, exits
ld   c, KEY7               ; C = key 7
call ToMove                ; Move to cell 7
ret                        ; Exits

As the squares are not numerically contiguous, at the end we load each key instead of incrementing C. From here on, all the checks to see if the Spectrum can win or lose are the same.

ASM

zxMoveToWin_258:
ld   a, (ix+$02)           ; A = cell value 2
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$08)           ; A+= cell value 8
cp   b                     ; A=B?
jr   nz, zxMoveToWin_369   ; No, skip
ld   c, KEY2               ; C = key 2
call ToMove                ; Move to cell 2
ret  z                     ; If correct, exits
ld   c, KEY5               ; C = key 5
call ToMove                ; Move to cell 5
ret  z                     ; If correct, exits
ld   c, KEY8               ; C = key 8
call ToMove                ; Move to cell 8
ret                        ; Exits
    
zxMoveToWin_369:
ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$06)           ; A+= cell value 6
add  a, (ix+$09)           ; A+= cell value 9
cp   b                     ; A=B?
jr   nz, zxMoveToWin_159   ; No, skip
ld   c, KEY3               ; C = key 3
call ToMove                ; Move to cell 3
ret  z                     ; If correct, exits
ld   c, KEY6               ; C = key 6
call ToMove                ; Move to cell 6
ret  z                     ; If correct, exits
ld   c, KEY9               ; C = key 9
call ToMove                ; Move to cell 9
ret                        ; Exits
    
zxMoveToWin_159:
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$09)           ; A+= cell value 9
cp   b                     ; A=B?
jr   nz, zxMoveToWin_357   ; No, skip
ld   c, KEY1               ; C = key 1
call ToMove                ; Move to cell 1
ret  z                     ; If correct, exits
ld   c, KEY5               ; C = key 5
call ToMove                ; Move to cell 5
ret  z                     ; If correct, exits
ld   c, KEY9               ; C = key 9
call ToMove                ; Move to cell 9
ret                        ; Exits

zxMoveToWin_357:
ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$07)           ; A+= cell value 7
cp   b                     ; A = B?
ret  nz
ld   c, KEY3               ; C = key 3
call ToMove                ; Move to cell 3
ret  z                     ; If correct, exits
ld   c, KEY5               ; C = key 5
call ToMove                ; Move to cell 5
ret  z                     ; If correct, exits
ld   c, KEY7               ; C = key 7
call ToMove                ; Move to cell 7
ret                        ; Exits

The set of routines zxMoveToWin is used both to know if Spectrum can win and make the move to do so, and to know if Spectrum can lose and make the move to avoid it.

If both player one and Spectrum have no chance of winning, we try to anticipate player one’s move. First we check if the player makes a diagonal move that occupies both vertices, and if so we make a cross block.

ASM

; -------------------------------------------------------------------
; Diagonal defensive movement.
; -------------------------------------------------------------------
zxMoveDefence_diagonally:
; Checks if player 1 has diagonal checkers
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$09)           ; A+= cell value 9
cp   b                     ; A = B?
jr   z, zxMoveDefence_crossBlock ; Yes, mov diagonal, skip
ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$07)           ; A+= cell value 7
cp   b                     ; A = B?
jr   nz, zxMoveDefence_crossBlock1 ; No, skip

zxMoveDefence_crossBlock:
; Cross locking
ld   c, KEY4               ; C = key 4
call ToMove                ; Move to cell 4
ret  z                     ; If correct, exits
ld   c, KEY6               ; C = key 6
call ToMove                ; Move to cell 6
ret  z                     ; If correct, exits
ld   c, KEY2               ; C = key 2
call ToMove                ; Move to cell 2
ret  z                     ; If correct, exits
ld   c, KEY8               ; C = key 8
call ToMove                ; Move to cell 8
ret  z                     ; If correct, exits

Then we check if he has tried a diagonal move with the centre occupied, and if so, depending on which vertex is occupied, we block the vertical.

ASM

; -------------------------------------------------------------------
; Defensive diagonal movement with the centre occupied.
; -------------------------------------------------------------------
zxMoveDefence_crossBlock1:
ld   a, (ix+$05)           ; A = cell value 5
and  $0f                   ; A = player value 1
jr   z, zxMoveDefence_cornerBlock16 ; Z = not occupied, skip
ld   a, (ix+$01)           ; A = cell value 1
and  $0f                   ; A = player value 1
jr   z, zxMoveDefence_crossBlock3 ; Z = not occupied, skip
ld   c, KEY7               ; C = key 7
call ToMove                ; Move to cell 7
ret  z                     ; If correct, exits

zxMoveDefence_crossBlock3:
ld   a, (ix+$03)           ; A = cell value 3
and  $0f                   ; A = player value 1
jr   z, zxMoveDefence_crossBlock7 ; Z = not occupied, skip
ld   c, KEY9               ; C = key 9
call ToMove                ; Move to cell 9
ret  z                     ; If correct, exits

zxMoveDefence_crossBlock7:
ld   a, (ix+$07)           ; A = cell value 7
and  $0f                   ; A = player value 1
jr   z, zxMoveDefence_crossBlock9 ; Z = not occupied, skip
ld   c, KEY1               ; C = key 1
call ToMove                ; Move to cell 1
ret  z                     ; If correct, exits

zxMoveDefence_crossBlock9:
ld   a, (ix+$09)           ; A = cell value 9
and  $0f                   ; A = player value 1
jr   z, zxMoveDefence_cornerBlock16 ; Z = not occupied, skip
ld   c, KEY3               ; C = key 3
call ToMove                ; Move to cell 3
ret  z                     ; If correct, exits

If player one has not attempted a diagonal move, we will see if he has attempted a cross move and try to block it.

ASM

; -------------------------------------------------------------------
; Defensive cross movement.
; -------------------------------------------------------------------
zxMoveDefence_cornerBlock16:
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$06)           ; A+= cell value 6
cp   b                     ; A = B?
jr   nz, zxMoveDefence_cornerBlock34 ; No, no mov cross, skip
ld   c, KEY3               ; C = key 3
call ToMove                ; Move to cell 3
ret  z                     ; If correct, exits

zxMoveDefence_cornerBlock34:
ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$04)           ; A+= cell value 4
cp   b                     ; A = B?
jr   nz, zxMoveDefence_cornerBlock67 ; No, no mov cross, skip
ld   c, KEY1               ; C = key 1
call ToMove                ; Move to cell 1
ret  z                     ; If correct, exits

zxMoveDefence_cornerBlock67:
ld   a, (ix+$06)           ; A = cell value 6
add  a, (ix+$07)           ; A+= cell value 7
cp   b                     ; A = B?
jr   nz, zxMoveDefence_cornerBlock49 ; No, no mov cross, skip
ld   c, KEY9               ; C = key 9
call ToMove                ; Move to cell 9
ret  z                     ; If correct, exits

zxMoveDefence_cornerBlock49:
ld   a, (ix+$04)           ; A = cell value 4
add  a, (ix+$09)           ; A+= cell value 9
cp   b                     ; A = B?
jr   nz, zxMoveDefence_cornerBlock1827 ; No, no mov cross, skip
ld   c, KEY7               ; C = key 7
call ToMove                ; Move to cell 7
ret  z                     ; If correct, exits

zxMoveDefence_cornerBlock1827:
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$08)           ; A+= cell value 8
cp   b                     ; A = B?
jr   z, zxMoveDefence_cornerBlock1827Cont ; Yes, mov cross, block
ld   a, (ix+$02)           ; A = cell value 2
add  a, (ix+$07)           ; A+= Value cell 7
cp   b                     ; A = B?
jr   nz, zxMoveDefence_cornerBlock2938 ; No, no mov cross, skip

zxMoveDefence_cornerBlock1827Cont:
ld   c, KEY4               ; C = key 4
call ToMove                ; Move to cell 4
ret  z                     ; If correct, exits

zxMoveDefence_cornerBlock2938:
ld   a, (ix+$02)           ; A = cell value 2
add  a, (ix+$09)           ; A+= cell value 9
cp   b                     ; A = B?
jr   z, zxMoveDefence_cornerBlock2938Cont ; Yes, mov cross, block
ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$08)           ; A+= cell value 8
cp   b                     ; A = B?
jr   nz, zxMoveAttack_123  ; No, no mov cross, skip

zxMoveDefence_cornerBlock2938Cont:
ld   c, KEY6               ; C = key 6
call ToMove                ; Move to cell 6
ret  z                     ; If correct, exits

If we’ve got this far, we’ve established that Spectrum has no move to win, that player one has no move to win, that player one is in no danger from player one’s diagonal or cross moves; it’s time for Spectrum to go on the attack.

This last part will only be done in the first few moves, as the board fills up we will be more concerned with defending than attacking.

ASM

; -------------------------------------------------------------------
; Horizontal, vertical and diagonal offensive movement.
; -------------------------------------------------------------------
zxMoveAttack_123:
ld   b, $20                ; B = Spectrum value with two boxes
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$02)           ; A+= cell value 2
add  a, (ix+$03)           ; A+= cell value 3
ld   c, a                  ; Preserve A in C
and  $03                   ; A = player 1 cells
jr   nz, zxMoveAttack_456  ; Any? Yes, jump
ld   a, c                  ; Retrieves A
and  $30                   ; A = Spectrum boxes
cp   b                     ; Two busy?
Jr   z, zxMoveAttack_456   ; Yes, jumps
ld   c, KEY1               ; C = key 1
call ToMove                ; Move to cell 1
ret  z                     ; If correct, exits
inc  c                     ; C = key 2
call ToMove                ; Move to cell 2
ret  z                     ; If correct, exits
inc  c                     ; C = key 3
call ToMove                ; Move to cell 3
ret  z                     ; If correct, exits

For the attack, we look for combinations where player one has no cells occupied and the Spectrum has only one.

The rest of the checks are very similar to the previous one.

ASM

zxMoveAttack_456:
ld   a, (ix+$04)           ; A = cell value 4
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$06)           ; A+= cell value 6
ld   c, a                  ; Preserve A in C
and  $03                   ; A = player 1 cells
jr   nz, zxMoveAttack_789  ; Any? Yes, jump
ld   a, c                  ; Retrieves A
and  $30                   ; A = Spectrum boxes
cp   b                     ; Two busy?
jr   z, zxMoveAttack_789   ; Yes, jumps
ld   c, KEY4               ; C = key 4
call ToMove                ; Move to cell 4
ret  z                     ; If correct, exits
inc  c                     ; C = key 5
call ToMove                ; Move to cell 5
ret  z                     ; If correct, exits
inc  c                     ; C = key 6
call ToMove                ; Move to cell 6
ret  z                     ; If correct, exits

zxMoveAttack_789:
ld   a, (ix+$07)           ; A = cell value 7
add  a, (ix+$08)           ; A+= cell value 8
add  a, (ix+$09)           ; A+= cell value 9
ld   c, a                  ; Preserve A in C
and  $03                   ; A = player 1 cells
jr   nz, zxMoveAttack_147  ; Any? Yes, jump
ld   a, c                  ; Retrieves A
and  $30                   ; A = Spectrum boxes
cp   b                     ; Two busy?
jr   z, zxMoveAttack_147   ; Yes, jumps
ld   c, KEY7               ; C = key 7
call ToMove                ; Move to cell 7
ret  z                     ; If correct, exits
inc  c                     ; C = key 8
call ToMove                ; Move to cell 8
ret  z                     ; If correct, exits
inc  c                     ; C = key 9
call ToMove                ; Move to cell 9
ret  z                     ; If correct, exits

zxMoveAttack_147:
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$04)           ; A+= cell value 4
add  a, (ix+$07)           ; A+= cell value 7
ld   c, a                  ; Preserve A in C
and  $03                   ; A = player 1 boxes
jr   nz, zxMoveAttack_258  ; Any? Yes, jump
ld   a, c                  ; Retrieves A
and  $30                   ; A = Spectrum boxes
cp   b                     ; Two busy?
jr   z, zxMoveAttack_258   ; Yes, jumps
ld   c, KEY1               ; C = key 1
call ToMove                ; Move to cell 1
ret  z                     ; If correct, exits
ld   c, KEY4               ; C = key 4
call ToMove                ; Move to cell 4
ret  z                     ; If correct, exits
ld   c, KEY7               ; C = key 7
call ToMove                ; Move to cell 7
ret   z                    ; If correct, exits

zxMoveAttack_258:
ld   a, (ix+$02)           ; A = cell value 2
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$08)           ; A+= cell value 8
ld   c, a                  ; Preserve A in C
and  $03                   ; A = player 1 cells
jr   nz, zxMoveAttack_369  ; Any? Yes, jump
ld   a, c                  ; Retrieves A
and  $30                   ; A = Spectrum boxes
cp   b                     ; Two busy?
jr   z, zxMoveAttack_369   ; Yes, jumps
ld   c, KEY2               ; C = key 2
call ToMove                ; Move to cell 2
ret  z                     ; If correct, exits
ld   c, KEY5               ; C = key 5
call ToMove                ; Move to cell 5
ret  z                     ; If correct, exits
ld   c, KEY8               ; C = key 8
call ToMove                ; Move to cell 8
ret  z                     ; If correct, exits

zxMoveAttack_369:
ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$06)           ; A+= cell value 6
add  a, (ix+$09)           ; A+= cell value 9
ld   c, a                  ; Preserve A in C
and  $03                   ; A = player 1 cells
jr   nz, zxMoveAttack_159  ; Any? Yes, jump
ld   a, c                  ; Retrieves A
and  $30                   ; A = Spectrum boxes
cp   b                     ; Two busy?
Jr   z, zxMoveAttack_159   ; Yes, jumps
ld   c, KEY3               ; C = key 3
call ToMove                ; Move to cell 3
ret  z                     ; If correct, exits
ld   c, KEY6               ; C = key 6
call ToMove                ; Move to cell 6
ret  z                     ; If correct, exits
ld   c, KEY9               ; C = key 9
call ToMove                ; Move to cell 9
ret  z                     ; If correct, exits

zxMoveAttack_159:
ld   a, (ix+$01)           ; A = cell value 1
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$09)           ; A+= cell value 9
ld   c, a                  ; Preserve A in C
and  $03                   ; A = player 1 cells
jr   nz, zxMoveAttack_357  ; Any? Yes, jump
ld   a, c                  ; Retrieves A
and  $30                   ; A = Spectrum boxes
cp   b                     ; Two busy?
Jr   z, zxMoveAttack_357   ; Yes, jumps
Ld   c, KEY1               ; C = key 1
call ToMove                ; Move to cell 1
ret  z                     ; If correct, exits
ld   c, KEY5               ; C = key 5
call ToMove                ; Move to cell 5
ret  z                     ; If correct, exits
ld   c, KEY9               ; C = key 9
call ToMove                ; Move to cell 9
ret  z                     ; If correct, exits

zxMoveAttack_357:
ld   a, (ix+$03)           ; A = cell value 3
add  a, (ix+$05)           ; A+= cell value 5
add  a, (ix+$07)           ; A+= cell value 7
ld   c, a                  ; Preserve A in C
and  $03                   ; A = player 1 cells
jr   nz, zxMoveGeneric     ; Any? Yes, jump
ld   a, c                  ; Retrieves A
and  $30                   ; A = Spectrum boxes
cp   b                     ; Two busy?
jr   z, zxMoveGeneric      ; Yes, skip
ld   c, KEY3               ; C = key 3
call ToMove                ; Move to cell 3
ret  z                     ; If correct, exits
ld   c, KEY5               ; C = key 5
call ToMove                ; Move to cell 5
ret  z                     ; If correct, exits
ld   c, KEY7               ; C = key 7	
call ToMove                ; Move to cell 7
ret  z                     ; If correct, exits

When we arrive here, the Spectrum has not found a place to go and will move to the first free cell.

ASM

; -------------------------------------------------------------------
; Generic movement. 
; If with all of the above, you have not made any movement
; moves to the first free cell.
; -------------------------------------------------------------------
zxMoveGeneric:
ld   c, '1'                ; C = ascii 1 (cell 1)
ld   b, $09                ; B = total cells
ld   a, $00                ; A = empty cell
ld   hl, Grid              ; HL = address 1st cell

zxMoveGeneric_loop:
cp   (hl)                  ; Free cell?
jr   z, zxMoveGeneric_end  ; Yes, skip
inc  c                     ; C = ascii next cell
inc  hl                    ; HL = next cell
djnz zxMoveGeneric_loop    ; Loop until B = 0

zxMoveGeneric_end:
call ToMove                ; Move to free cell
ret                        ; Exits

We have already implemented the way the Spectrum behaves in single player games. It’s not perfect, it has some loopholes and sometimes the Spectrum makes some erratic moves. That’s fine, if we made it perfect we could never beat the Spectrum and nobody likes that.

Now we need to integrate what we have implemented inside the main loop into main.asm.

Find the loop_lostMov tag, and five lines down replace JR Z, loop_keyCont with:

ASM

jr   z, loop_players       ; Not active, skip

Locate the loop_keyCont tag and replace the line above it, JR loop_cont, with:

ASM

jp   loop_cont             ; Jump

Between this line and loop_keyCont we add the Spectrum movement for single player games, this causes JR to give an out of range error, so we have replaced it with JP.

Finally, between this line and loop_keyCont, we add the following lines:

ASM

loop_players:
ld   a, (PlayerMoves)      ; A = player who moves
or   a                     ; Player 1?
jr   z, loop_keyCont       ; Yes, skip
ld   a, (MaxPlayers)       ; A = players
cp   $02                   ; 2 players?
jr   z, loop_keyCont       ; Yes, skip
call ZxMove                ; Move Spectrum
jr   nz, loop_players      ; NZ = incorrect, loop
push bc                    ; Preserve BC
ld   bc, SoundSpectrum     ; BC = sound address
call PlayMusic             ; Outputs sound
pop  bc                    ; Retrieves BC
jr   loop_print            ; Paints movement

We get which player is moving, if it is two we get how many players there are and if it is one it moves the spectrum.

Compile, load into the emulator and see the result. If all went well, we can now play against the Spectrum. If you think it is too easy, you can tweak the Spectrum’s movements, which we will do in the next chapter.

ZX Spectrum Assembly, Tic-Tac-Toe

In the next chapter of ZX Spectrum Assembly, we will make the final adjustments.

Download the source code from here.

Useful links

ZX Spectrum Assembly, Tic-Tac-Toe – 0x04 Options and end of game

Juan Antonio Rubio García — Thu, 05 Oct 2023 05:17:28 +0000

In this chapter of ZX Spectrum Assembly, we will implement the different options of the game and the end of the game; as we left off in the previous chapter, the game continues indefinitely. The options will be selected from a start menu.

Translation by Felipe Monge Corbalán

Colours

In var.asm we will add the following constants for the colours to avoid having to use numbers and to make it easier to change the colours during the game.

ASM

INK0: equ $00
INK1: equ $01
INK2: equ $02
INK3: equ $03
INK4: equ $04
INK5: equ $05
INK6: equ $06
INK7: equ $07
INK0: equ $00
INK1: equ $01
INK2: equ $02
INK3: equ $03
INK4: equ $04
INK5: equ $05
INK6: equ $06
INK7: equ $07

As an exercise, go through the title and text declarations and where you see $10, change the number that follows it to the corresponding INK tag.

In the same way, look for INK calls in the rest of the files, and instead of loading the ink number in A, load the corresponding INK tag.

Title3InStripe:    db $10, INK2, $13, $01, $16, $02, $09
                   defm "Three in a row"
TitleOptionStart:  db $10, INK1, $13, $01, $16, $08, $08, "0. "
                   db $10, INK5
                   defm "Start"
TitleOptionPlayer: db $10, INK7, $13, $01, $16, $0a, $08, "1. "
                   db $10, INK6
                   defm "Players"
TitleOptionPoint:  db $10, INK7, $16, $0c, $08, "2. ", $10, INK6
                   defm "Points"
TitleOptionTime:   db $10, INK7, $16, $0e, $08, "3. ", $10, INK6
                   defm "Time"
TitleEspamatica:   db $16, $14, $08
                   db $10, INK2, "E", $10, INK6, "s"
                   db $10, INK4, "p", $10, INK5, "a" 
                   db $10, INK2, "m", $10, INK6, "a"
                   db $10, INK4, "t", $10, INK5, "i"
                   db $10, INK2, "c", $10, INK6, "a"
                   db $10, INK7, " 2019", $ff

Now we have the definition of the start menu almost ready to paint, we just need a routine to paint the values of the options. We implement this in screen.asm.

ASM

; -------------------------------------------------------------------
; Paint the values of the options.
;
; Alters the value of the AF, BC and HL registers.
; -------------------------------------------------------------------
PrintOptions:
ld   a, INK4               ; A = green ink
call INK                   ; Change ink
ld   b, INI_TOP-$0a        ; B = coord Y
ld   c, INI_LEFT-$15       ; C = coord X
call AT                    ; Positions cursor
ld   hl, MaxPlayers        ; HL = value players
call PrintBCD              ; Paints it
ld   b, INI_TOP-$0c        ; B = coord Y
call AT                    ; Positions cursor
ld   hl, MaxPoints         ; HL = points value
call PrintBCD              ; Paints it
ld   b, INI_TOP-$0e        ; B = coord Y
call AT                    ; Positions cursor
ld   hl, MaxSeconds        ; HL = time value
jp   PrintBCD              ; Paints it and exits

PrintOptions paints the values of the options in green. It positions the cursor and paints each of the values.

Let’s see what the start menu looks like. We locate Main in main.asm, and under CALL OPENCHAN we add these lines:

ASM

Menu:
di                         ; Deactivate interruptions
im   $01                   ; Interruptions = mode 1
ei                         ; Activates interruptions

We have added a label for the menu part, disabled the interrupts to switch to mode one and enabled them again. We will then use the interrupts in mode two, so these lines are needed here.

At the bottom we find CALL CLS and then add the following lines:

ASM

ld   hl, Title3InStripe    ; HL = address three-inline	
call PrintString           ; Paints the menu
menu_op:    
call PrintOptions          ; Paint the options
jr   menu_op               ; Menu loop

We draw the start screen and the values of the options. We remain in an infinite loop as this is where we will implement the menu logic.

With the menu definition and a few lines we have painted it, but we still need to make it work.

Compile it, load it into the emulator and see how it looks.

Before implementing the menu logic, we will implement a routine in game.asm that uses the ROM to read the keyboard and return the ASCII code of the last key pressed. This routine will be used for the menu options and for the player name query.

ASM

; -------------------------------------------------------------------
; Wait for a key to be pressed and return its Ascii code.
;
; Output: A -> Ascii code of the key.
;
; Alters the value of the AF and HL registers.
; -------------------------------------------------------------------
WaitKeyAlpha:
ld   hl, FLAGS_KEY         ; HL = address flag keyboard
set  $03, (hl)             ; Input mode L

; Loop until a key is obtained.
WaitKeyAlpha_loop:
bit  $05, (hl)             ; Key pressed?
jr   z, WaitKeyAlpha_loop  ; Not pressed, loop
res  $05, (hl)             ; Bit set to 0 for future inspections

; Gets the Ascii of the key pressed.
; Valid Ascii 12 ($0C), 13 ($0D) and from 32 ($20) to 127 ($7F)
; If the key pressed is Space, load ' ' in A
WaitKeyAlpha_loadKey:
ld   hl, LAST_KEY          ; HL = last key pressed address
ld   a, (hl)               ; A = last key pressed
cp   $80                   ; Ascii > 127?
jr   nc, WaitKeyAlpha      ; Yes, invalid key, loop
cp   KEYDEL                ; Pushed Delete?
ret  z                     ; Yes, exit
cp   KEYENT                ; Press Enter?
ret  z                     ; Yes, exit
cp   KEYSPC                ; Powered Space?
jr   c, WaitKeyAlpha       ; Ascii < space, invalid, loop
ret                        ; Exits

WaitKeyAlpha waits until a key is pressed that is valid for us, that is: delete, enter or an ASCII code between thirty-two and one hundred and twenty-seven. When a valid key is pressed, it returns the ASCII code for that key in A.

We implement the menu routine in main.asm, just after CALL PrintOptions, and the final aspect is this:

ASM

menu_op:
call PrintOptions          ; Paint the options
call WaitKeyAlpha          ; Wait for keypress
cp   KEY0                  ; Pushed 0?
jr   z, Init               ; Yes, start game
menu_Players:
cp   KEY1                  ; Pushed 1?
jr   nz, menu_Points       ; No, skip
ld   a, (MaxPlayers)       ; A = players
xor  $03                   ; Alternates between 1 and 2
ld   (MaxPlayers), a       ; Update in memory
jr   menu_op               ; Loop
menu_Points:
cp   KEY2                  ; Pushed 2?
jr   nz, menu_Time         ; No, skip
ld   a, (MaxPoints)        ; A = points
inc  a                     ; A += 1
cp   $06                   ; A = 6?
jr   nz, menu_PointsDo     ; No, skip
ld   a, $01                ; A = 1
menu_PointsDo:  
ld   (MaxPoints), a        ; Update in memory
add  a, '0'                ; A = value ascii
ld   (info_points), a      ; Update in memory
cp   '1'                   ; Points 1?
jr   z, menu_Points1       ; Yes, skip
ld   a, 's'                ; Plural
jr   menu_PointsEnd        ; Jump
menu_Points1:
ld   a, ' '                ; Singular
menu_PointsEnd:
ld   (info_gt1), a         ; Update in memory
jr   menu_op               ; Loop
menu_Time:
cp   KEY3                  ; Pushed 3?
jr   nz, menu_op           ; No, loop
ld   a, (MaxSeconds)       ; A = seconds
add  a, $05                ; A += 5
daa                        ; Decimal setting
cp   $35                   ; A = 35 BCD?
jr   nz, menu_TimeDo       ; No, skip
ld   a, $05                ; A = 5
menu_TimeDo:
ld   (MaxSeconds), a       ; Refreshes in memory
jr   menu_op               ; Loop

After calling the routine that checks if a valid key has been pressed, it evaluates if it is any key between zero and three, and depending on which it is, it acts in one way or another. Note that it only does the decimal adjustment when incrementing seconds; it is the only option whose value is greater than nine.

We compile, load the emulator and see the results. Everything seems to go well until we press zero, start the game and the menu remains.

To fix this, we add the following line below the Init tag:

ASM

call CLS                   ; Clear screen

Start of game

When the game starts, the first thing we will do is ask for the names of the players. First, we add another constant to rom.asm; this address contains the coordinates of the cursor.

ASM

; Cursor position on screen 2. 
; If loaded at BC -> B = Y, C = X.
CURSOR: equ $5c88

We implement the routine responsible for retrieving the names of the players in game.asm. Although we won’t go through it instruction by instruction, due to the size of the routine we will implement it in blocks.

ASM

GetPlayersName:
ld   hl, Name_p1      
ld   de, Name_p1+$01  
ld   bc, LENNAME*2-$01
ld   (hl), " " 
ldir

We have cleared the names of the players.

ASM

ld   e, $01
getPlayersName_loop:
ld   a, INK4
call INK
ld   b, INI_TOP-$0f
ld   c, INI_LEFT-$01
call CLL
call AT

ld   hl, TitlePlayerNumber
ld   (hl), "1"
ld   a, $01
cp   e
jr   z, getPlayersName_cont
ld   (hl), "2"
getPlayersName_cont:
ld   hl, TitlePlayerName
call PrintString

ld   hl, Name_p1
ld   a, $01
cp   e
jr   z, getPlayersName_cont2
ld   hl, Name_p2

We make a loop of at most two iterations, one per player, change the colour, delete the line where the names are requested, position the cursor, prepare the title depending on the player, and point HL to the player’s name.

ASM

getPlayersName_cont2:
ld   d, $00
ld   a, INK3    
call INK   
call getPlayersName_getName 

ld   a, (MaxPlayers)           
cp   $02			 
jr   nz, getPlayersName_onlyOne
inc  e 
cp   e 
jr   z, getPlayersName_loop    
ret

We use D to control the length of the name, change the ink and ask for the player’s name. We get the players, see if there are two players, and if not, default the name to two. If there are two players, we check if the name entered is the name of player two, and if not, we loop to ask for it.

ASM

getPlayersName_onlyOne:
ld   hl, Name_p2Default
ld   de, Name_p2       
ld   bc, LENNAME       
ldir    
ret

If it is a single player, give the second player the default name.

ASM

getPlayersName_getName:
push hl  
call WaitKeyAlpha            
pop  hl  

cp   KEYDEL      
jr   z, getPlayersName_delete 
cp   KEYENT      
jr   z, getPlayersName_enter		
push de  
ld   e, a 
ld   a, LENNAME       
cp   d 
ld   a, e 
pop  de 
jr   z, getPlayersName_getName
                                 
ld   (hl), a 
inc  hl 
rst  $10
inc  d 
jr   getPlayersName_getName

We wait for a valid key to be pressed, check if it is Delete and if so, we jump to its operation. We check if it is enter and if it is, we jump to its operation.

If it is neither delete nor enter, we check if we have reached the maximum length and if not, we add the character to the name and draw it.

ASM

getPlayersName_delete:
ld   a, $00   
cp   d 
jr   z, getPlayersName_getName

dec  d 
dec  hl  
ld   a, ' ' 
ld   (hl), a 
ld   bc, (CURSOR)        
inc  c 
call AT  
rst  $10   
call AT  
jr   getPlayersName_getName

If the key pressed is delete and the length of the name is not zero, we delete the previous character of the name and the display.

ASM

getPlayersName_enter:
ld   a, 0 
cp   d 
jr   z, getPlayersName_getName
ret

If the key pressed is enter and the length of the name is not zero, the name request is terminated.

The final aspect of the routine is as follows:

ASM

; -------------------------------------------------------------------
; Ask for the names of the players.
;
; Alters the value of the AF, BC, DE and HL registers.
; -------------------------------------------------------------------
GetPlayersName:
ld   hl, Name_p1           ; HL = address player name 1
ld   de, Name_p1+$01       ; DE = HL+1
ld   bc, LENNAME*2-$01     ; BC = length names - 1
ld   (hl), " "             ; Clears first position
ldir                       ; Clean up the rest

ld   e, $01                ; E = 1
getPlayersName_loop:
ld   a, INK4               ; A = ink 4
call INK                   ; Change ink
ld   b, INI_TOP-$0f        ; B = coord Y
ld   c, INI_LEFT-$01       ; X = coord X
call CLL                   ; Delete the line
call AT                    ; Position cursor

ld   hl, TitlePlayerNumber ; HL = player number
ld   (hl), "1"             ; Player 1
ld   a, $01                ; A = 1
cp   e                     ; Player 1?
jr   z, getPlayersName_cont; Yes, skip
ld   (hl), "2"             ; Player 2 
getPlayersName_cont:
ld   hl, TitlePlayerName   ; HL = title player name
call PrintString           ; Paints it

ld   hl, Name_p1           ; HL = address player name 1
ld   a, $01                ; A = 1
cp   e                     ; Player 1?
jr   z, getPlayersName_cont2 ; Yes, skip
ld   hl, Name_p2           ; HL = address player name 2
getPlayersName_cont2:
ld   d, $00                ; D = counter length name
ld   a, INK3               ; A = ink 3
call INK                   ; Change ink
call getPlayersName_getName; Request player name

ld   a, (MaxPlayers)       ; A = players
cp   $02                   ; Two players?
jr   nz, getPlayersName_onlyOne ; One player, default name
inc  e                     ; E+=1
cp   e                     ; Compare with players
jr   z, getPlayersName_loop; Equals, jumps
ret

; Single player
; Copies the default name of player 2
getPlayersName_onlyOne:
ld   hl, Name_p2Default    ; HL = default player name 2
ld   de, Name_p2           ; DE = name player 2
ld   bc, LENNAME           ; Length name
ldir                       ; Copy default name
ret                        ; Sale

; Requests the player's name
getPlayersName_getName:
push hl                    ; Preserve HL
call WaitKeyAlpha          ; Wait for valid key
pop  hl                    ; Retrieve HL

cp   KEYDEL                ; Delete?
jr   z, getPlayersName_delete ; Yes, skip
cp   KEYENT                ; Enter?
jr   z, getPlayersName_enter ; Yes, skip	
push de                    ; Preserves DE
ld   e, a                  ; E = code Ascii
ld   a, LENNAME            ; A = maximum length name
cp   d                     ; D = maximum length?
ld   a, e                  ; A = code Ascii
pop  de                    ; Retrieve DE
jr   z, getPlayersName_getName ; D = maximum length
                               ; other character
                               ; Enter or Delete

ld   (hl), a               ; Append character to name
inc  hl                    ; HL = next position
rst  $10                   ; Print character
inc  d                     ; D+=1
jr   getPlayersName_getName; Request another character

getPlayersName_delete:
ld   a, $00                ; A = 0
cp   d                     ; Length 0?
jr   z, getPlayersName_getName ; Yes, another character

dec  d                     ; D-=1
dec  hl                    ; HL-=1, previous character
ld   a, ' '                ; A = space
ld   (hl), a               ; Clear previous character
ld   bc, (CURSOR)          ; BC = cursor position
inc  c                     ; BC = previous column for AT
call AT                    ; Position cursor
rst  $10                   ; Delete the display character	
call AT                    ; Position cursor
jr   getPlayersName_getName; Other character

getPlayersName_enter:
ld   a, 0                  ; A = 0
cp   d                     ; Length 0?
jr   z, getPlayersName_getName ; Yes, another character
ret                        ; End name

Let’s see if it works. In main.asm we find Init, and under CALL CLS we add the call to the name request, and another call to CLS.

ASM

call GetPlayersName        ; Request player names
call CLS                   ; Clear screen

We compile, load into the emulator and see the results. We can now enter the names of the players and they will appear in the game information. If it is a single player game, we are playing against ZX Spectrum.

Shift time

One of the options is the number of seconds each player has to make their move. If the move has not been made within these seconds, the player loses the turn and it passes to the other player.

We will use interrupts to control the time. We create the file int.asm.

At the top of main.asm, just below ORG $5E88, we add the following lines (we already did this in Space Battle):

ASM

; -------------------------------------------------------------------
; Flags
; bit 0 -> Reset countdown
; bit 1 -> Lose turn
; bit 2 -> Paint countdown
; bit 3 -> Warning sound, countdown ends
; -------------------------------------------------------------------
flags:     db $00
; Value countdown
countdown: db $00
; Seconds per shift
seconds:   db $00

Seconds is used to tell the interrupts how many seconds per turn the players have chosen. With seconds, the MaxSeconds variable is no longer needed, so we will remove it.

Locate Main and after the CALL OPENCHAN line, initialise seconds:

ASM

ld   a, $10                ; A = $10 BCD
ld   (seconds), a          ; Update seconds
ld   (countdown), a        ; Update countdown

Locate menu_Time and after JR NZ, menu_op modify the line LD A, (MaxSeconds), as follows:

ASM

ld   a, (seconds)          ; A = seconds

Locate menu_TimeDo, delete LD, (MaxSecond), A and add the following lines instead:

ASM

ld   (seconds), a          ; Update seconds
ld   (countdown), a        ; Update countdown

In screen.asm, at the end of the PrintOptions routine, we replace LD HL, MaxSeconds with:

ASM

ld   hl, seconds           ; HL = time value

Finally, we delete the MaxSeconds definition in var.asm.

The interrupt routine will change the value of the flags and the countdown, we need to take this into account in the main loop.

For the interrupt routine to run fifty times per second (in PAL, sixty in NTSC), mode two of the interrupts must be enabled. Locate Loop in main.asm and add over it:

ASM

di                         ; Disables interruptions
ld   a, $28                ; A = $28
ld   i, a                  ; I = A (interruptions in $7e5c)
im   $02                   ; Interruptions = mode 2
ei                         ; Activates interruptions

We disable the interrupts, load $28 into the interrupt register, set it to mode two and enable it.

We look for loop_key and just below it we implement the flag handling logic.

ASM

ld   a, (flags)            ; A = Flags
bit  $02, a                ; Bit 2 active?
res  $02, a                ; Disables bit 2
jr   z, loop_warning       ; Not active, skips
push af                    ; Preserve AF
call PrintCountDown        ; Paint countdown
pop  af                    ; Retrieve AF

We load the flags in A and evaluate if bit two is active and deactivate it. If it is not active, we jump, if it is, we draw the countdown.

ASM

loop_warning:
bit  $03, a                ; Bit 3 active?             
res  $03, a                ; Disable bit 3
jr   z, loop_lostMov       ; Not active, skip
ld   bc, SoundCountDown    ; BC = sound direction 
call PlayMusic             ; Outputs sound

We evaluate whether bit three is active and deactivate it. If it is active, we jump, if it is not, we give the warning sound.

ASM

loop_lostMov:
bit  $01, a                ; Bit 1 active?
res  $01, a                ; Disables bit 1
ld   (flags), a            ; Update in memory
halt                       ; Synchronise with interrupts
jr   z, loop_keyCont       ; Not active, skip
ld   hl, TitleLostMovement ; HL = address mov lost
ld   de, TitleLostMov_name ; DE = address name
call DoMsg                 ; Paint message
ld   bc, SoundLostMovement ; BC = sound direction
call PlayMusic             ; Outputs sound
jr   loop_cont             ; Jump
loop_keyCont:

We check if bit one is active, disable it, update the flags and synchronise with the interrupts. If it is, we draw the lost motion message and play the sound. The loop_keyCont tag is above the CALL WaitKeyBoard.

Finally, locate loop_cont, delete JR Loop and add the following lines in its place:

ASM

ld   a, $01                ; A = restart countdown
ld   (flags), a            ; Update flags
jp   Loop                  ; Main loop

We have updated the flags so that the interrupt routine restarts the countdown. We also replaced JR with JP because the lines we added make JR out of range.

In screen.asm we will implement the routine that draws the countdown.

ASM

; -------------------------------------------------------------------
; Paint the countdown.
;
; Alters the value of the AF, BC and HL registers.
; -------------------------------------------------------------------
PrintCountDown:
ld   a, INK3               ; A = ink 3
call INK                   ; Change ink
ld   b, INI_TOP-$0c        ; B = coord Y
ld   c, INI_LEFT           ; C = coord X
call AT                    ; Position cursor
ld   hl, countdown         ; HL = direction countdown
call PrintBCD              ; Paint countdown left
ld   c, INI_LEFT-$1e       ; C = coord X
call AT                    ; Position cursor
jp   PrintBCD              ; Paints countdown right and exits

We paint the countdown in two positions, on the left and right of the board. We set the ink to magenta, move the cursor to the left, draw the countdown, move the cursor to the right and draw the countdown.

The interrupt handling routine is implemented in int.asm (do not include this file in main.asm). We will also look at this implementation in blocks.

ASM

; -------------------------------------------------------------------
; int.asm
;
; Mode 2 Interrupt Handling
; -------------------------------------------------------------------
org $7e5c

; -------------------------------------------------------------------
; Indicators
; bit 0 -> Reset countdown
; bit 1 -> Lose turn
; bit 2 -> Paint countdown
; bit 3 -> Warning sound, countdown ends
; -------------------------------------------------------------------
FLAGS:     equ $5e88

COUNTDOWN: equ FLAGS+$01   ; Countdown Value
SECONDS:   equ FLAGS+$02   ; Seconds per turn

The interrupt routine is loaded at address $7E5C. Then we add the constants with the memory addresses we will use for the information exchange between main.asm and int.asm.

ASM

CountDownISR:
push af  
push bc  
push de  
push hl  
push ix                    ; Preserves records

The first step of the routine is to preserve the value of the registers.

ASM

countDown_flags:
ld   a, (FLAGS)            ; A = flags
and  $01                   ; Reset countdown?
jr   z, countDown_cont     ; No, skip
ld   a, (SECONDS)          ; A = SECONDS
ld   (COUNTDOWN), a        ; Refreshes in memory
ld   a, $04                ; A = paint countdown
ld   (FLAGS), a            ; Update in memory
jr   countDownISR_end      ; End

We check if main.asm indicates that the countdown should be restarted (shift change) and jump if it does not. If there is a shift, it restarts the countdown at the value specified in the menu, indicates in flags that the countdown should be painted, and jumps to exit the routine.

ASM

countDown_cont:
ld   hl, countDownTicks    ; HL = ticks counter
inc  (hl)                  ; Counter ticks+=1
ld   a, $32                ; A = 50
cp   (hl)                  ; Counter ticks = 50?
jr   nz, countDownISR_end  ; No, skip.
xor  a                     ; A = 0, Z = 1, Carry = 0
ld   (hl), a               ; Counter ticks = 0

In countDownTicks we add one at each pause, and when we reach fifty it is a sign that a second has passed, which we check in this block. If it has not reached fifty, it jumps to exit the routine, if it has, we set the ticks counter to zero and continue with the routine.

ASM

; It's reached 50, it's been a second.
ld   a, (COUNTDOWN)        ; A = countdown value
dec  a                     ; A-=1
daa                        ; Decimal setting
ld   (COUNTDOWN), a        ; Update in memory
ld   b, $04                ; B = paint countdown / 4 sec	
cp   b                     ; Less than 4 seconds?
jr   nc, countDownISR_reset; A >= 4, skip
set  $03, b                ; Warning sound
or   a                     ; A = 0?
jr   nz, countDownISR_reset; No, skip
set  $01, b                ; Misses turn

If one second has passed, we calculate what kind of information to pass to main.asm. We subtract one second from the countdown, see if it is below four (it also communicates to main.asm that the countdown has to be painted), and jump if it is not. If it is, we set the bit for the warning sound, evaluate whether the countdown has reached zero, and jump if it has not. Turn on the shift loss bit if it has reached zero.

ASM

countDownISR_reset:
ld   a, b                  ; A = B
ld   (FLAGS), a            ; Updates in memory

Update the value of flags with the information you want to pass to main.asm.

ASM

countDownISR_end:
pop  ix     
pop  hl     
pop  de     
pop  bc     
pop  af                    ; Retrieves records
	

ei                         ; Activates interruptions
reti                       ; Exits

countDownTicks: db $00     ; Ticks (50*sec)

We get the value of the registers, enable interrupts and exit. Finally we declare the tick counter.

Remember that we now need to compile two separate .tap’s and make our own loader.

The basic loader looks like this:

10 CLEAR 24200
20 LOAD ""CODE 24200
30 LOAD ""CODE 32348
40 RANDOMIZE USR 24200

The script to compile on Windows looks like this:

ShellScript

echo off
cls
echo Compiling oxo
pasmo --name OXO --tap main.asm oxo.tap oxo.log
echo Compiling int
pasmo --name INT --tap int.asm int.tap int.log
echo Generating Tic-tac-toe
copy /y /b loader.tap+oxo.tap+int.tap TicTacToe.tap
echo Process completed

The Linux version looks like this:

ShellScript

clear
echo Compiling oxo
pasmo --name OXO --tap main.asm oxo.tap oxo.log
echo Compiling int
pasmo --name INT --tap int.asm int.tap int.log
echo Generating Tic-tac-toe
cat loader.tap oxo.tap int.tap > TicTacToe.tap
echo Process completed

We compile it, load it into the emulator and check that the countdown is painted, that an alarm goes off if it goes under four seconds and that it loses the turn if it goes to zero. We also see the missed turn message.

End of game

At the end of this chapter we will implement the end of the game, which occurs when one of the players reaches the points defined in the menu, or when the maximum number of tables is reached.

At the end of the game we are asked if we want another game; we add the keys of the answer as constants in var.asm. We also add the maximum number of tables.

ASM

KEYN:       equ $4e        ; N key
KEYn:       equ $6e        ; Key n
KEYS:       equ $53        ; S key
KEYs:       equ $73        ; Key s
MAXTIES:    equ $05        ; Maximum number of tables

Depending on whether you want to play another game or not, you will jump to one place or another in main.asm. We locate the Init tag, and after CALL GetPlayersName we add the following tag:

ASM

Start:

We locate the loop_reset tag and just below it we will implement the check to see if someone has won the game.

ASM

call PrintPoints           ; Paint the dots
ld   a, (MaxPoints)        ; A = maximum points
ld   b, a                  ; B = A
ld   a, (Points_p1)        ; A = points player 1
cp   b                     ; Player 1 wins?
jr   z, EndPlay            ; Yes, skip 
ld   a, (Points_p2)        ; A = points player 2
cp   b                     ; Player 2 wins?
jr   z, EndPlay            ; Yes, skip
ld   b, MAXTIES            ; B = maximum tables
ld   a, (Points_tie)       ; A = points tables
cp   b                     ; A = B?
jr   z, EndPlay            ; Yes, skip

We draw the points and compare the players’ scores with the set maximum score. If one of the players has the required number of points, they win the game.

At the end of main.asm, before the includes, we add the split end routine.

ASM

EndPlay:
di                         ; Disables interrupts
im   $01                   ; Mode 1 interrupts
ei                         ; Activates interruptions
ld   hl, TitleGameOver     ; HL = title game over
call PrintMsg              ; Paints the message
endPlay_waitKey:
call WaitKeyAlpha          ; Wait key
cp   KEYN                  ; Pressed N?
jp   z, Menu               ; Yes, menu
cp   KEYn                  ; Pushed n?
jp   z, Menu               ; Yes, menu
cp   KEYS                  ; Pulsed S?
jp   z, Start              ; Yes, start
cp   KEYs                  ; Pushed s?
jp   z, Start              ; Yes, start
jr   endPlay_waitKey       ; Not pressed, loop

We deactivate interruptions, switch to mode one, activate interruptions, wait for the question to be answered and, depending on the answer, we jump to one place or another.

Menu: Return to the main menu. We can select the different options and enter new player names.
Start: is the label we have added. It clears the screen, paints the screen, resets the game data and switches interrupts to mode two.

If none of the expected keys have been pressed, it will loop until one is.

If you go to the Menu tag, you will see that the first three lines are for switching to interrupt mode one, which is what we do in EndPlay. Delete the three lines below the Menu tag.

We compile, load into the emulator and see the results. Everything seems to work fine, but at the end of the game the score is flashing. This is something we inherited from the beginning, although we didn’t notice it until now.

To change the behaviour, locate PrintPoints in screen.asm and add the lines needed to disable the flickering just below it.

ASM

ld   a,(ATTR_T)            ; A = temporary attributes
and  $7f                   ; Removes flicker 
ld   (ATTR_T), a           ; Update in memory

At this point, we can play the first full two-player games.

ZX Spectrum Assembly, Tic-Tac-Toe

Want to play against the Spectrum and beat it? We will implement this in the next chapter of ZX Spectrum Assembly,

Download the source code from here.

Useful links

ZX Spectrum Assembly, Tic-Tac-Toe – 0x03 Sound

Juan Antonio Rubio García — Wed, 04 Oct 2023 07:00:00 +0000

In this chapter of ZX Spectrum Assembly, we will implement different sounds and use them for timing by pausing between events.

Translation by Felipe Monge Corbalán

Sound

We will create the file sound.asm and add the include to main.asm.

In sound.asm we will add the definition of the different sounds and melodies.

ASM

; -------------------------------------------------------------------
; Sounds.
;
; Sounds end in $00, the byte indicating the end.
; -------------------------------------------------------------------
; Countdown
SoundCountDown:
db $03, $8c, $3a, $00

; Error
SoundError:
db $0d, $c6, $1e, $16, $13, $13, $00

; Loss of movement
SoundLostMovement:	
db $0d, $07, $10, $0b, $96, $12, $0a, $4d, $14
db $0b, $96, $12, $1a, $2c, $08, $00

; Next player
SoundNextPlayer:
db $01, $9d, $7b, $00

; Spectrum Movement
SoundSpectrum:
db $06, $6e, $20, $06, $6e, $20, $05, $b7, $24
db $06, $6e, $20, $05, $13, $29, $05, $b7, $24
db $06, $6e, $20, $00

; Tables
SoundTie:
db $0d, $07, $10, $0b, $96, $12, $06, $d4, $1e
db $0b, $96, $12, $07, $a6, $1b, $0b, $96, $12
db $08, $a5, $18, $0b, $96, $12, $09, $b4, $15
db $0b, $96, $12, $0a, $4d, $14, $0b, $96, $12
db $0d, $07, $10, $00

; Point
SoundWinGame:
db $06, $6e, $20, $05, $13, $29, $04, $40, $30
db $06, $6e, $20, $05, $13, $29, $04, $40, $30
db $06, $6e, $20, $05, $13, $29, $04, $c7, $2b
db $05, $13, $29, $05, $b7, $24, $05, $13, $29
db $06, $6e, $20, $05, $13, $29, $04, $40, $30
db $06, $6e, $20, $05, $13, $29, $04, $40, $30
db $06, $6e, $20, $05, $13, $29, $04, $c7, $2b
db $05, $13, $29, $05, $b7, $24, $06, $6e, $20
db $00

All sounds have a zero byte as their last byte, which we will use in the routine that plays them to know when they are finished.

In these definitions, each note is made up of three bytes instead of four, the first two being the note and the third being the low byte of the duration, all of which are sixteenths and/or half notes.

We implement the routine that plays the tones.

ASM

; -------------------------------------------------------------------
; Plays a melody or sound.
;
; Input: BC = Start address of the melody.
;
; To save is done byte by byte, with the duration always being fuzzy
; or half-fuse; only one byte is needed for the duration.
; This routine is adapted for this operation.
; -------------------------------------------------------------------
PlayMusic:
push af
push bc
push de
push hl
push ix                    ; Preserves records

playMusic_loop:
ld   a, (bc)               ; A = high byte note
ld   h, a                  ; H = A
or   a                     ; A = 0?
jr   z, playMusic_end      ; A = 0, end

inc  bc                    ; BC = next value
ld   a, (bc)               ; A = byte under note
ld   l, a                  ; L = A

inc  bc                    ; BC = next value
ld   a, (bc)               ; A = duration note
ld   e, a                  ; E = A
ld   d, $00                ; D = 0 (fuse or half-fuse)
inc  bc                    ; BC = next value

push bc                    ; Preserves BC
call BEEPER                ; Play note
pop  bc                    ; Recover BC

jr   playMusic_loop        ; Loop until it reaches 0 end melody

playMusic_end:
pop  ix
pop  hl
pop  de
pop  bc
pop  af                    ; Retrieves records
ret

PlayMusic receives the address of the sound to be played in BC, loads the note in HL, the duration in DE, plays it and loops until it reaches the zero byte which marks the end of the sound. D is always zero, only one byte is used for the duration.

In main.asm we will add the necessary calls to play the sounds.

We locate the Loop tag and delete from LD B, $19 to DJNZ loop_wait as we will be timing with the sound. Below this, after CALL PrintPoints, we add the next player sound:

ASM

ld   bc, SoundNextPlayer
call PlayMusic

Locate the loop_print tag and just above it the JR Loop line. Above this line we add the error sound:

ASM

ld   bc, SoundError
call PlayMusic

Locate the loop_win tag and just below it the INC (HL) line. Below this line we add the dot winner sound:

ASM

ld   bc, SoundWinGame
call PlayMusic

Locate the loop_reset tag and just above it add the table sound:

ASM

ld   bc, SoundTie
call PlayMusic

We compile, load into the emulator and listen to every single sound.

The main.asm file has grown considerably since we started, so it’s time to see what it looks like after commenting.

ASM

org  $5e88                 ; Loading address

Main:
ld   hl, Sprite_P1         ; HL = address Sprite_P1
ld   (UDG), hl             ; UDG = address Sprite_p1
ld   a, $02                ; A = 2
call OPENCHAN              ; Open channel 2

xor  a                     ; A = 0, Z = 0, C = 0
call BORDER                ; Change border
call CLA                   ; Changes display attributes
call CLS                   ; Clear screen

Init:
call PrintBoard            ; Paint board

ld   hl, Name_p1           ; HL = name player 1
ld   de, player1_name      ; DE = player1_name
ld   bc, LENNAME           ; BC = length name
ldir                       ; Pass data
ld   hl, Name_p2           ; HL = name player 2
ld   de, player2_name      ; DE = player 2 name
ld   bc, LENNAME           ; BC = length name
ldir                       ; Pass data
call PrintInfo             ; Paint info

ld   bc, LENDATA           ; BC = length of starting data
call ResetValues           ; Clear data

Loop:
ld   hl, TitleTurn         ; HL = shift address
ld   de, TitleTurn_name    ; DE = address name in turn name in turn
call DoMsg                 ; Compose and paint shift
call PrintPoints           ; PaintPoints
ld   bc, SoundNextPlayer   ; BC = sound direction
call PlayMusic             ; Play sound
loop_key:
call WaitKeyBoard          ; Wait for key press
ld   a, c                  ; A = C
cp   KEY0                  ; Key pressed?
jr   z, loop_key           ; No, loop
call ToMove                ; Check movement
jr   z, loop_print         ; Correct, skip
ld   hl, TitleError        ; HL = address error
call PrintMsg              ; Paint Error
ld   bc, SoundError        ; BC = sound address
call PlayMusic             ; Play sound
jr   Loop                  ; Main loop
loop_print:
call PrintOXO              ; Paint token
loop_checkWinner:
call CheckWinner           ; Any winners?
jr   nz, loop_tie          ; No, check tables
call PrintWinnerLine       ; Paints winning line
ld   hl, TitlePointFor     ; HL = winning address
ld   de, TitlePointName    ; HL = address winning name
call DoMsg                 ; Compose and paint winner
ld   hl, Points_p1         ; HL = address points player 1
ld   a, (PlayerMoves)      ; A = player that moved
or   a                     ; Player 1?
jr   z, loop_win           ; Yes, skip
inc  hl                    ; HL = address points player 2
loop_win:
inc  (hl)                  ; Increases score
ld   bc, SoundWinGame      ; BC = sound address
call PlayMusic             ; Play sound
jr   loop_reset            ; Jump
loop_tie:
ld   hl, MoveCounter       ; HL = move counter address
inc  (hl)                  ; Increments counter
ld   a, $09                ; A = 9
cp   (hl)                  ; Counter = 9?
jr   nz, loop_cont         ; No, skip
ld   hl, Points_tie        ; HL = address points tables
inc  (hl)                  ; Increases score
ld   hl, TitleTie          ; HL = address tables
call PrintMsg              ; Paint tables
ld   bc, SoundTie          ; BC = sound direction
call PlayMusic             ; Play sound
loop_reset:
ld   bc, LENDATA-$04       ; BC = data length clean data
call ResetValues           ; Clear data
call PrintBoard            ; Paint board
loop_cont:
ld   a, (PlayerMoves)      ; A = player who moved
xor  $01                   ; A = next player
ld   (PlayerMoves), a      ; Refresh in memory
jr   Loop                  ; Main loop

include "game.asm"
include "rom.asm"
include "screen.asm"
include "sprite.asm"
include "sound.asm"
include "var.asm"

end  Main

ZX Spectrum Assembly, Tic-Tac-Toe

We have a large part of the game developed and working. We can play our first games with friends and/or family and we have sound.

In the next chapter of ZX Spectrum Assembly, we will implement the different options of the game and the end of the game.

Download the source code from here.

Useful links

ZX Spectrum Assembly, Tic-Tac-Toe – 0x02 Scoreboards and a two player game

Juan Antonio Rubio García — Tue, 03 Oct 2023 05:06:53 +0000

In this chapter of ZX Spectrum Assembly, will be to implement the scoreboards and the two-player game, which will form a large part of the programme.

Translation by Felipe Monge Corbalán

Information

First we add the name of the programme, the players, the markers and the moving piece.

In var.asm we add the necessary data.

ASM

LENNAME: equ $0c           ; Length name players

; Information
Info:              db $10, $07, $16, $00, $03, "Three in a row at "
info_points:       db "5 point"
info_gt1:          db "s"

player1_title:     db $10, $05, $16, $02, $00
player1_name:      defs LENNAME, " "
player1_figure:    db $16, $04, $00, $90, $91, $0d, $91, $90

player_tie:        db $10, $02, $16, $02, $0d, "Tables"

player2_title:     db $10, $06, $16, $02, $14
player2_name:      defs LENNAME, " "
player2_figure:    db $16, $04, $1b, $92, $93, $16, $05, $1b
                   db $94, $95, $ff

; Titles
TitleTurn:         db $16, $15, $05, $13, $01
                   db "Shift for "
TitleTurn_name:    defs LENNAME, " "
                   db $ff
TitleError:        db $10, $02, $16, $15, $0a, $12, $01, $13, $01
                   defm "Box occupied", $ff
TitleEspamatica:   defm "Espamatica 2019", $ff
TitleGameOver:     db $10, $07, $16, $15, $03, $12, $01, $13, $01
                   defm "Game terminated. Other?", $ff
TitleLostMovement: db $10, $02, $12, $01, $13, $01, $16, $15, $05
                   defm "Lose turn "
TitleLostMov_name: defs LENNAME, " "
                   db $ff
TitleOptionStart:  defm "0. Start", $ff
TitleOptionPlayer: defm "1. Players", $ff
TitleOptionPoint:  defm "2. Points", $ff
TitleOptionTime:   defm "3. Time", $ff
TitlePlayerName:   defm "Player "
TitlePlayerNumber: db " : ", $ff
TitlePointFor:     db $10, $07, $16, $15, $05, $12, $01, $13, $01
                   defm "Point for "
TitlePointName:    defs LENNAME, " "
                   db $ff
TitleTie:          db $10, $07, $16, $15, $0d, $12, $01, $13, $01
                   defm "Tables", $ff

; -------------------------------------------------------------------
; Development of the game.
; -------------------------------------------------------------------
; Board squares. One byte per square, from 1 to 9.
; Bit 0, square occupied by player 1.
; Bit 4, square occupied by player 2.
Grid:          db $00, $00, $00, $00, $00, $00, $00, $00, $00
; Positions of the pieces on the board, 2 bytes per piece X, Y
GridPos:       db POS1_LEFT, POS1_TOP ; 1
               db POS2_LEFT, POS1_TOP ; 2
               db POS3_LEFT, POS1_TOP ; 3
               db POS1_LEFT, POS2_TOP ; 4
               db POS2_LEFT, POS2_TOP ; 5
               db POS3_LEFT, POS2_TOP ; 6
               db POS1_LEFT, POS3_TOP ; 7
               db POS2_LEFT, POS3_TOP ; 8
               db POS3_LEFT, POS3_TOP ; 9

Points_p1:     db $00            ; Points player 1
Points_p2:     db $00            ; Points player 2
Points_tie:    db $00            ; Points tables
PlayerMoves:   db $00            ; Player who moves

MaxPlayers:    db $01            ; Maximum players
MaxPoints:     db $05            ; Maximum Points
MaxSeconds:    db $10            ; Maximum seconds

Name_p1:       db "Amstrad CPC " ; Player name 1
Name_p2:       db "ZX Spectrum " ; Player name 2
Name_p2Default:db "ZX Spectrum " ; Default name

In the Info tag, we define the literals that will be displayed at the top of the screen. Although it may seem strange, the division into several labels is due to the fact that there are values that change depending on the choices made by the players:

Points needed to win the game.
If it is more than one point, it is written in the plural.
The names of the players.

We also define the labels we will use to keep track of each player’s score and name.

We go to screen.asm and implement one routine to draw the information and another to draw the score.

ASM

; -------------------------------------------------------------------
; Paint the information of the game.
;
; Alters the value of HL.
; -------------------------------------------------------------------
PrintInfo:
ld   hl, Info              ; HL = information
jp   PrintString           ; Paints it

PrintInfo paints the information to be displayed at the top of the screen. It does not assign ink colours or positions, as this is all defined in the Info tag.

ASM

; -------------------------------------------------------------------
; Paint the score.
;
; Alters the value of AF, BC, DE and HL.
; -------------------------------------------------------------------
PrintPoints:
ld   a, $05                ; A = cyan ink
call INK                   ; Change ink
ld   b, INI_TOP-$04        ; B = coord Y
ld   c, INI_LEFT-$03       ; C = coord X
call AT                    ; Position cursor
ld   hl, Points_p1         ; HL = points player 1
call PrintBCD              ; Paints them

ld   a, $02                ; A = red ink
call INK                   ; Change ink
ld   b, INI_TOP-$04        ; B = coord Y
ld   c, INI_LEFT-$0f       ; C = coord X
call AT                    ; Position cursor
ld   hl, Points_tie        ; HL = points tables
call PrintBCD              ; Paints them

ld   a, $06                ; A = yellow ink
call INK                   ; Change ink
ld   b, INI_TOP-$04        ; B = coord Y
ld   c, INI_LEFT-$1e       ; C = coord X
call AT                    ; Position cursor
ld   hl, Points_p2         ; HL = points player 2
jp   PrintBCD              ; Paints them in and out

PrintPoints paints the players’ scores and tables. For each score, it changes the ink, positions the cursor and paints the score.

Now we have everything ready. We go to main.asm and after the call to PrintBoard we add the code that paints the information and the score.

ASM

ld   hl, Name_p1
ld   de, player1_name
ld   bc, LENNAME
ldir
ld   hl, Name_p2
ld   de, player2_name
ld   bc, LENNAME
ldir
call PrintInfo

xor  a
ld   hl, Points_p1
ld   de, Points_p1+$01
ld   bc, $03
ld   (hl), a
ldir
call PrintPoints

The names of the players are in the Name_p1 and Name_p2 tags, so we need to pass them to the appropriate place in the information. We initialise the score and draw it.

We compile, load into the emulator and see the results.

Two-player game

We will implement the two-player game: controls, tile moves, checks for correctness, and tic-tac-toe performance.

In var.asm we include a series of constants with ink colours, lines on which the three dashes occur, and key codes, which we will use together with the ROM routine to check the controls.

ASM

INKWARNING: equ $C2        ; Ink Warnings
INKPLAYER1: equ $05        ; Player ink 1
INKPLAYER2: equ $06        ; Player 2 ink
INKTIE:     equ $07        ; Ink tables

KEYDEL:     equ $0c        ; Delete key
KEYENT:     equ $0d        ; Enter Key
KEYSPC:     equ $20        ; Space Key
KEY0:       equ $30        ; Key 0
KEY1:       equ $31        ; Key 1
KEY2:       equ $32        ; Key 2
KEY3:       equ $33        ; Key 3
KEY4:       equ $34        ; Key 4
KEY5:       equ $35        ; Key 5
KEY6:       equ $36        ; Key 6
KEY7:       equ $37        ; Key 7
KEY8:       equ $38        ; Key 8
KEY9:       equ $39        ; Key 9

WINNERLINE123: equ $01     ; Winning line 123
WINNERLINE456: equ $02     ; Winning line 456
WINNERLINE789: equ $03     ; Winning line 789
WINNERLINE147: equ $04     ; Winning line 147
WINNERLINE258: equ $05     ; Winning line 258
WINNERLINE369: equ $06     ; Winning line 369
WINNERLINE159: equ $07     ; Winning line 159
WINNERLINE357: equ $08     ; Winning line 357

We implement the logic in the file game.asm. We build it and add the include to main.asm.

ASM

; -------------------------------------------------------------------
; Wait for a key to be pressed on the board.
; During the game the interruptions are activated in order
; to perform the countdown. 
; With interrupts enabled, it does not update FLAGS_KEY/LAST_KEY.
;
; Output: C -> Key pressed.
;
; Alters the value of the AF and BC registers.
; -------------------------------------------------------------------
WaitKeyBoard:
ld   a, $f7                ; A = half-row 1-5
in   a, ($fe)              ; Read half-row
cpl                        ; Invert bits, keys pressed to 1
and   $1F                  ; A = bits 1 to 4
jr   z, waitKey_cont       ; No key pressed, skips

; Evaluates the key pressed from 1 to 5.
ld   c, KEY1               ; C = key 1
ld   b, $05                ; B = keys to check
waitKey_1_5:
rra                        ; Pulsed key?
ret  c                     ; Pressed, jump
inc  c                     ; C = code next key
djnz waitKey_1_5           ; Loop for 5 keys

waitKey_cont:
ld   a, $ef                ; A = half-row 0-6
in   a, ($fe)              ; Read half-row
cpl                        ; Invert bits, keys pressed to 1
and  $1F                   ; A = bits 1 to 4
jr   z, waitKey_end        ; No key pressed, skip

; Evaluates the key pressed 9 to 6
rra                        ; Skip zero key
ld   c, KEY9               ; C = key 9
ld   b, $04                ; B = keys to check
waitKey_9_6:
rra                        ; Pulsed key?
ret  c                     ; Pressed, jump
dec  c                     ; C = next key code
djnz waitKey_9_6           ; Loop for 4 keys

; No key has been pressed
waitKey_end:
ld   c, KEY0
ret

With WaitKeyBoard we will check if any of the keys on the board, from one to nine, have been pressed. In this case we will not use the ROM routine, because later we will have the mode two interrupts active, and neither FLAGS_KEY nor LAST_KEY will be updated, and the ROM will not be able to tell us the last key pressed.

The key check is very similar to the one we did in Space Battle, with the following variations:

CPL: we invert the bits and evaluate if any keys were pressed with AND $1F; we skip if none were pressed.
What we return, in this case in C, is the ASCII code of the key pressed; of the zero key if none was pressed.

We can also see that, before checking the keys 9 to 6, we make a rotation to ignore the 0 key.

We now continue with the logic of the token movement.

ASM

; -------------------------------------------------------------------
; Check and carry out the movement if it is correct.
;
; Input:  C  -> Key pressed
; Output: Z  -> Correct movement
;         NZ -> Incorrect movement
;
; Alters the value of the AF and HL registers.
; -------------------------------------------------------------------
ToMove:
push bc                    ; Preserves BC
ld   hl, Grid              ; HL = grid address
ld   a, c                  ; A = C (key code)
sub  $30                   ; A = numeric value key
dec  a                     ; A-=1, so that it does not add up 
                           ; to one more
ld   b, $00                ; B = 0
ld   c, a                  ; C = A, BC = offset
add  hl, bc                ; HL = key box address
pop  bc                    ; Retrieves BC

ld   a, (hl)               ; A = box value
or   a                     ; Are you free?
ret  nz                    ; Busy, exits

ld   a, (PlayerMoves)      ; A = player moving
or   a                     ; Player 1?
jr   nz, toMove_p2         ; Player 2, jump
set  $00, (hl)             ; Activate box player 1
jr   toMove_end            ; Skip

toMove_p2:
set  $04, (hl)             ; Activate player 2 box

toMove_end:
xor  a                     ; Puts flag Z
ret                        ; Exits

ToMove receives the code of the key pressed in C. We calculate the value by subtracting the ASCII code from zero, subtracting one so as not to add too much to the offset, and point to the cell corresponding to the key pressed. We check that the cell is not occupied, if it is not, we activate bits one or four of the cell according to the player who is moving. If the cell is occupied, it goes out with NZ, if not, it goes out with Z (XOR A).

We need a routine that paints the tile in the right place; we implement this in screen.asm.

ASM

; -------------------------------------------------------------------
; Paint the card.
;
; Input: C -> Key pressed.
;
; Alters the value of the AF, BC and HL registers.
; -------------------------------------------------------------------
PrintOXO:
; Calculation of the card position
ld   a, c                  ; A = key
sub  $30                   ; A = key value
dec  a                     ; A-=1, so as not to over-add in offset
add  a, a                  ; A+=A, offset, two bytes per position
ld   b, $00                ; B = 0
ld   c, a                  ; C = A
ld   hl, GridPos           ; HL = address grid positions
add  hl, bc                ; HL+=BC, address coord X cell
ld   c, (hl)               ; C = coord X cell
inc  hl                    ; HL = address coord Y
ld   b, (hl)               ; B = coord Y cell
call AT                    ; Position cursor

; Calculation sheet
ld   a, (PlayerMoves)      ; A = player who moves
or   a                     ; Check player
jr   nz, printOXO_Y        ; Non-zero, skip

printOXO_X:
ld   a, INKPLAYER1         ; A = ink player 1
call INK                   ; Change ink
ld   a, $90                ; A = 1st sprite
rst  $10                   ; Paints it
ld   a, $91                ; A = 2nd sprite
rst  $10                   ; Paints it
dec  b                     ; B = bottom line
call AT                    ; Position cursor
ld   a, $91                ; A = 2nd sprite
rst  $10                   ; Paints it
ld   a, $90                ; A = 1st sprite
rst  $10                   ; Paints it
ret                        ; Exists

printOXO_Y:
ld   a, INKPLAYER2         ; A = ink player 2
call INK                   ; Change ink
ld   a, $92                ; A = 1st sprite
rst  $10                   ; Paints it
ld   a, $93                ; A = 2nd sprite
rst  $10                   ; Paints it
dec  b                     ; B = bottom line
call AT                    ; Position cursor
ld   a, $94                ; A = 3rd sprite
rst  $10                   ; Paints it
ld   a, $95                ; A = 4th sprite
rst  $10                   ; Paints it
ret

In the first part of PrintOXO, the offset is calculated to obtain the coordinates where to paint the piece, the cursor is obtained and positioned. Then you get the moving player.

The way to paint one tile or the other is almost identical: change the colour, paint the top part, position the cursor on the bottom line and paint the bottom part before leaving.

Now we can start testing how everything we have implemented looks in the program. We go to main.asm and under the Loop tag, before JR Loop, we add the calls to the implemented routines.

ASM

call WaitKeyBoard
ld   a, c
cp   KEY0
jr   z, loop_cont
call ToMove
jr   nz, loop_cont
call PrintOXO
ld   a, (PlayerMoves)
xor  $01
ld   (PlayerMoves), a
loop_cont:

We wait for the player to press a key, and when he does, we check that the move is correct, and if it is, we paint the piece and change players.

We compile, load the emulator and see the results.

We see how the tiles are painted and once the whole board is occupied we can only restart and reload, so we have to implement the following:

When the board is full, reset it.
Display information messages.
Check if there is a tic-tac-toe or a board.
Refresh the scoreboard.

Resetting the board

In var.asm, before PlayersMoves, we add a tag to keep track of the number of moves. The board is full when the value reaches nine.

We put it first because PlayersMoves is only restarted at the start of a game. If we reset it with every point, player one would always move first.

ASM

MoveCounter: db $00        ; Move counter

Also in var.asm, we add a constant at the beginning where we specify the length of data to initialise in each line item.

ASM

LENDATA: equ $04           ; Length of data to be initialised

As we need to add more data to initialise, we change the value of this constant.

In main.asm we locate the Loop tag and four lines before the line LD BC, $03. Replace this line with the following:

ASM

ld   bc, LENDATA

Compile, load into the emulator and check that everything still works.

As we have mentioned, we will not always initialise all the data, so it is a good idea to implement a routine that can be passed the length of the data to be initialised, so that it can be called from different places with different values.

The values we want to initialise are:

Points_p1
Points_p2
Points_tie
MoveCounter
PlayerMoves (only at the start of the game)

There are more values to initialise, but they are higher up, so either we initialise them in two parts, or we change the label. The label is Grid (each player’s moves) and we need to set all the values to zero at the start of each point. Let’s change the position of the label, just above Points_p1, like this:

ASM

; -------------------------------------------------------------------
; Development of the game.
; -------------------------------------------------------------------
; Positions of the pieces on the board, 2 bytes per piece Y, X
GridPos:     db POS1_LEFT, POS1_TOP ; 1
             db POS2_LEFT, POS1_TOP ; 2
             db POS3_LEFT, POS1_TOP ; 3
             db POS1_LEFT, POS2_TOP ; 4
             db POS2_LEFT, POS2_TOP ; 5
             db POS3_LEFT, POS2_TOP ; 6
             db POS1_LEFT, POS3_TOP ; 7
             db POS2_LEFT, POS3_TOP ; 8
             db POS3_LEFT, POS3_TOP ; 9

; Board squares. One byte per square, from 1 to 9.
; Bit 0 to 1, square occupied by player 1.
; Bit 4 to 1, square occupied by player 2.
Grid:        db $00, $00, $00, $00, $00, $00, $00, $00, $00
Points_p1:   db $00        ; Points player 1
Points_p2:   db $00        ; Points player 2
Points_tie:  db $00        ; Points tables
MoveCounter: db $00        ; Move counter
PlayerMoves: db $00        ; Player moving

The value of LENDATA has to be changed to $0D.

We implement the initialisation routine in game.asm.

ASM

; -------------------------------------------------------------------
; Initialises the values of the item/item.
;
; Input: BC -> Length of the values to be initialised.
;
; Alters the value of the BC, DE and HL registers.
; -------------------------------------------------------------------
ResetValues:
ld   hl, Grid              ; HL = Grid address
ld   de, Grid+$01          ; DE = address of Grid+1
ld   (hl), $00             ; Resets first position to zero
ldir                       ; Resets the remainder (BC) to zero

ret

ResetValues gets the number of bytes to clear in BC (must be one less than the total length, that’s why LENDATA is $0D instead of $0E), points HL and DE to the first and second grid positions, clears the first and then the rest.

If you look closely, this routine should look very familiar, take a look at the CLS routine in screen.asm. They are almost identical!

We could implement a routine with the lines LD (HL), $00, LDIR and RET, bearing in mind that before calling it we would have to load the necessary values in HL and BC, and remove CLS and ResetValues. I’ll leave it up to you, I’m going to leave it as it is now.

We go back to main.asm, find Loop and a few lines above XOR A. From XOR A to CALL PrintPoint, we keep only the lines LD BC, LENDATA and CALL PrintPoints, the rest we delete.

Between LD BC, LENDATA and CALL PrintPoints, we add the call to initialise the values, as follows:

ASM

call PrintInfo

ld   bc, LENDATA
call ResetValues
call PrintPoints

Loop:

After loading the length of data to be cleaned into BC, we call the initialisation of the values and draw the points.

We compile, load into the emulator and see that everything still works.

To know if the board is full, we need to update MoveCounter with every move and check if it has reached nine.

Locate loop_cont and add the following lines just above it, after LD (PlayerMoves), A:

ASM

ld   hl, MoveCounter
inc  (hl)
ld   a, $09
cp   (hl)
jr   nz, loop_cont
ld   bc, LENDATA-$01
call ResetValues
call PrintBoard

We increment the move counter, check if it has reached nine, in which case we load into BC the length of the data to be erased minus one (so as not to erase the moving player), initialise the data and draw the board empty.

Compile and load into the emulator. If we press the keys from one to nine until the board is full, the player whose turn it is to move has not been cleared and will move the player whose turn it was in the next turn.

Information messages

During the course of the game there are several messages that need to be displayed to the players: if the move is wrong, which player is moving, who gets the point, if there is a draw and when the game is over.

The messages have been defined at the beginning of the chapter, and in each of them the ink, brightness, flicker and location, so all we need to do is call PrintString with the address of the message in HL.

There are two reasons why this cannot be done:

The messages Turn to, Missed turn and Point to are not complete, they are completed with the name of the player who has the turn.
Before writing a message, the line must be cleared.

We will implement two routines, one in game.asm and the other in screen.asm; these routines will act as a bridge when we call PrintString.We will start with the routine we have implemented in screen.asm.

ASM

; -------------------------------------------------------------------
; Paint the messages
;
; Input: HL-> message address
; -------------------------------------------------------------------
PrintMsg:
ld   b, INI_TOP-$15        ; B = coord Y line to be deleted (inverted)
call CLL                   ; Deletes the line
jp   PrintString           ; Paint the message

PrintMsg receives the address of the message in HL, clears the message line and jumps to paint the message, where it exits. Clearing the line before painting a new message is the only use of this routine.

We implement the game.asm routine, which completes the three messages that paint the player’s name.

ASM

; -------------------------------------------------------------------
; Completes the messages in which the player's name is displayed.
;
; Input: HL -> message address
;        DE -> address where the name should go
;
; Alters the value of the AF, BC and DE registers.
; -------------------------------------------------------------------
DoMsg:
push hl                    ; Preserves HL
ld   hl, player1_name      ; HL = name player 1
ld   a, (PlayerMoves)      ; A = player
or   a                     ; Player 1?
ld   a, INKPLAYER1         ; A = ink player 1
jr   z, doMsg_cont         ; Player 1, skip
ld   hl, player2_name      ; HL = name player 2
ld   a, INKPLAYER2         ; A = ink player 2
doMsg_cont:
call INK                   ; Change ink
ld   bc, LENNAME           ; BC = length name
ldir                       ; Pass player name to message
pop  hl                    ; Retrieve HL
jp   PrintMsg              ; Paint message

DoMsg receives the address of the message to be painted in HL and the address where the player’s name is to be placed in DE. He checks which player’s turn it is, places one or the other name and the player’s ink. He paints the message and leaves.

We go to main.asm and paint all the messages we can, starting with who has the turn.

Locate Loop and add the following lines just below it:

ASM

ld   b, $19
loop_wait:
halt
djnz loop_wait
ld   hl, TitleTurn
ld   de, TitleTurn_name
call DoMsg
loop_key:

Each time we go through the loop, we paint the player whose turn it is to move. Before we do this, we pause for about half a second to allow time to read the messages.

Now find the line CP KEY0 and just below it in the line JR Z, loop_cont, change loop_cont to loop_key.

Compile, load it into the emulator and you will see that we can see which player has the turn to move.

Let’s also draw the busy box error message. Find the CALL ToMove line, delete the following line, JR NZ, loop_cont, and add the following lines:

ASM

jr   z, loop_print
ld   hl, TitleError
call PrintMsg
jr   Loop
loop_print:

If it returns from the ToMove routine with the Z flag active, this means that the movement is correct and we jump to loop_print, the label we added before CALL PrintOXO. If not, the move is incorrect and we print the error message and go back to the start of the loop.

Compile, load into the emulator and try to move to an occupied square. The error message should be painted, even if it’s only visible for a short time; don’t worry, we’ll remove the pause at the beginning of the loop later and use the sound effects for timing.

Table check

The draw check is simple; if there are nine moves and no three in a row, there is a draw.

Find the loop_cont tag and four lines above it, between JR NZ, loop_cont and LD BC, LENDATA-$01, add the following:

ASM

ld   hl, Points_tie
inc  (hl)
ld   hl, TitleTie
call PrintMsg

With these lines, if nine moves are reached without three in a row, one move is added to the draw score.

Go to the loop_key tag and add the following line above it:

ASM

call PrintPoints

Now, in each iteration of the loop, we draw the notes. The CALL PrintPoints just above the Loop tag can be removed.

Compile, load in the emulator and you will see that not everything works as it should, the table marker is not updated.

Actually everything works as it should, the problem is that ResetValues is resetting the scores, which is easy to fix, but we will fix it later.

We also notice that when repainting the board the flashing is active because the message Tables leaves it that way.

To solve this we could implement a routine to remove the flickering, but we decided to solve it in the board definition. We go to var.asm and just below the Board_1 tag we add the following line to disable the flickering and glowing when the board is painted.

ASM

db $12, $00, $13, $00

Compile, load into the emulator, move until the board is full and check that there is no flickering when repainting.

Tic-tac-toe check

The three in a row check should not be made until at least three moves have been made. In principle, there should be at least five moves before there are three in a row, but since we are going to implement the possibility of the player losing the turn if it takes longer than the set time, it is possible that there will be three in a row with three moves. However, we are going to perform the operation each time a piece is moved, so it will always take the same (approximate) time for each iteration of the loop.

In game.asm we add the routine that checks for tic-tac-toe.

ASM

; -------------------------------------------------------------------
; Check if there are three in a row.
;
; Return: A -> tic-tac-toe line
;         Z if there are three in a row, NZ otherwise.   
; 
; Alters the value of the AF, B and IX registers.
; -------------------------------------------------------------------
CheckWinner:
ld   ix, Grid-$01          ; IX = grid address - 1
ld   b, $03                ; B = sum cells player 1
ld   a, (PlayerMoves)      ; A = player
or   a                     ; Player 1?
jr   z, CheckWinner_check  ; Player 1, skip
ld   b, $30                ; B = sum cells player 2

CheckWinner_check:
ld   a, (ix+1)             ; A = cell 1
add  a, (ix+2)             ; A+= cell 2
add  a, (ix+3)             ; A+= cell 3
cp   b                     ; Three in a row?
ld   a, WINNERLINE123      ; A = flag line 123
ret  z                     ; Tic-tac-toe, exits

ld   a, (ix+4)             ; A = cell 4
add  a, (ix+5)             ; A+= cell 5
add  a, (ix+6)             ; A+= cell 6
cp   b                     ; Three in a row?
ld   a, WINNERLINE456      ; A = indicator line 456
ret  z                     ; Tic-tac-toe, exits

ld   a, (ix+7)             ; A = cell 7
add  a, (ix+8)             ; A+= cell 8
add  a, (ix+9)             ; A+= cell 9
cp   b                     ; Three in a row?
ld   a, WINNERLINE789      ; A = line indicator line 789
ret  z                     ; Tic-tac-toe, exits

ld   a, (ix+1)             ; A = cell 1
add  a, (ix+4)             ; A+= cell 4
add  a, (ix+7)             ; A+= cell 7
cp   b                     ; Three in a row?
ld   a, WINNERLINE147      ; A = indicator line 147
ret  z                     ; Tic-tac-toe, exits

ld   a, (ix+2)             ; A = cell 2
add  a, (ix+5)             ; A+= cell 5
add  a, (ix+8)             ; A+= cell 8
cp   b                     ; Three in a row?
ld   a, WINNERLINE258      ; A = indicator line 258
ret  z                     ; Tic-tac-toe, exits

ld   a, (ix+3)             ; A = cell 3
add  a, (ix+6)             ; A+= cell 6
add  a, (ix+9)             ; A+= cell 9
cp   b                     ; Three in a row?
ld   a, WINNERLINE369      ; A = indicator line 369
ret  z                     ; Tic-tac-toe, exits

ld   a, (ix+1)             ; A = cell 1
add  a, (ix+5)             ; A+= cell 5
add  a, (ix+9)             ; A+= cell 9
cp   b                     ; Three in a row?
ld   a, WINNERLINE159      ; A = indicator line 159
ret  z                     ; Tic-tac-toe, exits

ld   a, (ix+3)             ; A = cell 3
add  a, (ix+5)             ; A+= cell 5
add  a, (ix+7)             ; A+= cell 7
cp   b                     ; Three in a row?
ld   a, WINNERLINE357      ; A = line indicator 357
ret                        ; Last condition, always comes out

In CheckWinner we point IX to the address above the grid, in B we load the value that the cells should add if one or the other player wins: three for player one and thirty for player two.

Then we check the possible combinations of three in a row that exist and leave if there were any, with the winning combination in A and the Z flag activated. To check if there were three in a row, we add up the values of the cells in A and check with B.

In the final check, if there are no three in a row, the Z flag is deactivated (NZ).

In main.asm we will add the lines to do the three in a row check and to act on whether it is successful or not. We add the following lines just below CALL PrintOXO.

ASM

loop_checkWinner:
call CheckWinner
jr   nz, loop_tie
ld   hl, TitlePointFor
ld   de, TitlePointName
call DoMsg
ld   hl, Points_p1
ld   a, (PlayerMoves)
or   a
jr   z, loop_win
inc  hl
loop_win:
inc  (hl)
jr   loop_reset 
loop_tie:

We call the tic-tac-toe check and skip if there are no tic-tac-toes. If there are three in a row, we draw the point-to message, find out which player made it and increase their score.

Just below loop_tie are these lines:

ASM

ld   a, (PlayerMoves)
xor  $01
ld   (PlayerMoves), a

We remove it and put it under the loop_cont tag, otherwise the next point will be started by the same player who won the previous one.

Finally, we add the loop_reset tag before LD BC, LENDATA-$01.

We compile, load into the emulator and everything seems to work, except for the bookmarks, which still don’t update.

We will visually mark where the three in a row have occurred by drawing a diagonal across the three tiles. We implement this routine in screen.asm.

ASM

; -------------------------------------------------------------------
; Print the winning line.
;
; Entry: A -> Winning line
;
; Alters the value of the AF, BC, DE and HL registers.
; -------------------------------------------------------------------
PrintWinnerLine:
ld   hl, COORDX            ; HL = coord X
ld   bc, $6c6c             ; BC = displacement
ld   de, $01ff             ; DE = orientation
cp   WINNERLINE159         ; Does line 159 win?
jr   z, printWinnerLine_159; Yes, skip
ld   e, $01                ; DE = orientation
cp   WINNERLINE357         ; Does line 357 win?
jr   z, printWinnerLine_357; Yes, skip

ld   c, $00                ; Displacement
cp   WINNERLINE147         ; Do you win line 147?
jr   z, printWinnerLine_147; Yes, skip
cp   WINNERLINE258         ; Does line 258 win?
jr   z, printWinnerLine_258; Yes, skip
cp   WINNERLINE369         ; Does line 369 win?
jr   z, printWinnerLine_369; Yes, skip

ld   bc, $006c             ; Displacement
ld   (hl), $48             ; Coord X
inc  hl                    ; Aim HL at coord Y
cp   WINNERLINE123         ; Do you win line 123?
jr   z, printWinnerLine_123; Yes, skip
cp   WINNERLINE456         ; Do you win line 456?
jr   z, printWinnerLine_456; Yes, skip
cp   WINNERLINE789         ; Does line 789 win?
jr   z, printWinnerLine_789; If so, jump to painting it.

printWinnerLine_159:
ld   (hl), $b7             ; Coord X
jr   printWinnerLine_Y

printWinnerLine_357:
ld   (hl), $48             ; Coord X
jr   printWinnerLine_Y

printWinnerLine_147:
ld   (hl), $58             ; Coord X
jr   printWinnerLine_Y

printWinnerLine_258:
ld   (hl), $80             ; Coord X
jr   printWinnerLine_Y

printWinnerLine_369:
ld  (hl), $a8              ; Coord X

printWinnerLine_Y:
inc  hl                    ; Aim HL at coord Y
ld   (hl), $10             ; Coord Y
jr   printWinnerLine_end   ; Paint the line

printWinnerLine_123:
ld   (hl), $70             ; Coord Y
jr   printWinnerLine_end   ; Paint the line

printWinnerLine_456:
ld   (hl), $47             ; Coord Y
jr   printWinnerLine_end   ; Paint the line

printWinnerLine_789:
ld   (hl), $20             ; Coord Y

printWinnerLine_end:
jp   DRAW                  ; Paint the line

PrintWinnerLine gets the winning line in A. First we evaluate which is the line to jump to one part of the routine or another. As the different lines to be drawn share common data, we only change the data that differs and call DRAW to draw the line and exit (see the DRAW comments in ROM.asm for more information).

In main.asm, locate the loop_checkWinner tag and add the following line under JR NZ, loop_tie:

ASM

call PrintWinnerLine

We compile, load in the emulator and see the results.

As we can see, a line is drawn by marking the three in a row, although it is so fast that we can hardly see it. In the next chapter we will use sound for timing.

However, if you want to check that the line is drawn, you can put these two lines below CALL PrintWinnerLine:

ASM

tmp:
jr   tmp

Don’t forget to remove them afterwards.

Scoreboard update

We are going to fix the long-standing bug that causes the scoreboard not to be updated.

In var.asm we locate the Grid tag and see that below it are the Points_p1, Points_p2 and Point_tie tags. We move these three tags to just below MoveCounter.

ASM

; -------------------------------------------------------------------
; Development of the game.
; -------------------------------------------------------------------
; Positions of the pieces on the board, 2 bytes per piece Y, X
GridPos:     db POS1_LEFT, POS1_TOP ; 1
             db POS2_LEFT, POS1_TOP ; 2
             db POS3_LEFT, POS1_TOP ; 3
             db POS1_LEFT, POS2_TOP ; 4
             db POS2_LEFT, POS2_TOP ; 5
             db POS3_LEFT, POS2_TOP ; 6
             db POS1_LEFT, POS3_TOP ; 7
             db POS2_LEFT, POS3_TOP ; 8
             db POS3_LEFT, POS3_TOP ; 9

; Board squares. One byte per square, from 1 to 9.
; Bit 0 to 1, square occupied by player 1.
; Bit 4 to 1, square occupied by player 2.
Grid:        db $00, $00, $00, $00, $00, $00, $00, $00, $00
MoveCounter: db $00        ; Move counter
Points_p1:   db $00        ; Points player 1
Points_p2:   db $00        ; Points player 2
Points_tie:  db $00        ; Points tables
PlayerMoves: db $00        ; Player moving

In main.asm, find the loop_reset tag, and on the bottom line, LD BC, LENDATA-$01, replace $01 with $04.

Compile, load into the emulator, and now the bookmarks are updated.

ZX Spectrum Assembly, Tic-Tac-Toe

In the next chapter of ZX Spectrum Assembly, we will implement different sounds and use them for timing by pausing between events.

Download the source code from here.

Useful links

ZX Spectrum Assembly, Tic-Tac-Toe – 0x01 Game board

Juan Antonio Rubio García — Mon, 02 Oct 2023 05:23:33 +0000

In this chapter of ZX Spectrum Assembly, we begin the development of another game, in this case Tic-Tac-Toe.

Translation by Felipe Monge Corbalán

Introduction

Tic-tac-toe was born from reading the book «ZX Spectrum Game Programming Club» by Gary Plowman. When we finish typing the Basic list in the book, he suggests adding the single player mode as an exercise.

Having concluded that Basic was not my thing, I decided to develop the game from scratch in Assembly, with the following options:

One and two player modes.
Possibility to specify the names of the players.
Points to be earned to finish the game.
Maximum time per move.

In Space Battle we saw the use of the ROM routine for keyboard handling, but it is in Tic Tac Toe where it is used most intensively.

We will also use interrupts to control the maximum time per move and give the user a countdown of the seconds left to move; he will lose his turn if he uses them up without having made the move.

At this point you should already have a certain level, so we will not explain the instructions one by one; we will explain what the routine does as a whole, which together with the comments should be sufficient for your understanding.

Game board

The first thing we are going to do is to design and paint the game board, which consists of a grid of nine cells.

We create the folder TicTacToe and the files:

Main.asm
Rom.asm
Screen.asm
Sprite.asm
Var.asm

This time I won’t create folders for each step, but if you prefer you can continue this way.

Sprites

We define the graphics in sprite.asm: the X for player one, the O for player two, the board crosshairs and the vertical and horizontal lines. As in Space Battle, we will use the UDGs.

The appearance of the graphics in sprite.asm is as follows:

ASM

; -------------------------------------------------------------------
; File: sprite.asm
;
; Definition of graphs.
; -------------------------------------------------------------------
; Sprite player 1
Sprite_P1:
db $c0, $e0, $70, $38, $1c, $0e, $07, $03 ; $90
db $03, $07, $0e, $1c, $38, $70, $e0, $c0 ; $91

; Sprite player 2
Sprite_P2:
db $03, $0f, $1c, $30, $60, $60, $c0, $c0 ; $92 Top/Left
db $c0, $f0, $38, $0c, $06, $06, $03, $03 ; $93 Up/right
db $c0, $c0, $60, $60, $30, $1c, $0f, $03 ; $94 Down/Left
db $03, $03, $06, $06, $0c, $38, $f0, $c0 ; $95 Down/Right

; Sprite crosshead
Sprite_CROSS:
db $18, $18, $18, $ff, $ff, $18, $18, $18 ; $96

; Sprite vertical line
Sprite_SLASH:
db $18, $18, $18, $18, $18, $18, $18, $18 ; $97

; Sprite horizontal line
Sprite_MINUS:
db $00, $00, $00, $ff, $ff, $00, $00, $00 ; $98

With the practice you got in Space Battle, you should be able to draw the sprites on paper to see how they look.

The next step is to draw the board. Constants are needed to reference the ROM, define positions, data to be painted and routines to paint it.

ROM routines and variables

The ROM constants are defined in rom.asm.

ASM

; -------------------------------------------------------------------
; File: rom.asm
;
; ROM routines and system variables.
; -------------------------------------------------------------------

; Permanent attributes of screen 2, main screen.
ATTR_S: equ $5c8d

; Current display attributes 2.
ATTR_T: equ $5c8f

; Edge attribute and screen 1. Used by BEEPER.
BORDCR: equ $5c48

; Address of starting coordinates X and Y (PLOT)
COORDX: equ $5c7d
COORDY: equ $5c7e

;--------------------------------------------------------------------
; Address where the keypad status flags are located when 
; the interruptions are not active.
;
; Bit 3 = 1 input in L mode, 0 input in K mode.
; Bit 5 = 1 a key has been pressed, 0 has not been pressed.
; Bit 6 = 1 numeric character, 0 alphanumeric.
;--------------------------------------------------------------------
FLAGS_KEY: equ $5c3b

;--------------------------------------------------------------------
; Address where the last key was pressed
; when interrupts are not active.
;--------------------------------------------------------------------
LAST_KEY: equ $5c08

; Direction of user-defined graphics.
UDG: equ $5c7b

; Start address of the graphics area of the VideoRAM.
VIDEORAM: equ $4000

; Length of the graphics area of the VideoRAM.
VIDEORAM_L: equ $1800

; Start address of the VideoRAM attributes area.
VIDEOATT: equ $5800

; Length of the VideoRAM attribute area.
VIDEOATT_L: equ $0300

;--------------------------------------------------------------------
; ROM beeper routine.
;
; Input: HL -> Note.
;        DE -> Duration.
;
; Alters the value of the AF, BC, DE, HL and IX registers.
;--------------------------------------------------------------------
BEEPER: equ $03b5

;--------------------------------------------------------------------
; Draw a line from the COORDS coordinates.
;
; Input: B -> Vertical displacement of the line.
;        C -> Horizontal displacement of the line.
;        D -> Vertical orientation of the line:
;               $01 = Up, $FF = Down.
;        E -> Horizontal orientation of the line:
;               $01 = Left, $FF = Right.
;
; Alters the value of the AF, BC and HL registers.
;--------------------------------------------------------------------
DRAW: equ $24ba

;--------------------------------------------------------------------
; ROM AT routine. Position the cursor.
;
; Input: B -> Y-coordinate.
;        C -> X-coordinate.
;
; The top left corner of the screen is 24, 33.
; (0-21) (0-31)
;--------------------------------------------------------------------
LOCATE: equ $0dd9

;--------------------------------------------------------------------
; ROM routine that opens the output channel.
;
; Input: A -> Channel (1 = lower display, 2 = upper display).
;--------------------------------------------------------------------
OPENCHAN: equ $1601

As you will see, we have added variables and routines that we have not seen before. Don’t worry, we’ll see them as we go along.

Variables

In var.asm we add the necessary data to paint the board.

ASM

; -------------------------------------------------------------------
; File: var.asm
;
; Variable and constant declarations.
; -------------------------------------------------------------------

; Board ink
INKBOARD: equ $04

; Position Y = 0 for LOCATE.
INI_TOP:  equ $18
; Position X = 0 for LOCATE.
INI_LEFT: equ $21
; Positions for painting OXO elements.
POS1_TOP: equ INI_TOP  - $07
POS2_TOP: equ POS1_TOP - $05
POS3_TOP: equ POS2_TOP - $05

POS1_LEFT: equ INI_LEFT  - $0a
POS2_LEFT: equ POS1_LEFT - $05
POS3_LEFT: equ POS2_LEFT - $05
; -------------------------------------------------------------------
; Graphics.
; -------------------------------------------------------------------
; Vertical lines of the board.
Board_1:		
db $20, $20, $20, $20, $97, $20, $20, $20, $20, $97, $20, $20, $20
db $20, $ff

; Horizontal lines of the board.
Board_2:		
db $98, $98, $98, $98, $96, $98, $98, $98, $98, $96, $98, $98, $98
db $98, $ff

; -------------------------------------------------------------------
; Parts of the screen.
; -------------------------------------------------------------------
; Guide numbers so that the player knows which key to press
; to place the tokens (O X O)
Board_Helper:
; Magenta ink
db $10, $03 
; AT,Y,X,number
db $16, $08, $0a, "1", $16, $08, $10, "2", $16, $08, $15, "3"
db $16, $0d, $0a, "4", $16, $0d, $10, "5", $16, $0d, $15, "6"
db $16, $12, $0a, "7", $16, $12, $10, "8", $16, $12, $15, "9"
db $ff

Screen

In screen.asm we will implement the necessary routines to draw the elements on the screen.

ASM

; -------------------------------------------------------------------
; Position the cursor. The upper corner is at 24.33.
;
; Input: B -> Y.
;        C -> X.
; -------------------------------------------------------------------
AT:
push af
push bc
push de
push hl                    ; Preserve records

call LOCATE                ; Position cursor

pop  hl
pop  de
pop  bc
pop  af                    ; Retrieves records
ret

The AT routine receives the Y and X coordinates simultaneously in the B and C registers (they are inverted coordinates). It calls the ROM routine that positions the cursor.

We will manage the different colour attributes in a differentiated way, with one routine for each attribute.

ASM

; -------------------------------------------------------------------
; Change the border colour.
;
; Input: A -> Colour for the border.
;
; Alters the value of the AF registers.
; -------------------------------------------------------------------
BORDER:
push bc                    ; Preserves BC
and  $07                   ; A = colour
out  ($fe), a              ; Change border colour

rlca
rlca
rlca                       ; Rotate three bits to the left to set
                           ; colour in paper/border bits
ld   b, a                  ; B = A
ld   a, (BORDCR)           ; A = system variable BORDCR
and  $c7                   ; Remove the paper/border bits
or   b                     ; Adds the paper/border 	colour

ld   (BORDCR), a           ; BORDCR = A, so that BEEPER does not change
pop  bc                    ; Retrieves BC

ret

The BORDER routine receives in A the colour to be assigned to the border. To make sure it is the right colour, we keep bits 0, 1 and 2. We change the border colour and then set the value in the system variable BORDCR so that BEEPER does not change it.

ASM

; -------------------------------------------------------------------
; Assigns the colour of the ink.
;
; Input: A -> Ink colour.
;             FBPPPIII
;
; Alters the value of the AF registers.
; -------------------------------------------------------------------
INK:
push bc                    ; Preserves BC
and  $07                   ; A = INK
ld   b, a                  ; B = A

ld   a, (ATTR_T)           ; A = current attribute
and  $f8                   ; A = FLASH, BRIGHT and PAPER
or   b                     ; Add INK

ld   (ATTR_T), a           ; Update current attribute
ld   (ATTR_S), a           ; Update permanent attribute
pop  bc                    ; Retrieves BC

ret

The INK routine gets the ink colour in A. We make sure to keep only the ink colour, get the current attributes, leave the flicker, brightness and background and add the ink. We update the system variables queried by RST $10 and by changing the channel to apply the colour attributes.

ASM

; -------------------------------------------------------------------
; Assigns the background colour.
;
; Input: A -> Background colour.
;
; Alters the value of the AF registers.
; -------------------------------------------------------------------
PAPER:
push bc                    ; Preserves BC
and  $07                   ; A = colour
rlca
rlca
rlca                       ; Rotate three bits to the left to set 
                           ; colour in paper/border bits
ld   b, a                  ; B = A
ld   a, (ATTR_T)           ; A = current attribute
and  $c7                   ; Remove background

or   b                     ; Add background
ld   (ATTR_T), a           ; Update current attribute
ld   (ATTR_S), a           ; Update permanent attribute
pop  bc                    ; Retrieves BC

ret

The PAPER routine gets the colour in A. We keep the colour, rotate it three bits to the left to put it in the background bits, and store it in B. We get the current attributes, remove the background, and add the one that came in A.

ASM

; -------------------------------------------------------------------
; Paints strings ending in $FF.
;
; Input: HL -> Address of the string.
;
; Alters the value of the AF and HL registers.
; -------------------------------------------------------------------
PrintString:
ld   a, (hl)               ; A = character to paint
cp   $ff                   ; Is it $FF?
ret  z                     ; Yes, exit
rst  $10                   ; Paints character
inc  hl                    ; HL = next character
jr   PrintString           ; Loop to end of string

The PrintString routine has already been seen in Space Battle, so it needs no explanation.

We will implement routines to clean up the whole screen, a line and the attributes.

ASM

; -------------------------------------------------------------------
; Changes the attributes of the VideoRAM with the specified attribute.
;
; Input: A -> Specified attribute (FBPPPIII)
;             Bits 0-2 Ink colour (0-7).
;             Bits 3-5 Paper colour (0-7).
;             Bit  6   Brightness (0/1).
;             Bit  7   Blink (0/1).
;
; Alters the value of the BC, DE and HL registers.
; -------------------------------------------------------------------
CLA:
ld   hl, VIDEOATT          ; HL = start attributes
ld   (hl), a               ; Change attribute
ld   de, VIDEOATT+1        ; DE = 2nd address attributes VideoRAM
ld   bc, VIDEOATT_L-1      ; BC = length attributes - 1
ldir                       ; Changes the attributes

ld   (ATTR_T), a           ; Updates system variable
ld   (ATTR_S), a           ; current attribute, permanent
ld   (BORDCR), a           ; and border
ret

The CLA routine receives in A the attributes to be assigned to the screen, in the format already seen above. It modifies them and updates the current, permanent and border attribute system variables.

ASM

; -------------------------------------------------------------------
; Deletes the specified screen line.
;
; Input: B -> Screen line to be deleted.
;             Inverted coordinates.
;
; Alters the value of the AF registers.
; -------------------------------------------------------------------
CLL:
ld   a, (ATTR_T)           ; A = current attributes
and  $3f                   ; A = PAPER + INK
ld   (ATTR_T), a           ; Update in memory

push bc                    ; Preserves BC

ld   c, INI_LEFT           ; C = 1st column
call AT                    ; Position cursor
ld   b, $20                ; B = 32 columns*line
CLL_loop:
ld   a, $20                ; A = space
rst  $10                   ; Prints it out
djnz CLL_loop              ; Loop while B > 0

pop  bc                    ; Recover BC

ret

The CLL routine receives the line to be deleted in A (with inverted coordinates) and deletes it. Before it does this, it removes the brightness and blinking of the current attributes.

ASM

; -------------------------------------------------------------------
; Deletes the graphics from the VideoRAM.
;
; Alters the value of the BC, DE and HL registers.
; -------------------------------------------------------------------
CLS:
ld   hl, VIDEORAM          ; HL = VideoRAM address
ld   de, VIDEORAM+1        ; DE = 2nd address VideoRAM
ld   bc, VIDEORAM_L-1      ; BC = length VideoRAM - 1
ld   (hl), $00             ; Clean 1st position
ldir                       ; Clean up the rest

ret

The CLS routine erases the graphic area of the screen, the pixels.

As in Space Battle, we will draw some numerical data in BDC format, but this time, because the range of numbers will be between zero and ten, we will check if the ten is zero to draw a space instead.

ASM

; -------------------------------------------------------------------
; Paints the value of BCD numbers.
;
; It only paints numbers from 0 to 99.
;
; Input: HL -> Pointer to the number to be painted.
;
; Alters the value of the AF register.
; -------------------------------------------------------------------
PrintBCD:
ld   a, (hl)               ; A = number to paint
and  $f0                   ; A = tens
rrca
rrca
rrca
rrca                       ; Tens to bits from 0 to 3
or   a                     ; Tens = 0?
jr   nz, PrintBCD_ascii    ; No, skip
ld   a, ' '                ; Tens = 0
jr   PrintBCD_continue     ; Paint space

PrintBCD_ascii:
add  a, '0'                ; A = A + Ascii code of 0

PrintBCD_continue:
rst  $10                   ; Paint 1st digit
ld   a, (hl)               ; A = number to paint
and  $0f                   ; Keeps the units
add  a, '0'                ; A = A + Ascii code of 0
rst  $10                   ; Print 2nd digit
ret

PrintBCD gets the HL pointer to the number to paint, loads it into A, takes the tens and if they are zero, paints a space. The rest of the routine is the same as in Space Battle.

We have almost everything ready to paint the board, we just need the routine to do it.

ASM

; -------------------------------------------------------------------
; Paint the board.
;
; Alters the value of the AF, BC, D and HL registers.
; -------------------------------------------------------------------
PrintBoard:
ld   a, INKBOARD           ; A = ink
call INK                   ; Change ink

; Initial coordinates of the board
ld   b, INI_TOP-$06        ; B = coord Y
ld   c, INI_LEFT-$09       ; C = coord X
ld   d, $0e                ; D = number of rows board

printBoard_1:
call AT                    ; Position cursor
ld   hl, Board_1           ; HL = vertical line
call PrintString           ; Paints vertical line characters
dec  b                     ; B-=1, next line
dec  d                     ; D-=1
jr  nz, printBoard_1       ; Loop while D > 0

printBoard_2:
; Coordinates of the first horizontal line
ld   b, INI_TOP-$0a        ; B = coord Y
ld   c, INI_LEFT-$09       ; C = coord X
call AT                    ; Position cursor
ld   hl, Board_2           ; HL = horizontal line
call PrintString           ; Paint horizontal line

; Coordinates of the second horizontal line, 
; X-coordinate does not change.
ld   b, INI_TOP-$0f        ; B = coord Y
call AT                    ; Position cursor
ld   hl, Board_2
call PrintString           ; Paint horizontal line

printBoard_3:
; Paints the guide numbers so that the user knows which key to press
; To place the tokens (O X O)
ld   hl, Board_Helper      ; HL = helper
jp   PrintString           ; Paints helper and exits

PrintBoard paints the board, changes the ink and prepares everything for painting the vertical line, which is painted on printBoard_1. The horizontal line is painted on printBoard_2 and the guide for the player to know which keys to press is painted on printBoard_3.

When the vertical and horizontal lines are drawn, the vertical line is erased where it crosses. Look closely at the definition of board2 and you will see that the same character is not painted over the whole board.

Main

To see if everything works, we implement the first version of the main.asm file.

ASM

org  $5e88

Main:
ld   hl, Sprite_P1
ld   (UDG), hl
ld   a, $02   
call OPENCHAN

xor  a
call BORDER
call CLA
call CLS

Init:
call PrintBoard

Loop:
jr   Loop

include "rom.asm".
include "screen.asm"
include "sprite.asm"
include "var.asm"

end  Main

We set the start address, bearing in mind that we will be making a custom loader. We show where the UDGs are, open channel two, change the border, attributes, clear the screen and paint the board. We stay in an infinite loop, which will be the main loop.

We compile, load into the emulator and see the results.

ZX Spectrum Assembly, Tic-Tac-Toe

We already have the board on which the game will be played.

In the next chapter of ZX Spectrum Assembly, will be to implement the scoreboards and the two-player game, which will form a large part of the programme.

Download the source code from here.

Useful links

ZX Spectrum Assembly, Space Battle – 0x0F ZEsarUX

Juan Antonio Rubio García — Sun, 01 Oct 2023 06:42:48 +0000

In this chapter of ZX Spectrum Assembly, we will go deeper into the use of ZEsarUX.

Translation by Felipe Monge Corbalán

ZEsarUX

Throughout this tutorial I have used ZEsarUX, an emulator developed by César Hernández Bañó, which you can get for free at https://github.com/chernandezba/zesarux. César is constantly adding new features and making improvements.

We have used ZEsarUX as a ZX Spectrum emulator, but it is capable of emulating many machines and doing many other things.

In this chapter we will not be creating folders, copying files or generating code.

Personalisation

The first step is to set up ZEsarUX to suit your needs. ZEsarUX has many options that can be configured, but we are going to focus on the ones that I think are most interesting for the use we are going to make of it in this book. I encourage you to do your own research.

To customise ZEsarUX, press F5 to access the menu and then click on Preferences.

The first thing we need to do is configure a function key to restart the machine and another to enter debugging. Go to Settings and select the Function Keys option.

Once in the Function Keys, select the F11 key by either clicking or pressing Enter.

Once the key has been selected, we are shown the options available to us; we choose DebugCPU. We repeat the operation for the F12 key, but in this case we select Reset.

We need to test the buttons. Leave the menu by pressing Esc until it closes completely, or press F5 to go to the main menu and then Esc.

Once the menu is closed, check that pressing F11 opens the debug window and that pressing F12 restarts the machine.

There are many functions that can be associated with a function key, in fact I have defined several keys.

I do not define F5 or F9 as one opens the menu and the other gives direct access to file upload.

When debugging, I keep the debug window and the memory window visible, so it can be inferred that I am running out of space.

Next we go to Settings, select ZX Desktop and then the first option, Enabled. When you select it, more options are displayed, the first of which we are interested in, width. Click on it until the value is 512 (or another value that suits you). We can also set the value directly if we select custom Width.

To open the menu on the desktop, select the Open Menu on ZX Desktop option. On the other hand, if you don’t want the menu to open when you click on it, I find it more convenient to go to Preferences/General and uncheck the Clicking mouse open menu option.

Now we have space to open other windows so that they don’t share space with the screen of our beloved ZX Spectrum.

As I mentioned before, I like to have both the debug and memory windows visible while debugging. We need to change some options to be able to see how the memory is being updated while the program is running, and to be able to stop execution when the menu is open.

Go to Settings/ZX Vision and almost at the end, select the options Stop emulation on menu and Background Windows. Once the second option is activated, you will see another option to activate Even when menu closed.

We have already set up the environment. All we need to do is open the debug windows and the hexadecimal editor from the Debug menu and place them where we want them; press F11 to open the debug window.

Under Settings/General we can change the language, although at the time of writing not all terms have been translated.

If at any time the windows do not respond, press F5.

Debugging

Let’s say we have a program and we load it at address $8000; make sure you don’t have the 16K machine selected or it won’t work.

ASM

org  $8000

Start:
ld   hl, $4000
ld   de, $8100
ld   a, $ff

Loop:
ld   (hl), a
ld   (de), a
dec  a
jr   nz, Loop

Exit:
jr   Start

end  $8000

In this programme we point HL to the start of the VideoRAM, DE to position $8100 and load 255 ($FF) into A. Then we go through a loop in which we load the value of A into the positions pointed to by HL and DE and decrement A. At the end of the loop we go back to the start and continue in an infinite loop.

The programme is very simple, but it is enough to show what I want to show you.

The first thing we do is go into Debug and set a breakpoint at memory address $8000 so that execution stops at the start of the programme.

The different options are accessed by pressing the key corresponding to the highlighted letter.

In the central part of the screen, on the left, we see the disassembled code and the address where each instruction is assembled. On the right, we see mainly the value of the different registers and the state of the flags. Just below this we see the values of the stack.

At the top and bottom we see the different options; we will only see the ones we need to start debugging our programs.

On the top right we see 1-7: View. Clicking from one to seven will show different views of this window; by default view one is shown.

At the top left we see mptr. Pressing the M key opens a window where we can enter the address we want to go to. If we are entering hexadecimal values, the suffix H must be used.

Once we have entered the address, we press Enter and the disassembly from that address is displayed.

As we haven’t loaded any programs yet, the only disassembly we see is NOP ($00).

We set a breakpoint at address $8000. If we look at the fourth option in the second line of options, at the bottom of the window, we see Togl; by pressing the L key we set or remove a breakpoint on the selected line.

We already have a breakpoint set at address $8000. When the program is loaded it will stop at this address and we will enter debugging mode. Press the N (Run) key to continue and return to Basic.

ZEsarUX displays a window warning us that there is a breakpoint, we have to press a key to enter the Debug window. We can prevent this window from appearing in the debug properties.

We load the program and debug it.

To follow the programme, we can run it intwo ways: en: Stp and Stovr. In other environments, these are known as Step-by-instruction and Step-by-procedure.

Step by step by instructions (Enter) executes the instructions one by one, and when we are faced with a CALL to a routine, either ours or from the ROM, we enter it, with the possibility of executing it step by step and seeing its code.

In step by step procedures (O key), the execution is done instruction by instruction, but when we are faced with a CALL to a routine, either ours or from the ROM, it is executed and the PC (program counter) is passed to the instruction following the CALL; this must be taken into account in the loops.

In our programme, when PC is at instruction JR NZ, 8008, if we press Enter and A is not zero, it will jump to address $8008. Conversely, pressing O will execute the whole loop (all iterations) and point PC to the next instruction, JR 8000. Try it and see how it works.

At each iteration of the loop, it loads the value of A into the addresses pointed to by HL and DE. We can only see the different values loaded at the address pointed to by HL because it points to VideoRAM.

To see how the value of address $8100 changes, press F5, select the Hexadecimal Editor window, press M (memptr), type in address 8100H and press Enter.

If we remove the breakpoint and press N (Run) we will see that the position $8100 is updated.

With this you should be able to debug programs, although ZEsarUX offers much more power, but it’s up to you to discover it, but let’s talk about one last thing: adding or modifying code directly in the debugger.

In the first line of options at the bottom, pressing the S (stM) key will display other options. Pressing the A (assemble) key allows us to modify the instruction at the selected address. To leave the Assemble window, press the Esc key.

In our case, we will change the VideoRAM address where we load the value of A to column ten.

As you can see in the picture, the value of A is painted in column ten.

ZX Spectrum Assembly, Space Battle

We have adapted ZEsarUX and acquired the necessary knowledge to debug our programs, but ZEsarUX is very powerful and there is still a lot to discover.

Download the source code from here.

Useful links

ZX Spectrum Assembly, Space Battle by Juan Antonio Rubio García.
Translation by Felipe Monge Corbalán.
This work is licensed to Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0).
Any comments are always welcome.