ApeEscapeRecompiled

Ape Escape Recompiled — Mod Developer Toolkit

This guide describes the project-owned native plugin interface and the launcher tools added for mod authors. The launcher includes a Mod Toolkit page with a copyable read-only plugin example. The matching source template is in templates/mod-plugin/example_plugin.c.

Start with a read-only plugin

1. Copy the template and give the plugin a unique ID for this project.
2. Keep the corresponding feature disabled by default in its manifest.toml.
3. Build with the runtime’s runtime/include headers. The release workflow syntax-checks the example plugin.
4. Add a small, specific regression check for the manifest, callback registration, and any constants used.
5. Test from a backed-up save and a clean test profile. Record the game version, stage, setup, and observed behavior.
6. Only enable the feature on a normal playthrough after in-game behavior has been checked.

Callback and game-state rules

• Prefer observation and logging before writes. Read-only access is not automatically proof that an address means what its name suggests.
• Use the project’s exported psx_mod_* functions and supported callbacks. Do not copy undocumented runtime internals into a plugin without pinning and verifying the dependency.
• Gate stage-specific behavior on an independently verified gameplay phase. Loading screens, transitions, pauses, and game-over phases can share memory with gameplay.
• Clear timers, edge-detection latches, counters, and transient state when a stage exits or the plugin is reactivated. Consider savestate loads as a discontinuity.
• Avoid writing control-flow values, object pointers, boss phase variables, or broad RAM ranges unless the address, width, valid range, and lifecycle are known.
• Never assume that forcing health to zero, changing a timer, or rewriting a few values constitutes a full stage reset.
• Every feature should be opt-in, independently disableable, and should not change the original game when disabled.
• Make save compatibility explicit in the manifest. Test enabling and disabling the feature against a backed-up test card.

Manifest and test expectations

Every distributable package belongs under mods/preloaded/packages/<package-id>/<version>/ or the separately documented external-mod flow. Keep the package ID, plugin ID, feature IDs, and option IDs consistent. For built-in mods:

• Default every feature to off.
• Add a check that reads the manifest through the runtime’s package parser.
• Check the resolved plugin plan and any declarative guest writes, not just that the manifest parses.
• Add syntax checks to CI for native code.
• Keep experimental or unverified behavior labeled as such in the manifest and README.
• Do not embed retail game images, BIOS files, saves, or user-specific paths in a plugin.

Save Protection Center

The launcher dashboard provides Create Backup Now, a selectable backup history, Restore Selected, and Export Selected. Restore creates a safety snapshot before applying an older snapshot, then merges files without deleting files absent from the selected snapshot. Export copies the selected snapshot into a chosen destination folder. Retention is configurable from 5 to 50 snapshots and is applied only after a successful backup or restore. The updater and rollback also create safety snapshots before starting. Keep external copies of important memory-card files as well.

Setup Doctor, Controller Test Lab, and release information

The launcher Setup Doctor checks the selected disc path, disc identity, custom BIOS path, application-data write access, and whether a save backup exists. Its report contains build metadata and diagnostic status, not the disc image or full local file paths. Controller Test Lab reads live SDL gamepad state and offers an explicit optional rumble test; it does not change controller mappings. Update & Release Center opens the Nightly updater and the project changelog. Checksums remain the updater’s responsibility and must pass before installation.

Daily Challenge and Stage Guide

Daily challenges are generated deterministically from the local calendar date and offer combinations of the existing timed-hunt, no-damage, and limited-lives challenge rules. The launcher never silently enables mods; players must enable matching Challenge Pack features manually. Completion marks are self-reported and stored locally. There is no online leaderboard or automatic gameplay verification.

Stage Knowledge Cards read stage names, counts, and reference links from the project’s existing North-American monkepedia.tsv catalogue. The briefings are general tactics, not route-verified walkthroughs or live tracking of monkeys.

Reporting a bug

Include the installed build information from Quick Tools, the OS and controller, the selected challenge/mod settings, and whether the issue reproduces with all mods disabled. Do not attach disc images or retail BIOS files. If a bug involves saves, reproduce on a copy and retain the untouched original.

This site is open source. Improve this page.