# readable/ — human-readable C decompilation

Parallel clean-C tree for bit Generations: Orbital. `src/matched/` stays the
byte-exact source of truth (mixed readable C + `naked` Thumb transcriptions
that must assemble identically); `readable/` holds the same functions written
as normal, understandable C.

## Rules

* One file per function, same basename as `src/matched/` (e.g.
  `readable/Object_WrapPosition.c` mirrors `src/matched/Object_WrapPosition.c`).
* Plain C89 + `include/game_types.h` types (`u32/s32/u16/...`). No
  `__attribute__((naked))`, no `register __asm__` pins, no `volatile` or
  `asm` barriers used as codegen hacks. (`volatile` only for real MMIO.)
* Logic must match the naked source: same calls in the same order, same
  branches, same memory accesses. Register allocation, pool layout, and
  instruction scheduling do NOT need to match — that is what `src/matched/`
  is for.
* Unknown struct layouts stay as explicit offsets (`p[13]`, `*(u32*)((char*)p
  + 0x48)`) with a `/* TODO(struct) */` note; do not invent field names.
* Unknown callees keep their `Sub_0x...` / existing names. Correct the name
  here when the target is identified, and note it.
* File header comment: ROM address, real size, and one-line behavior.
* Coroutine/stack-switching functions (resume-PC pattern) are documented as
  state machines in comments; the C describes one logical pass.

## Gate

```bash
python3 tools/check_readable.py        # agbcc-compile every readable/*.c
```

All files must compile. Failures block the batch commit.