Skip to content

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Head Over Heels — Reverse-Engineered & Fully Commented

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.

Head Over Heels 48K title screen Room &8A re-rendered by the disassembly

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

▶ Start with the code-walk

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 engine at a glance

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.


What's in the repo

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

All 301 rooms on the world grid

All 301 rooms reconstructed onto the world grid with teleport links (full [room contact sheet](rooms_contact_sheet.png) also included).

Sprite atlas decoded from the graphics banks

Sprites decoded straight from the graphics banks — one of several [atlases in `gfx/`](gfx/), alongside the extracted font.

Build

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 target

Requirements: 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.


Play with cheats

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.


Accuracy & provenance

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.

Releases

Packages

Contributors

Languages