docs: factual rewrite of README, GitHub Pages, and CONTRIBUTING; remove Ghidra references by Copilot · Pull Request #57 · OpenRakis/Cryogenic

Copilot · 2026-04-04T09:49:14Z

Description of Changes

Rewrites all user-facing documentation to use factual, zero-hype language. Documents actual code segments with per-field override counts and per-driver remapping details. Removes all Ghidra references from the entire codebase.

Files changed:

README.md — Factual description of what Cryogenic does and how. Detailed segment table showing what each cs1–cs5 field contains and how many overrides are registered against it. Driver remapping table listing all 5 remapped drivers with their target addresses and purposes. Full code structure tree with per-file descriptions (function counts, addresses, domains). Removed emojis, marketing language, social badges (stars/forks/issues).
docs/index.html — Replaced all section text with factual descriptions. Replaced "Project Goals" section with "Code Structure" section containing the segment table, driver remapping table, per-file override documentation, and supporting code descriptions. Removed Ghidra Integration feature card. Simplified contributing section.
CONTRIBUTING.md — Factual setup and workflow instructions. Updated .NET version reference from 8 to 10. Added the same detailed segment and driver remapping tables. Removed Ghidra tool recommendation and Ghidra plugin note. Streamlined by removing redundant sections (Code of Conduct, Communication, Questions).
src/Cryogenic/DriverLoadToolbox.cs — Removed Ghidra issue URL from XML doc comment.
src/Cryogenic/Overrides/VgaDriverCode.cs — Replaced 7 occurrences of "in ghidra" with "in disassembly" in inline comments.

Rationale behind Changes

The existing documentation used hype language ("deep dive", "power of hybrid emulation", "preserve gaming history") and generic descriptions ("CS2/3/4 for drivers"). This rewrite makes every claim specific and verifiable: segment fields list their actual values, override counts, and which drivers map where. Ghidra references are removed per project direction (the Ghidra plugin is abandoned; CFGCPU is the recommended analysis tool).

Suggested Testing Steps

Review README.md rendering on GitHub
Review docs/index.html in a browser (or wait for Pages deployment)
Verify dotnet build passes (confirmed — build succeeds with 0 errors, 0 warnings)
Grep for "ghidra" to confirm all references are removed (confirmed — 0 matches)

…, no hype Agent-Logs-Url: https://github.com/OpenRakis/Cryogenic/sessions/be596f46-8b1d-4a05-a979-74e098040fd2 Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

…re docs, no Ghidra Agent-Logs-Url: https://github.com/OpenRakis/Cryogenic/sessions/be596f46-8b1d-4a05-a979-74e098040fd2 Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

… from codebase Agent-Logs-Url: https://github.com/OpenRakis/Cryogenic/sessions/be596f46-8b1d-4a05-a979-74e098040fd2 Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

…river documentation Agent-Logs-Url: https://github.com/OpenRakis/Cryogenic/sessions/be596f46-8b1d-4a05-a979-74e098040fd2 Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

Copilot

Pull request overview

Documentation-focused PR that rewrites user-facing docs to be factual/low-hype, adds more concrete architecture details (segments, driver remapping, file structure), and removes Ghidra references from the repository’s docs/comments.

Changes:

Rewrites README.md, docs/index.html, and CONTRIBUTING.md to describe Cryogenic’s hybrid override model, segment layout, driver remapping, and code structure.
Removes/renames Ghidra references in comments and documentation (e.g., “in disassembly” wording).
Trims/updates various docs sections (badges, contributing workflow, .NET 10 references).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 19 comments.

Show a summary per file

File	Description
`README.md`	Reworked project description and added detailed segment/driver remapping + code-structure documentation.
`docs/index.html`	Replaced “goals/marketing” content with factual “code structure / execution flow” documentation for GitHub Pages.
`CONTRIBUTING.md`	Simplified contribution guide and added segment/driver remapping + workflow notes.
`src/Cryogenic/DriverLoadToolbox.cs`	Removes Ghidra issue URL from XML doc remark.
`src/Cryogenic/Overrides/VgaDriverCode.cs`	Replaces “in ghidra” phrasing with “in disassembly” in comments.

Copilot · 2026-04-04T09:57:35Z

README.md

+| `cs1` | `0x1000` | Main game code (`DNCDPRG.EXE` loaded here) | ~80 functions across most override files |
+| `cs2` | `0xD000` | DNVGA — VGA graphics driver | 32 functions in `VgaDriverCode.cs`, 1 in `StaticDefinitions.cs` |
+| `cs3` | `0xE000` | DNPCS2 / DNSBP — PCM audio driver | None (declared but unused in current overrides) |
+| `cs4` | `0xE000` | Reserved for MIDI driver memory-dump hooks | 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE |


The README describes cs4 as "Reserved for MIDI driver memory-dump hooks", but MIDI/music drivers are remapped to 0xF000 (DriverLoadToolbox.DRIVER3_SEGMENT) while cs4 is set to 0xE000 in Overrides.cs. This row should avoid implying cs4 is the MIDI segment; consider describing it as the 0xE000 segment used for the inline memory-dump hooks (or for self-modifying-code dump hooks), without calling it MIDI-specific.

Suggested change

| `cs4` | `0xE000` | Reserved for MIDI driver memory-dump hooks | 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE |

| `cs4` | `0xE000` | Reserved `0xE000` segment for inline memory-dump hooks | 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE |

Copilot · 2026-04-04T09:57:35Z

README.md

+├── DriverLoadToolbox.cs           Remaps driver segments to 0xD000/0xE000/0xF000
+├── Overrides/
+│   ├── Overrides.cs               Defines segment fields (cs1–cs5), registers all overrides
+│   ├── VgaDriverCode.cs           23 VGA functions: mode setting, blitting, palette, mouse cursor


The file tree claims VgaDriverCode.cs contains "23 VGA functions", but DefineVgaDriverCodeOverrides() registers 32 driver functions (and only a subset have C# implementations). Please update this count (and/or clarify the distinction between functions registered for tracing vs functions actually overridden).

Suggested change

│ ├── VgaDriverCode.cs 23 VGA functions: mode setting, blitting, palette, mouse cursor

│ ├── VgaDriverCode.cs VGA driver overrides/helpers; only a subset of the 32 registered VGA driver entry points are implemented here (mode setting, blitting, palette, mouse cursor)

Copilot · 2026-04-04T09:57:35Z

README.md

+├── Overrides/
+│   ├── Overrides.cs               Defines segment fields (cs1–cs5), registers all overrides
+│   ├── VgaDriverCode.cs           23 VGA functions: mode setting, blitting, palette, mouse cursor
+│   ├── MenuCode.cs                14 menu-type constants, 2 menu state overrides


MenuCode.cs is described as having "14 menu-type constants", but Overrides/MenuCode.cs declares 16 MENU_TYPE_* constants. Update the count (and optionally note that MENU_TYPE_ORNI_MAP shares a value with MENU_TYPE_MOVE_TROOP).

Suggested change

│ ├── MenuCode.cs 14 menu-type constants, 2 menu state overrides

│ ├── MenuCode.cs 16 menu-type constants (including `MENU_TYPE_ORNI_MAP`, which shares a value with `MENU_TYPE_MOVE_TROOP`), 2 menu state overrides

Copilot · 2026-04-04T09:57:36Z

README.md

+│   ├── MenuCode.cs                14 menu-type constants, 2 menu state overrides
+│   ├── DialoguesCode.cs           3 dialogue functions: counter, init, hex-digit conversion
+│   ├── MapCode.cs                 5 map/cursor functions and click-handler address constants
+│   ├── DisplayCode.cs             11 framebuffer and font selection functions


DisplayCode.cs is described as having "11 framebuffer and font selection functions", but DefineDisplayCodeOverrides() currently registers 12 functions (excluding the commented-out one). Please update the count to match what is actually registered.

Suggested change

│ ├── DisplayCode.cs 11 framebuffer and font selection functions

│ ├── DisplayCode.cs 12 framebuffer and font selection functions

Copilot · 2026-04-04T09:57:36Z

README.md

+│   ├── DatastructuresCode.cs      2 memory structure functions (index-to-pointer, sprite lookup)
+│   ├── InitCode.cs                1 VGA state initialization function
+│   ├── MT32DriverCode.cs          3 Roland MT-32 MIDI driver functions at segment 0xF000
+│   ├── UnknownCode.cs             20 partially understood functions (bit ops, memcpy, state flags)


UnknownCode.cs is described as having "20 partially understood functions", but DefineUnknownCodeOverrides() registers 21 functions (including two that are defined by name only). Please update the count or clarify what is being counted.

Suggested change

│ ├── UnknownCode.cs 20 partially understood functions (bit ops, memcpy, state flags)

│ ├── UnknownCode.cs 21 registered functions (including 2 name-only definitions; bit ops, memcpy, state flags)

Copilot · 2026-04-04T09:57:38Z

CONTRIBUTING.md

+├── Overrides/
+│   ├── Overrides.cs               Defines segment fields (cs1–cs5), registers all overrides
+│   ├── VgaDriverCode.cs           23 VGA functions (mode, blit, palette, cursor, retrace)
+│   ├── MenuCode.cs                14 menu-type constants, 2 menu state overrides


The tree says MenuCode.cs has 14 menu-type constants, but Overrides/MenuCode.cs declares 16 MENU_TYPE_* constants. Update the count so it matches the code.

Suggested change

│ ├── MenuCode.cs 14 menu-type constants, 2 menu state overrides

│ ├── MenuCode.cs 16 menu-type constants, 2 menu state overrides

Copilot · 2026-04-04T09:57:38Z

CONTRIBUTING.md

+│   ├── MenuCode.cs                14 menu-type constants, 2 menu state overrides
+│   ├── DialoguesCode.cs           3 dialogue system functions
+│   ├── MapCode.cs                 5 map/cursor functions and click-handler constants
+│   ├── DisplayCode.cs             11 framebuffer and font selection functions


The tree says DisplayCode.cs has 11 functions, but DefineDisplayCodeOverrides() registers 12 functions (excluding the commented-out registration). Please correct the count.

Suggested change

│ ├── DisplayCode.cs 11 framebuffer and font selection functions

│ ├── DisplayCode.cs 12 framebuffer and font selection functions

Copilot · 2026-04-04T09:57:39Z

CONTRIBUTING.md

+│   ├── DatastructuresCode.cs      2 memory structure functions
+│   ├── InitCode.cs                1 VGA state initialization function
+│   ├── MT32DriverCode.cs          3 Roland MT-32 MIDI functions at segment 0xF000
+│   ├── UnknownCode.cs             20 partially understood functions


The tree says UnknownCode.cs has 20 functions, but DefineUnknownCodeOverrides() registers 21 functions. Please update the number or clarify what is being counted.

Suggested change

│ ├── UnknownCode.cs 20 partially understood functions

│ ├── UnknownCode.cs 21 partially understood functions

Copilot · 2026-04-04T09:57:39Z

CONTRIBUTING.md

+| `cs1` | `0x1000` | Main game code (`DNCDPRG.EXE` loaded here) | ~80 functions across most override files |
+| `cs2` | `0xD000` | DNVGA — VGA graphics driver | 32 functions in `VgaDriverCode.cs`, 1 in `StaticDefinitions.cs` |
+| `cs3` | `0xE000` | DNPCS2 / DNSBP — PCM audio driver | None (declared but unused in current overrides) |
+| `cs4` | `0xE000` | Reserved for MIDI driver memory-dump hooks | 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE |


This table describes cs4 (0xE000) as "MIDI driver memory-dump hooks", but the MIDI/music drivers are remapped to 0xF000 (DriverLoadToolbox.DRIVER3_SEGMENT). Please avoid describing cs4 as the MIDI segment and instead describe it as the segment used for the inline dump hooks (or similar).

Suggested change

| `cs4` | `0xE000` | Reserved for MIDI driver memory-dump hooks | 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE |

| `cs4` | `0xE000` | Reserved for inline memory-dump hooks | 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE |

Copilot · 2026-04-04T09:57:39Z

CONTRIBUTING.md

+// Correct
+globalsOnDs.Set(0x47A8, value);

-1. **Keep generated naming** - Override methods use pattern `{Segment}_{Offset}_{Linear}` (e.g., `SetBackBufferAsActiveFrameBuffer_1000_C085_01C085`)
+// Incorrect — bypasses synchronization
+memory.UInt16[state.DS, 0x47A8] = value;
+```


The example uses globalsOnDs.Set(0x47A8, value), but ExtraGlobalsOnDs/GlobalsOnDs don't have a generic Set(offset, value) API. Please update the example to use the generated, typed accessor for that address (e.g. the Set1138_47A8_* method) so contributors can copy/paste a working pattern.

Copilot AI and others added 4 commits April 4, 2026 09:36

docs: rewrite README.md with factual tone, code segment documentation…

c9faefc

…, no hype Agent-Logs-Url: https://github.com/OpenRakis/Cryogenic/sessions/be596f46-8b1d-4a05-a979-74e098040fd2 Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

docs: rewrite GitHub Pages index.html with factual tone, code structu…

ce377e7

…re docs, no Ghidra Agent-Logs-Url: https://github.com/OpenRakis/Cryogenic/sessions/be596f46-8b1d-4a05-a979-74e098040fd2 Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

docs: rewrite CONTRIBUTING.md factually, remove all Ghidra references…

5ec0eab

… from codebase Agent-Logs-Url: https://github.com/OpenRakis/Cryogenic/sessions/be596f46-8b1d-4a05-a979-74e098040fd2 Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

docs: replace generic segment table with detailed per-field and per-d…

d44ee20

…river documentation Agent-Logs-Url: https://github.com/OpenRakis/Cryogenic/sessions/be596f46-8b1d-4a05-a979-74e098040fd2 Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

Copilot AI assigned Copilot and maximilien-noal Apr 4, 2026

Copilot created this pull request from a session on behalf of maximilien-noal April 4, 2026 09:49 View session

Copilot finished work on behalf of maximilien-noal April 4, 2026 09:49

Copilot AI requested a review from maximilien-noal April 4, 2026 09:49

maximilien-noal approved these changes Apr 4, 2026

View reviewed changes

maximilien-noal marked this pull request as ready for review April 4, 2026 09:52

Copilot AI review requested due to automatic review settings April 4, 2026 09:52

maximilien-noal merged commit a5b6a06 into main Apr 4, 2026
3 checks passed

maximilien-noal deleted the copilot/revamp-text-and-readme branch April 4, 2026 09:52

Copilot started reviewing on behalf of maximilien-noal April 4, 2026 09:52 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: factual rewrite of README, GitHub Pages, and CONTRIBUTING; remove Ghidra references#57

docs: factual rewrite of README, GitHub Pages, and CONTRIBUTING; remove Ghidra references#57
maximilien-noal merged 4 commits intomainfrom
copilot/revamp-text-and-readme

Copilot AI commented Apr 4, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	\| `cs4` \| `0xE000` \| Reserved for MIDI driver memory-dump hooks \| 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE \|
	\| `cs4` \| `0xE000` \| Reserved `0xE000` segment for inline memory-dump hooks \| 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE \|

	│ ├── VgaDriverCode.cs 23 VGA functions: mode setting, blitting, palette, mouse cursor
	│ ├── VgaDriverCode.cs VGA driver overrides/helpers; only a subset of the 32 registered VGA driver entry points are implemented here (mode setting, blitting, palette, mouse cursor)

	│ ├── MenuCode.cs 14 menu-type constants, 2 menu state overrides
	│ ├── MenuCode.cs 16 menu-type constants (including `MENU_TYPE_ORNI_MAP`, which shares a value with `MENU_TYPE_MOVE_TROOP`), 2 menu state overrides

	│ ├── DisplayCode.cs 11 framebuffer and font selection functions
	│ ├── DisplayCode.cs 12 framebuffer and font selection functions

	│ ├── UnknownCode.cs 20 partially understood functions (bit ops, memcpy, state flags)
	│ ├── UnknownCode.cs 21 registered functions (including 2 name-only definitions; bit ops, memcpy, state flags)

	│ ├── UnknownCode.cs 20 partially understood functions
	│ ├── UnknownCode.cs 21 partially understood functions

	\| `cs4` \| `0xE000` \| Reserved for MIDI driver memory-dump hooks \| 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE \|
	\| `cs4` \| `0xE000` \| Reserved for inline memory-dump hooks \| 2 inline hooks for memory dumps at offsets 0x02DC and 0x03EE \|

Conversation

Copilot AI commented Apr 4, 2026

Description of Changes

Rationale behind Changes

Suggested Testing Steps

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants