Crash Bandicoot: The Wrath of Cortex (GameCube)

A work-in-progress decompilation of Crash Bandicoot: The Wrath of Cortex for GameCube.

This repository does not contain game assets. You must provide your own dumped game files.

Supported versions:

• GCBE7D: Rev 0 (USA)

Dependencies

Windows

On Windows, native tooling is the intended local setup.

• Install Python and add it to PATH.
• Install ninja and add it to PATH.
  • Quick install: pip install ninja
• Install Git.

Most project tools are downloaded automatically on first configure:

• decomp-toolkit
• objdiff-cli
• binutils
• compiler packages

Linux / macOS

Local development is primarily tested on Windows. CI uses a private Linux container for protected build assets and compiler execution.

Building

• Clone the repository:

  git clone https://github.com/denzi-gh/crashwoc-decomp.git
  cd crashwoc-decomp

• Provide the original game executable:

  orig/GCBE7D/sys/main.dol
  

  Expected SHA-1:

  c9cbd49a9eb0006f55533eb7d0fb5ebe2a73b72f
  

• Configure:

  python configure.py --version GCBE7D --toolchain prodg35

• Build:

  ninja

Project layout

• config/GCBE7D/splits.txt: object and section ownership for the retail DOL
• config/GCBE7D/symbols.txt: validated symbol names
• config/GCBE7D/ldscript.ld: checked-in ProDG linker script
• src/: recovered source tree
• orig/GCBE7D/: required original game files

Diffing

Once the initial build succeeds, objdiff.json will be generated in the project root.

Download the latest release from encounter/objdiff. Set the project directory to this repository and the configuration should load automatically.

AI-assisted workflows

Repository AI guidance lives in:

• AGENTS.md
• .github/copilot-instructions.md
• .github/instructions/*.instructions.md
• .github/prompts/match-unit.prompt.md

Repo-local helper commands include:

• python tools/ai_context.py <symbol-or-unit>
• python tools/ai_lookup_symbol.py <symbol-or-address>
• python tools/ai_lookup_unit.py <unit-or-path>
• python tools/ai_match_plan.py <unit-or-path>

Provider-neutral task packs (preferred)

The same decompilation task can be driven by any agent (Codex, Claude Code, Aider, GitHub Copilot, Gemini, local models, or browser ChatGPT) via a self-contained task pack:

python tools/ai_task.py unit src/gamecode/crate.c
python tools/ai_run.py --backend print .ai/tasks/<task>

python tools/ai_task.py writes .ai/tasks/<timestamp>-<target>/ containing task.json (canonical task), prompt.md, context.md, verify.sh, and notes.md. It also supports function <symbol-or-address> and decompme <zip-or-dir> modes.

Browser ChatGPT / unsupported agents:

1. Generate a task pack with python tools/ai_task.py.
2. Run python tools/ai_run.py --backend print <task>.
3. Paste the combined prompt/context into the browser agent.
4. Apply the suggested changes locally.
5. Verify locally with sh <task>/verify.sh.

When a local CLI is available, use it directly: python tools/ai_run.py --backend copilot <task> (or codex/claude/aider/gemini). The task-pack skill under tools/skills/ documents this loop.

MCP clients can connect to the read-only repo-index tools via the stdlib JSON-RPC stdio server: python tools/mcp_decomp.py serve (use list to inspect the tool surface).

GitHub Copilot (compatibility)

The original command still works and now builds a unit task pack before launching Copilot:

python tools/ai_launch_copilot.py src/gamecode/crate.c

Use --no-launch --print-prompt if you only want the generated prompt text.

Please always review AI generated Code. The workflows are designed in way that prevents the AI to generate slop like inline Assembly and compiler specific patterns that no human would write but you never know!

Pull Requests

Pull requests are welcome.

For build or decomp changes, keep them focused and include:

• what changed
• what was verified locally
• whether matching, build behavior, or tooling behavior changed

Community

Discord: https://discord.gg/kmCPpW4KvJ