A byte-exact, 100 %-line-commented disassembly of the ZX Spectrum classic Head Over Heels (Jon Ritman & Bernie Drummond / Ocean, 1987 — the "Filmation II" isometric engine), with a narrated code-walk and a full set of study aids.
Left: the original title / option screen, decoded from the snapshot. Right: a room re-rendered by driving the game's own room-enter + redraw under the project's Z80 emulator — play-field 99.6 % identical to the real machine.
| Commented | 8 803 / 8 803 code instructions = 100 % |
| Faithful | byte-exact — reassembles to the original, same SHA-256 |
| Targets | ZX Spectrum 48K (beeper) + 128K (AY music) |
| Extras | EN + SK code-walk · extracted graphics · 301 room renders · Python reimplementation |
The friendliest way in is the code-walk — a 19-part narrative that builds the whole engine up one machine instruction at a time, every chapter grounded in real addresses. Written in English and Slovak.
| 00–02 | what makes it tick · anatomy of one frame · the heartbeat |
| 03–07 | reading the player's will · a world from bits · objects that draw themselves · walk/jump/carry · collision |
| 08–11 | death & lives · 3D → pixels · showing the dirty bits · music for two machines |
| 12–18 | where the sprites live · a castle of 301 rooms · a bestiary of behaviours · colour on a clash machine · the front end · proving it true · the trick reel |
Prefer a reference map over a narrative? → docs/hoh_study_guide.md.
The Filmation II engine runs a fixed 50 Hz frame: read controls → update every object → project to isometric → masked-blit back-to-front into an off-screen buffer → flush the dirty rectangles to the screen. Collision is object-vs-object (there is no tile map), and all ~300 rooms are bit-packed, decompressed on entry.
| RAM | Holds | Subsystem | Entry | Does | |
|---|---|---|---|---|---|
&4000–&5AFF |
screen bitmap + attrs | main loop / IRQ | &7030 / &706B |
per-frame update chain @ 50 Hz | |
&5B00–&702F |
301 rooms, bit-packed | object model | draw_object &82A1 |
updates and draws each object (type 1–37) | |
&7030–&FF62 |
game code | render | render_room &93B0 |
iso projection, 12 blit variants, dirty-rect flush | |
&B800–&BFFF |
v_buf off-screen buffer |
rooms | room_decode &780E |
bit-stream decode + shared object-group macros | |
&C000–&F9FF |
sprite bitmaps + masks | sound | &9675 / &964F |
beeper (48K) · AY driver (128K) |
Deeper dives: the big-picture analysis docs/hoh.md, the engine brief
frags/AGENT_CONTEXT.md, plus focused docs on the
isometric projection, room compression,
sound, data structures and
Z80 idioms.
| Path | Contents |
|---|---|
hoh_full_commented.asm |
the whole game in one file — every code line commented |
hoh_code_*.asm |
the same code split into 29 bands by function (index + coverage proof) |
hoh.asm |
a curated, prose-commented extract of the highest-value routines |
docs/ |
study docs + the codewalk/ narrative (EN + sk/) |
frags/ |
the per-line comment sources (one dict per band) + the engine brief |
gfx/ · rooms/ |
extracted sprites & font · 301 engine-rendered rooms |
reimpl/ |
a runnable Python / Pygame teaching reimplementation |
data/ · snapshots/ |
binary RAM images + .szx/.tap — the two sources of truth |
*.py, Makefile |
the toolchain that regenerates every artifact above |
Everything is generated from two sources — the data/symbol map in build_listing.py
and the per-line comments in frags/ — so never hand-edit the .asm: edit the source and
run make.
make # regenerate all listings, symbols, graphics and room renders
make verify # prove byte-exactness: reassemble == original (SHA-256)
make help # list every targetRequirements: python3 (+ Pillow), z80dasm, and z88dk's z80asm. The round-trip uses an
independent assembler, so a make verify pass genuinely proves the code/data split
(VERIFICATION.md). To step through the code in an emulator, load
hoh.sym / hoh_sjasm.sym / hoh.lbl — see docs/SYMBOLS.md.
| Effect | POKE | Where |
|---|---|---|
| Infinite lives | POKE 42195,0 |
&A4D3 (SUB 1 → SUB 0) |
| Immortality | POKE 45844,175 |
&B314 (AND A → XOR A, at flag_kill) |
snapshots/hoh_lives.szx ships with infinite lives already applied.
Reverse-engineered from Fuse .szx snapshots (snapshots/hoh.szx 48K, snapshots/hoh128.szx
128K). No comment is fabricated: where a routine's purpose wasn't proven, the comment
states mechanically what the code does, and sprite labels are by behaviour (from the
code), never guessed lore. The disassembly is byte-exact — make verify reassembles it
to a binary identical (SHA-256) to the original &4000–&FFFF RAM image.
Original game © 1987 Ocean Software / Jon Ritman & Bernie Drummond. This is an unofficial reverse-engineering for study and preservation.



