# ApeEscapeRecomp
> _This recompilation is a **byproduct of developing
> [psxrecomp](https://github.com/mstan/psxrecomp)** — the games are the proving ground, the framework is the goal.
> **These are in-development previews, not finished ports — expect rough
> edges**, and depth will keep landing over months, not days. My time for any
> one title is limited, so I ask for your patience. Contributions are welcome —
> testing, issues, and PRs to the game or framework all help and will
> accelerate this game's polish. More on the why at:
> [Recomp + AI: 5 Months Later »](https://1379.tech/recomp-ai-5-months-later/)_
Ape Escape (USA, SCUS-94423) statically recompiled to a native PC executable
with [PSXRecomp](https://github.com/mstan/psxrecomp) — the same framework behind
[TombaRecomp](https://github.com/mstan/TombaRecomp) and
[MegaManX6Recomp](https://github.com/mstan/MegaManX6Recomp).
Known issues live in [`ISSUES.md`](ISSUES.md).
Releases precompile 47 archive overlays and two minigame executables directly
from the original disc using the shared psxrecomp AOT pipeline. See
[AOT overlay evidence and limits](docs/AOT_OVERLAYS.md) and the
[shared method guide](psxrecomp-v4/docs/AOT_SHARDING.md). Two unresolved archive
members remain excluded; fallback stays enabled and complete static coverage
is not claimed.
## What This Is
This repository contains the game-specific configuration, seeds, tools, and
build glue for running Ape Escape on the PSXRecomp framework. The game's MIPS
code is machine-translated ("recompiled") ahead of time into native C, then
compiled into a real Windows program that runs the game's own logic on a
faithful simulation of the PS1 hardware (GPU, SPU, GTE, memory cards) plus the
real, recompiled PS1 BIOS — no high-level emulation shims.
It does **not** contain the Ape Escape disc image, a retail PS1 BIOS, generated
game code, or any decompiled game C. Release builds include the MIT-licensed
OpenBIOS from PCSX-Redux; game data and an optional retail BIOS come from your
own legally obtained assets.
Important files:
- `game.toml`: runtime / recompiler / video / controller / widescreen config.
- `mods/preloaded/`: built-in, default-off mod packages shown by the launcher.
- `seeds/`: Ghidra-derived function starts and game-specific seed data.
- `tools/regen.ps1`: regenerates the recompiled C output.
- `tools/package_release.ps1`: builds the redistributable release zip.
- `psxrecomp-v4/`: framework submodule commit this project is known-good against.
- `ISSUES.md`: game-specific issue log.
- `DISC.md`: source-disc identity and verification hashes.
## Status
**Playable preview — `v0.4.0`.** Ape Escape **boots from the PS1 BIOS and
plays** — through the intro, the title, and into gameplay, with dual-analog
controller input including **L3/R3 stick clicks** (added in v0.0.3), a
**controls fix** so the analog stick no longer spins the camera (v0.0.5),
and working memory-card **save/load** (fixed in v0.0.2). It has not yet been verified all the way to the end,
so treat it as a very playable preview rather than a certified full playthrough.
| Area | State |
|---|---|
| Boot (real PS1 BIOS) | ✅ Boots to intro / title / gameplay |
| Rendering | ✅ OpenGL (default) and Software backends |
| Controller | ✅ DualShock analog (auto-bound; the net/movement scheme is dual-stick) |
| Memory cards | ✅ Standard PS1 `.mcd` save/load |
| Save states / rewind | ✅ Launcher-backed hotkeys and runtime state capture |
| FMV / audio | ✅ MDEC video + XA/SPU audio (auto-skip FMV optional) |
| Mods | ✅ Built-in catalog with Ape-specific and framework-owned enhancements |
| Widescreen 16:9 / 21:9 / Adaptive | ✅ Opt-in 16:9, 21:9, and live-window adaptive modes |
| Interpolated rendering | ✅ Opt-in display / 60 / 90 / 120 / 144 / 165 / 240 FPS |
| Full playthrough | ⚠️ Not yet verified end-to-end |
### Built-in mods
The launcher's **Mods** page includes four Ape-specific bundled enhancements:
- **Ape Escape Widescreen** moves the existing game-specific enhancement out
of generic Video settings. Its picker offers **16:9**, **21:9**, and
**Adaptive** (live window aspect from 4:3 through 21:9).
- **Ape Escape Frame Interpolation** redraws intermediate camera and model
transforms using the game drawing code. Display refresh and fixed output
rates leave simulation, timers, audio and input at their stock cadence.
Existing Frame Smoothing selections use interpolation automatically.
- **PGXP** adds subpixel geometry and perspective-correct textures. Internal
resolution, texture filtering and FMV filtering remain configurable in Settings.
- **Skip FMVs** ends movies through the game's normal completion path.
- **Quick Gadget Select**, contributed by mthsk, recreates the later Ape
Escape quick gadget switching flow for the face-button gadget menu.
The widescreen mod uses Ape Escape's stable GTE projection-and-stretch path
for a wider 3D field of view. HUD/UI proportion correction is enabled for its
front ordering-table layer; remaining draw-distance and scene-culling limits
are tracked in [`ISSUES.md`](ISSUES.md). With the mod disabled, 4:3
presentation is unchanged.
The launcher's Video page exposes **Supersampling (1x-4x)**,
**Antialiasing**, and **Texture filtering**. On OpenGL, supersampling is true
ordered-grid SSAA: geometry and shading are rasterized at a higher internal
resolution and resolved to the window, while native PSX VRAM remains the
authoritative game-visible buffer. Antialiasing controls the linear SSAA resolve
and final presentation filtering; it is not RT64-style MSAA. Try **2x** first on
a discrete GPU, keep texture filtering at **Nearest** for the authored PSX look,
and return to 1x if a demanding scene misses full speed.
## Playing
1. Run `ApeEscapeRecomp.exe`. A launcher window opens.
2. OpenBIOS is selected automatically. Optionally select your legally obtained
`SCPH1001.BIN` in the BIOS row.
3. Set the game disc (a legally obtained Ape Escape (USA, SCUS-94423) image —
`.cue`+`.bin`, pick the `.cue`). Do **not** convert to a 2048-byte "cooked"
`.iso`; that discards the XA sectors used for FMV/audio.
4. Adjust display options and select any features on the **Mods** page,
then press **Launch**.
Ape Escape is a dual-analog title — the right stick swings the catch net — so an
analog controller is strongly recommended. Any plugged pad is auto-bound and
presented to the game as a DualShock; a keyboard folds onto the analog stick.
Save states and rewind are exposed through launcher hotkeys; by default F7 opens
the save-state menu and F8 rewinds.
The disc path, optional retail BIOS choice, and options are saved next to the
exe. Clear the BIOS row to return to OpenBIOS.
## Development Rules
- Use the real recompiled BIOS and real hardware simulation in PSXRecomp.
- No HLE BIOS shims, no stubs, no fake events, no hand-edited generated files.
- Framework changes go in `mstan/psxrecomp`, not here.
- Game binaries, generated code, memory cards, Ghidra databases, and build
outputs stay local.
- See `CLAUDE.md` for project-specific rules.
## License
PolyForm Noncommercial 1.0.0. See `LICENSE`.
Ape Escape is copyright Sony Computer Entertainment / SIE. This repository
contains none of the game's original binaries or assets. Release packages
include PCSX-Redux OpenBIOS under the MIT notice in
`bios/OpenBIOS.LICENSE`; they contain no retail BIOS, game assets, or disc data.
The release executable contains a statically recompiled (machine-translated)
build of the game's code.
---
R.A.I.D. — Retro AI Development · a Discord for AI-assisted retro reverse-engineering, decomp & recomp
## v0.4.0 rendering update
Game-code interpolation replaces Frame Smoothing while retaining saved rate selections. Adds internal-resolution presets, PGXP geometry/perspective correction and filtering options. Fixes the GPU foreground classification behind flickering black wall polygons. The memory-card menu uses its native layout in widescreen. Late beach-ball appearance remains under investigation.