Getting started

Just reading

The listings in src/*.asm are commented and need nothing built to be read. Where to start, depending on what you're after:

I want to see...	look at
How the game boots	alehop_game_nucleo.asm, at 0xC000
The engine: physics, collision, scrolling	alehop_game_extra.asm
The music player	alehop_game_sonido.asm
The turbo tape loader	alehop_slots.asm
The maps and graphics	alehop_game_datos.asm

The comments are in Spanish, matching the game's own language.

Rebuilding it

make

That extracts the tape, traces the code, regenerates the five game listings plus the other three modules, and verifies everything. Green means four things:

1. Every listing reassembles to the original binary, byte for byte.
2. The five game chunks, concatenated in load order, reproduce the whole turbo block.
3. No data region has been mistaken for code.
4. Not one byte of the 42645 is unexplained.

Then the 36 tests run.

You'll need:

• python3
• pasmo — to assemble (brew install pasmo)
• z80dasm — to disassemble
• openmsx — only for the emulator parts

The .tsx tape image isn't distributed with this repository. Without it, make says what it can't do rather than pretending it went fine.

The images

make imagenes

Draws the six levels from the game's own data: the full strip for each one (2048x64) and a real screen with its three bands. These aren't screen captures — they're generated by decompressing the graphics and assembling the maps, which is the best evidence that the format is properly understood.

How the data blocks are laid out

Every data range declared in the notes comes out as a block of its own: its own heading saying what it is for, its own label, and the dump aligned to its first byte. An optional line gives the block the row width of its real structure, and that is what makes the levels readable in the listing itself: 32 bytes per row, which is exactly the 32 columns the camera shows, so a whole screen of that row of the strip is one line. The presentation, the intro, the scoreboard and the title screen come out the same way -one row of the screen per line-, the fixed sprites four bytes at a time -one attribute record each- and the graphics table as defw pairs: source and video destination side by side.

The emulator

ALEHOP_TSX="$PWD/alehop.tsx" ALEHOP_OUT="$PWD/dump" \
  openmsx -machine Philips_VG_8020-20 -script tools/omsx_load.tcl

This loads the original tape using the game's own loader as the decoder and dumps RAM at each stage. It produces dump/full_recolocado.bin, the 64 KB image the code is traced against: addresses only mean anything once the game has been relocated in memory.

To watch it play and take screenshots:

ALEHOP_TSX="$PWD/build/alehop_rebuild.tsx" ALEHOP_OUT="$PWD/build/capturas" \
  openmsx -machine Philips_VG_8020-20 -script tools/omsx_juega.tcl

Loading takes about seven minutes of emulated time, same as it did in 1988.

Modifying the game

Comments go in src/*.notes, anchored to addresses so they survive a full re-trace; the .asm files are generated from them, so a comment written into an .asm is lost on the next trace.

To change the code itself, edit the .asm and then:

python3 tools/build_tape.py build build/my_alehop.tsx

That assembles, rebuilds the blocks with their headers and checksums, and produces a loadable tape. As long as make was green before you touched anything, any change in behaviour can be pinned on what you changed rather than on a misreading of the binary.