Making an MSX game — a snake, step by step

What you need

• The MSX: the MSX app, right here in your browser — or MSX.eeform in EEditor (download). Load cartridge… takes a .rom; click the screen so it gets the keys. Snake plays the finished game.

• The assembler: z80asm.mjs, one file with nothing else needed but Node.js. It turns a .asm file into a .rom:

  node z80asm.mjs step1.asm          → step1.rom
  node z80asm.mjs step1.asm -l       the same, and a listing: address, bytes, source
  

  It takes the usual Z80 source syntax, close to sjasmplus's.

• The source of each step, below.

So the loop is: edit → node z80asm.mjs → Load cartridge…. After you rebuild, load the new .rom again; Reset restarts the cartridge that's already loaded.

Step 1 — a cartridge that says hello

step1.asm

The header

When the MSX starts, the BIOS looks in each slot for the letters AB. If it finds them at 0x4000, it calls the address stored right after them:

         org 0x4000             ; the bytes that follow go at 0x4000
         db "AB"
         dw start               ; where our program starts
         ds 12                  ; the rest of the 16-byte header: unused

Calling the BIOS

The BIOS has an entry point for each routine at a fixed address, the same on every MSX. We give them names with equ:

CHGCLR   equ 0x0062     ; set the screen's colours from FORCLR, BAKCLR and BDRCLR
INIT32   equ 0x006F     ; SCREEN 1: 32×24 tiles of 8×8 pixels
FORCLR   equ 0xF3E9     ; the BIOS's colour variables, in RAM

start:   ld a,15                ; white letters
         ld (FORCLR),a
         ld a,4                 ; on dark blue
         ld (BAKCLR),a
         ld (BDRCLR),a
         call CHGCLR
         call INIT32            ; SCREEN 1, the font loaded, the screen cleared

The MSX has 16 colours, numbered 0–15: 1 black, 4 dark blue, 15 white, and so on. You can see all 16 in TMS_PALETTE in src/display/tms9918.ts.

SCREEN 1

The whole game uses SCREEN 1, "Graphics I" in the chip's own terms. The screen is a grid of 32×24 cells, and each cell shows one of 256 tiles of 8×8 pixels. Three tables in video memory make the picture:

INIT32 loads the font into the patterns, so tile 65 is a letter A. To put a letter on the screen, we write its code into the names table. The cell at column x, row y is at 0x1800 + y*32 + x.

Writing to the video chip

setwrite:
         di
         ld a,l
         out (VDP_CTRL),a       ; the address's low byte…
         ld a,h
         or 0x40                ; …then the high byte, with 01 in the top bits: for writing
         out (VDP_CTRL),a
         ei
         ret

After this, each out (VDP_DATA),a writes a byte and moves the address on. print uses it to write a string that ends in 0, starting at cell DE.

Why di/ei? Sixty times a second the video chip interrupts the Z80, and the BIOS's interrupt handler reads the chip's status. That read resets the chip's "first or second byte?" latch. If the interrupt came between our two bytes, the chip would take our second byte as a first one. So the two outs go with interrupts off.

Doing nothing, properly

forever: ei
         halt                   ; wait for the next frame, for ever
         jr forever

halt stops the Z80 until the next interrupt, which arrives at the start of every frame, 60 times a second. A game's main loop is exactly this, with work between the halts. It's how the game keeps time.

Build it, load it, and the screen says hello.

Step 3 — the snake moves

step3.asm

Where the snake is: a ring

The snake is a list of cells, from its tail to its head. Each step, a new cell goes on at the head and one comes off at the tail. A ring buffer does this without moving anything: 256 entries of 2 bytes at RING, and two one-byte indexes. HEADI is the head's entry and TAILI the tail's. Moving means inc on each index, and because they're bytes, 255 wraps round to 0 by itself. ringat turns an index into the entry's address.

A cell is a number from 0 to 767 (y*32 + x). That makes moving a single addition: +1 is right, −1 left, +32 down, −32 up. DIR holds the one we're going in.

Time

The main loop runs once per frame. The snake moves only once every SPEED frames, counted down in TIMER. With 8 frames per step that's 7.5 cells a second:

play:    ei
         halt                   ; the next frame
         call steer             ; read the keys every frame…
         ld hl,TIMER
         dec (hl)
         jr nz,play             ; …but move only when the timer runs out
         ld a,(SPEED)
         ld (TIMER),a
         call step
         jr nc,play             ; no carry: still alive

Steering

GTSTCK with A=0 reads the cursor keys as a direction: 1 up, 3 right, 5 down, 7 left (and the diagonals in between). steer turns that into a step and keeps it in WANT. It doesn't go into DIR straight away: step takes it only if it isn't the exact opposite of DIR, which would send the snake into its own neck. A direction plus its opposite is 0, so that's the test:

step:    ld hl,(WANT)
         ld de,(DIR)
         add hl,de              ; a direction and its opposite add up to 0
         ld a,h
         or l
         jr z,.ahead            ; straight back: ignore it

Moving, and crashing

Each step:

1. The head's cell becomes BODY.
2. The next cell is the head's cell + DIR.
3. get reads the tile on that cell from the names table (setread, then in a,(VDP_DATA)). The screen is our map: if the cell isn't EMPTY, we've hit a wall or ourselves. We return with the carry flag set.
4. Otherwise HEAD goes on the new cell, and the cell is added at HEADI.
5. The tail's cell becomes EMPTY, and TAILI moves on.

When step returns with the carry set, the main loop prints GAME OVER and stops.

Step 5 — sound, a title, the best score, again

snake.asm

Sound

The PSG is set through its registers: WRTPSG writes E into register A. psg writes a list of register and value pairs that ends with 0xFF, so each sound is a line of data:

quiet:   db 7,0b10011110, 8,0, 9,0, 10,0, 0xFF
chomp:   db 0,80, 1,0, 8,16, 10,0, 11,0, 12,4, 13,0, 0xFF
crash:   db 6,31, 8,0, 10,16, 11,0, 12,40, 13,0, 0xFF

The envelope makes each sound fade out by itself. The game starts a sound and never has to stop it, so there's no sound code in the main loop. The eating blip is channel A's tone with a short envelope. The crash is noise on channel C with a long one.

The title, and random apples at last

Before the first game, the program draws the field with the title over it and calls waitspace. waitspace waits for Space to be let go, then pressed (GTTRIG with A=0 is the space bar). It calls frame once per frame, and frame also adds 1 to SEED. How long the player takes to press Space decides where the apples fall, so no two games are the same.

The best score

BCD numbers compare just like ordinary ones, so finding a new best is a 16-bit subtraction:

         ld hl,(HISCORE)
         ld de,(SCORE)
         or a                   ; clear the carry…
         sbc hl,de              ; …HISCORE − SCORE: a carry means SCORE is higher
         jr nc,.over
         ld (HISCORE),de

Then GAME OVER, waitspace, and jp newgame. The game goes on as long as you want to play.

When something goes wrong

• A BIOS call changed my registers. Most BIOS routines change AF, BC, DE and HL. Keep what you need with push/pop around the call, as psg does around WRTPSG.
• "the jump is … out of reach". JR and DJNZ reach only 127 bytes either way. Use JP.
• The screen is garbled. The two bytes to VDP_CTRL were split by the interrupt (keep them in di/ei), or a tile went past the screen (cell over 767).
• Nothing happens at all. Check the header: "AB" at 0x4000 and the dw start after it. Build with -l and look at the listing.
• The program freezes. Look for a halt with interrupts off. ei before each halt.
• The .rom is too big. The final ds 0x8000 - $ says "the code before it is too long" if the program grows past 16 KB. Without a mapper a cartridge can be 32 KB: ds 0xC000 - $ (docs/msx/MSX.md).