HarkinianPad

Ocarina of Time via Ship of Harkinian, rebuilt for iPhone and iPad.
Native Metal rendering, touch controls, Files-based setup, and support for keyboards, pointing devices, and iOS game controllers.

HarkinianPad packages the full Ship of Harkinian source port as a native iOS/iPadOS app. It renders through Metal, imports a user-provided supported Ocarina of Time ROM through Files, and includes a landscape touch controller that can be hidden whenever a physical controller is connected.

This repository contains the mobile integration and pinned build scripts. The exact maintained forks and pins are in sources.lock.json. See mod compatibility and support priorities. The source-maintenance qualification records the remaining source-delivery and reproducibility boundaries. It does not contain Ocarina of Time, a ROM, or a playable ROM-derived archive. See the scoped rights and licensing boundary; it does not relicense Shipwright, third-party projects, or game material.

Note

AI disclosure: HarkinianPad 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 HarkinianPad's workflow, not the authorship of its upstream projects.

Install status

Option	Status	What to do
Make your own IPA with PadMint	Available now	On a Mac, PadMint builds HarkinianPad from this repository's latest release and saves an unsigned IPA; install it with AltStore Classic, SideStore or Sideloadly. See Get started.
AltStore PAL / computer-free install	Not available	The current IPA is not an AltStore PAL release. Installing AltStore Classic through PAL does not remove Classic's requirement for AltServer on a Mac or Windows PC.
Local iPad build	Available now	Build and sign with your Apple development team using the instructions below.
Simulator	Available now	Best for development and UI testing; it is not a substitute for physical-device testing.
App Store / TestFlight	Not announced	No listing or public TestFlight currently exists.

Earlier development builds have been signed, installed, and played on a 12.9-inch iPad Pro (6th generation) running iPadOS 26.5.2. Files import, on-device archive loading, touch gameplay, save loading, the settings menu, and in-place app updates have all been exercised on that hardware. Preview 6's mod-pack changes have Simulator startup validation; physical-device gameplay has not yet been verified for that release.

Audio has been heard during repeated physical-iPad playtests. Headphone, Bluetooth, and interruption recovery still need a complete device matrix. Controller sleep/reconnect ownership now has deterministic regression coverage and physical-iPad foreground proof; hands-on Bluetooth, wired, natural-sleep, mapping, rumble, motion, and two-controller acceptance remains open.

Get started

The easy way: on a Mac with Xcode, the current public release requires these build libraries:

brew install cmake ninja pkgconf sdl2 glew nlohmann-json libpng libzip \
  tinyxml2 libogg libvorbis opus opusfile sdl2_net

then download PadMint, unzip it, double-click PadMint.command and choose HarkinianPad. PadMint builds the app from this repository's latest release (about 15 minutes) and saves an unsigned IPA in your Downloads folder. Install it with your sideloading tool, copy your ROM into the HarkinianPad folder in Files, then return to the app and tap Rescan (see First launch). Releases publish no app: the app is compiled from the Ship of Harkinian decompilation, so you make your own.

The released recipe checks the build tools but does not check these desktop libraries before compiling. Install the libraries above before starting PadMint.

By hand:

You need:

• a Mac with Xcode and its command-line tools;
• Homebrew;
• an Apple ID configured in Xcode for physical-device signing; and
• your own legally acquired, supported Ocarina of Time ROM.

For the source build below, install CMake and use Python 3.9 or newer:

brew install cmake

Current source generates port resources with Python and fetches the iOS libraries through CMake. Desktop SDL2, GLEW, Ninja and pkg-config are no longer player-build prerequisites. The public release above still uses its older recipe.

Clone and build:

git clone https://github.com/chrissotraidis/harkinianpad.git
cd harkinianpad

# Simulator
scripts/build-ios.sh --simulator

# Physical iPhone or iPad
DEVELOPMENT_TEAM=ABCDE12345 \
BUNDLE_ID=com.yourname.harkinianpad \
scripts/build-ios.sh --device

Replace ABCDE12345 with the 10-character team identifier shown in Xcode and use a bundle identifier that belongs to you. The device app is written to:

build-ios-soh/soh/Release-iphoneos/HarkinianPad.app

If Xcode needs to register the device or create a provisioning profile, open build-ios-soh/Ship.xcodeproj, select the soh target and your device, then choose your team under Signing & Capabilities.

See docs/BUILDING.md for the complete Simulator, signing, installation, controller, and package-audit workflow. docs/INSTALL_IPA.md is the short AltStore Classic installation guide for the IPA you made.

Before publishing or sharing a build, follow the release checklist.

First launch

HarkinianPad never downloads or bundles game data.

1. Launch HarkinianPad once so iOS creates its Files-visible folder.
2. Open Files → On My iPad → HarkinianPad. This is the app's Documents folder. In LiveContainer, open HarkinianPad's container and use its Documents folder, not SystemData.
3. Move your supported Ocarina of Time ROM into that folder.
4. Return to HarkinianPad and select Rescan.
5. Leave the app open while it creates the local oot.o2r archive.
6. Press the on-screen Start button or Start on a connected controller.

The original ROM and generated archive stay inside the app container. They are ignored by Git and rejected by the repository's package audit.

Touch controls

HarkinianPad selects a landscape layout for the current device class:

• Left: a separate D-pad, the control stick, and Z within left-thumb reach.
• Right: Start/R/L, the native A/B/C HUD controls, and their transparent UIKit touch targets.
• Menu: the small ••• button remains available even when gameplay touch controls are disabled.
• Toggle: use Settings → Controls → Touch Controls to hide or restore the gameplay overlay.
• Transparency: enable Touch Control Transparency to reveal a 25%–100% opacity slider. This is off by default and does not change touch targets.
• Customize: choose Customize Touch Layout to move, resize, or hide controls in separate phone and tablet layouts.
• Fallback: enable Legacy Fixed Touch Controls to use the previous non-customizable UIKit controller. Opening the menu hides the gameplay controls so the settings interface remains usable. Closing it restores the controls only when Touch Controls is enabled.

Touch control	Shipwright binding
Control stick	W/A/S/D, including diagonals
D-pad	T/G/F/H
A / B	X / C
L / Z / R	E / Z / R
Start	Space or Return
C buttons	Arrow keys
Menu	Escape

The touch stick is currently an eight-way control. A physical controller remains the preferred option for full analog precision.

Physical controllers

HarkinianPad uses libultraship's SDL2 controller manager. It reconciles the currently attached controllers at startup, controller add/remove/remap events, foreground resume, and a bounded active check. A valid controller keeps its player slot; a stale controller is closed and releases its slot and held input; a sole returning controller reclaims player 1; and an additional controller uses the next free slot without displacing player 1. Existing mappings remain in Shipwright's controller configuration.

These guarantees are covered by deterministic fake-controller tests and the startup/foreground path has executed on the physical iPad. That evidence is separate from hands-on controller acceptance: no Bluetooth, wired, natural-sleep, full-mapping, or two-controller scenario is claimed as passed until it is exercised with that hardware.

What works

Area	Current result
Native app	Current source defaults to arm64 iOS/iPadOS 15+; preserved earlier builds used 14+
Rendering	Metal rendering works in Simulator and on physical iPad
Game setup	Files-visible ROM import and local oot.o2r loading work
Touch	Stick, D-pad, A/B/Z, C buttons, shoulders, Start, and persistent menu access
Saves	File creation/loading and in-place app updates preserving Documents data work
Input options	Touch, keyboard, mouse/trackpad, and reconciled SDL2 controller slots are included
Packaging	ROM/game-data exclusions and signed-package checks are built into the scripts

For detailed engineering evidence and remaining hardware checks, see docs/remaining-work.md.

Supported game

Game	Engine	Status
The Legend of Zelda: Ocarina of Time	Ship of Harkinian	Supported
The Legend of Zelda: Majora's Mask	2 Ship 2 Harkinian	Not supported by this app; it requires a separate port

HarkinianPad is a native source-port integration, not a general Nintendo 64 emulator. A Majora's Mask ROM cannot be substituted for Ocarina of Time data.

Reproducible and ROM-free

flowchart LR
    A["HarkinianPad scripts"] --> B["Pinned maintained source"]
    B --> C["Committed iOS integration"]
    C --> D["iOS app or unsigned preview IPA"]
    E["Your supported ROM"] --> F["Files-visible app folder"]
    D --> G["Local extraction"]
    F --> G
    G --> H["Local oot.o2r and gameplay"]

Loading

The compile never reads your ROM. scripts/build-ios.sh fetches exact maintained submodule commits, verifies their contents and modes, generates Shipwright's ROM-free soh.o2r, and builds the app. Your ROM is introduced only after installation.

To create the unsigned, re-signable developer-preview package, run:

scripts/package-ios.sh

The current defaults in version.json are HarkinianPad 0.2.1, build 8, with bundle identifier com.chrissotraidis.harkinianpad. The package is named HarkinianPad-0.2.1-preview.8-unsigned.ipa. It contains no maintainer certificate or provisioning profile; a sideload tool such as AltStore Classic must re-sign it for the installer's device.

Releases publish no IPA; this packaging step is for your own local builds. CI compiles and checks the package without uploading a downloadable full app. An unsigned or ROM-free package is not automatically cleared for publication.

The audit rejects Simulator products, stale signing material, original ROMs, ROM-derived oot*.o2r/.otr files, and prohibited game data. For a local maintainer-signed package, use REQUIRE_SIGNED=1 scripts/package-ios.sh. Your local IPA is an unsigned, self-signable package, not a public download, App Store or TestFlight artifact. It does not currently carry a standalone Apple privacy manifest; that remains an official-store distribution gate.

Frequently asked questions

Where is the IPA?

There is no public IPA: HarkinianPad is compiled from the Ship of Harkinian decompilation, so PadMint builds your own on an Apple Silicon Mac. See Get started.

Does this repository include Ocarina of Time?

No. You must provide your own legally acquired supported ROM. Do not open issues requesting game data or download links.

Does audio work?

Yes. Audio has been heard during repeated physical-iPad gameplay sessions. Speaker playback is accepted for the developer preview; headphone, Bluetooth, and interruption recovery remain additional hardware checks.

Can I hide touch controls and get them back later?

Yes. The persistent ••• button keeps the menu reachable. Open Settings → Controls and toggle Touch Controls.

Does it support controllers?

The existing Shipwright SDL controller mappings are compiled into the app for iOS-compatible controllers. Physical gameplay, reconnect, rumble, and motion support still require model-specific verification.

Is this an App Store or TestFlight release?

No. PadMint makes an unsigned IPA on your Mac for personal re-signing. App Store, TestFlight, AltStore PAL, and SideStore distribution are separate projects with different signing, review, account, and regional requirements.

What is the licensing status?

Each upstream component retains its own license and copyright. Libultraship, ZAPDTR, OTRExporter, SDL, and their dependencies carry their respective licenses. HarkinianPad-owned integration code, scripts, documentation, artwork, and original patch content are publicly readable but currently carry no license grant. HarkinianPad is therefore source-available, not broadly redistributable open source.

The pinned Shipwright tree also has no top-level license. Shipwright's official modding guide documents public forks, modifications, and distributable builds. The free, unsigned, ROM-free HarkinianPad developer preview follows that community modding model. GitHub-hosted maintenance follows those explicit fork instructions. Complete release-source distribution remains unqualified, alongside paid access, commercial binary licensing and official-store distribution. See the modernization record.

Project map

Path	Purpose
scripts/build-ios.sh	Complete Simulator or device build
scripts/package-ios.sh	Unsigned/signed IPA and game-data audit
scripts/check-repo-safety.sh	Fast tracked-asset, history, patch, script, and documentation gate
patches/	Historical Preview 5 patch mapping; not used by normal builds
docs/BUILDING.md	Full build, signing, installation, and testing guide
docs/INSTALL_IPA.md	Developer-preview IPA installation with AltStore Classic
docs/RELEASE_CHECKLIST.md	Source and IPA publication gates
docs/touch-controls-design.md	Touch layout and input contract
docs/native-hud-touch-experiment.md	Native HUD touch implementation history and physical test log
docs/customizable-touch-controls.md	Default movable/resizable touch controls and legacy fallback
docs/remaining-work.md	Evidence ledger and remaining gates
ref/	Ignored local reference area; only its safety README is tracked

Build directories, artifacts, ROMs, and ROM-derived archives are ignored and must never be committed.

Contributing and support

Join the Discord community for questions and discussion.

Use the structured bug report for reproducible gameplay or platform defects. Read CONTRIBUTING.md before proposing a change and SECURITY.md before reporting a sensitive vulnerability. Never attach or request game data.

Community and support

Join the Discord for help and news. It is one community for HarkinianPad 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.

Legal and acknowledgements

HarkinianPad is an unofficial community project and is not affiliated with or endorsed by Nintendo or Harbour Masters. It does not provide the game, ROM downloads, or playable ROM-derived data.

This project builds on Ship of Harkinian, libultraship, ZAPDTR, OTRExporter, the Ocarina of Time decompilation project, SDL, and their contributors. All projects, copyrights, and trademarks belong to their respective owners.

Preview 6 adds Files import and per-pack controls; see pack formats, creator links and tested limits.

Legal

HarkinianPad is an unofficial, fan-made project. It is not affiliated with, endorsed by, or sponsored by Nintendo. The Legend of Zelda: Ocarina of Time and related names and marks are trademarks of Nintendo (and their respective owners). This repository contains no game data, ROMs, or extracted assets. To use it, you need your own legally obtained copy of the game, and you build it yourself on your own machine. Please don't share game files or builds made from them.