PaperPad 0.2.0 uses Harbour Masters’ PaperBoat, with PaperPad's native Apple touch controls, settings, ROM import and diagnostics. The app and download are named PaperPad.
- iPhone/iPad, iOS/iPadOS 16.3 or newer; unsigned IPA for signing with your own credentials.
- Supply an unmodified Paper Mario (US) 1.0 ROM locally. No ROM or extracted game archive is included.
- Floating touch-down stick, compact native settings, controller support, Auto/1×–4× rendering and shared diagnostics.
- The new app keeps separate saves from PaperPad Original. Earlier progress stays in Original; there is no automatic conversion.
- Title-menu animation stutter remains a known issue. See the release notes for test scope and limitations.
The release includes exact nested sources, notices, build provenance and checksums. Source updates and offline archive builds and rights limitations are documented. Report app/platform issues here with the build and diagnostic log; do not assume upstream owns an Apple-port issue.
Note
AI disclosure: PaperPad uses substantial AI assistance for code, tests, documentation, debugging and maintenance. Some support replies and maintenance tasks are automated. There is no audited percentage of AI-generated code. Build, test and device records describe what was checked. This disclosure concerns PaperPad's workflow, not the authorship of its upstream projects.
Releases publish no app: PaperPad is compiled from the Paper Mario decompilation, so you make your
own on an Apple silicon Mac with Xcode and its iOS platform. Install CMake and Ninja
once with brew install cmake ninja, then download
PadMint, unzip it, double-click
PadMint.command and choose PaperPad. PadMint builds the app from this repository's
latest release and saves an unsigned
IPA in your Downloads folder; install it with AltStore Classic, SideStore or Sideloadly (see the
unsigned IPA installation guide). On first launch, choose your own Paper Mario
(USA) 1.0 ROM in Files; PaperPad extracts it privately on the device. Install over an existing
PaperPad to keep your saves. PaperPad Original (below) is a separate app with separate saves.
The following screenshots, platform status and instructions describe the retained Original Preview 2 build. Its ReCut/RT64 runtime and earlier saves remain available separately; they are not the PaperBoat build above.
Paper Mario recompiled for Apple Silicon.
Native Metal rendering, customizable iPhone and iPad controls, controller support, and private ROM import.
PaperPad combines the pmret Paper Mario decompilation with the statically recompiled runtime and renderer from Paper-Mario-ReCut, pinned through PaperPad’s maintained source branch. It adds a native Apple application shell, Metal presentation, keyboard and controller input, customizable touch controls, native settings, and private first-run ROM import.
PaperPad is a game-specific static recompile, not a general Nintendo 64 emulator. It currently supports only an unmodified Paper Mario (US) 1.0 ROM supplied by the user.
This repository contains integration source, pinned maintained dependencies, scripts, and documentation. It does not contain Paper Mario, a ROM, extracted Nintendo assets, generated playable game code, saves, or a playable ROM-derived archive. Read the rights and licensing boundary before redistributing source or a build.
PaperPad Original's preview downloads are retired. PadMint builds the current PaperPad (see Get PaperPad); to build Original yourself, use scripts/build-ios-device.sh --rom /absolute/path/to/rom as described in Get started. There is no TestFlight, App Store release, signed download, or notarized macOS build.
| Target | Current status |
|---|---|
| Apple Silicon macOS | Source build, launch, file creation, early gameplay, keyboard input, and clean quit verified |
| iPhone Simulator | Current development build and compact touch layout verified |
| iPad Simulator | Current development build, touch/settings flows, diagnostics, and later-game fixture verified |
| Physical iPad | Preview 2 installed in place and booted through active gameplay without changing the private ROM, saves, or controller preferences; earlier battle, progression, and longer controller routes remain valid |
| Physical iPhone | Current clean build installed and launched; private test ROM/save migrated, with hands-on touch and gameplay acceptance open |
Preview 2 adds targeted SDL2 controller-slot reconciliation for missed disconnects, reconnects, and foreground resume. Deterministic tests cover single-controller return, two-controller slot preservation, held-input release, and a missed removal event. The exact signed release candidate also booted on the attached iPad after an in-place update that preserved its private ROM, saves, and controller preferences. Physical Bluetooth, wired, and natural-sleep reconnect acceptance remains open, as do complete mapping, physical-iPhone hands-on acceptance, and chapter-spanning testing.
See Current status, Technical debt, and the Release checklist for dated evidence and the remaining gates.
- An Apple Silicon Mac
- Xcode with the macOS and iOS SDKs, plus the downloadable Metal Toolchain
- Homebrew
- CMake, Ninja, Git, jq, Python 3.11 or newer, and Rust/Cargo
- GNU
cpp-16(brew install gcc) - Several gigabytes of free build space
- Your own legally obtained, unmodified Paper Mario (US) 1.0 ROM
PaperPad accepts .z64, .v64, and .n64 byte orders. The supported ROM normalizes to 40 MiB with SHA-1 3837f44cda784b466c9a2d99df70d77c322b97a0. This fingerprint verifies compatibility; it is not a download hint.
Clone the repository:
git clone https://github.com/chrissotraidis/paperpad.git
cd paperpadxcodebuild -downloadComponent MetalToolchain
export TOOLCHAINS="$(xcodebuild -showComponent MetalToolchain -json | plutil -extract toolchainIdentifier raw -o - -)"
scripts/build-macos-app.sh --rom /absolute/path/to/your/paper-mario-rom
open build-macos-release/PaperPad.appThe first command installs Xcode's optional Metal compiler, and TOOLCHAINS selects the installed version explicitly for Xcode releases that do not select it automatically. The build then fetches and verifies pinned maintained source, validates the ROM, generates local AOT game code, builds PaperPad, and ad-hoc signs a ROM-free app. After the first successful generation, incremental builds can run without --rom in the same shell:
scripts/build-macos-app.shThe macOS app reads the normalized ROM from the ignored local workspace. It is not copied into PaperPad.app.
Build the app, boot one Simulator at a time, then install and launch it:
scripts/build-ios-simulator.sh --rom /absolute/path/to/your/paper-mario-rom
xcrun simctl list devices available
xcrun simctl boot "iPad Pro 11-inch (M4)"
open -a Simulator
xcrun simctl install booted build-ios-simulator/Release/PaperPad.app
xcrun simctl launch booted com.chrissotraidis.paperpadOn first launch, select your ROM through the native document picker. PaperPad validates the exact revision, normalizes its byte order, and stores the private copy in that Simulator's Application Support container. The installed .app remains ROM-free.
Shut down the active Simulator before switching device classes:
xcrun simctl terminate booted com.chrissotraidis.paperpad || true
xcrun simctl shutdown bootedPhysical iPhone and iPad builds require your own Apple development team and provisioning profile. Follow the device build and in-place installation guide; never uninstall an existing copy merely to update it if its private ROM, saves, or settings must be preserved.
PaperPad never downloads game data.
- Launch the iPhone, iPad, or Simulator app.
- Choose Choose ROM.
- Select your own supported dump in Files.
- Wait for validation and private normalization to complete.
- Start the game with the on-screen Start button or a connected input device.
Use PaperPad Menu → Settings → Manage Game ROM to replace or remove the private copy later. ROM and save contents are never included in shared diagnostics.
PaperPad provides every standard N64 input on screen: analog stick, D-pad, A, B, Z, C-buttons, L, R, and Start. Phone and tablet layouts are independent, persist locally, and can be moved or reset from Settings.
- Menu: the persistent
•••button opens PaperPad settings and support actions. - Touch controls: show or hide the gameplay overlay and adjust its opacity.
- Layout editor: move controls without snapping their centers to the initial touch point. D-pad and C buttons move individually by default; select one and choose Link to move that four-button cluster together, or Unlink to return to individual placement. Reset restores the current device-class defaults.
- Resolution: choose Auto, 1x, 2x, 3x, or 4x internal rendering. Auto reports its current renderer-confirmed scale and dimensions and may exceed 4x when the display permits it.
- Framing: Original preserves the largest centered 4:3 presentation. Fill Screen center-crops that presentation and may crop image edges on wider displays.
- Volume: adjust and persist master output volume.
- Diagnostics: create a reviewable text report through the system share sheet.
- ROM management: replace or remove the privately stored game ROM.
Opening the menu, Settings, share sheet, or ROM picker clears held input and hides gameplay touch targets. Dismissing the sheet restores them only when Touch Controls is enabled. When a hardware controller is connected, the iOS build hides the gameplay overlay while keeping the menu available, then restores touch controls on disconnect. SDL2 handles are reconciled on controller events, foreground resume, and a bounded active check so stale handles release their player slot and held input; hands-on reconnect and complete mapping acceptance remain open.
| N64 input | macOS keyboard | N64 input | macOS keyboard |
|---|---|---|---|
| A | Z |
B | X |
| Start | Return | Z | Left Shift |
| L / R | Q / E |
Analog stick | Arrow keys |
| D-pad | W A S D |
C-buttons | I J K L |
SDL-compatible controllers use the left stick, D-pad, face buttons, shoulders, left trigger for Z, and right stick for the C-buttons. A physical Kishi V2 session verified analog plus A/B/Z/L/R/Start during sustained play. Automated tests cover disconnect input release, single-controller reconnect, two-controller slot preservation, and foreground reconciliation after a missed removal; D-pad, all C directions, Bluetooth/wired reconnect, and natural-sleep behavior still require physical acceptance.
|
|
| Battle gameplay Native Metal presentation with the complete touch interface. |
Paper Mario on iPad Original 4:3 presentation with customizable controls. |
| Area | Current implementation |
|---|---|
| Native code | Static arm64 game code on Apple targets; no JIT or downloaded executable code |
| Rendering | RT64 presentation through Metal with Retina drawable sizing |
| Game setup | Native ROM selection, three-byte-order normalization, exact revision validation, and private storage |
| Touch | Full N64 overlay, multi-touch, fixed/clamped analog knob, opacity, independent phone/tablet layouts, editing, and reset |
| Display | Auto and fixed 1x–4x internal scales; original 4:3 and center-cropped Fill Screen modes |
| Input | macOS keyboard/controller support and iOS SDL controller mappings |
| Saves | Flash-save handling plus in-place device updates that preserve the app container |
| Support | First-level diagnostics action, bounded current/previous logs, session marker, and system share sheet |
| Repository safety | Pinned dependencies, maintained patch replay, and ROM/signing/private-data publication checks |
Internal resolution improves geometry edges and sampling, but it cannot reconstruct detail absent from the original low-resolution text, sprites, or textures. PaperPad uses RT64's stable smooth path and does not ship or endorse a third-party texture pack.
| Game | Revision | Status |
|---|---|---|
| Paper Mario | US 1.0 | Supported input for local builds and runtime import |
| Paper Mario | Japan, PAL, iQue, modified/randomized ROMs | Not supported by the current configuration |
| Other Nintendo 64 games | Any | Not supported; PaperPad is not a general emulator |
Open PaperPad Menu → Share Diagnostics & Logs… after reproducing a problem. The generated report includes:
- app/build, system, screen, settings, and renderer-confirmed resolution metadata;
- only whether a supported-size ROM is present, never its contents;
- at most the last 512 KiB of the current and previous runtime logs; and
- a possible-unclean-session label when the previous run did not remove its private session marker.
Each private log is capped at 4 MiB. Known app-container, home, and temporary paths are replaced, but arbitrary runtime text is not guaranteed to be anonymous. Review and redact the report before sharing it.
Include the PaperPad commit, device and OS, exact reproduction steps, expected and actual behavior, and a screenshot for visual defects. Never attach or request ROMs, extracted assets, generated playable code, saves, signing files, credentials, or private device data. See CONTRIBUTING.md.
flowchart LR
A["PaperPad scripts"] --> B["Pinned upstream source"]
B --> C["Maintained Apple/runtime patches"]
D["Your supported ROM"] --> E["Ignored local AOT generation"]
C --> E
E --> F["ROM-free PaperPad app"]
D --> G["Private first-run import on iOS"]
F --> H["Local gameplay"]
G --> H
dependencies.lock.json records exact source revisions and the supported ROM fingerprint. The maintained ReCut fork is pinned at vendor/paper-mario-recut; unmodified inputs remain under ignored ref/, and private ROM-derived/AOT input under ignored generated/. Normal builds verify clean sources and do not replay patches. See source maintenance, source archives and rollback.
The PaperBoat audit and engine decision selects PaperBoat as the foundation for a future major version. This source-maintenance change keeps the existing ReCut engine and Preview 2 behavior; no PaperBoat features or new binary release are included.
Before publishing source, run:
scripts/check-repo-safety.sh
git diff --checkThe safety audit rejects game data, generated packages, signing material, likely credentials, tracked reference checkouts, personal paths, and oversized files from the publishable tree and history.
Does PaperPad include Paper Mario?
No. You must provide your own legally obtained, unmodified Paper Mario (US) 1.0 ROM. Do not open issues requesting game data or download links.
Is there an IPA or App Store build?
No published IPA: PadMint builds your own on an Apple silicon Mac (see Get PaperPad). There is no App Store or TestFlight build.
Why does Auto sometimes show more than 4x?
Manual choices are capped at 4x. Auto chooses the largest integer scale that fits the current display and reports the renderer-confirmed value, so it can legitimately show a higher number.
Why can the game still look soft at a high internal resolution?
Higher internal resolution improves polygon edges and sampling. It cannot add detail to original low-resolution glyphs, sprites, or textures. The removed Crisp 2D experiment made those assets harsher rather than genuinely clearer.
Does it support physical controllers?
Controller mappings and touch-overlay handoff are implemented through SDL2. A physical Kishi V2 has completed a longer iPad gameplay session using analog plus A/B/Z/L/R/Start. Deterministic reconnect coverage now protects player slots and held-input release, while D-pad, all C directions, physical reconnect/sleep, and iPhone controller behavior remain release checks.
Is the entire game verified?
No. Development testing covers the opening flow, early battles and progression, selected later-game fixtures, and targeted stability routes. A chapter-spanning/full-game regression and longer device soak remain open.
| Path | Purpose |
|---|---|
apple/app/ |
UIKit lifecycle, setup, settings, diagnostics, touch UI, privacy manifest, and app metadata |
src/ |
Native runner, input, renderer bridge, runtime hooks, paths, and generated-code integration |
config/ |
N64Recomp configuration |
vendor/paper-mario-recut |
Pinned maintained ReCut/runtime/compiler/RT64 source |
patches/ |
Historical provenance only; mapped to maintained source commits |
scripts/ |
Fetch, validate, generate, build, test-support, and repository-audit automation |
docs/ |
Architecture, building, status, testing, dependencies, issues, and release documentation |
ref/ |
Ignored pinned source and local reference inputs; never published |
generated/ |
Ignored ROM-derived/AOT build input; never published |
- Building and device installation
- Install the unsigned IPA
- Preview 2 release notes
- Preview 1 release notes
- Architecture
- Current status
- Technical debt and prioritized release gates
- Testing history
- Known issues and investigation archive
- Dependency inventory
- Release checklist
- Contributing
- Security policy
- Rights and licensing boundary
Join the Discord for help and news. It is one community for PaperPad and its sibling projects, such as KartPad, BlueWake and MeleePad: ask about setup, building with PadMint, and installing, share how it runs on your device, and hear about new releases first.
Found a bug? Open an issue with your device, its OS version, and the steps that led to it.
PaperPad builds on work from pmret/papermario, Paper-Mario-ReCut, N64Recomp/N64ModernRuntime, RT64, mupen64plus-rsp-hle, SDL, zstd, and their contributors.
Its phone/tablet layout, persistent menu, modal input lifecycle, and customization model are adapted from HarkinianPad. PaperPad retains its own SDL2/N64 input bridge and does not copy another project's controller patch: physical controller acceptance, HarkinianPad's hold-to-latch Z gesture, and per-control gameplay VoiceOver elements remain open or intentionally separate.
PaperPad is an independent, unofficial project and is not affiliated with or endorsed by Nintendo or any upstream project. Paper Mario and all related game names, characters, copyrights, and trademarks belong to their respective owners. Every dependency retains its own license and rights boundary; the combined tree should not be described as carrying a single blanket license. See RIGHTS_AND_LICENSES.md and docs/DEPENDENCIES.md. Neither document is legal advice.