zdebel

zdebel / DOS_RECONSTRUCTION_PLAYBOOK.md

Last active 2 weeks ago

Like 0

revised this gist 2 weeks ago · 9d79dfb

1 file changed, 38 insertions, 19 deletions

DOS_RECONSTRUCTION_PLAYBOOK.md

Diff is too large to be shown

revised this gist 2 weeks ago · b3c605b

1 file changed, 1 insertion, 1 deletion

DOS_RECONSTRUCTION_PLAYBOOK.md
@@ -347,7 +347,7 @@ Before certifying a DOS reconstruction as **1:1 Bit-Exact Complete**, verify all
347 347 * [ ] Assert $0$ mismatches across position ($X, Y$), velocity ($VX, VY$), and collision states.
348 348
349 349 ### 2. Rare State Machine Edge-Cases
350 - * [X] Verify actor knockback, hitstun, and recovery states.
350 + * [ ] Verify actor knockback, hitstun, and recovery states.
351 351 * [ ] Verify entity destruction, rubble/shrapnel countdown timers, and despawn cycles.
352 352 * [ ] Verify environmental submergence, buoyancy physics, and out-of-bounds checks.
353 353

revised this gist 2 weeks ago · 087be62

1 file changed, 18 insertions, 9 deletions

DOS_RECONSTRUCTION_PLAYBOOK.md
@@ -1,4 +1,5 @@
1 1 # Universal DOS Game Reconstruction Playbook
2 +
2 3 ### A Game-Agnostic Engineering Guide to Bit-Exact (1:1) Clean-Room Reverse Engineering, Differential CPU Harnessing, and Modern Recompilation
3 4
4 5 ---
@@ -23,9 +24,7 @@ flowchart TD
23 24 DEBUG --> CODE
24 25 ```
25 26
26 - > [!IMPORTANT]
27 - > **The Golden Rule of 1:1 Parity:**
28 - > Do not guess formulas. If an algorithm's behavior is ambiguous, isolate its entry point in an x86 CPU emulator, feed it controlled register/memory states, and verify that the re-implemented function reproduces the exact register and memory mutations across all value domains.
27 + > [!IMPORTANT] **The Golden Rule of 1:1 Parity:** Do not guess formulas. If an algorithm's behavior is ambiguous, isolate its entry point in an x86 CPU emulator, feed it controlled register/memory states, and verify that the re-implemented function reproduces the exact register and memory mutations across all value domains.
29 28
30 29 ---
31 30
@@ -57,8 +56,8 @@ A complete clean-room reconstruction requires four decoupled layers:
57 56 The differential harness executes the original DOS machine code inside an emulated memory space. Below is the game-agnostic architecture for a 16-bit DOS real-mode sandbox.
58 57
59 58 ### 3.1. Real-Mode Memory Layout
60 - In x86 16-bit real mode, physical memory addresses are calculated as:
61 - $$\text{Physical Address} = (\text{Segment} \times 16) + \text{Offset}$$
59 +
60 + In x86 16-bit real mode, physical memory addresses are calculated as: $$\text{Physical Address} = (\text{Segment} \times 16) + \text{Offset}$$
62 61
63 62 A standard 2 MB virtual address space accommodates the entire legacy environment:
64 63
@@ -206,6 +205,7 @@ graph LR
206 205 * Locate the handler jump table (`call word ptr [bx + state_offset]`).
207 206 2. **Translate Jump Tables into Reconstructed State Machines:**
208 207 * Convert indirect assembly function pointer tables into explicit state enumerations:
208 +
209 209 ```python
210 210 class EntityState(Enum):
211 211 INIT = 0x08
@@ -243,8 +243,7 @@ class PitAudioAccumulator:
243 243
244 244 ### Phase 5: Lifecycle & Frontend Integration
245 245 1. **State Flow Mapping:**
246 - * Trace the global finite state machine:
247 - $$\text{Intro Cutscene} \longrightarrow \text{Title Menu} \longrightarrow \text{Level Loading} \longrightarrow \text{Game Loop} \longrightarrow \text{Level Transition} \longrightarrow \text{Game Over / Victory}$$
246 + * Trace the global finite state machine: $$\text{Intro Cutscene} \longrightarrow \text{Title Menu} \longrightarrow \text{Level Loading} \longrightarrow \text{Game Loop} \longrightarrow \text{Level Transition} \longrightarrow \text{Game Over / Victory}$$
248 247 2. **Binary Data Persistence:**
249 248 * Map save-game structures and high-score files.
250 249 * If the DOS game XOR-encrypts or checksums save files (e.g., `XOR 0xFF` on high-score bytes), re-implement the exact byte manipulation so existing legacy save files load seamlessly.
@@ -256,31 +255,41 @@ class PitAudioAccumulator:
256 255 These 5 failure modes represent the most frequent sources of discrepancies in DOS-to-modern ports:
257 256
258 257 > [!WARNING]
258 + >
259 259 > ### Pitfall 1: Procedure Coverage vs. Integration Lifecycle Blind Spots
260 + >
260 261 > A test harness verifying that 100% of individual assembly procedures produce identical math when called in isolation does **not** prove that the game loop connects them correctly.
261 262 > * *Failure Example:* An entity collision function works identically, but the main game loop fails to invoke the sound trigger event or resets a multiplier on the wrong screen transition.
262 263 > * *Mitigation:* Always complement procedural unit tests with long-running, multi-level **Scenario Tests (End-to-End)** that simulate real player death, level completions, and menu exits.
263 264
264 265 > [!CAUTION]
266 + >
265 267 > ### Pitfall 2: Silent Audio Loss via Emulator Stubs
268 + >
266 269 > When constructing a CPU differential harness, external driver far-calls (such as `play_sfx` or `start_music`) are routinely stubbed out with `RETF` to prevent the CPU emulator from getting bogged down in low-level sound card hardware registers.
267 270 > * *Failure Example:* The CPU emulator succeeds because the stub returns cleanly, but the developer forgets to wire that specific trigger into the modern audio queue. The game runs with missing sound effects.
268 271 > * *Mitigation:* Build a static audit listing **every single call site** to the audio entry points in the original binary disassembly. Assert that each call site corresponds to an event dispatched in the modern engine.
269 272
270 273 > [!IMPORTANT]
274 + >
271 275 > ### Pitfall 3: Level Transition Audio State Leaks
276 + >
272 277 > In DOS games, the main loop often re-arms background music at the beginning of a level reload.
273 278 > * *Failure Example:* A modern port starts background music in `start_game()`, but when the player loses a life and restarts the level, the level-card display silences the audio, and no routine restarts the track.
274 279 > * *Mitigation:* Track the entry-point address of restart loops in disassembly. If the DOS assembly jumps to a location that calls `start_music(TRACK_ID)` before re-entering the main loop, ensure the modern loop mirrors that exact call.
275 280
276 281 > [!NOTE]
282 + >
277 283 > ### Pitfall 4: 16-Bit Integer Wrapping and Subpixel Boundary Inaccuracies
284 + >
278 285 > In 16-bit x86 code, registers wrap at 65,536 (`0xFFFF`), and signed comparisons (`JL`, `JLE`) behave differently from unsigned comparisons (`JB`, `JBE`).
279 286 > * *Failure Example:* Translating `CMP AX, BX / JLE target` to high-level code as `if ax < bx:` instead of `if ax <= bx:` causes boundary conditions (e.g., surface water line, platform edge) to trigger one pixel early or late.
280 287 > * *Mitigation:* Always enforce explicit 16-bit masking (`val & 0xFFFF`) on accumulator registers and translate conditional jumps strictly according to x86 flag definitions (ZF, SF, OF, CF).
281 288
282 289 > [!TIP]
290 + >
283 291 > ### Pitfall 5: Display Refresh Rate Bottlenecks (70 Hz vs. 35 Hz)
292 + >
284 293 > Standard VGA Mode 13h and Mode X refresh at **70.086 Hz** ($25.175\text{ MHz} / (800\text{ clocks} \times 449\text{ lines})$). The DOS main loop polls VBLANK (`IN AL, 0x3DA / TEST AL, 8`).
285 294 > * *The Issue:* On original 286/386 hardware, complex planar rendering often exceeded 14.2 milliseconds per frame. As a result, the game regularly missed the vertical retrace and dropped to **35 FPS** (every second VBLANK).
286 295 > * On a modern machine running the code at an unconstrained 70.086 Hz, the game will feel significantly faster than players remember from childhood hardware.
@@ -338,7 +347,7 @@ Before certifying a DOS reconstruction as **1:1 Bit-Exact Complete**, verify all
338 347 * [ ] Assert $0$ mismatches across position ($X, Y$), velocity ($VX, VY$), and collision states.
339 348
340 349 ### 2. Rare State Machine Edge-Cases
341 - * [ ] Verify actor knockback, hitstun, and recovery states.
350 + * [X] Verify actor knockback, hitstun, and recovery states.
342 351 * [ ] Verify entity destruction, rubble/shrapnel countdown timers, and despawn cycles.
343 352 * [ ] Verify environmental submergence, buoyancy physics, and out-of-bounds checks.
344 353
@@ -371,4 +380,4 @@ Before certifying a DOS reconstruction as **1:1 Bit-Exact Complete**, verify all
371 380
372 381 ## 8. Summary
373 382
374 - A true 1:1 reconstruction does not rely on approximations. By establishing an x86 CPU differential harness, cataloging every procedure, intercepting hardware registers, and enforcing strict dual-execution assertions, legacy DOS titles can be preserved in modern software stacks with absolute mathematical fidelity.
383 + A true 1:1 reconstruction does not rely on approximations. By establishing an x86 CPU differential harness, cataloging every procedure, intercepting hardware registers, and enforcing strict dual-execution assertions, legacy DOS titles can be preserved in modern software stacks with absolute mathematical fidelity.

revised this gist 2 weeks ago · cccf7a5

1 file changed, 374 insertions

DOS_RECONSTRUCTION_PLAYBOOK.md (file created)

Diff is too large to be shown