tdkpin/tdkpin-rs/RECONSTRUCTION.md

Reconstruction ledger

Source artifacts

The reconstruction was derived from the preserved files under ../original/. The primary program fingerprint is:

a9022f1894e3e6e21fc42e8f6c932f7c549ca77f63aaa0c488bb9d55d9d0174c  TDKPIN.EXE
f1d9ac980c7bfba5dc53eaa9e7cb2c3cd9b82f879ee8962ad40bf863d641bb49  MMTIMER.DLL

The Ghidra recovery covers all 301 named NE exports plus 62 internal function entries. Its raw output and coverage tables remain beside the binary, so later work can be checked against the same evidence rather than against this Rust implementation.

Coverage by subsystem

Subsystem	Rust status	Evidence and boundary
Artwork	Exact	All 34 custom DIB images, three standard bitmaps, icon, and palette derivatives are preserved in assets/original/. The game uses the original 640x460 table, loading, help, ball, wheel, robot, plunger, media, and diamond frames.
Audio	Exact samples	All 16 mono PCM WAV resources are embedded unchanged. Their trigger roles were recovered from resource use and gameplay context.
Help and languages	Exact	Original resource images 1001-1005 are displayed directly.
Playfield collision layout	Recovered	All 109 active type-2 line objects and 40 static active type-1 circles are transcribed from the original 175-object registration table. The registration routine converts its sideways inputs with screen = (y, x - 20) and accumulates explicitly relative objects. Type-2 records retain every recovered Real48 normal/tangent response pair and registered one-sided orientation. Type-1 records retain their swept-circle radius, radial rebound, tangent coupling, and bumper kick. Each flipper uses its exact two line records plus moving tip circle in both positions. The upward edge transfer matches three live probes and the downstroke matches its live position-preserving (3519,6302) transfer; both are mirrored on the right. Object 174 is omitted because the original overwrites it with the live ball every frame.
Ball launcher	Recovered	The initial 32-bit fixed-point coordinates decode to (325, 413) in the right shooter lane. The port reproduces the initial -375 millipixel Down event, 650 ms repeat delay, 40 ms repeats, release impulse, and randomized clamp below the original -3800 maximum. This replaces the former guessed 330-430 px/s shot.
Physics arithmetic	Recovered gameplay behavior	Production movement uses the original 10 ms millipixel substep, +15 vertical acceleration, 3800 speed bound, point-path type-2 intersection, one-sided line response, swept type-1 circle response, and swept non-physical sensor contacts. It evaluates all records and applies the earliest contact along the substep. Live probes cover ordinary rails, ordinary circles, a kicked bumper, lock holes, magnetic fields, all claw exits, and both flipper directions. Rust represents the original per-ball contact words as path-entry/inside latches; this is a source-structure difference rather than a missing collision route.
Rules	Recovered gameplay paths	Player count, controls, the five three-line bumper-value groups, four three-line TDK-diamond groups, five doubling-value lock holes, wheel-reset target, seven-way effect selector/consumer including multiball, permanent double scoring, and four exact media/extra-ball thresholds follow original help/code paths, globals, and object flags. Claw contact and all initially active type-4 targets use recovered records. The top three targets score 500 each and independently enable the left, center, or right magnetic field record; each field pulls the ball upward until it exits and then deactivates. The claw state machine and release table have live differential coverage for all four random terminals. Remaining timing uncertainty is presentation batching at non-default detail settings, not gameplay routing.
Numeric scoring	Recovered gameplay values	Static scores come from the initialized 175-object ledger. Dynamic bumper progression, target-bank completion, diamond awards, 10k-160k lock bonuses, 310k transfer, six effect values, multiball mode, and all four media thresholds are transcribed from 1000:b476, 1000:c4e1, 1000:bc36, and live state probes.
High scores	Compatible import	The original 276-byte table is decoded as ten IWIK-XOR-obfuscated little-endian scores plus ten 22-byte names, sorted, then migrated to portable JSON.
Configuration	Behaviorally compatible	Sound, language, and five detail levels are retained. Storage moves from a local Win16 INI file to the platform user-data directory.
Windows UI shell	Deliberately modernized	Win16 menus, modal dialogs, GDI blitting, and multimedia timers are replaced by a fixed native window with keyboard overlays. The visible game and original help render one-for-one at the original 640x460 pixels.

Extracted asset inventory

assets/original/ contains 69 files used or preserved by the modern project:

• 40 image files, including all gameplay frames and five localized help pages;
• 16 original WAV resources;
• six decoded dialog descriptions;
• the original icon in ICO and PNG form;
• palette and version metadata;
• the original high-score table and INI configuration sample.

The parent original/assets/ directory remains the lossless extraction record, including raw resource blobs and the extraction manifest. The Rust copy is the decoded, build-ready subset; it does not replace that evidence archive.

Validation levels

• Static coverage: all intended decoded visual/audio resources are preserved; the recovered static collision layout is represented in Rust.
• Build coverage: cargo check, unit tests, and strict Clippy complete on the host. Cross-target checks pass for x86_64-pc-windows-gnu and x86_64-apple-darwin; CI is configured to build and test natively on Linux, macOS, and Windows.
• Runtime coverage: the Linux executable was launched through the real window backend, the attract screen was inspected, a game was started, a ball was launched, collision scoring was observed, and a rendered frame was captured.
• Original-runtime comparison: Wine 11.15 staging ran the preserved Win16 NE executable. Live millipixel traces cover keypad +, repeat-driven charging, release, the shooter route, ordinary rail responses, and a controlled terminal-18 claw capture and release. The line solver has unit tests against exact outer/inner shooter-wall states from those traces.
• Deterministic mechanics coverage: named launcher, flipper, and all four claw terminal scenarios are driven by a 120 Hz validation clock while production physics accumulates the recovered 100 Hz substep. Traces include the last collision-object id and can export the logical 640x460 render target.
• End-to-end gameplay coverage: seeded autoplay charges each launcher ball and operates both flippers from ball position. The two-minute acceptance run covers repeated launches, both flippers, targets, bumpers, lock holes, a claw capture/release pair, and drains while checking every state for finite values.
• Semantic boundary: gameplay routes and initialized values are covered, but no claim is made that every host floating conversion or repaint tick is binary- identical to Borland Real48 and Win16 GDI execution. Live-fitted flipper transfer and non-default repaint batching remain documented source/platform differences.

Architecture

• app.rs: screen flow, controls, rendering, audio dispatch, and overlays;
• assets.rs: compile-time original asset embedding;
• game.rs: fixed-step game state, recovered walls, rules, and scoring;
• geometry.rs: segment/circle collision primitives;
• original_physics.rs: millipixel integration and recovered type-2 responses;
• table.rs: source-traceable collision objects recovered from the Win16 table;
• persistence.rs: platform paths, settings, high scores, and legacy import.