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, help, ball, wheel, robot, plunger, media, and item frames. DAT400-407 expose the current per-player bonus/collect/release effect at (55,79) while preserving the saved 14x14 wheel overlap. Loading presents DAT995 and advances the original DAT994 strip at raw 1000:531e destination (202,328), height 13, and clipped width (stage-1)*7 through stages 2-35. Player items 1-5 cumulatively light the five recovered bumper-value Word-Quads from 2,000 through 6,000 points. The nine partially completed bumper/TDK bank heads use their record-ledger overlay-A bounds until each three-line group rearms. Record 148's armed player-item-20 state uses its exact overlay-A Word-Quad (9,14)-(25,30).
Audio	Exact samples and recovered dispatch	All 16 mono PCM WAV resources are embedded unchanged. Playback is emitted at the reconstructed call sites, including multi-sound bank completions, nudge-then-tilt ordering, and Tilt suppression of the pre-reset WAVE-2008 drain cue. Like Win16 `SndPlaySound(SND_ASYNC
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. Both left/right relative slingshot chains (54-59 and 69-74) are checked record-for-record against their accumulated ledger coordinates. Every static record retains its +0x49 layer mask; the scanner selects layer 1 below the old Y value 250,000 and layer 2 at or above it, while mask 3 records remain shared. Before detection, the raw 1000:9b69 predicted position must lie in the record bounds derived with the registered five-pixel ball margin. 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. Detection retains unresolved normal/material candidates so later scan-time motion changes can participate in the selected response. Raw stack slot SS:...d8a2 makes the first detected record ID win; later nearer candidates are stored but never applied, and both C/Rust have two-candidate regression coverage for this quirk. Each flipper uses its exact two line records plus moving tip circle in both positions. Moving-flipper contact ports 1000:7ed9 rather than fitting live samples: delta-specific pivots/edges, integer cross gates, radial/penetration calculations, response-record gain, and position/velocity publication are tested against all four C harness directions and the raised release geometry. Object 174 is overwritten with the live first ball and Rust handles its ball-to-ball role directly.
Ball launcher and nudge input	Recovered	The initial 32-bit fixed-point coordinates decode to (325, 413) in the right shooter lane. Each Down keydown subtracts 15*50 = 750 millipixels, release subtracts another 15*100 = 1500, and the result follows the recovered randomized -3800 lower and -2280 weak upper clamp branches. The ten decoration frames use the same strict 750-millipixel thresholds. Left Shift and keypad 3 apply their directional (50-Random(20))*15 impulses; Space uses the recovered Real48 horizontal factor and (60-Random(20))*15 vertical impulse. With two balls, the key path still consumes those active-window draws, then applies its separately recovered fixed/shared random slot impulse to both saved velocities. Each nudge adds 25 to the wrapping 16-bit tilt counter, compares it with 30+Random(10), and the detail timer decrements a nonzero counter once per callback. Flipper key flags and raised geometry survive ordinary drains; Tilt and a player's final ball clear the flags, lower raised flippers through the normal WAVE-2021 timer edge, and require a physical key release before another press.
Physics arithmetic	Recovered Real48 core	Production movement uses the original 10 ms millipixel substep, +15 vertical acceleration, Real48 3800/speed clamp, four-sided pre-scan prediction bounds (0,340000] x (0,460000], type-2 distance/cross gates, type-1 midpoint normal, first-detected candidate selection, persistent Real48 spin, and the common impulse response. The standard dot-product tangent tv=(vx*nx+vy*ny)/length drives spin_delta=tv*0.02*response_tangent; the current response opposes its sign with magnitude abs(normal_velocity)*response_tangent (negative when tv==0), while retained spin*0.4 contributes independently. The scan follows record chunks 1-5, 6, 7-88, 89, 90-128, 129-133, 134-139, 140-152, 153-154, 155-173, and dynamic 174/175 while carrying prediction separately from mutable motion. Negative auxiliary thresholds and kick coefficients are retained for bumpers 51-53 and lines 55/74/107, including weak-hit score behavior, unscored-rail WAVE 2019, and tilt suppression. Type-3 reads the pre-movement coordinate for pull/hold, obeys its prediction broadphase, and contributes its recovered radial rim candidate when a nonzero contact is outside the deep zone. Type-4 randomization mutates motion before the selected candidate is resolved and before position publication; only rectangular magnetic records rewrite prediction. Detail callbacks freeze their starting ball count, run all 5/4/3/2/1 substeps for slot 1 before slot 2, stop a slot after its first collision/reset/removal, and apply effect-seven spawn requests after the current batch. Dynamic records 174/175 use their 21-pixel prediction bounds and transfer normal impulse only when the other slot's capture age is nonpositive; successful transfer then applies normal_velocity-1000, while a held slot remains unchanged and leaves the moving normal velocity intact. Effect seven spawns record/slot 2 from record 148 coordinates (17000,23000) with exact (0,3040) velocity. Both slots traverse the same type-3/type-4 dispatcher. Capture age is saved per slot, contact words retain ball ownership, a completed multiball capture removes exactly that slot and promotes the survivor when needed, and effect seven's argument-2 guard prevents a third ball. The original Borland seed update, high-word Random(n), and normalized Real48 random register result drive launcher variation, effects, claw terminals, magnetic fields, and trigger response. Type-4 triggers retain a shared transient entry flag; type-3 captures retain per-player 16-bit contact words, deep-inside pull/hold progression to age 300, first-contact sound, and 99/2 completion sentinels. Zero-spin C harnesses and retained-spin Wine probes are tested separately rather than conflated.
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, record-148 special/multiball hole, seven-way effect selector/consumer including multiball, ball-scoped double scoring, and four exact media/extra-ball thresholds follow original help/code paths, globals, and object flags. The ninth diamond pays the original 24,464 completion value, then immediately enables double scoring and all three magnetic fields before that collision's static 1,500-point award. Further completed banks during that ball add 100,000 to the per-player secondary score. A normal ball end clears double scoring, so the first later completion re-enables it without adding 100,000; effect seven's special respawn preserves it because it bypasses normal_ball_end. Bumpers 51-53 and targets 140-147/150-152 use the original 5/20/10 active-callback countdowns and exact overlay-A render rectangles. Record 121 runs the six-active-callback DAT600 target rotation with exact 91x90 frames/target points and rotates the five contact/item values at state 6; it pauses while a ball waits in the launcher and survives a normal drain. Completing all five lock holes with one ball suspends physics for the full 281-callback panel animation, clears contact/item state at the recovered boundaries, and uses the exact WAVE 2013/2012/stop sequence. A fifth multiball capture still transfers the capped 160,000-step secondary award, multiplier, and extra ball but defers the panel; a later survivor recapture can perform the same capped completion and start it, while any intervening Type-3 reset with all five contacts set also starts it through 1000:9e85. Capturing record 148 sets player item/contact 20 and preserves all five lock-hole items and contacts. Effect seven retains required state through active multiball; when the last ball is lost, 1000:ae6e grants one uncharged special respawn at (17000,23000)/(0,3040), clears required state, and suppresses record 148 until a broadphase-active type-4 record clears 0x0875. Turn changes mirror the original save/load of all 175 collision active/contact states plus wheel/top targets and selected effect. 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 rectangular field requires the previous position inside, applies its Real48/random pull, and deactivates when raw 1000:9b69 finds the resulting 07db/07df prediction outside any edge. The claw state machine and release table have live differential coverage for all four random terminals.
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. The central helper suppresses all mutation during Tilt, applies a 2x active-multiball factor, and then independently applies the active ball's 2x factor, allowing the original 4x stack. Lock and effect awards share the original per-player secondary score and display multiplier; the fifth hole transfers and clears it, increments the multiplier, and grants the recovered ball award. Score mutation uses the original 32-bit wrapping behavior; media markers use the binary's signed-high/unsigned-low comparison, and each add operation can advance at most one threshold. Type-4 WAVE 2004, bumper WAVE 2006, and bank-completion WAVE 2017 dispatch before their associated score mutations, leaving a crossed marker's WAVE 2007 as the audible asynchronous sample. Rendering separately follows 1008:0996's eight-place 130x40 fields/right edge X=606 and 1008:0b9e's strict signed status thresholds; configured-player rows and 5x5 remaining-ball markers retain their exact dimensions and current/noncurrent counts.
High scores	Recovered visible flow; portable storage	The original 276-byte table is decoded as ten IWIK-XOR-obfuscated little-endian scores plus ten 22-byte names. Each player is checked immediately when their own last ball is lost; qualifying scores use the original signed-high/unsigned-low comparison and a TDK Pinball Player-prefilled DIALOG 32514 flow with the exact caption, prompt, 21-character limit, OK/Cancel semantics, and allowance for an empty accepted name. The HighScore child uses exact DAT993 at 360x300, heading (180,27), name/rank X=30, right-aligned score X=320, and ten 20-pixel rows before play resumes. Persisted updates use portable JSON rather than rewriting the Win16 file.
Configuration	Recovered behavior; portable follow-up storage	Before portable JSON exists, Rust reads the original case-insensitive [Settings] keys Language, Speed, and singular Sound from the executable-adjacent INI, falling back to the embedded distributed TDKPIN.INI. Values retain the Win16 defaults/clamps; the shipped file therefore selects German, speed 3, and sound-on because its plural Sounds line does not override singular Sound. F12 toggles only runtime playback without UI or persistence. Later explicit F10 changes use the platform user-data directory.
Windows UI shell	Original gameplay surface with native host shell	Win16 window ownership and GDI calls are replaced by a fixed native window, but the visible game, help resources, automatic per-player high-score flow, original keys, and 640x460 logical pixels are retained. Idle mode advances on the selected detail callback and reproduces idle_transition_tick: target/word-quad/record-strip chases, magnetic flashes, four-point chase, DAT801-809 item progression, and the circular BITMAP500 WELCOME TO THE MACHINE marquee composited over exact DAT997 regions. F2/F3 remain unassigned as in normal original operation; optional portable settings and table viewers use F10/F9 and do not replace gameplay input.

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/circle tangent responses, and a controlled terminal-18 claw capture and release. A current one-substep record-2 probe proves special-respawn publication (17000,23000)/(0,3040) followed by the same response's (16698,21191)/(-302,-1809) continuation. Rust tests assert these exact live states.
• 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. Seeded runs use the original Borland random stream. 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: collision, random, spin, fixed-point state, detail callback batching, and flipper publication now use the reconstructed Borland/Win16 timing model. Native texture drawing replaces Win16 GDI calls while preserving the logical 640x460 framebuffer and original resource pixels.

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;
• real48.rs: bit-exact Borland six-byte arithmetic, conversion, and square root;
• flipper_physics.rs: reconstructed moving-flipper geometry and response;
• table.rs: source-traceable collision objects recovered from the Win16 table;
• persistence.rs: platform paths, settings, high scores, and legacy import.