GitHub - adonis-singh/re4: Resident Evil 4 (GameCube, G4BE08 debug build) — complete byte-identical decompilation to C/C++ · GitHub

Skip to content

Navigation MenuSign inAppearance settingsPlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub Copilot appDirect agents from issue to mergeMCP RegistryIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesCode QualityEnforce quality at mergeAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersView all resourcesOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityGitHub StarsArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricingSearch/Sign inSign upAppearance settings

You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

adonis-singh

/

re4

Public

Notifications
You must be signed in to change notification settings

Fork
12

Star
138

Code

Issues
2

Pull requests
0

Actions

Projects

Security and quality
0

Insights

Additional navigation options

Code

Issues

Pull requests

Actions

Projects

Security and quality

Insights

masterBranchesTagsGo to fileCodeOpen more actions menuLatest commit History771 Commits771 CommitsFolders and filesNameNameLast commit messageLast commit date.github/ISSUE_TEMPLATE.github/ISSUE_TEMPLATE  config/G4BE08config/G4BE08  docsdocs  includeinclude  orig/G4BE08orig/G4BE08  srcsrc  toolstools  .clang-format.clang-format  .editorconfig.editorconfig  .gitattributes.gitattributes  .gitignore.gitignore  CONTRIBUTING.mdCONTRIBUTING.md  LICENSELICENSE  README.mdREADME.md  configure.pyconfigure.py  View all filesRepository files navigationREADMEContributingCC0-1.0 licenseMore itemsResident Evil 4 (GameCube) — decompilation
A complete, byte-identical decompilation of Resident Evil 4 for the Nintendo GameCube: the
G4BE08 debug build (the "Nov 25 2004" prototype, both discs), whose Bio4.sym files name every
function. Building the repository reproduces main.dol and all 114 REL overlays exactly
(config/G4BE08/build.sha1, checked on every build).

Objects
1083 (675 in the DOL, 408 across the 114 RELs), all byte-identical; 15641 functions

Source
~555k lines of C/C++ (src/), ~33k lines of headers (include/); no assembly files

Game code
SN Systems ProDG 3.9.3 — GCC 2.95.3 "SN BUILD v1.79", built natively from SN's GPL source drop

CRI middleware (src/lib/adx_*, sfd_*, mpv_*, …)
Metrowerks CodeWarrior 2.4.7 (GC/2.7), the compiler CRI shipped the libraries with

Nintendo SDK (src/lib/OS*, GX*, …)
Metrowerks CodeWarrior GC/1.2.5n, sources from dolsdk2004

The repository contains no game assets and no code or data copied from the discs. You need your
own images of the debug discs to build (disc 1 for main.dol and most RELs, disc 2 for the four
island-stage RELs); the original files are read from them at configure time.
Building
Linux, Python 3, ninja. Compilers and tools (decomp-toolkit, objdiff,
wibo, the CodeWarrior builds) are downloaded by the first configure run, except the native SN GCC:
# 1. the native cc1/cc1plus (once): needs SN's GPL source drop, see tools/sn-gcc/build.sh
SN_GCC_SRC=/path/to/NGC_GNU_SRC/NGC tools/sn-gcc/build.sh

# 2. your disc images (disc 1: main.dol + 110 RELs; disc 2: the four island-stage RELs st3_0..st3_3)
cp re4_debug_disc1.iso re4_debug_disc2.gcm orig/G4BE08/

# 3. build and verify
python3 configure.py && ninja
ninja ends with the progress report (100% matched and linked for the DOL and the REL modules);
build/tools/dtk shasum -c config/G4BE08/build.sha1 prints 115 OK lines. To work on a unit, python3 tools/bytecmp.py game/foo compares its object with
the original word by word and python3 tools/fdiff.py game/foo <symbol> shows one function.
Layout

src/game/ — the game (C++; a few newlib C units). src/em*/ enemies, src/wep*/ weapons,
src/pl*/ player characters, src/st*/ rooms (one REL per room), src/t_*/, src/Tools/,
src/tools/ the in-game debug editors, src/Sscrn/ the sub-screens, src/lib/ SDK, CRI and runtime.
include/ — headers, including the reconstructed struct layouts.
config/G4BE08/ — unit lists (objects.py, modules.py), symbols.txt, splits.txt, linker
scripts, per-module REL data (modules/<mod>/), build.sha1.
tools/ — build generator (project.py), the ProDG driver (ngccc.py), REL rebuild (make_rel.py,
link_rel.py), the compare tools, sn-gcc/ (native compiler build), research/ (compiler-analysis kit),
motion_export.py + motion/ (animation export to glTF/BVH, evaluated with the game's own code and
verified against the game running in Dolphin).
docs/overview.md — how the engine is put together: a reading guide to src/ by subsystem.
docs/matching.md — how the matching was done: compiler provenance, the catalogue of compiler
mechanisms and the source shapes that reproduce them, rules of thumb for both compilers.
docs/unit-notes.md — per-unit notes. docs/research/ — the pass-by-pass research log.

What "matching" means here
Every unit compiles to the original bytes with the original compilers. Where the compiler needed a
particular source shape to reproduce a register choice or a schedule and no natural spelling was
found, the construct is marked with a // COMPILER-DIFF: comment (644 of them: dead tests, empty
asm("") launders and anchors, register T x asm("rN") pins, padding statements). None of them
emits an instruction: python3 tools/asmcheck.py --all compiles every GCC unit with its asm templates
marked and lists the instructions that came from a template — the only hits are the hardware kernels
below (TOTAL 231; the eight asm-bodied units are reported on their own line and kept out of that
number). An earlier state of this tree had ~100 hand-placed instructions (asm("li %0,0"),
asm("lis/addi"), asm("mr")) in the game code and ~100 register-pinning asm { } blocks in the CRI
libraries; they were replaced by C on 2026-09-17 (docs/research/compiler.md, section "Asm-removal pass", records the recipe
and the compiler mechanism per site). Each tag's mechanism is documented in docs/matching.md and
docs/research/.
Assembly that remains, all of it code the original authors also wrote in assembly because their
compilers had no other way to express it:

GCC 2.95 game code: paired-single kernels (SINF/COSF/RSQRT/LIMIT_ANGLE in math_sub, the
matrix kernels in trans, shape, dbmodule, quantised psq_l in Espgen42/espgen45), the
GQR setup in main/scheduler, and the libsn sndvd exception handler.
MWCC CRI libraries: the paired-single / cache / SPR kernels (mpv_umc, mpv_mc, dct_fsri,
cftyp422_ppc, mpv_lib), the SDK's mtx/vec/quat/GX intrinsics, and one register-steering
block in dct_ac (dctac_Init: the vendor's compiler build pooled .bss but not the function's
8-byte literals; ours pools both). Codeless asm { mr r11, x; mr x, r11 } pins (both moves are
deleted by the allocator; they narrow the colour set by one register) and asm { mr v, v } self
copies (an opaque second definition) remain in 27 places.
Eight asm-bodied units: crt0 (__start), eabi, SN's tealeaf/fileserver/ppcdown/proview
(src/lib/<name>.c), and Capcom's memset_2 and yz2asm (src/game/<name>.cpp). The originals
were assembly (SN's libsn/crt0 objects and Capcom's own asm; no compiler idiom in the bytes), so
each is a C file whose functions are whole-function top-level asm() bodies in GAS syntax
(.globl/.type/label/.size, local .L_ labels, .4byte/.float/.skip data), compiled by
the same ProDG driver as the rest (include/asm_regs.h supplies the r3/f1/GQR0 names as
.set constants; NgcAs takes bare numbers). tools/asmcheck.py lists them as asm-bodied.

Naming
Function names are Capcom's, from the debug build's Bio4.sym files; they are C++-mangled, which is
why the game code is C++ and the SDK, CRI and newlib units are C. File names and unit boundaries come
from the D:/Bio4/Prog/<file>.cpp strings the asserts left in the binaries. Struct and field names are
of three kinds: the vendor's, from the PS2 debug build's type information (matched to the GameCube
layouts by tools/ps2sym.py); ours, named from usage and marked as such; and placeholders xNN
(offset in hex, meaning unknown). Vendor names keep the vendor's spelling, so the tree mixes
conventions on purpose. #line directives reproduce the vendor's line numbers in the assert strings.
docs/naming.md has the full account and the counts.
Contributing
CONTRIBUTING.md: build, the three verification checks, the rules (bytes never change, no
instruction-emitting asm, naming), and how to propose a rename with evidence.
Legal
The reconstructed game and SDK source is the intellectual property of its respective owners
(Capcom, Nintendo, CRI Middleware) and is published for research and preservation only. The build
scripts, tools and documentation written for this project are released under CC0 (LICENSE).
AboutResident Evil 4 (GameCube, G4BE08 debug build) — complete byte-identical decompilation to C/C++Topicsdecompilationgamecubepowerpcresident-evil-4reverse-engineeringResourcesReadmeCC0-1.0 licenseContributingContributingActivityStars138 starsWatchers2 watchingForks12 forksReport repositoryReleasesPackagesContributorsLanguages

Footer

© 2026 GitHub, Inc.

Footer navigation

Terms

Privacy

Security

Status

Community

Docs

Contact

Manage cookies

Do not share my personal information

You can’t perform that action at this time.

This repository documents a complete, byte-identical decompilation of the Resident Evil 4 debug build for the Nintendo GameCube (G4BE08), encompassing both game discs. The project aims to reproduce the main.dol file and all one hundred fourteen REL overlays exactly, relying on a rigorous process of reverse engineering and source reconstruction based on the original compiled artifacts. The resulting codebase is composed of approximately five hundred fifty-five thousand lines of C and C++ code, along with thirty-three thousand lines of header files, and notably contains no assembly files.

The construction of this decompilation involves integrating source materials from various components, including the SN Systems ProDG, Metrowerks CodeWarrior, and Nintendo SDKs, which were used when the original software was compiled. The methodology centers on a "matching" process, which mandates that every unit in the decompiled result must compile to the original bytes using the original compilers. This verification step is detailed through extensive documentation, demonstrating how compiler provenance, the catalogue of compiler mechanisms, and source shapes are used to reconstruct the original execution environment. Specific attention is paid to accounting for compiler differences, such as register choices and padding statements, which are documented through commentary within the source code to track deviations from natural spelling.

The repository structure organizes the project logically, separating game logic, SDK and runtime libraries, configuration data, and specialized tools necessary for the build and verification process. The source code is logically divided into game components such as enemies, weapons, player characters, and room definitions, alongside specific files for the SDK, CRI middleware, and runtime environments. The configuration directory contains essential unit lists, symbols, and linker scripts required for the compilation process.

The process of building the project necessitates the use of specific disc images as input, and the system automatically downloads necessary compilers and tools upon the initial configuration. The build process utilizes standardized commands and tools, such as python3, ninja, and specialized comparison utilities to ensure byte-level accuracy against the original files. The system employs detailed tools for comparison, allowing for word-by-word checks between the reconstructed objects and the original word by word, as well as function identification tools.

The analysis also details the fate of assembly code within the reconstructed structure. While most assembly that was present was either eliminated or documented through compiler mechanisms applied during the reconstruction, specific assembly code remains because it represents instructions the original authors wrote directly, as their compilers offered no other method of expression. The project meticulously tracks assembly-bodied units and registers derived from the environment, noting where register allocation mechanisms were handled and where instructions were preserved. Furthermore, the project addresses naming conventions, noting that function names originate from the debug build's symbol files, and struct and field names are tracked based on vendor information, usage, and the identification of unknown offsets.

The project emphasizes that the reconstructed game and SDK source, along with the associated build scripts and documentation, are intellectual property belonging to Capcom, Nintendo, and CRI Middleware, and are published strictly for research and preservation purposes. The project is released under a Creative Commons Zero license.