crimsonland 0.1.0.dev12__tar.gz → 0.1.0.dev14__tar.gz

crimsonland-0.1.0.dev14/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.3
+Name: crimsonland
+Version: 0.1.0.dev14
+Requires-Dist: construct>=2.10.70
+Requires-Dist: pillow>=12.1.0
+Requires-Dist: platformdirs>=4.5.1
+Requires-Dist: raylib>=5.5.0.4
+Requires-Dist: typer>=0.21.1
+Requires-Python: >=3.13
+Project-URL: Documentation, https://crimson.banteg.xyz/
+Project-URL: Repository, https://github.com/banteg/crimson
+Description-Content-Type: text/markdown
+
+# Crimsonland 1.9.93 decompilation + rewrite
+
+This repository is a **reverse engineering + high‑fidelity reimplementation** of **Crimsonland 1.9.93 (2003)**.
+
+- **Target build:** `v1.9.93` (GOG "Crimsonland Classic") — see [docs/provenance.md](docs/provenance.md) for exact hashes.
+- **Rewrite:** a runnable reference implementation in **Python + raylib** under `src/`.
+- **Analysis:** decompiles, name/type maps, and runtime evidence under `analysis/`.
+- **Docs:** long-form notes and parity tracking under `docs/` (start at [docs/index.md](docs/index.md)).
+
+The north star is **behavioral parity** with the original Windows build: timings, RNG, UI/layout quirks, asset decoding, and gameplay rules should match as closely as practical.
+
+**[Read the full story](https://banteg.xyz/posts/crimsonland/)** of how this project came together: reverse engineering workflow, custom asset formats, AI-assisted decompilation, and game preservation philosophy.
+
+---
+
+## Quick start
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager.
+
+### Run the latest packaged build
+
+If you just want to play the rewrite:
+
+```bash
+uvx crimsonland@latest
+```
+
+### Run from a checkout
+
+```bash
+gh repo clone banteg/crimson
+cd crimson
+uv run crimson
+```
+
+### Keep runtime files local to the repo
+
+By default, runtime files (e.g. `crimson.cfg`, `game.cfg`, highscores, logs, downloaded PAQs) live in your per-user data dir.
+To keep everything under this checkout:
+
+```bash
+export CRIMSON_RUNTIME_DIR="$PWD/artifacts/runtime"
+mkdir -p artifacts/runtime
+uv run crimson
+```
+
+---
+
+## Assets + binaries
+
+There are two separate “inputs” to this repo:
+
+1. **Runtime assets for the rewrite** (PAQ archives)
+2. **Original Windows binaries for reverse engineering** (`crimsonland.exe`, `grim.dll`, …)
+
+We keep them out of git and expect a local layout like:
+
+```text
+game_bins/
+  crimsonland/
+    1.9.93-gog/
+      crimsonland.exe
+      grim.dll
+      crimson.paq
+      music.paq
+      sfx.paq
+artifacts/
+  runtime/        # optional: where you run the rewrite (cfg/status/paqs)
+  assets/         # optional: extracted PAQs for inspection/tools
+```
+
+### Running the rewrite
+
+The rewrite loads the assets from original archives:
+
+- `crimson.paq`
+- `music.paq`
+- `sfx.paq`
+
+### Extracted assets
+
+For inspection/diffs/tools, you can extract PAQs into a filesystem tree:
+
+```bash
+uv run crimson extract crimsonland_1.9.93 artifacts/assets
+```
+
+Same as the original, many loaders can work from either:
+
+- **PAQ-backed assets** (preferred when available), or
+- the **extracted filesystem layout** under `artifacts/assets/`.
+
+---
+
+## CLI cheat sheet
+
+Everything is exposed via the `crimson` CLI (alias: `crimsonland`):
+
+```bash
+uv run crimson               # run the game (default command)
+uv run crimson view ui       # debug views / sandboxes
+uv run crimson quests 1.1    # print quest spawn script
+uv run crimson config        # inspect crimson.cfg
+uv run crimson extract <game_dir> artifacts/assets
+```
+
+Useful flags:
+
+- `--base-dir PATH` / `CRIMSON_RUNTIME_DIR=...` — where saves/config/logs live
+- `--assets-dir PATH` — where `.paq` archives (or extracted assets) are loaded from
+- `--seed N` — deterministic runs for parity testing
+- `--demo` — enable shareware/demo paths
+- `--no-intro` — skip logos/intro music
+
+---
+
+## Docs
+
+Docs are authored in `docs/` and built as a static site at https://crimson.banteg.xyz/
+
+For development, it's useful to have a live local build:
+
+```
+uv tool install zensical
+zensical serve
+```
+
+---
+
+## Development
+
+### Tests
+
+```bash
+uv run pytest
+```
+
+### Lint / checks
+
+```bash
+uv run lint-imports
+uv run python scripts/check_asset_loader_usage.py
+```
+
+### `justfile` shortcuts
+
+If you have `just` installed:
+
+```bash
+just --list
+just test
+just docs-build
+just ghidra-exe
+just ghidra-grim
+```
+
+---
+
+## Reverse engineering workflow
+
+High level:
+
+- **Static analysis is the source of truth.**
+  - Update names/types in [analysis/ghidra/maps/](analysis/ghidra/maps/).
+  - Treat [analysis/ghidra/raw/](analysis/ghidra/raw/) as generated output (regenerate; do not hand-edit).
+- **Runtime tooling** (Frida / WinDbg) validates ambiguous behavior and captures ground truth.
+  - Evidence summaries live under [analysis/frida/](analysis/frida/).
+
+---
+
+## Contributing notes
+
+- Keep changes small and reviewable (one subsystem/feature at a time).
+- Prefer *measured parity* (captures/logs/deterministic tests) over “looks right”.
+- When porting float constants from decompilation, prefer the intended value
+  (e.g. `0.6` instead of `0.6000000238418579` when it’s clearly a float32 artifact).
+
+---
+
+## Legal
+
+This project is an independent reverse engineering and reimplementation effort for preservation, research, and compatibility.
+
+No original assets or binaries are included. Use your own legally obtained copy.

{crimsonland-0.1.0.dev12 → crimsonland-0.1.0.dev14}/pyproject.toml

@@ -1,6 +1,7 @@
 [project]
 name = "crimsonland"
-version = "0.1.0.dev12"
+version = "0.1.0.dev14"
+readme = { file = "readme.md", content-type = "text/markdown" }
 requires-python = ">=3.13"
 dependencies = [
     "construct>=2.10.70",
@@ -10,6 +11,10 @@ dependencies = [
     "typer>=0.21.1",
 ]
 
+[project.urls]
+Documentation = "https://crimson.banteg.xyz/"
+Repository = "https://github.com/banteg/crimson"
+
 [project.scripts]
 crimsonland = "crimson.cli:main"
 crimson = "crimson.cli:main"

crimsonland-0.1.0.dev14/readme.md

@@ -0,0 +1,184 @@
+# Crimsonland 1.9.93 decompilation + rewrite
+
+This repository is a **reverse engineering + high‑fidelity reimplementation** of **Crimsonland 1.9.93 (2003)**.
+
+- **Target build:** `v1.9.93` (GOG "Crimsonland Classic") — see [docs/provenance.md](docs/provenance.md) for exact hashes.
+- **Rewrite:** a runnable reference implementation in **Python + raylib** under `src/`.
+- **Analysis:** decompiles, name/type maps, and runtime evidence under `analysis/`.
+- **Docs:** long-form notes and parity tracking under `docs/` (start at [docs/index.md](docs/index.md)).
+
+The north star is **behavioral parity** with the original Windows build: timings, RNG, UI/layout quirks, asset decoding, and gameplay rules should match as closely as practical.
+
+**[Read the full story](https://banteg.xyz/posts/crimsonland/)** of how this project came together: reverse engineering workflow, custom asset formats, AI-assisted decompilation, and game preservation philosophy.
+
+---
+
+## Quick start
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager.
+
+### Run the latest packaged build
+
+If you just want to play the rewrite:
+
+```bash
+uvx crimsonland@latest
+```
+
+### Run from a checkout
+
+```bash
+gh repo clone banteg/crimson
+cd crimson
+uv run crimson
+```
+
+### Keep runtime files local to the repo
+
+By default, runtime files (e.g. `crimson.cfg`, `game.cfg`, highscores, logs, downloaded PAQs) live in your per-user data dir.
+To keep everything under this checkout:
+
+```bash
+export CRIMSON_RUNTIME_DIR="$PWD/artifacts/runtime"
+mkdir -p artifacts/runtime
+uv run crimson
+```
+
+---
+
+## Assets + binaries
+
+There are two separate “inputs” to this repo:
+
+1. **Runtime assets for the rewrite** (PAQ archives)
+2. **Original Windows binaries for reverse engineering** (`crimsonland.exe`, `grim.dll`, …)
+
+We keep them out of git and expect a local layout like:
+
+```text
+game_bins/
+  crimsonland/
+    1.9.93-gog/
+      crimsonland.exe
+      grim.dll
+      crimson.paq
+      music.paq
+      sfx.paq
+artifacts/
+  runtime/        # optional: where you run the rewrite (cfg/status/paqs)
+  assets/         # optional: extracted PAQs for inspection/tools
+```
+
+### Running the rewrite
+
+The rewrite loads the assets from original archives:
+
+- `crimson.paq`
+- `music.paq`
+- `sfx.paq`
+
+### Extracted assets
+
+For inspection/diffs/tools, you can extract PAQs into a filesystem tree:
+
+```bash
+uv run crimson extract crimsonland_1.9.93 artifacts/assets
+```
+
+Same as the original, many loaders can work from either:
+
+- **PAQ-backed assets** (preferred when available), or
+- the **extracted filesystem layout** under `artifacts/assets/`.
+
+---
+
+## CLI cheat sheet
+
+Everything is exposed via the `crimson` CLI (alias: `crimsonland`):
+
+```bash
+uv run crimson               # run the game (default command)
+uv run crimson view ui       # debug views / sandboxes
+uv run crimson quests 1.1    # print quest spawn script
+uv run crimson config        # inspect crimson.cfg
+uv run crimson extract <game_dir> artifacts/assets
+```
+
+Useful flags:
+
+- `--base-dir PATH` / `CRIMSON_RUNTIME_DIR=...` — where saves/config/logs live
+- `--assets-dir PATH` — where `.paq` archives (or extracted assets) are loaded from
+- `--seed N` — deterministic runs for parity testing
+- `--demo` — enable shareware/demo paths
+- `--no-intro` — skip logos/intro music
+
+---
+
+## Docs
+
+Docs are authored in `docs/` and built as a static site at https://crimson.banteg.xyz/
+
+For development, it's useful to have a live local build:
+
+```
+uv tool install zensical
+zensical serve
+```
+
+---
+
+## Development
+
+### Tests
+
+```bash
+uv run pytest
+```
+
+### Lint / checks
+
+```bash
+uv run lint-imports
+uv run python scripts/check_asset_loader_usage.py
+```
+
+### `justfile` shortcuts
+
+If you have `just` installed:
+
+```bash
+just --list
+just test
+just docs-build
+just ghidra-exe
+just ghidra-grim
+```
+
+---
+
+## Reverse engineering workflow
+
+High level:
+
+- **Static analysis is the source of truth.**
+  - Update names/types in [analysis/ghidra/maps/](analysis/ghidra/maps/).
+  - Treat [analysis/ghidra/raw/](analysis/ghidra/raw/) as generated output (regenerate; do not hand-edit).
+- **Runtime tooling** (Frida / WinDbg) validates ambiguous behavior and captures ground truth.
+  - Evidence summaries live under [analysis/frida/](analysis/frida/).
+
+---
+
+## Contributing notes
+
+- Keep changes small and reviewable (one subsystem/feature at a time).
+- Prefer *measured parity* (captures/logs/deterministic tests) over “looks right”.
+- When porting float constants from decompilation, prefer the intended value
+  (e.g. `0.6` instead of `0.6000000238418579` when it’s clearly a float32 artifact).
+
+---
+
+## Legal
+
+This project is an independent reverse engineering and reimplementation effort for preservation, research, and compatibility.
+
+No original assets or binaries are included. Use your own legally obtained copy.

{crimsonland-0.1.0.dev12 → crimsonland-0.1.0.dev14}/src/crimson/assets_fetch.py

@@ -2,7 +2,9 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
+import os
 import shutil
+import tempfile
 import urllib.request
 
 from grim.console import ConsoleState
@@ -19,17 +21,30 @@ class DownloadResult:
 
 
 def _download_file(url: str, dest: Path) -> None:
-    tmp = dest.with_suffix(dest.suffix + ".tmp")
-    if tmp.exists():
-        tmp.unlink()
+    tmp_path: Path | None = None
     try:
         req = urllib.request.Request(url, headers={"User-Agent": "crimsonland-decompile"})
-        with urllib.request.urlopen(req, timeout=30) as resp, tmp.open("wb") as handle:
-            shutil.copyfileobj(resp, handle)
-        tmp.replace(dest)
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            with tempfile.NamedTemporaryFile(
+                mode="wb",
+                delete=False,
+                dir=dest.parent,
+                prefix=dest.name + ".",
+                suffix=".tmp",
+            ) as handle:
+                tmp_path = Path(handle.name)
+                shutil.copyfileobj(resp, handle)
+                handle.flush()
+                os.fsync(handle.fileno())
+        if tmp_path is None:
+            raise RuntimeError("assets: temporary file not created")
+        tmp_path.replace(dest)
     finally:
-        if tmp.exists():
-            tmp.unlink()
+        if tmp_path is not None:
+            try:
+                tmp_path.unlink()
+            except FileNotFoundError:
+                pass
 
 
 def download_missing_paqs(

crimsonland-0.1.0.dev14/src/crimson/frontend/high_scores_layout.py

@@ -0,0 +1,26 @@
+"""
+Layout constants for the classic high scores screen (state_id=14).
+
+Measured from analysis/frida/ui_render_trace_oracle_1024x768.json.
+"""
+
+from __future__ import annotations
+
+# Panel positions are expressed in "panel pos" (pre-offset) space, matching other menu panels:
+#   panel_top_left = (panel_pos_x + MENU_PANEL_OFFSET_X, panel_pos_y + y_shift + MENU_PANEL_OFFSET_Y)
+
+HS_LEFT_PANEL_POS_X = -119.0
+HS_LEFT_PANEL_POS_Y = 185.0
+HS_LEFT_PANEL_HEIGHT = 378.0
+
+HS_RIGHT_PANEL_POS_X = 609.0
+HS_RIGHT_PANEL_POS_Y = 200.0
+HS_RIGHT_PANEL_HEIGHT = 254.0
+
+# Buttons inside the left panel (relative to the left panel top-left).
+HS_BUTTON_X = 234.0  # x0=136 at 1024x768
+HS_BUTTON_Y0 = 268.0  # y0=462
+HS_BUTTON_STEP_Y = 33.0
+
+HS_BACK_BUTTON_X = 400.0  # x0=302
+HS_BACK_BUTTON_Y = 301.0  # y0=495

{crimsonland-0.1.0.dev12 → crimsonland-0.1.0.dev14}/src/crimson/frontend/menu.py

@@ -19,8 +19,8 @@ if TYPE_CHECKING:
     from ..game import GameState
 
 
-MENU_LABEL_WIDTH = 124.0
-MENU_LABEL_HEIGHT = 30.0
+MENU_LABEL_WIDTH = 122.0
+MENU_LABEL_HEIGHT = 28.0
 MENU_LABEL_ROW_HEIGHT = 32.0
 MENU_LABEL_ROW_PLAY_GAME = 1
 MENU_LABEL_ROW_OPTIONS = 2
@@ -31,18 +31,17 @@ MENU_LABEL_ROW_QUIT = 6
 MENU_LABEL_ROW_BACK = 7
 MENU_LABEL_BASE_X = -60.0
 MENU_LABEL_BASE_Y = 210.0
-MENU_LABEL_OFFSET_X = 270.0
-MENU_LABEL_OFFSET_Y = -38.0
+MENU_LABEL_OFFSET_X = 271.0
+MENU_LABEL_OFFSET_Y = -37.0
 MENU_LABEL_STEP = 60.0
-MENU_ITEM_OFFSET_X = -72.0
-MENU_ITEM_OFFSET_Y = -60.0
-MENU_PANEL_WIDTH = 512.0
-MENU_PANEL_HEIGHT = 256.0
-# ui_menu_assets_init:
-#   - ui_menuPanel starts with offset_x=+20 (ui_element_set_rect)
-#   - the menu-panel layout copy applies data_48fdb4 -= 116, so offset_x becomes -96
-MENU_PANEL_OFFSET_X = -96.0
-MENU_PANEL_OFFSET_Y = -82.0
+MENU_ITEM_OFFSET_X = -71.0
+MENU_ITEM_OFFSET_Y = -59.0
+MENU_PANEL_WIDTH = 510.0
+MENU_PANEL_HEIGHT = 254.0
+# Measured from ui_render_trace at 1024x768 (stable timeline):
+# panel top-left is (pos_x + 21, pos_y - 81) and size is 510x254, plus a shadow pass at +7,+7.
+MENU_PANEL_OFFSET_X = 21.0
+MENU_PANEL_OFFSET_Y = -81.0
 MENU_PANEL_BASE_X = -45.0
 MENU_PANEL_BASE_Y = 210.0
 MENU_SCALE_SMALL_THRESHOLD = 640
@@ -52,10 +51,10 @@ MENU_SCALE_SMALL = 0.8
 MENU_SCALE_LARGE = 1.2
 MENU_SCALE_SHIFT = 10.0
 
-MENU_SIGN_WIDTH = 573.44
-MENU_SIGN_HEIGHT = 143.36
-MENU_SIGN_OFFSET_X = -577.44
-MENU_SIGN_OFFSET_Y = -62.0
+MENU_SIGN_WIDTH = 571.44
+MENU_SIGN_HEIGHT = 141.36
+MENU_SIGN_OFFSET_X = -576.44
+MENU_SIGN_OFFSET_Y = -61.0
 MENU_SIGN_POS_Y = 70.0
 MENU_SIGN_POS_Y_SMALL = 60.0
 MENU_SIGN_POS_X_PAD = 4.0
@@ -584,21 +583,24 @@ class MenuView:
         start_ms: int,
         end_ms: int,
         width: float,
+        direction_flag: int = 0,
     ) -> tuple[float, float]:
         # Matches ui_element_update: angle lerps pi/2 -> 0 over [end_ms, start_ms].
-        # Direction flag (element+0x314) appears to be 0 for main menu elements.
+        # direction_flag=0 slides from left  (-width -> 0)
+        # direction_flag=1 slides from right (+width -> 0)
         if start_ms <= end_ms or width <= 0.0:
             return 0.0, 0.0
+        dir_sign = 1.0 if int(direction_flag) else -1.0
         t = self._timeline_ms
         if t < end_ms:
             angle = 1.5707964
-            offset_x = -abs(width)
+            offset_x = dir_sign * abs(width)
         elif t < start_ms:
             elapsed = t - end_ms
             span = float(start_ms - end_ms)
             p = float(elapsed) / span
             angle = 1.5707964 * (1.0 - p)
-            offset_x = -((1.0 - p) * abs(width))
+            offset_x = dir_sign * ((1.0 - p) * abs(width))
         else:
             angle = 0.0
             offset_x = 0.0

{crimsonland-0.1.0.dev12 → crimsonland-0.1.0.dev14}/src/crimson/frontend/panels/base.py

@@ -8,6 +8,7 @@ from grim.assets import PaqTextureCache
 from grim.audio import play_sfx, update_audio
 from grim.terrain_render import GroundRenderer
 
+from ...ui.menu_panel import draw_classic_menu_panel
 from ..assets import MenuAssets, _ensure_texture_cache, load_menu_assets
 from ..menu import (
     MENU_ITEM_OFFSET_X,
@@ -70,6 +71,9 @@ class PanelMenuView:
         body: str | None = None,
         panel_pos_x: float = PANEL_POS_X,
         panel_pos_y: float = PANEL_POS_Y,
+        panel_offset_x: float = MENU_PANEL_OFFSET_X,
+        panel_offset_y: float = MENU_PANEL_OFFSET_Y,
+        panel_height: float = MENU_PANEL_HEIGHT,
         back_pos_x: float = PANEL_BACK_POS_X,
         back_pos_y: float = PANEL_BACK_POS_Y,
         back_action: str = "back_to_menu",
@@ -79,6 +83,9 @@ class PanelMenuView:
         self._body_lines = (body or "").splitlines()
         self._panel_pos_x = panel_pos_x
         self._panel_pos_y = panel_pos_y
+        self._panel_offset_x = panel_offset_x
+        self._panel_offset_y = panel_offset_y
+        self._panel_height = panel_height
         self._back_pos_x = back_pos_x
         self._back_pos_y = back_pos_y
         self._back_action = back_action
@@ -223,40 +230,21 @@ class PanelMenuView:
         if assets is None or assets.panel is None:
             return
         panel = assets.panel
-        panel_w = MENU_PANEL_WIDTH
-        panel_h = MENU_PANEL_HEIGHT
         _angle_rad, slide_x = MenuView._ui_element_anim(
             self,
             index=1,
             start_ms=PANEL_TIMELINE_START_MS,
             end_ms=PANEL_TIMELINE_END_MS,
-            width=panel_w * self._menu_item_scale(0)[0],
+            width=MENU_PANEL_WIDTH * self._menu_item_scale(0)[0],
         )
         item_scale, _local_y_shift = self._menu_item_scale(0)
-        dst = rl.Rectangle(
-            self._panel_pos_x + slide_x,
-            self._panel_pos_y + self._widescreen_y_shift,
-            panel_w * item_scale,
-            panel_h * item_scale,
-        )
-        origin = rl.Vector2(-(MENU_PANEL_OFFSET_X * item_scale), -(MENU_PANEL_OFFSET_Y * item_scale))
+        panel_w = MENU_PANEL_WIDTH * item_scale
+        panel_h = float(self._panel_height) * item_scale
+        top_left_x = self._panel_pos_x + slide_x + self._panel_offset_x * item_scale
+        top_left_y = self._panel_pos_y + self._widescreen_y_shift + self._panel_offset_y * item_scale
+        dst = rl.Rectangle(float(top_left_x), float(top_left_y), float(panel_w), float(panel_h))
         fx_detail = bool(self._state.config.data.get("fx_detail_0", 0))
-        if fx_detail:
-            MenuView._draw_ui_quad_shadow(
-                texture=panel,
-                src=rl.Rectangle(0.0, 0.0, float(panel.width), float(panel.height)),
-                dst=rl.Rectangle(dst.x + UI_SHADOW_OFFSET, dst.y + UI_SHADOW_OFFSET, dst.width, dst.height),
-                origin=origin,
-                rotation_deg=0.0,
-            )
-        MenuView._draw_ui_quad(
-            texture=panel,
-            src=rl.Rectangle(0.0, 0.0, float(panel.width), float(panel.height)),
-            dst=dst,
-            origin=origin,
-            rotation_deg=0.0,
-            tint=rl.WHITE,
-        )
+        draw_classic_menu_panel(panel, dst=dst, tint=rl.WHITE, shadow=fx_detail)
 
     def _draw_entry(self, entry: MenuEntry) -> None:
         assets = self._assets