Skip to content

About

Resources

Stars

1 star

Watchers

0 watching

Forks

 
 

Repository files navigation

Ship of Harkinian Ship of Harkinian

Note

This is an unofficial fork that adds Apple TV (tvOS) support. It is not affiliated with or supported by HarbourMasters. For the official project, see HarbourMasters/Shipwright. Please don't take tvOS issues to the official Discord.

tvOS Fork

This fork builds Ship of Harkinian as a native Apple TV app:

  • Metal rendering. libultraship's Metal backend is used; OpenGL is not available on tvOS.
  • Wi-Fi asset upload. tvOS apps can't open a file picker or run the ROM extractor. On first launch, the app starts a small HTTP server on your local network and shows its URL and a QR code on the TV. Open that page on a phone or computer and upload an oot.o2r / oot-mq.o2r you generated with a desktop build.
  • Platform fixes. CoreMotion is stubbed out, the audio codecs (Ogg, Vorbis, Opus) and SDL_net are built from source for tvOS, and the app adopts the UIScene lifecycle required by the tvOS 27 SDK. Writable data goes in the app's Caches directory, the only sandbox location tvOS lets the app write to.

The tvOS changes span this repo and the libultraship submodule, so clone recursively.

Building for tvOS

Requirements: macOS with Xcode (tvOS SDK; the app targets tvOS 15.0+) and CMake. The build script generates soh.o2r automatically with the host asset tools.

git clone --recursive <this-fork-url>
cd Shipwright
./scripts/apple/build-tvos.sh                                   # unsigned / simulator
./scripts/apple/build-tvos.sh --team <TEAM_ID> --bundle-id <your.bundle.id>   # signed, for a device
open build-tvos/Ship.xcodeproj

In Xcode, select the soh scheme and your Apple TV (or a simulator), then Run. Pass --release for a Release configuration.

Getting game assets onto the Apple TV

  1. Run a desktop build with your supported ROM to generate oot.o2r (and/or oot-mq.o2r).
  2. Launch the app on the Apple TV. It will show an upload URL and a QR code.
  3. On a device on the same network, open the URL and upload the .o2r file. The game starts after the upload completes.

The upload server has no authentication and only runs until the assets are received, so use it on a trusted network. As with upstream, no copyrighted assets are included. You must provide your own legally obtained copy of the game.

tvOS status / TODO

This port is a work in progress. Known gaps:

Not working / missing

  • Saves can be lost. All app data (saves, settings, uploaded .o2r files) lives in Library/Caches, which tvOS may purge when storage runs low. Needs iCloud (CloudKit / key-value storage) or another persistent option.
  • Simulator builds fail to link. CMake picks up zlib/bzip2 from the device SDK, so only real Apple TV builds work.
  • No way to add files after setup. The upload server only runs when no oot.o2r / oot-mq.o2r is present, so you can't add Master Quest later, replace an archive, or add mods and custom music packs (which the audio codecs now support).
  • Scripting (TCC mods) and text-to-speech aren't available on tvOS.
  • Gyro aiming is unavailable; SDL's motion sensors are disabled in the tvOS build.

Upload server

  • No authentication; anyone on the network can reach it while it runs.
  • Filenames must be exactly oot.o2r or oot-mq.o2r; renamed files are rejected.
  • The whole upload is held in memory (up to 512 MB, copied once more while parsing), which is heavy for Apple TV RAM.
  • A malformed Content-Length header crashes the app (std::stoull throws).
  • The destination directory passed to the server is ignored; it always writes to Caches.

Untested on device

  • Custom/streamed music (Opus, Ogg Vorbis).
  • Siri Remote and controller navigation of the ImGui menus, including text entry.
  • Online features (Anchor, via SDL_net).
  • Release builds.

Future ideas

  • Upload the ROM itself and extract on the Apple TV with Torch, instead of requiring a desktop-generated oot.o2r.
  • A tvOS build in CI.

If you're having any trouble after reading through this README, feel free to ask for help in the Support text channels. Please keep in mind that we do not condone piracy.

Quick Start

The Ship does not include any copyrighted assets. You are required to provide a supported copy of the game.

1. Verify your ROM dump

You can verify you have dumped a supported copy of the game by using the compatibility checker at https://ship.equipment/. If you'd prefer to manually validate your ROM dump, you can cross-reference its sha1 hash with the hashes here.

2. Download The Ship of Harkinian from Releases

3. Launch the Game!

Windows

  • Extract the zip
  • Launch soh.exe

Linux

  • Place your supported copy of the game in the same folder as the appimage.
  • Execute soh.appimage. You may have to chmod +x the appimage via terminal.

macOS

  • Run soh.app. When prompted, select your supported copy of the game.
  • You should see a notification saying Processing OTR, then, once the process is complete, you should get a notification saying OTR Successfully Generated, then the game should start.

Apple TV (tvOS, this fork only)

Nintendo Switch

  • Run one of the PC releases to generate an oot.o2r and/or oot-mq.o2r file. After launching the game on PC, you will be able to find these files in the same directory as soh.exe or soh.appimage. On macOS, these files can be found in /Users/<username>/Library/Application Support/com.shipofharkinian.soh/
  • Copy the files to your sd card
sdcard
└── switch
    └── soh
        ├── oot-mq.o2r
        ├── oot.o2r
        ├── soh.nro
        └── soh.o2r
  • Launch via Atmosphere's Game+R launcher method.

4. Play!

Congratulations, you are now sailing with the Ship of Harkinian! Have fun!

Configuration

Default keyboard configuration

N64 A B Z Start Analog stick C buttons D-Pad
Keyboard X C Z Space WASD Arrow keys TFGH

Other shortcuts

Keys Action
ESC Toggle menu
F2 Toggle capture mouse input
F5 Save state
F6 Change state
F7 Load state
F9 Toggle Text-to-Speech
F11 Fullscreen
Tab Toggle Alternate assets
Ctrl+R Reset

Project Overview

Ship of Harkinian (SOH) is built atop a custom library dubbed libultraship (LUS). Back in the N64 days, there was an SDK distributed to developers named libultra; LUS is designed to mimic the functionality of libultra on modern hardware. In addition, we are dependent on the source code provided by the OOT decompilation project.

In order for the game to function, you will require a legally acquired ROM for Ocarina of Time. Click here to check the compatibility of your specific rom. Any copyrighted assets are extracted from the ROM and reformatted as a .o2r archive file which the code uses.

Graphics Backends

Currently, there are three rendering APIs supported: DirectX11 (Windows), OpenGL (all platforms), and Metal (MacOS). You can change which API to use in the Settings menu of the menubar, which requires a restart. If you're having an issue with crashing, you can change the API in the shipofharkinian.json file by finding the line gfxbackend:"" and changing the value to sdl for OpenGL. DirectX 11 is the default on Windows.

Custom Assets

Custom assets are packed in .otr archive files. To use custom assets, place them in the mods folder.

If you're interested in creating and/or packing your own custom asset .otr files, check out the following tools:

Development

Building

If you want to manually compile SoH, please consult the building instructions.

Playtesting

If you want to playtest a continuous integration build, you can find them at the links below. Keep in mind that these are for playtesting only, and you will likely encounter bugs and possibly crashes.

Further Reading

More detailed documentation can be found in the 'docs' directory, including the aforementioned building instructions.

Powered by libultraship

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages