F-Zero X rebuilt as a native Apple app.
Metal rendering, local game-data setup, customizable touch controls, and
support for keyboards and iOS-compatible game controllers.
Download · Build · Game data · Touch controls · Status · Known issues · Evidence
F0X packages the native decompiled F-Zero X game logic from [G-Diffuser](https://github.com/Zorkats/G-Diffuser) with [libultraship/Fast3D](https://github.com/Zorkats/libultraship) and its Metal backend. It is a source-port integration, not a general Nintendo 64 emulator. This repository contains the Apple integration, maintained patches, documentation, and original F0X artwork. It does **not** contain F-Zero X, a ROM, extracted Nintendo assets, saves, or a playable ROM-derived archive. You must supply your own legally acquired supported cartridge dump; setup and extraction happen locally, and nothing is uploaded. > [!NOTE] > **AI disclosure:** F0x 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 F0x's workflow, not the authorship of its upstream projects. ## Install status | Option | Status | What to do | |---|---|---| | App Store / TestFlight | **Not announced** | F0X has no store listing or public TestFlight. | | Local iPad build | **Owner-played and accepted** | The signed arm64 build has been installed, updated in place, and played on a physical 12.9-inch iPad Pro. Normal game start, touch racing, audio, and course presentation are accepted on that device. | | Local iPhone build | **Installed; layout accepted** | The universal build is signed and running on a physical iPhone 14 with verified local game data. Its owner-arranged touch profile is now the independent phone default; broader phone gameplay testing continues. | | iPhone/iPad Simulator | **Available for development** | The native arm64 app imports local game data, renders through Metal, and has completed touch/UI/race stability verification. Simulator evidence is not physical-device acceptance. | | Apple Silicon macOS | **Available for development** | The native `F0X.app` builds, seals locally, imports game data, persists saves, and renders a live Metal race. | F0X's developer previews have been retired while a new version is prepared. The current physical-iPad build is owner-accepted for normal game start, touch gameplay, audio, course previews, and racing. The iPhone 14 layout is also owner-arranged and promoted to independent defaults; broader phone gameplay testing continues. Headset/Bluetooth routes, lifecycle interruptions, thermals, physical controllers, stress multi-touch, and long-session coverage remain open. See the exact [evidence ledger](docs/STATUS.md) rather than inferring completion from a build or Simulator screenshot. ## Download Build your own copy with [PadMint](https://github.com/chrissotraidis/padmint/releases/latest) 0.5.5 or newer on an Apple Silicon Mac with Xcode: choose **F-Zero X**, then **iPhone or iPad** or **This Mac**, and follow the page. PadMint builds F0X from this repository's latest release; it never reads your ROM. You choose your own US revision 0 ROM inside F0X the first time it opens. You can also [build F0X yourself](#get-started). **No Mac?** You can build the iPhone and iPad app on GitHub's free Mac from Windows, Linux or any computer with a web browser: follow [PadMint's steps](https://github.com/chrissotraidis/padmint#no-mac-build-on-githubs-mac). Older F0X previews were **unsigned, ROM-free, arm64 IPAs** for iPhone and iPad on iOS and iPadOS 16 or newer, which you re-sign with your own Apple identity. They never include F-Zero X or extracted game assets: after installing, select your own supported US revision 0 ROM from Files, and extraction stays on the device. When one is published, install it over the existing `com.chrissotraidis.f0x` app without uninstalling first, so your saves, settings and touch layouts stay. ## Get started You need: - an Apple Silicon Mac with Xcode and its command-line tools; - CMake, Ninja, and Python 3; - your own legally acquired supported F-Zero X ROM; and - an Apple ID configured in Xcode if you intend to install on hardware. Install the basic host tools with [Homebrew](https://brew.sh): ```sh brew install cmake ninja python ``` Clone F0X and run the pinned-source setup. Generated sources and build products live under ignored `ref/` and `build/`; maintained Apple changes stay reviewable in `patches/`. ```sh git clone https://github.com/chrissotraidis/f0x.git cd f0x scripts/setup-sources.sh ``` Build the Apple Silicon macOS app: ```sh cmake -S ref/G-Diffuser -B build/macos-f0x-bundle -G Ninja \ -DCMAKE_BUILD_TYPE=Debug \ -DGDX_EXPANSION_KIT=OFF \ -DGDX_MACOS_BUNDLE=ON \ -DPython3_EXECUTABLE="$PWD/build/python-build-tools/bin/python" cmake --build build/macos-f0x-bundle --target G-Diffuser --parallel 4 open build/macos-f0x-bundle/port/F0X.app ``` The iPhone/iPad Simulator and unsigned arm64 device recipes are in [`docs/BUILDING.md`](docs/BUILDING.md). Device installation additionally requires a development team, provisioning profile, controlled bundle ID, and connected iPhone or iPad. Never commit signing material or team identifiers. ## First launch F0X never downloads or bundles game data. 1. Open F0X and choose **Manage Game Data** or the first-run setup action. 2. Select your supported ROM with the native file picker. 3. F0X copies the file into its private container and validates its identity. 4. Choose **Build game data and continue**. 5. The in-process Torch pipeline creates and validates `fzerox.o2r` locally. 6. F0X activates the archive atomically and continues into the native game. The verified iPad Simulator path completes selection, validation, in-process extraction, hot mounting, and a visible race without starting a second app. Archive-only relaunch also works after the original ROM is removed. Physical device storage-pressure, interruption, invalid-input, and cancellation paths still need hardware acceptance. ## Supported game data | Property | Supported value | |---|---| | Game | F-Zero X | | Region / revision | US revision 0 | | Format | Big-endian `.z64` | | Size | 16 MiB (`16,777,216` bytes) | | SHA-1 | `5f658e88ffa9de23cba6986a8fd3d3a90d7b4340` | | Local archive | `fzerox.o2r`, 3,610 records | Byte-swapped `.v64` and `.n64` inputs are not currently advertised. Do not open issues requesting ROMs, extracted archives, or download links. ## Touch controls F0X uses an original UIKit touch controller adapted to F-Zero X rather than simulating keyboard events. It writes atomic N64 pad state directly into port 1 and merges cleanly with a physical controller. - **Left:** continuous analog steering, a separate D-pad, and the left slide/attack control. - **Right:** accelerator, boost, brake, right slide/attack, camera, look-back, Start, and secondary controls. - **Menu:** `•••` remains available whenever the game surface is active. - **Settings:** use **Settings → Controls → Touch Controls** for visibility, controller auto-hide, haptics, opacity, and reset controls. - **Customize:** move, resize, show, or hide controls in independent phone and tablet layouts; saved layouts survive relaunch. The owner-accepted physical iPad layout is the tablet default, and the separately arranged physical-iPhone profile is now the phone default. Reset or a clean install selects the correct device-class layout without changing an existing saved profile. - **Racing assist:** holding A for one second can lock acceleration during a race. Hold-to-lock is disabled in game menus and is cleared when a race ends, so menu confirmation and back/forward navigation always receive fresh taps. - **Input Editor:** the mobile-safe editor uses two balanced columns on iPad and one on iPhone, with every stick, rumble, gyro, and LED section reachable. Opening Settings or the Input Editor releases and hides gameplay input. Internal race/menu transitions also clear held racing assists. The focused merge/profile suite passes 87 checks, and live iPad/iPhone Simulator verification covers visual layout, menu/editor behavior, persistence, and a touch-driven route into a race. Ordinary physical-iPad touch gameplay and the current tablet layout are owner- accepted. Physical-iPhone geometry is accepted. Stress multi-touch, controller handoff, haptic feel, and broader phone gameplay remain under test. | Touch label | F-Zero X action | |---|---| | Analog stick | Steering and menu navigation | | A | Accelerate / confirm | | B | Boost / cancel | | C↓ | Brake | | Z / R | Left / right slide and attack inputs | | C→ | Change camera | | C↑ | Look back | | Start | Start / pause | | D-pad | Menus and editor functions | ## What works | Area | Current evidence-backed result | |---|---| | Native runtime | Decompiled F-Zero X logic runs as host arm64 code; this is not an emulator frontend | | Rendering | libultraship/Fast3D renders through Metal on Apple Silicon macOS, iOS Simulator, the owner-tested physical iPad, and the launched physical iPhone build | | Game setup | Native picker, local validation, in-process extraction, atomic install, hot mount, and archive-only relaunch | | Touch | Full control set, phone/tablet layouts, customization, persistence, safe cancellation, menu access, and controller auto-hide | | Input Editor | Responsive iPhone/iPad layout with aligned mappings and unobstructed controls | | Saves | Exact 32 KiB settings-SRAM write, relaunch, load, and reversal verified on macOS | | Audio | Retail cartridge synthesis, corrected cartridge instrument mapping, 59.94 Hz mobile pacing, and SDL 32 kHz stereo transport; normal physical-iPad gameplay is owner-accepted, while the iPhone and alternate route/interruption matrix remain open | | Course previews | The six rotating course maps use the host-compatible packed 0.25 model scale and are owner-accepted on the physical iPad | | Physical iPhone | Signed build installed and running on iPhone 14; ROM/archive/save/control hashes and live archive/audio startup are verified, while hands-on play remains open | | Diagnostics | Privacy-scrubbed runtime report and native Share sheet verified on macOS and iPhone Simulator | | Stability | Converted display-list cache regression plus a 5:16 guarded Simulator race/transition soak with no crash | | Packaging | Sealed local macOS bundle plus deterministic, ROM-free unsigned arm64 iPhoneOS IPA workflow | Still open: physical-iPhone gameplay and layout acceptance, stress multi-touch, route/interruption matrices, high-refresh and Low Power Mode behavior, release signing/notarization, a human-completed macOS race on this host, and Expansion Kit support. ## Reproducible and ROM-free ```mermaid flowchart LR A["F0X repository"] --> B["Pinned G-Diffuser sources"] B --> C["Maintained Apple patches"] C --> D["ROM-free F0X app"] E["Your supported ROM"] --> F["Local validation"] D --> G["In-process extraction"] F --> G G --> H["Private fzerox.o2r and gameplay"] ``` The compile never needs or packages your ROM. Repository and package audits must reject original game media, derived playable archives, saves, credentials, provisioning profiles, certificates, and signing keys. Exact pins and licenses are recorded in [`docs/DEPENDENCIES.md`](docs/DEPENDENCIES.md). ## Frequently asked questions