Shadow the Hedgehog

<img src="https://decomp.dev/dev-camo/shadow-decomp.svg?w=512&h=256" width="512" height="256">

<!-- decomp.dev progress badges See https://decomp.dev/api for an API overview. -->

A work-in-progress decompilation of Shadow the Hedgehog.

This repository does not contain any game assets or assembly whatsoever. An existing copy of the game is required.

Supported versions:

• GUPE8P: Rev 0 (USA)
• GUPJ8P: Rev 0 (Japan)
• GUPP8P: Rev 0 (Europe / Australia)

AI Use Disclosure

This project uses large language model (LLM) assistance tools to support decompilation analysis, code development, build troubleshooting, and documentation.

Dependencies

Install uv, then run these commands from the repository root:

uv sync --locked

The project requires Python 3.14 or newer. uv creates .venv and installs the Ninja version recorded in uv.lock, obtaining a compatible Python if needed. Use uv run --locked for project commands; activating the environment is optional. Keep pyproject.toml and uv.lock together when setting up another checkout. If --locked reports an inconsistent lockfile, resolve the manifest/lockfile mismatch instead of bypassing the check or upgrading dependencies as part of a normal build.

The build downloads its pinned decomp-toolkit, objdiff CLI, compiler package, and other native tools into build/. These are separate from uv's Python environment. On Linux/macOS, the build uses wibo to run the Windows compiler tools; on Windows, use native tooling. Cross-host filesystem watching can affect objdiff automatic rebuilds, so rebuild explicitly if changes are not detected.

Building

• Clone the repository:

  git clone https://github.com/dev-camo/shadow-decomp.git
  

• Copy your game's disc image to orig/{GUPE8P,GUPJ8P,GUPP8P}.

  • Supported formats: ISO (GCM), RVZ, WIA, WBFS, CISO, NFS, GCZ, TGC
  • After the initial build, the disc image can be deleted to save space.

• Configure:

  uv run --locked python configure.py
  

  To use another region, run uv run --locked python configure.py --version GUPJ8P or uv run --locked python configure.py --version GUPP8P before building. Running uv run --locked python configure.py selects the default GUPE8P (USA).

• Build:

  uv run --locked ninja
  

Diffing

Once the initial build succeeds, an objdiff.json should exist in the project root.

If launching objdiff outside the uv environment on Linux/macOS, configure with uv run --locked python configure.py --ninja .venv/bin/ninja so automatic rebuilds use the project's Ninja. Include --version GUPJ8P or --version GUPP8P when working on those regions. On Windows, use .venv/Scripts/ninja.exe for this option.

Download the latest release from encounter/objdiff. Under project settings, set Project directory. The configuration should be loaded automatically.

Select an object from the left sidebar to begin diffing. Changes to the project will rebuild automatically: changes to source files, headers, configure.py, splits.txt or symbols.txt.

Attribution

This decompilation builds on work published by other decompilation and reverse-engineering projects. Their sources were used as references for the code, names and layouts listed below; every reconstructed file is still verified against this game's own executable.

Project	Used for
Resident Evil 4 (GameCube)	CRI middleware sources used as the basis for most of src/CRI/: ADX (ADXF, ADXB format decoders, ADXSJD, ADXT init, header decoding, ADXPD, ADXRNA, ADXAMP, errors), LSC, SJ, SVM, CVFS and the MFCI/GCCI device interfaces, Sofdec MPV/MPS/SFD and UTY helper units and the MWSTM stream glue; the CRI interface and Sofdec layout headers; the Dolphin SDK headers (include/dolphin, include/libc) and SDK sources in src/dolphin/; names for CRI and Dolphin SDK functions
Dolphin SDK 2004 decompilation	Origin of the Dolphin SDK sources and headers (taken via the Resident Evil 4 project) behind src/dolphin/, include/dolphin and include/libc, including the SDK_REVISION handling of the Nov 2004 GX/OS builds; also used directly for CARDOpen.c, CARDNet.c, __start.c, __ppc_eabi_init.c, dsp_debug.c and odenotstub.c in src/dolphin/
Mario Party 4 PC port (partyboard)	OdemuExi2 DebuggerDriver.c source used for src/dolphin/DebuggerDriver.c (taken via the Resident Evil 4 project)
The Legend of Zelda: Twilight Princess	CodeWarrior runtime and MSL C sources and headers (src/PowerPC_EABI_Support/): fdlibm math, mem, mem_funcs, direct_io, signal, string, strtoul, strtold, wchar_io, arith, buffer_io, char_io, ctype, extras (file layout), file_io, FILE_POS, critical_regions, errno, ansi_files, uart_console_io_gcn, __va_arg, ptmf and NMWException, and the GC/2.7 runtime build flags; the MSL alloc.c pool structures and __pool_free, and the Gecko_ExceptionPPC fragment registration, used by src/Runtime.PPCEABI.H/
Mortal Kombat: Deception (GameCube)	CRI svm.c, lsc.c and adx_fini.c references: function order and names such as SVM_ExecSvrMain/Fs/Vsync/MwIdle, SVM_SetCbBdr, LSC_SetLpFlg and LSC_Start; the inlined cosine helper dctac_Cos in CRI dct_ac.c
Street Fighter III: 3rd Strike	Newer CRI lsc.c reference: source order, error-code numbering and names such as LSC_ResetEntry and the LSC stream queries; CRI adx_fs.c function bodies and ADXF/ADXSTM function names; CRI adx_lsc.c function names, order and error codes; CRI adx_tlk2.c (ADXT_StartFname, ADXT_StartAfs) and ADXT names such as ADXT_StopWithoutLsc and ADXT_GetTimeReal
Teenage Mutant Ninja Turtles 2: Battle Nexus (PC reimplementation)	CRI adx_fs.c structure: public ADXF_* entries wrapping adxf_* workers, and names such as adxf_OpenRange
The World Ends With You	CRI adx_crs.c function order and the names ADXCRS_Enter and ADXCRS_Leave; CRI adx_stmc.c structure (public ADXSTM_* entries over adxstm_* workers)
Dragon Ball Z: Budokai Tenkaichi 3	CRI adx_fs.c worker and wrapper naming notes
Xenoblade Chronicles	CRI sj_crs.c names SJCRS_Init and SJCRS_Finish
Sonic Heroes	CRI cri_cvfs.c and adx_fini.c comparison references
The Legend of Zelda: The Wind Waker and Twilight Princess	Metrowerks runtime and Dolphin OS references for GCN_mem_alloc.c, abort, signal and heap function names; the CPlusLibPPC.cp runtime file layout (Wind Waker)
Pikmin 2	Metrowerks MSL allocator references (alloc.c function names and sizes); the MSL __strtold body used for strtold.c, the ansi_fp.c, printf.c, scanf.c and mbstring.c functions, the MetroTRK sources and headers, and the float.c and locale.c data; original sizes of the dead-stripped MSL string.c functions
Metroid Prime and Mario Kart: Double Dash!!	Metrowerks MSL allocator comparison references
fdlibm via newlib	The single precision acos (ef_acos.c, float conversion by Ian Lance Taylor, Cygnus Support) adapted for the keyframe interpolation in src/rw/fn_80445CF4.c; its notices are kept with the code
Boost 1.32 (Boost Software License 1.0)	The headers in include/boost/ (config (exception configuration), checked_delete, scoped_ptr, scoped_array, shared_ptr with its shared_count, weak_ptr, throw_exception, get_pointer, mem_fn, bind, visit_each, function, utility/addressof) are adapted from the Boost 1.32 sources and checked against the game's code; each file keeps its Boost copyright notice and include/boost/LICENSE_1_0.txt is the license text
decomp-toolkit, dtk-template and objdiff	Project tooling, build template and object diffing