CODE & BOOKS
Cover of MSX Assembly: white title on black under a Z80 listing, the MSX logo in a frame, red, orange, yellow and blue stripes, and a line drawing of an MSX computer in blue on a grid.
MSXOn Amazon

MSX Assembly

Z80 code on the MSX1, measured on the machine: two complete games, and every screen photographed

by Aravind J. Deshmukh and Henry Radclyffe

Buy the paperbackon Amazon.com
Other Amazon stores

The code is free · MIT

Download from GitHub zip

Chapter by chapter · Repository on GitHub

From your first byte to two complete games

On the MSX, the picture is not in the processor’s memory. It lives in sixteen kilobytes that belong to the video chip, and the processor reaches them only through a pair of ports, a byte at a time, at a speed the video chip decides. This book teaches Z80 assembly language on the MSX1 by facing that fact head on, and it measures what it claims.

It begins before the beginning: binary and hexadecimal, then the sjasmplus assembler, the openMSX emulator and C-BIOS on Windows, macOS and Linux. Part II teaches the Z80 one family of instructions at a time and prices each in T-states. Then graphics, sound, input and cartridge memory, and along the way two original games, Grin Alley, a single-screen arcade game in which a runner crosses four alleys of faces to pick up gems, and Lantern Keep, a keep of sixteen rooms with thirty-two lanterns to light and twenty-eight guards on their rounds.

Every program is yours. The companion repository holds every program of the book, in a folder for each chapter, with the cartridges that were photographed, the measuring scripts and the twelve machines of the book for openMSX. A verification program reassembles every program and compares it, byte for byte, with the cartridges the book was photographed from. The code is free to use under the MIT licence.

Understand the machine. Build with confidence.

Inside the book

  • Z80 instructions, registers, flags, the stack and macros, priced in T-states with the wait the MSX adds to every opcode fetch
  • The VDP: sixteen kilobytes behind two ports, the screen modes, Graphic II and colour clash, tiles, hardware sprites and scrolling
  • The PSG and a music and effects engine that runs from the interrupt, keyboard and joysticks
  • Collisions, score, game states and the frame budget at 50 and 60 Hz
  • MegaROM banking, a 128 KB cartridge, compression and optimisation
  • Grin Alley and Lantern Keep: two complete games, from source to ROM

What makes this book different

  • Every screen is real

    202 of the 219 figures are frames captured from openMSX while it ran a program from the book's repository, which the caption names. No screen was drawn or redrawn.

  • Measured, not remembered

    Every number was measured on openMSX by a program written to produce it, and chapter 55 gives you a cartridge that measures, on a real MSX, what an emulator may get wrong.

  • Two complete games

    Grin Alley, a single-screen arcade game, and Lantern Keep, a keep of sixteen rooms, from the first line of a specification to a cartridge. Appendices K and L print their sources, commented.

  • Learn from the broken screen

    57 “Where it breaks” boxes, 50 “Count the T-states” and a Workshop at the end of every chapter, with the answers in appendix I.

Contents

7 parts, 56 chapters

Code for every chapter →

Part I Before the first byte

  1. 01A machine made from a standard: what MSX is, and why it is programmed this way

    ch01/ on GitHub

  2. 02Numbers a computer understands: bits, bytes, hexadecimal, and two's complement

    ch02/ on GitHub

  3. 03Inside the case: the Z80, the VDP, the PSG, the PPI, and the slots

    ch03/ on GitHub

  4. 04Setting up the development environment: sjasmplus, openMSX, and C-BIOS

    ch04/ on GitHub

  5. 05Your first program: a coloured border, from source to cartridge, photographed

    ch05/ on GitHub

  6. 06Seeing inside the machine: the openMSX debugger

    ch06/ on GitHub

Part II The Z80 language

  1. 07Registers, flags, and the shape of a Z80 instruction

    ch07/ on GitHub

  2. 08Moving data: LD and every addressing mode

    ch08/ on GitHub

  3. 09Arithmetic: eight-bit and sixteen-bit sums, carries, and BCD

    ch09/ on GitHub

  4. 10Logic, bits, shifts, and rotates

    ch10/ on GitHub

  5. 11Making decisions: the flags, JP, JR, DJNZ, and conditional returns

    ch11/ on GitHub

  6. 12Subroutines and the stack: CALL, RET, PUSH, POP, and the shadow registers

    ch12/ on GitHub

  7. 13Blocks, tables, and the index registers: LDIR, IX, IY, and lookup tables

    ch13/ on GitHub

  8. 14Counting T-states: the Z80 at 3.58 MHz, and the wait the MSX adds to every M1

    ch14/ on GitHub

  9. 15sjasmplus for the MSX: labels, macros, the cartridge header, and a ROM image

    ch15/ on GitHub

  10. 16The BIOS as a library: the jump table, the system variables, and the hooks

    ch16/ on GitHub

Part III The VDP: video memory behind a port, tiles, and thirty-two sprites

  1. 17Taking the machine: the BIOS interrupt, the H.TIMI hook, and an interrupt of your own

    ch17/ on GitHub

  2. 18How a frame is built: 228 T-states a line, 313 lines in Europe and 262 in Japan

    ch18/ on GitHub

  3. 19Talking to the VDP: two ports, eight registers, and sixteen kilobytes you cannot address

    ch19/ on GitHub

  4. 20How fast the VDP listens: access slots, the 29 T-state loop, and what a write too soon destroys

    ch20/ on GitHub

  5. 21The screen modes: text, Graphic I, Graphic II, and multicolour

    ch21/ on GitHub

  6. 22Graphic II, the screen of the games: three thirds, 768 patterns, and colour in strips of eight

    ch22/ on GitHub

  7. 23Colour clash on the MSX: two colours in eight pixels, and how to draw around it

    ch23/ on GitHub

  8. 24Tiles and the name table: screens built from 8 × 8 pieces, and a copy in RAM

    ch24/ on GitHub

  9. 25Plotting and drawing in Graphic II: pixels and lines through a port

    ch25/ on GitHub

  10. 26Hardware sprites I: the attribute table, patterns, size, magnification, and the early clock

    ch26/ on GitHub

  11. 27Hardware sprites II: four on a line, the fifth-sprite flag, and flicker by rotation

    ch27/ on GitHub

  12. 28Software sprites in the tiles: redrawing patterns to move what the hardware cannot

    ch28/ on GitHub

  13. 29Scrolling without hardware help: by tile, by pre-shifted tiles, and what each costs

    ch29/ on GitHub

  14. 30Fonts and text: the BIOS character set, a set of your own, and a status line

    ch30/ on GitHub

  15. 31Fast transfers to VRAM: unrolled OUTI, the vertical-blank budget, and the blanked screen

    ch31/ on GitHub

  16. 32Racing the beam on an MSX1: register changes in mid-frame, timed from the interrupt

    ch32/ on GitHub

Part IV Making it a game machine

  1. 33The frame loop: the interrupt as a heartbeat, fifty or sixty times a second

    ch33/ on GitHub

  2. 34Reading the keyboard: the PPI, eleven rows, ghosting, and layouts that change by country

    ch34/ on GitHub

  3. 35Joysticks through the PSG: two ports, two buttons, and one standard

    ch35/ on GitHub

  4. 36The PSG: three tones, noise, envelopes, and the mixer bits that must not move

    ch36/ on GitHub

  5. 37An engine for sound effects and music that runs from the interrupt, at 50 and 60 Hz

    ch37/ on GitHub

  6. 38Slots and memory: where the RAM is, how a 32 KB cartridge finds itself, and where things live

    ch38/ on GitHub

  7. 39Collisions: tile tests, bounding boxes, and the coincidence flag

    ch39/ on GitHub

  8. 40Score, text, and a status line that never flickers

    ch40/ on GitHub

  9. 41Random numbers, the R register, and game states

    ch41/ on GitHub

  10. 42The frame budget: fitting a game into 59,736 T-states

    ch42/ on GitHub

Part V Two complete games

  1. 43The first game I: a single-screen arcade game, from specification to cartridge

    ch43/ on GitHub

  2. 44The first game II: sound, score, difficulty, and the finished ROM

    ch44/ on GitHub

  3. 45The second game I: a flip-screen world, rooms in ROM, and a map

    ch45/ on GitHub

  4. 46The second game II: enemies, items, music, and the finished ROM

    ch46/ on GitHub

  5. 47Where to go next: three projects, sketched

    ch47/ on GitHub

Part VI Beyond the 32 KB cartridge

  1. 48MegaROMs: mappers, banks, and a 128 KB cartridge

    ch48/ on GitHub

  2. 49Samples through the PSG: drums and voices from the volume registers

    ch49/ on GitHub

  3. 50Tape and disk: BLOAD, CAS and DSK files, and when a cartridge is not the answer

    ch50/ on GitHub

  4. 51One cartridge, many machines: makers, MSX2 and later, 50 and 60 Hz, and the slot zoo

    ch51/ on GitHub

  5. 52Optimisation: T-states, unrolled loops, code copied to RAM, and self-modifying code

    ch52/ on GitHub

Part VII The rest of the craft

  1. 53Compression: RLE, and a packer for screens and levels, unpacked straight into VRAM

    ch53/ on GitHub

  2. 54Title screens, demo mode, and attract mode

    ch54/ on GitHub

  3. 55Testing on real hardware: real MSX machines, flash cartridges, and the video output

    ch55/ on GitHub

  4. 56Releasing your work: ROM files, cartridges, labels, and the MSX scene today

    ch56/ on GitHub

Appendices

  1. AThe Z80 instruction set, with T-states measured on the MSX
  2. BThe undocumented Z80: SLL, the index-register halves, and the hidden flags
  3. CThe VDP, the PSG, and the PPI: every register and every port
  4. DGraphic II address tables: pattern, colour, and name for every cell
  5. EThe fifteen colours, measured, and what they become in grey
  6. FThe BIOS: the jump table and the system variables this book uses
  7. Gsjasmplus and openMSX command reference
  8. HTroubleshooting: what a broken screen is telling you
  9. IWorkshop solutions, every chapter
  10. JGlossary and reading paths
  11. KThe first game: the complete source, commented
  12. LThe second game: the complete source, commented
  13. MIndex

Errata

Corrections

No errors have been reported for this edition yet.

Found a mistake? Open an issue on GitHub or write to [email protected], with the page number and what it should say.