ToonTalk on WebAssembly

Top-down versus bottom-up surface memory

The canvas present read the surface bottom-up while the DirectDraw-path blits wrote top-down, so every sprite placed through blt_to_back_surface — which pre-flips its y-up marks into top-down rects, exactly as real DDraw expects — rendered mirrored about the horizontal midline.

What made it expensive was that GDI content compensated with a flip of its own, which hid the mismatch. Backgrounds looked right; sprites did not. The fix was to standardise every shim on top-down memory rather than to correct any individual blit, which retired a whole family of positional bugs at once.

Fifty-four stubs where GMP used to be

ToonTalk's exact-arithmetic layer is GNU GMP, reached through mpq_* / mpz_* DLL exports. The Win32 .lib binaries cannot link into wasm, so all 54 imports had become return-0 stubs.

Integer pads appeared to work throughout, because small values ride a separate LongNumberValue path. Only the rational path — fractional sensor values, big numbers, exact comparisons — was returning garbage, and Pong's serve trigger is precisely that path: the ball's X sensor pushes a RationalNumberValue. Replaced with mini-gmp and mini-mpq compiled directly into the build.

Signed overflow in a per-frame compensation

The port's registration compensation in Sprite::update_display feeds offset_delta * y_scale — millions of units at high camera scale — into shrink_height_from_640x480_screen_size, whose h * 480 product overflows 32 bits beyond about 4.4 million. The original's overflow guard only catches positive h.

The wrapped result flipped sign, so each rotor-frame swap ratcheted the craft roughly 28,000 units upward. Console telemetry pinned it exactly: yo dropped 14,264 while dy gained 13,698. The end state — all water, no helicopter, unresponsive input — had been reported several times before as separate bugs.

sizeof(time_t) in a recorded file

read_use_profile read three time_t fields at sizeof(time_t) — 4 bytes on the 32-bit MSVC that wrote the recordings, 8 in wasm. Twelve bytes over-consumed shifted the entire log preface, so load_city_from_log met a failed stream instead of the file-name marker.

Reads and writes now use explicit 4-byte time values under Emscripten, preserving compatibility with recordings made by the original. With that, every segment's marker reads at tellg = 752 and the shipped demo corpus replays end to end.

Two-byte stride over one-byte characters

The wide-text clipping routine advanced two bytes per character, correct where wchar_t is 2 bytes wide, wrong in wasm where it is 4 and wrong again for the on-disk representation. Every read landed between characters and produced the fallback glyph.

Related, and fixed alongside: XML blobs inside recorded logs are stored as 2-byte wide characters regardless of the host's wchar_t, so they are now read explicitly at that width rather than at the native one.

COM lifetime in a hand-written DOM

The shim's document owned its nodes outright but got the reference model wrong, releasing storage while the engine still held pointers into it. The next virtual call went through a freed vtable and, with undefined symbols permitted, surfaced as an indirect call to index 0.

The first fix was also wrong — it tested rc > 1, but the engine releases the mint reference after appending, so a legitimately held node sits at exactly 1 and was declared unreferenced. The correct model counts client references only: a fresh node starts at 0, every factory and cloneNode hands out an AddRef, and teardown is deferred while any node is still held. Headless replay then ran to frame 13,243, against a hard trap at 7,520 before.

Luminance is not a palette lookup

Number::display paints a non-blank pad's face as a solid GDI rectangle rather than sprite art, using a true RGB COLORREF from tt_colors. The shim was mapping every COLORREF to a palette index by luminance — a shortcut valid only against the grayscale development palette, and against the real one it lands on arbitrary entries. The pad's warm-white face mapped to black.

The shim now holds the live palette, fed from the DirectDraw shim's SetEntries, and maps by nearest colour with a fast path for explicit palette indices.

A stub that measured every file at zero by zero

UserImage::compute_dimensions measures a file with load_image_dimensions, which is GDI+. There is no GDI+ in wasm: the stubbed Bitmap constructor does nothing, GetLastStatus() returns 0 — which is Ok — and GetWidth()/GetHeight() return 0. So the call “succeeded” with 0×0 and set file_read, which skipped the DibReadBitmapInfoFromFileName measurement immediately below it. set_dimensions then clamped both axes to 1.

Every image loaded from a real file was therefore one city unit across. The buttons were laid out, blitted and dirtied every frame at 1×1 — present the entire time, sub-pixel. Two further causes sat behind it: no FileSearchPath in the synthesised .ini, so bare-name lookups failed name resolution outright (the retail installer writes that entry); and the pointing-cursor artwork had never been staged, which is why the frozen screen appeared not to repaint at all.

Transparency is palette index 0

The retail button art ships as GIF, which the port cannot decode, so it is converted to BMP ahead of time. The first conversion preserved each GIF's own palette — but the engine runs 8-bit against ToonTalk's palette and treats index 0 as transparent, which in the retail art is black.

In the GIF palette index 0 is the crimson button body. So the body became the transparency hole and every other colour was resolved against the wrong table. The conversion now remaps each pixel to the nearest colour in ToonTalk's palette, sends the GIF's transparency index to 0, and keeps opaque pixels off index 0 so a dark pixel can never become a hole.

The pattern held

CreateDirectory did nothing, so time travel recorded into folders that were never created and produced not one byte. dzip — every zip WRITE in the program — returned ZE_OK without writing, so no archive could exist. GDI+ measured every image file at 0×0 and reported success, so all file-loaded art was laid out one city unit across. And setAttribute silently dropped any VARIANT that was not a string, so every numeric XML attribute the port had ever written came out empty — saved cities and notebooks included.

Each presented as "the logic is wrong" and resolved as "the logic is fine, it was handed a confident zero". That is now five instances counting the GMP one above, which is enough to call it the defining hazard of this port rather than a run of bad luck.

Things Windows did for free

The time-travel buttons and the emulated cursor are asked for by bare name, and only resolve because the retail installer writes a FileSearchPath entry. The port synthesises its own ini and had no such entry, so every one of them failed name resolution. Reaching the end of a demo QUIT rather than handing over the controls, because ExitWhenDemoEnds — another installer-written switch — defaults on.

And file names: one demo's narration script asks for us\s01.wav where the archive stores US/s01.wav. Windows does not care; the browser's filesystem does, so that demo played with subtitles and no voice. Lookups now fall back to a case-insensitive match, which is what the engine was written against.

A real font engine

The port had none. In-game text came from three embedded 1-bit bitmaps point-sampled to whatever size was requested, drawn on a fixed-width cell — so edges were jagged, proportional text rendered monospace, and there was no descent allowance. That single gap accounted for the coarse subtitles, the clipped descenders, a letter not fitting inside a character's button, and digits that shrank badly. Text is now rasterised by the browser's own font engine at the exact requested size, with GDI's lfWidth stretching reproduced so the engine's fit-to-pad arithmetic sees unchanged numbers, and coverage blended against the palette.

A compensation that overreached

An earlier fix made stop_sound silence the whole mixer, to catch a looping effect the engine had lost track of. But stop_sound(narration_too) takes an argument, and the compensation ran before the check — so all seven callers that ask for "effects only", including the landing, cut the demo narration off mid-sentence. The lesson is narrow and repeatable: a compensation must respect the contract of the function it is compensating inside.

lfHeight is pixels, and has been misread since the nineties

The engine's set_font multiplies its pixel cell by −72/96, believing it converts to points. LOGFONT::lfHeight is in logical units — pixels under MM_TEXT — so on real Windows every font came out three-quarters of the layout cell, for the program's entire life. Invisibly: the engine measures the text it gets (digit_height_to_character_height comes from a live get_extent_size of the digit “0”) and tunes its layout from the measurement, so twenty years of margins and fudge factors quietly encoded the mistake.

The shim performed the conversion correctly, drawing 4/3-size glyphs. Single lines self-corrected through the measure-and-fit loops; the stacked fraction, whose line pitch comes from the same measurements, could not. A temporary print in TextOut settled it in one run: 36-pixel cells drawn on a 22-pixel pitch. Taking |lfHeight| as pixels made the same scene draw 27-pixel cells on a 30-pixel pitch, and the self-measuring layout snapped back to the original's own proportions everywhere at once.

Two companion fixes in the same family: glyph ink anchors at GDI's baseline geometry (ascent 0.9 of the cell, matching Arial's real tables) rather than centred in the cell — which is what places the fraction bar, an underscore, in the descent zone under the numerator where number.cpp draws it — and the raster buffer now carries descent room below the cell, because GDI happily inks below the line and the engine's layout depends on it.

The archive that overwrote itself

Not in the original's code: in the port's own tt_finish_time_travel_archive(), added so the page can offer a session as a download. It called close_log_and_open_next() unconditionally — and after the user has jumped back in time, “the next” segment already exists on disk. A tester's segment went from 13,181 bytes to 5,389, restamped with the previous segment's clock. The guard is one comparison — only advance when current == youngest — and the verification was byte-level: nine segments recorded, a jump back to seven, a save, and every log and city snapshot checked against the size the console reported when it was written.

Same lesson as the sound case above, sharpened: a compensation must respect the contract of the machinery it sits inside, and the port's additions are the least-tested code in the building.

The mouse mode must be derived, never assigned

The engine has a relative mouse mode (deltas, original full-screen behaviour) and an absolute one (pen and tablet support, which the browser resembles). The port's recurring mistake was setting the mode to a constant at transition points — end of a demo, exit from time travel, taking over recording — when the only correct value is whatever the pointer-lock state actually is. Every variant produced the same signature: a hand that jams against an edge or snaps to the wrong place. The eventual fix checks lock-versus-mode on every mouse move, two integers compared, which closed the class rather than the instance. Two adjacent traps: a key release swallowed by a text box strands the key down engine-side (Alt-Tab's blur handler was “fixing” this for one tester), and JavaScript-initiated pointer-lock exits must be marked, or the shell's Escape-forwarding helpfully delivers an Escape nobody pressed.

The headless harness died and nobody noticed

Adding browser-storage persistence (IDBFS) silently killed the node test harness: under node there is no indexedDB, the mount's first sync aborts the Emscripten runtime, and an aborted runtime fails every later call while the harness pumps a dead module. The boot log even said persist: loaded, because the JavaScript side caught the error and carried on. Guarding the mount on indexedDB existing revived the harness — which mattered the same day, because the fraction fix above was verified with its framebuffer dumps.

A safety net that became the bug

An earlier commit had capped a free number pad's width at seventeen tiles and forced font-fitting at the cap — a guard added while containment was broken, in the same commit that fixed containment. Retail photographs settled what the original actually does: it lets the face grow to the digits' full natural width, wider than the screen if need be, with full-size digits and the shorter line centred. The cap was the divergence, and it was also what armed the fisheye display that produced the garbled glyphs.

The reproduction mattered as much as the fix. A pad built fresh with the same value looked perfect; the fault only appeared when the pad had first displayed 3/2 and was then given a large value, because it sized itself from the stale small-text font. Replaying the user's construction sequence — take the notebook's Fraction page, drop a typed 100^ on it — was what made it reproducible at all.

Twenty-year-old student programs still load

The WebLabs cardinality study (Kahn, Sendova, Sacristán & Noss, 2011) had children aged 9–13 building infinite sequences in ToonTalk. Its worksheets survive in the author's own files; 464 of the students' programs survive in the Wayback Machine, under weblabs.org.uk/wlplone/Members/…, and still download intact.

Loading them needed no new engine code. sprite_from_file_name — what the native build calls when a .tt file is double-clicked — parses them directly. Seven 2005 programs were tried: the Match Maker, the Diagonal team, the duplicate removers, a Bulgarian student's multiple-sequence box. All loaded and rendered, boxes with live nests and trained robots inside.

Handing one to a running world is the same path: the sprite goes to tt_add_sprite_when_on_floor, which the floor's own react() picks up a frame later. That is what the activity page's load buttons do, so nothing restarts and the learner keeps what they have built.

Out of the tab, onto a disk

The engine has always written both kinds of file — the paused dialog's save what is in the hand (case 7) and save everything (case 4). Natively they land in My Documents, which a browser tab has no equivalent of, so the port runs those same paths into its own filesystem and hands the bytes to the browser as a download. Reading one back is the loader above.

The trap was in the city path. City::compute_full_file_name takes a name that already ends in .cty verbatim, and otherwise resolves it against the user's folder — so an absolute path became <user dir>//toontalk/save/…, wrote nothing, and still returned TRUE. It now checks file_exists before claiming success: 10,181 bytes for a city, 662 for a held robot, and the robot's file reloads.

The probes become the problem

Debugging probes added for one bug outlive it. Two of them printed per robot-match attempt — fine for a Pong demo, catastrophic in Resort Infinity where robots match every frame, at two console lines each. One had a multi-line robot name in it, so the printf split across console lines and the second half slipped past a filter that keyed on the line's prefix. Another was called holefail, and hole mismatches are routine — the resort's machinery probes an incomplete solution box every cycle — so the word “fail” in its own name held the quiet filter open.

Console output is now off by default and available behind ?log=1, the filter sits on console.log as well as on printf because half the probes bypass the latter, and probes that report expected conditions no longer say FAIL. The remaining bulk of that 52,000-line log was Chrome's own [Violation] notices, which only exist while DevTools is open.

A fact written twice will drift

Whether a sheet had a printable PDF was deduced from which group it was listed in, in two places that then disagreed. Moving one sheet between groups made it claim a PDF that was never built; fixing the first copy of the rule left the second still serving the 404. The rule is now generated — the build script lists the PDF folder and writes out what it finds.

It is the same shape as the port bugs catalogued above: one quantity computed in two places that must agree. The port has been producing them at about the rate it finds them in the original.