Diff is too large to be shown
zdebel / DOS_RECONSTRUCTION_PLAYBOOK.md
Last active 2 weeks ago
revised this gist 2 weeks ago
·
9d79dfb
1 file changed, 38 insertions, 19 deletions
revised this gist 2 weeks ago
·
b3c605b
1 file changed, 1 insertion, 1 deletion
| @@ -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
| @@ -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
Diff is too large to be shown