Tour — JavaScript port
A study port of "Tour" (Pulse / Pygmy Projects / Virtual Dreams, Assembly '98, 3rd place with 752 points), a DOS demo,
re-implemented in plain JavaScript for the browser and Node 22, with the reverse-engineering notes, tools and write-up.
It is the predecessor of the engine of 73 million seconds (see the sister project 73-Million-Seconds-by-Pulse).
Site (GitHub Pages): docs/ — player (demo.html), engine notes (index.html), the best asm tricks (writeup.html).
What is here
- Faithful port: the original
script.unr drives the demo (buffers + events run every frame in creation order, timed by the XM module position).
Effects: basic2d (palette, doubleimage, blend, fade, mapimage, blit), feedback (echo5, reebok), cellrd (Gray-Scott reaction-diffusion),
scene3d (software 3D: .exp/.lwe scenes, unrdisp, bomb, displace247), volumes (metaballs, plasma, marching cubes). 3D, 2D, volume and feedback effects were
verified against the original executable running in a CPU emulator (most of them bit-exact, see re/*.md).
- Whole-demo check: the original engine is run headlessly under Unicorn (
re/golden.py) and its frames are compared with the port's (tools/replay.mjs, tools/cmp-all.py):
mean error 1.2 / 255 per channel, 93.6 % of pixels within 8 levels over the 152 s of the demo (the JPEG decoder of the original differs from the browser's: that alone is a ~1 level floor).
- Reverse-engineering:
re/unpack_pmodew.py runs the PMODE/W loader (real mode → protected mode) in Unicorn to unpack TOUR.EXE; re/boot.py boots the unpacked original to its main loop;
re/harness.py calls any original function with custom buffers; tools/extract.py decodes TOUR.98 (dlz LZ, byte RLE, adaptive-Huffman LZ, BWT+MTF+Huffman).
Layout
docs/ GitHub Pages site: index.html, demo.html, writeup.html, js/ (core, engine, assets, archive, fx/*), notes/*.html, assets/
re/ reverse-engineering notes (*.md), unpacker, emulator core (emucore.py), harness, golden-frame runner, differential tests (dt_*/)
tools/ extractor, renderers, comparison and test scripts
ENGINE.md the port's engine contract (was the brief for the parallel work)
TOUR.EXE TOUR.98 original demo files (unmodified)
Running
cd docs && python3 -m http.server # http://localhost:8000/
python3 tools/mkraw.py # once (Pillow): build/raw for the node renderer
node tools/render.mjs 75 out.ppm # render the port at t = 75 s
node tools/test-engine.mjs; node tools/test-volumes.mjs; node tools/test-basic2d.mjs # self-checks
Reference (needs pip install unicorn capstone pillow numpy):
cd re && python3 boot.py # ~40 s, makes state.bin
python3 golden.py 0 153 0.033333 golden/full # the original's frames (EVERY=15 to keep one in 15; ~25 min)
cd .. && node tools/replay.mjs re/golden/full /tmp/replay && python3 tools/cmp-all.py re/golden/full /tmp/replay
Music clock: the player follows libopenmpt, so docs/assets/xm_times.json (made by tools/openmpt_times.py) gives the exact start time of every (order,row).
Credits
Demo, music and assets © Pulse, Pygmy Projects, Virtual Dreams (1998): camel, silver eagle, unreal, fndr, visualize, falcon. Music played with
chiptune3 / libopenmpt. This port and the notes are non-commercial, for study.
