entityseven/factorio-ios
2
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simple install guide and one-step install.sh

Browse Source 
- README rewritten as a step-by-step guide for non-developers
- install.sh: build, install and copy data with plain error messages
- build_native.py: bundle identifier from the user's provisioning
  profile (Xcode project named factorio), version check on every
  build, friendly errors
This commit is contained in:
SashaGoncharov19 committed 2026-10-23 15:40:18 +04:00
1 parent 51d085e865
commit 30b961c923
4 files changed
+227 -133
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+115 -94
View File
@@ -1,114 +1,135 @@
# Factorio on iPhone (personal port)
# Factorio on iPhone
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.
Play your own copy of **Factorio** on your iPhone. You build the app on your Mac from the
Factorio you already own on Steam, and install it on your phone with a cable.
**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.
This project contains **no game files**. Everything comes from your own installed copy. It is an
unofficial fan project, not made or supported 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).
## What you need
| 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 |
- A **Mac** (tested on Apple Silicon).
- **Factorio 2.0.77 for Mac, bought on Steam** and installed.
- An **iPhone** (tested on iPhone 15 Pro) and its **cable**.
- A free or paid **Apple account**.
- About **3 GB** of free space on the phone.
No JIT and no emulation: the game's own ARM64 machine code runs natively, signed with your
developer certificate.
---
## Requirements
## Install, step by step
- 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).
### Step 1: Install Xcode
## Quick start
1. Open the **App Store** on your Mac, search for **Xcode** and install it (it is large and takes
a while).
2. Open Xcode once. When it asks which platforms to install, choose **iOS**.
### Step 2: Sign in to Xcode with your Apple account
1. In Xcode open **Xcode → Settings → Accounts**.
2. Click **+**, choose **Apple ID** and sign in.
### Step 3: Connect your iPhone
1. Plug the iPhone into the Mac, unlock it, and tap **Trust**.
2. On the iPhone open **Settings → Privacy & Security → Developer Mode**, turn it **on**, and let
the phone restart. (If you don't see **Developer Mode** yet, do Step 4 first and come back.)
### Step 4: Let Xcode set up signing (one time only)
Your iPhone only runs apps signed with your Apple account. A tiny empty Xcode project sets this
up once:
1. In Xcode choose **File → New → Project… → iOS → App → Next**.
2. Fill in:
- **Product Name:** `factorio`
- **Team:** your Apple account
- **Organization Identifier:** `com.` followed by your name, for example `com.alexsmith`
3. Click **Next** and save it anywhere.
4. At the top of the Xcode window, pick your **iPhone** as the run destination and press
**▶ (Run)**. A blank white app appears on the phone; that means it worked. If the phone says
**Untrusted Developer**, open **Settings → General → VPN & Device Management**, tap your
account and choose **Trust**, then press **▶** again.
You can now close Xcode and delete that project. The real Factorio app will replace the blank one.
### Step 5: Download this project
Open the **Terminal** app on your Mac and run:
```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
git clone https://git.entityseven.com/entityseven/factorio-ios.git
cd factorio-ios
```
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).
### Step 6: Install Factorio on the phone
## Controls
Keep the iPhone **plugged in and unlocked**, then run:
| Input | Action |
```sh
./install.sh
```
This builds the app, installs it, and copies the game data (about 1.5 GB) to the phone. It takes
a few minutes. When it says **Done**, the **Factorio** icon is on your home screen.
---
## Playing
- **Tap** = left click. **Hold** = right click (hold on ore or trees to mine them).
- **Two-finger drag** = zoom and scroll.
- **Left stick** = walk. Buttons **E Q R F M T**, **Esc**, **Tab**, **⇧**, **Ctrl** = the same keys
as on a computer.
- **⌨︎** opens the keyboard. **◐** hides the on-screen buttons.
- A Bluetooth keyboard works too.
The text is small at first: in the game open **Settings → Interface** and set **UI scale** to
about **175–200 %**.
The game takes about 15 seconds to start. Your saves stay on the phone, also when you update the
app.
All controls: [docs/controls.md](docs/controls.md).
---
## Updating
```sh
cd factorio-ios
git pull
./install.sh
```
---
## Problems?
| What you see | What to do |
| --- | --- |
| 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 |
| `Factorio not found` | Install Factorio from Steam on this Mac and let it finish downloading. |
| `wrong Factorio version` | This version of the port needs Factorio **2.0.77**. In Steam, open the game's **Properties** and keep it on that version. |
| `no provisioning profile found` | Do **Step 4** again. The Xcode project must be named `factorio`. |
| `no iPhone found` | Plug in the phone, unlock it, tap **Trust**, and check **Developer Mode** (Step 3). |
| `Xcode is not installed` / `iOS platform is missing` | Do **Step 1**. |
| `device was not unlocked` | Unlock the phone and run `./install.sh` again. |
| App says **Game data missing** | Run `./install.sh` again with the phone unlocked. |
| App stops opening after 7 days | Free Apple accounts sign apps for 7 days. Run `./install.sh` again; your saves are kept. |
| The game closes while playing | Run `python3 tools/build_native.py --no-build --launch` and send the output as a bug report. |
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 %.
## More information
## How it works
- [docs/building.md](docs/building.md): advanced build options and troubleshooting.
- [docs/native-port.md](docs/native-port.md): how the port works.
- [docs/research/](docs/research/static-translation.md): earlier research (ARM64 → WASM
translation).
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.
**Third-party software:** [Wuffs](https://github.com/google/wuffs) (Apache-2.0) is downloaded
during the build to decode PNG images. Factorio itself uses [SDL](https://github.com/libsdl-org/SDL)
(zlib). Factorio is a trademark of Wube Software Ltd.; all game code and assets belong to them.