crimsonland 0.1.0.dev13__py3-none-any.whl → 0.1.0.dev14__py3-none-any.whl

crimsonland-0.1.0.dev14.dist-info/METADATA

@@ -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.dev13.dist-info → crimsonland-0.1.0.dev14.dist-info}/RECORD

@@ -140,7 +140,7 @@ grim/sfx.py,sha256=cpn2Mmeio7BSDgbStSft-eZchO9Ot2MrK6iXJqxlLqU,7836
 grim/sfx_map.py,sha256=FM5iBzKkG30Vtu78SRavVNgXMbGK7ZFcQ8i6lgMlzVw,4697
 grim/terrain_render.py,sha256=EZ7ySYJyTZwXcrJx1mKbY3ewZtPi7Y270XnZgGJyZG8,31509
 grim/view.py,sha256=oF4pHZehBqOxPjKMU28TDg3qATh_amMIRJp-vMQnpn4,334
-crimsonland-0.1.0.dev13.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
-crimsonland-0.1.0.dev13.dist-info/entry_points.txt,sha256=jzzcExxiE9xpt4Iw2nbB1lwTv2Zj4H14WJTIPMkAjoE,77
-crimsonland-0.1.0.dev13.dist-info/METADATA,sha256=zmr0z7DJR6Z72vu_5i0IQbCO1qJ-sDd25SGmghwEtWA,244
-crimsonland-0.1.0.dev13.dist-info/RECORD,,
+crimsonland-0.1.0.dev14.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+crimsonland-0.1.0.dev14.dist-info/entry_points.txt,sha256=jzzcExxiE9xpt4Iw2nbB1lwTv2Zj4H14WJTIPMkAjoE,77
+crimsonland-0.1.0.dev14.dist-info/METADATA,sha256=oXFIziqtI4gQTabCnabSQ9Q9omr3LkcdySpATsnsuqA,5262
+crimsonland-0.1.0.dev14.dist-info/RECORD,,

crimsonland-0.1.0.dev13.dist-info/METADATA

@@ -1,9 +0,0 @@
-Metadata-Version: 2.3
-Name: crimsonland
-Version: 0.1.0.dev13
-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