tdkpin/tdkpin-rs/CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Fixed

- Keep a ball captured by the Greifarm during multiball instead of consuming it;
  latch the two-ball capture rule at each entry, exclude the launcher release
  while that capture is active, and let later single-ball re-entries use all
  four original release choices.
- Preserve that entry decision through the complete pull phase, scope it to the
  entering slot until that ball exits the capture zone, and migrate Greifarm
  state when a held secondary ball becomes the primary ball.

## [1.2.0] - 2026-08-31

### Added

- Seed new SQLite high-score databases that did not exist before opening with
  the ten distributed demo scores.

### Fixed

- Deliberately diverge from the original game's multiball contact sentinel so a
  reserve ball that fills a wheel hole leaves it permanently occupied; the
  surviving ball can no longer enter and score that visibly filled slot again.
- Match capture-driven multiball collapse timing so the surviving slot keeps
  double scoring through the current callback, then returns to normal scoring on
  the next callback and the returning claw remains paused until that collapse;
  completing the fifth wheel lock still ends multiball scoring immediately.
- Derive wheel-lock awards from the original live contact words so two balls
  settling into different slots at once receive the same accumulated award as
  the original game.
- Stage an effect-seven reserve-ball request until ball 1's full substep batch
  has returned, preventing the new slot from participating in collision and
  capture rules before the original creates it.
- Bound high-score server resource usage with 1 KiB route body limits,
  single-operation database concurrency gating, 503 shedding, and offloading
  SQLite operations to blocking worker threads.
- Use a relative path for the web build's high-score API endpoint so deployments
  under nested URL subpaths route requests correctly.
- Implement bounded exponential backoff with jitter, initial delay and maximum
  delay bounds, and `Retry-After` header support for failed web high-score
  submissions.

## [1.1.0] - 2026-08-29

### Added

- Add a static WebAssembly (WASM) browser build and web shell for TDK Pinball,
  persisting settings and scores in browser localStorage.
- Add a standalone Axum and SQLite high-score service (`highscore-server`) for
  an optional shared top-ten leaderboard, including an nginx reverse-proxy
  configuration and API endpoints.
- Route the browser high-score table through the shared service when available,
  retaining the local-storage fallback when offline or unconfigured.

### Fixed

- Allow launcher input while tilted so a waiting ball in the shooter lane is not
  stranded after a tilt, while retaining launch sound suppression.
- Bundle the official Macroquad browser loader and WASM bootstrap locally so a
  CSP does not require inline JavaScript or code from `not-fl3.github.io`.
- Keep the web canvas centered at the original fixed 640x460 presentation size
  instead of scaling with the browser viewport.
- Seed the initial gameplay random stream from the startup clock so the first
  maximum-power launcher shot is not identical on every run.
- Require an unconsumed record-148 contact before the effect-seven special
  respawn, preventing a released reserve ball from being duplicated after both
  multiball balls drain.
- Apply type-4 entry latches only inside each target's registered broadphase,
  preventing an unrelated multiball slot from clearing an upper-left target's
  latch and causing repeated scoring while the ball remains there.

## [1.0.0] - 2026-08-29

### Fixed

- Restore the common response's standard dot-product tangent
  `tv=(vx*nx+vy*ny)/length`: `tv*0.02*response_tangent` updates spin, while the
  current response opposes its sign with magnitude
  `abs(normal_velocity)*response_tangent` (negative when `tv==0`). Live probes
  match horizontal drain `(-302,-1809)`, ordinary circle `(94,564)`, bumper
  `(197,3096)`, relative record 57 `(1839,1832)` with spin `-5.28`, and record
  72 `(-2095,1669)` with spin `+5.46`.
- Gate dynamic record 174/175 impulse transfer on the other slot's capture age:
  a held ball remains velocity-stationary and the moving response retains its
  full normal velocity instead of always subtracting 1,000.
- Restore `1000:ae6e`'s required-ball special respawn: armed or completed
  effect-seven play grants one final `(17,23)/(0,3040)` ball without consuming a
  marker, clears required state including record 148's contact word, and
  suppresses record 148 until the next broadphase-active type-4 record reenables
  it.
- Replace the invented post-move `y>470` fallback with the original pre-scan
  prediction bounds `x<=0 || x>340000 || y<=0 || y>460000`, including one-slot
  removal during multiball and next-substep handling after a response.
- Remove the invented 180 ms whole-frame nudge shake; original nudges affect
  ball-slot velocities, sound, and Tilt state without moving the viewport.
- Match `SndPlaySound(SND_ASYNC|SND_NODEFAULT)` playback: stop the previous WAV
  before every new resource and use full host mixer volume instead of an
  invented 72 percent attenuation/overlap.
- Load and draw all DAT400-407 player/effect sprites at `(55,79)`, preserving
  the original saved 14x14 wheel overlap at `(84,77)`; selected bonuses,
  collect-bonus, and release-ball states are now visible.
- Restore display blits from `1008:0996`/`1008:0b9e`: 130x40 score fields at
  X=478, eight places ending at X=606, exact 139x31 configured-player rows,
  11x11 active/status markers, 5x5 remaining-ball markers for every player, and
  strict signed score-status thresholds independent of media awards.
- Import exact `[Settings]` `Language`, `Speed`, and singular `Sound` values
  from an adjacent/original TDKPIN.INI before creating portable JSON. Fresh
  installs now inherit the distributed German help setting; F12 is again a
  silent runtime-only toggle and cannot leak into a later save.
- Replace modern high-score/name overlays with the reconstructed `HighScore`
  child: exact DAT993 360x300 background, heading/row coordinates, unpadded
  scores, and DIALOG 32514 caption, prompt, 21-character edit, OK, and Cancel.
  Escape now follows original Cancel semantics and empty names are accepted.
- Restore the staged loading presentation by blitting original DAT994 over
  DAT995 at `(202,328)`, height 13 and clipped width `(stage-1)*7`; correct the
  previously impossible Pascal-order C interpretation of a 328x202 blit.
- Restore the original idle/attract timer animation: target and word-quad
  chases, magnetic flashes, five-record strip, four-point chase, DAT801-809 item
  progression, and the circular `WELCOME TO THE MACHINE` BITMAP500 marquee. Each
  nested phase uses the binary's remainder first: `%32/2`, `%32/4`, `%40/4`,
  `%16/4`, and `%144/8`. Move gameplay item frames to their exact `(123,300)`
  destination.
- Match central score/event side effects: every stored collision candidate
  clears its ball slot's capture age, Tilt suppresses all score and rule-record
  mutations, and active multiball doubles points before permanent Double can
  double them again.
- Scan static, capture, trigger, magnetic, and dynamic record ranges in exact ID
  order with a separately tracked prediction. Preserve the raw scanner's
  first-detected-candidate quirk even when a later record is geometrically
  nearer, plus type-3 and dynamic-record broadphase behavior.
- Run type-3/type-4 processing before response and position publication:
  captures now test the old position, contacted type-3 rims contribute radial
  candidates, triggers mutate the live motion first, and sensor IDs execute in
  binary order without Hold/Complete prematurely ending the record scan.
- Apply the collision table's predicted-position broadphase bounds before
  type-1/type-2 detection, including the registered five-pixel ball margin, and
  retain unresolved candidates until the selected response phase.
- Correct the two relative slingshot initializer chains after records 55 and 70:
  circles 56/58/71/73 and lines 57/59/72/74 now accumulate from each preceding
  path endpoint exactly as the 175-record ledger specifies. The flagless TDK
  companion lines also retain their zero contact/link field rather than carrying
  unused synthetic head IDs. Record 57 additionally matches the live original's
  `(75530,354765)/(3000,15)` to `(77369,356597)/(1839,1832)` transition;
  symmetric record 72 matches `(235348,356825)/(-3000,15)` to
  `(233253,358494)/(-2095,1669)`.
- Match rectangular type-4 magnetic gates to raw `1000:9b69`: enter only when
  the previous position is inside, then deactivate when the newly predicted
  position exits any edge, replacing a swept-intersection approximation.
- Decay the 16-bit tilt counter once per selected 50/40/30/20/10 ms detail
  callback, replacing an invented independent 30 ms accumulator.
- Match the multiball nudge path's saved-slot behavior: consume the active
  formula's random draws, then add one shared fixed/random impulse to both slot
  velocity records instead of applying different formulas to each ball.
- Restore auxiliary response thresholds/kicks for bumpers 51-53 and line records
  55, 74, and 107, including weak-hit bumper scoring, WAVE 2019 on kicked
  unscored rails, and the original tilt suppression.
- Preserve every collision record's `+0x49` layer mask and select upper layer 1
  or lower layer 2 from the ball's previous 250,000-millipixel Y boundary.
- Match the original detail callback's slot-major integration order, stop a
  slot's remaining 10 ms substeps after its first collision/action, delay a
  newly requested second ball until the next callback, and retain ball-two
  identity while a captured/drained ball one is collapsed.
- Run type-3 captures and type-4 triggers for both live ball slots, including
  per-slot capture age/contact ownership, exact captured-slot removal, survivor
  promotion, and the effect-seven ball-number guard against a third ball.
- Spawn effect-seven ball 2 from record 148 at `(17,23)` with exact `(0,3040)`
  millipixel velocity, instead of launching a guessed second ball upward from
  the shooter lane.
- Treat record 148 as the special/multiball hole represented by player item 20;
  capturing it preserves all five lock-hole items and contacts instead of
  inventing an immediate wheel reset. Its exact 17x17 overlay-A Word-Quad at
  `(9,14)` remains visible until the required contact is consumed.
- Replace invented bumper outline/cooldown effects with the original per-record
  5/20/10 callback countdowns and exact overlay-A render rectangles for bumpers
  51-53 and targets 140-147/150-152.
- Render the five cumulative bumper-value lamps from original player items 1-5
  at their recovered Word-Quad bounds as the value rises from 1,000 to 6,000.
- Render the nine in-bank hit states for record heads 90/93/96/99/102 and
  109/112/115/118 from their exact overlay-A bounds until bank completion rearms
  each three-line group.
- Replace the free-running wheel animation with the original six-callback 91x90
  target rotation, WAVE 2011 start, exact DAT600 frames/target positions, and
  state-6 rotation of the five per-player contact/item values. It advances only
  for an active ball, pauses in the launcher, and survives a normal drain.
- Restore the complete 281-callback DAT600 panel sequence after the fifth lock
  hole, including physics suspension, contact/item cleanup, all nine image
  phases, and the original WAVE 2013/2012/stop boundaries. A fifth lock captured
  during multiball still transfers its capped 160,000-step award but defers the
  panel until a later single-ball completion. Any subsequent type-3 reset with
  all five contacts set, including the special hole, also starts the panel as
  `1000:9e85` does.
- Remove the invented attract-screen instruction panel and stop assigning the
  original F2/F3 keys to modern overlays. The idle view is the original table;
  optional settings/high-score viewers move to F10/F9.
- Batch physics and flipper publication on the original 50/40/30/20/10-ms detail
  callbacks with exactly 5/4/3/2/1 internal 10-ms substeps, instead of exposing
  every substep on host render frames.
- Separate flipper key flags from rendered/collision position so press/release
  edges and WAVE 2021 occur only when the detail timer processes them.
- Add a bit-exact Borland Real48 core and route speed clamps, type-1 circles,
  type-2 segments, moving flippers, capture pulls, trigger randomization, and
  magnetic impulses through its original rounding behavior.
- Preserve per-ball Real48 spin and use it in collision tangent response, so
  zero-spin C fixtures and retained-spin Wine traces are both represented.
- Implement dynamic records 174/175 with bidirectional ball impulse transfer and
  the original post-collision speed clamp instead of a one-sided secondary
  bounce.
- Split collision contact state into per-player 16-bit type-3 contact words and
  transient type-4 entry flags. Type-3 records now use the original deep-inside
  gate, `v*0.9 +/-150` pull, stationary sound/contact publication, 5-step age
  progression to 300, and `99`/`2` completion sentinels.
- Replace the live-fitted flipper transfer polynomials with the reconstructed
  `1000:7ed9` millipixel geometry gates, penetration, gain, response-record,
  velocity, and position calculations for both directions and both balls.
- Preserve every gameplay millipixel across the float-only render projection so
  exact integer physics results are not changed when stored for drawing.
- Restore launcher input to the setup scalar: each Down keydown subtracts 750
  millipixels, release subtracts 1,500, then applies the recovered `-3800` and
  `-2280` clamp/jitter branches and the ten original decoration thresholds.
- Apply the original independent `1.03 - Random * 0.08` X/Y velocity response
  after entering radius-bearing type-4 targets, preserving both motion and the
  subsequent shared PRNG sequence.
- Check every player against the high-score table when their own last ball is
  lost, prefill the original `TDK Pinball Player` name, show the table before
  resuming the next player, and use the original signed-high/unsigned-low score
  ordering instead of selecting only the maximum score at whole-game end.
- Preserve each player's complete rule-record state across turn changes instead
  of globally clearing wheel holes, top targets, 176 active/contact slots,
  selected effect, and multiball readiness on every drain.
- Store lock-hole and effect awards in the original per-player secondary score
  instead of a global bonus. The fifth hole now transfers
  `310000 * score_multiplier`, clears it, increments the multiplier and ball
  count, while effect 6 transfers the same display value and drain leaves it
  intact.
- Replace the cooldown/float-meter nudge approximation with the original
  Left-Shift, keypad-3, and Space formulas using scalar 15, the shared Borland
  random stream, 32-bit velocity wrapping, and the decaying 16-bit `+25` tilt
  counter with its randomized `30..39` threshold.
- Preserve held flipper keys and raised geometry across ordinary drains. Tilt
  and a player's final ball now clear the key latch, release a raised flipper
  through its normal WAVE 2021 timer edge, and require physical key-up before
  the same key can raise it again.
- Match the original low-byte keyboard scans: both Ctrl keys operate the left
  flipper, both Enter keys operate the right, and the physical `0x1b`
  main-keyboard plus/right-bracket position starts or adds players.
- Dispatch add-player, nudge, and F12 sound-toggle actions on key release
  through the original `1000:638e` timing rather than on their initial key
  press.
- Enforce the original auxiliary-window input gate: F1 and F12 are ignored while
  Help, HighScore, or name-entry UI is open instead of controlling the main game
  through a child window.
- Route a single-ball type-3 completion during Tilt through `1000:ae6e` instead
  of granting a free launcher reset: lock holes consume the ball, while record
  148 can still take its required-state special-respawn branch.
- Replace the Xorshift gameplay RNG with the original Borland linear stream and
  unbiased `Random(n)` high-word mapping. Launcher variation, effect selection,
  claw terminals, and magnetic-field impulses now share the recovered sequence.
- Preserve the Borland seed across game-over/high-score flow so a new game
  continues the program-global random stream instead of reseeding per game.
- Restore the magnetic-field response as `vx * 0.9` and a randomized
  `-3800 * (1 - Random * 0.3)` vertical impulse instead of a fixed upward speed.
- Dispatch the original per-call-site sound sequences instead of assigning one
  guessed WAV to each logical event. This removes the nonexistent WAV 2022
  playback and restores bank, trigger, capture, nudge, tilt, and drain cues.
  Type-4 WAVE 2004 and bumper WAVE 2006 now precede their score mutations so a
  simultaneously crossed media marker leaves WAVE 2007 audible, as in the
  monophonic original. A tilted drain suppresses WAVE 2008 before reset, while a
  following flipper-release edge may still play WAVE 2021 after reset.
  Bumper/TDK bank completion WAVE 2017 likewise precedes its 50,000 or
  10,000..24,464 award, preserving the marker cue when that award crosses one.
- Advance media/extra-ball thresholds only from score additions, preserve 32-bit
  score wrapping, and restore the ninth-diamond ordering: its 24,464 award
  remains single, then ball-scoped double scoring and all three magnetic fields
  activate before the collision's static score. Further completed banks during
  that ball add 100,000 to the secondary score; a normal ball end clears the
  multiplier, while effect seven's special respawn preserves it. Marker
  comparisons retain the binary's signed-high/unsigned-low 32-bit ordering after
  score wrap.
- Match the original 640x460 window, native 16x28 score glyphs, and
  `TDK Pinball Machine 1.00` title so the recovered artwork is presented
  one-for-one instead of enlarged or resampled.