factorio-ios/README.md

# Factorio on iPhone (personal port)

Run your own copy of **Factorio 2.0.77** natively on an iPhone. The original macOS ARM64 game
code from your local install runs unchanged on iOS; this repository supplies the glue: a Mach-O
retargeting step, a small set of shims for the macOS APIs iOS lacks, touch and keyboard
controls, and build/sign/install tooling.

**This repository contains no game files.** You need a legitimately owned copy of Factorio for
macOS (the Steam build). The build reads the executable and data from your local install and
installs them only on your own device. This is an unofficial, personal project and is not
affiliated with or endorsed by Wube Software.

## Status

Tested on an iPhone 15 Pro (iOS 27.0.1) with Xcode 26.6 (iOS SDK 26.5), using the Steam macOS
build of Factorio 2.0.77 (base game).

| Area | State |
| --- | --- |
| Startup to main menu | ~16 s |
| Rendering | Metal, native panel resolution (2556×1179 on iPhone 15 Pro) |
| New game, playing, autosave | Working |
| Audio | Working (plays with the silent switch on, mixes with other apps) |
| Touch controls, on-screen overlay | Working |
| Hardware keyboard, iOS keyboard with extra keys | Working |
| Loading saves, long sessions, large factories | Not yet verified |
| Mods, multiplayer, Space Age | Not tested |

No JIT and no emulation: the game's own ARM64 machine code runs natively, signed with your
developer certificate.

## Requirements

- A Mac (tested on Apple Silicon) with **Xcode**, including the iOS platform, and **Python 3**.
- **Factorio 2.0.77 for macOS from Steam**, installed at the default Steam location (or pass
  `--game`). The build checks the exact executable hash and refuses other versions.
- An iPhone with an A-series chip that supports Metal, **Developer Mode** enabled, paired with
  the Mac.
- An Apple developer account signed into Xcode, with a development provisioning profile that
  covers the app's bundle identifier (a wildcard team profile works). See
  [docs/building.md](docs/building.md#signing).

## Quick start

```sh
# 1. Build, sign and install the app; copy the game data (~1.5 GB) into the app once.
python3 tools/build_native.py --install --push-data

# 2. Launch with the console attached (or tap the Factorio icon on the home screen).
python3 tools/build_native.py --no-build --launch
```

Later rebuilds only need `python3 tools/build_native.py --install`. Game data and saves live in
the app's Documents folder and survive reinstalls. Full instructions, options and
troubleshooting: [docs/building.md](docs/building.md).

## Controls

| Input | Action |
| --- | --- |
| Tap / drag | Left mouse button |
| Long press (hold) | Right mouse button held: mining, removing; drag to keep going |
| Two-finger drag | Mouse wheel (zoom, scroll lists) |
| Left stick | W A S D movement |
| E Q R F M T buttons | Inventory, pipette, rotate, pick up, map, technologies |
| ⇧ and Ctrl buttons | Sticky modifiers for the next click or key |
| Esc, Tab | Escape and Tab |
| ⌨︎ | iOS keyboard plus a bar with Esc, Tab, Ctrl, Alt, ⇧, arrows, Home/End, PgUp/PgDn, F1–F12 |
| ◐ | Hide or show the on-screen controls |

A Bluetooth or USB keyboard works directly with Factorio's normal key bindings. Details:
[docs/controls.md](docs/controls.md).

Factorio's interface is small at native resolution; set **Settings → Interface → UI scale** to
around 175–200 %.

## How it works

1. `tools/retarget.py` turns the unmodified macOS executable into an iOS-loadable dynamic
   library by editing only Mach-O header fields (platform, file type, page-zero size,
   framework paths). It verifies that no byte after the header changes.
2. `platform/native/shim/` implements the ~150 macOS symbols iOS lacks: an AppKit layer on
   UIKit sized to the SDL 2.24 Cocoa backend Factorio links statically, CoreGraphics display
   and CoreAudio device models, PNG decoding through Wuffs, Metal device properties, and
   stubs for Steam, Carbon, ForceFeedback, OpenCL and LDAP.
3. A small host app starts UIKit, loads the game library and calls its original `main` on the
   main thread with a larger stack.

The design, every shim, and the verification behind it are described in
[docs/native-port.md](docs/native-port.md).

## Repository layout

| Path | Contents |
| --- | --- |
| `tools/build_native.py` | Build, sign, install, copy data, launch |
| `tools/retarget.py` | Header-only Mach-O retargeting of the game executable |
| `tools/native_audit.py` | Lists game imports that iOS lacks (needs shims) |
| `tools/symbolize_native.py` | Symbolizes crash reports against the game's debug symbols |
| `tools/make_icon.m` | Builds the app icon from the game's own icon |
| `platform/native/` | iOS host app and macOS API shims |
| `tests/native/` | PNG decoder parity test against macOS ImageIO |
| `docs/` | Build guide, controls, architecture |
| `docs/research/`, `runtime/`, `tests/*.py`, other `tools/` | Earlier static-translation research (ARM64 → WASM → native), kept for reference |

## Third-party software

- [Wuffs](https://github.com/google/wuffs) v0.3.4 (Apache-2.0): PNG decoding. Downloaded at
  build time into `third_party/` and checked against a pinned SHA-256; not vendored.
- [SDL](https://github.com/libsdl-org/SDL) 2.24 (zlib): statically linked inside the game
  binary; its source was used as a reference for the AppKit shim and is not included.
- [WABT](https://github.com/WebAssembly/wabt) (Apache-2.0): used only by the research track.

Factorio is a trademark of Wube Software Ltd. All game code and assets remain theirs.