# bit Generations: Orbital — GBA Decompilation

**Game:** bit Generations: Orbital (Japan) (En) · GBA · Skip Ltd. / Nintendo (2006)
**Status: COMPLETE — 1096/1096 mapped sources match, 121,244 bytes TRUSTED (95.05%) + 127,564 / 127,564 bytes VERIFIED (100%)**

## Method

Each function is verified by linking its source at its real ROM address and
comparing the linked bytes unmasked against the ROM. Zero diffs or it doesn't
count. Two counters (`tools/check_direct.py --all` -> `build/direct_match.json`,
local-only via `.gitignore`):

- `TRUSTED` = code bytes `[start, last-return)` — strict function match.
- `VERIFIED` = full span incl. literal pools, alignment padding, shared-epilogue
  tails, ARM blobs, and data islands.

```bash
python3 tools/check_direct.py --all        # scoreboard -> build/direct_match.json
python3 tools/check_direct.py src/matched/<Name>.c 0x0800XXXX
python3 tools/check_direct.py src/matched/<Name>.s 0x0800XXXX
python3 tools/validate_code_section.py     # full-section stub vs ROM
```

Per-function results live in `build/direct_match.json`. `PROGRESS.md` is the
grind journal.

## State

- Code section `0x080000C0–0x0801F30C` (127,564 bytes), boundary map in
  `function_list_v2.txt`, sources in `src/matched/` (825 `.c` + 273 `.s` on
  disk; 1096 mapped and all matching).
- 2 unmapped stale files on disk (`Bignum_Init_0801C4BA.c`,
  `Physics_DistanceSquared.c`) are superseded by merged spans and excluded
  from the scoreboard (`SKIP: no address mapping`).
- Stub image accuracy 100% (0 diffs); former ~6.2KB gap is now claimed as
  `Boot_Init.s` (268B ARM) + `Data_08012572` (890B) + 274 `Data_*` pool/pad
  spans, all verified.

## Layout

```
function_list_v2.txt      boundary map (source of truth)
src/matched/*.c/*.s       decomp sources (readable C, naked asm where needed,
                          plus Boot/Data .s spans for pools/pads/ARM/data)
tools/check_direct.py     matcher + scoreboard (TRUSTED + VERIFIED)
tools/dbg.py              ROM-vs-linked disasm debugger
tools/gen_stubs.py        rebuild stub image + symbol map
tools/segment_functions.py / tools/validate_code_section.py
```

## Requirements

- `python3` (all tools; no extra packages)
- `agbcc` submodule (`git submodule update --init`)
- ARM GNU toolchain 13.3.rel1 (`bash setup_tools.sh`, or place
  `arm-none-eabi-*` on `PATH`)
- The ROM file itself: `bit Generations - Orbital (Japan) (En).gba`
  in the repo root

## What's left

Code matching is done (VERIFIED 100%) and the full 16MB ROM rebuilds
byte-identical (`make verify`: stub 100% + `build/orbital.gba` sha1 match;
see `docs/rom_map.md`). Remaining: readable-C conversion of naked-asm
stopgaps, real type names, and moddable asset rebuild (edit a blob, keep its
offset/size).

Educational reverse-engineering project. Original game © Nintendo / Skip Ltd.

Chat: [xmpp:tujopup@muc.fuzzing.uk?join](xmpp:tujopup@muc.fuzzing.uk?join)