Install guide

iPhone & iPad

There is no App Store release: you build the app on your Mac with Xcode and install it on your own iPhone or iPad. On its first start it copies the game data from your own copy.

  • iOS and iPadOS 15 or later
  • A Mac with Xcode 26
  • A free Apple ID works
  • About 2 GB free on the device

1What you need

  • A Mac with Xcode 26 or later, from the Mac App Store. Open Xcode once so it installs its components.
  • An Apple ID, signed in under Xcode › Settings › Accounts. A free one works, but its apps stop opening after seven days and need building again; a paid Developer Program membership signs for a year.
  • An iPhone or iPad with iOS or iPadOS 15 or later, and its cable, or paired with the Mac over Wi-Fi.
  • Your Total Annihilation folder, the one with totala1.hpi: about 1.1 GB with both expansions and the music. Where to find it on a Mac.

2Install the tools

Open Terminal and install Xcode's command line tools, then CMake and Ninja, for example with Homebrew. Python 3 comes with the command line tools.

Terminal
$ xcode-select --install$ brew install cmake ninja
Illustration

3Get the source

The first build also fetches and builds the libraries the game needs for iOS, once.

Terminal
$ git clone https://github.com/open-annihilation/open-annihilation.git$ cd open-annihilation$ python3 tools/bootstrap_text_fonts.py --fonts-only
Illustration

4Make the Xcode project

Find your team ID: in Xcode › Settings › Accounts, choose your Apple ID 1 and read the team's ID 2.

Accounts
GeneralAccountsBehaviorsNavigationThemes
Apple IDs
you@example.com
TeamRole
Your Name (Personal Team)User
A1B2C3D4E5
Illustration

Then, from the open-annihilation folder, make the project. It opens in Xcode:

Terminal
$ platforms/ios/scripts/xcode.sh --device --team A1B2C3D4E5 --open
Illustration

For a test device, cmake -B build-ios-xcode -DOA_IOS_BUNDLED_GAME_DIR="$HOME/Games/Total Annihilation" builds your game folder into the app: about 1.1 GB larger, but it plays as soon as it is installed.

5Build and install

  1. Connect the iPhone or iPad and unlock it. The first time, tap Trust on the device.
  2. In Xcode's toolbar, choose the oa-game scheme 1 and your device 2.
  3. If Xcode says the app's identifier is not available, change Bundle Identifier under Signing & Capabilities to one of your own 4, such as net.yourname.open-annihilation.
  4. Choose Product › Run 3.
▶oa-game›Commander’s iPhoneReady
open-annihilation
oa-game
platforms
src
GeneralSigning & CapabilitiesInfoBuild Settings
Automatically manage signing
Your Name (Personal Team)
net.yourname.open-annihilation
Illustration

6Allow the app on the device

The first time, the device refuses to open an app from your own team. On iOS and iPadOS 16 and later, turn on Developer Mode: Settings › Privacy & Security › Developer Mode 1, turn it on 2 and restart the device when it asks.

9:41
‹ SettingsPrivacy & Security
Location ServicesOn›
Tracking›
Local Network›
Security
Developer ModeOff›
9:41
‹ BackDeveloper Mode
Developer Mode
Turning on Developer Mode restarts the device.
Illustration

Then trust your developer profile: Settings › General › VPN & Device Management, choose your Apple ID under Developer App 1 and tap Trust 2. Now open Open Annihilation from the Home Screen.

9:41
‹ GeneralVPN & Device Management
VPNNot Connected›
Developer App
Apple Development: you@example.com›
9:41
‹ BackApple Development
Trust “Apple Development: you@example.com”
Apps from this developer: Open Annihilation
Illustration

7Add your game files

The first time you open it, the Game files screen offers three ways to bring your Total Annihilation files onto the device. Whichever you choose, the files are checked, and the app never closes for lack of them.

The Game files screen on an iPad
ScreenshotThe Game files screen on an iPad.
  1. Put your Total Annihilation folder where the device can reach it: iCloud Drive, a USB drive, a computer's shared folder (connect to it in the Files app first), or the device itself.
  2. Tap CHOOSE FOLDER, then Browse, find the folder, open it and tap Open. The app reads only names and sizes, so nothing downloads yet.
  3. Ready to copy shows what it found, with switches for the optional parts, what it leaves out, and the space the copy needs. Tap COPY.
Ready to copy
ScreenshotReady to copy.
  1. The copy shows its progress, the time left and the file it is on. Keep the app open until it ends; if you leave, it pauses and continues when you come back. Files only in iCloud download as they are copied.
Copying
ScreenshotCopying.
  1. The copy is checked with the game's own check, then Ready to play says what the game will play. Tap PLAY.
Ready to play
ScreenshotReady to play.

8Play

Open Open Annihilation and turn the device on its side: the game is landscape only. The touch controls cover tapping to move, the build drawer, the order wheel on a long press and pinch to zoom; a keyboard, mouse or trackpad works as on a computer.

✓You're in, Commander

When the main menu appears, the game has found your files. Pick a campaign, a skirmish or a network game.

Open Annihilation main menu
Screenshot

Managing the game files

Open the OA settings from the main menu and choose Game files: what is installed, its size and the space free, whether the files go in device backups (off by default, since they would count about 1.1 GB against iCloud), and MANAGE…, which adds an expansion, maps or a mod, checks the files again, or removes or replaces them. Saved games and settings always stay.

Managing the game files on an iPhone
ScreenshotManaging the game files on an iPhone.

Network games

The first time the game uses the network, iOS asks whether it may find and connect to devices on your local network: tap Allow, or turn it on later in Settings › Privacy & Security › Local Network. A build signed with a free Apple ID cannot search for games by broadcast: join by typing the host's address on the TCP/IP screen (a device's address is under Settings › Wi-Fi, the information button). A paid team can request Apple's multicast networking entitlement and build with --multicast-entitlement.

Troubleshooting

“Untrusted Developer”
Trust your developer profile, step 6.
The app stopped opening after a week
A free Apple ID signs for seven days: build and install again, step 5.
“This folder does not hold a Total Annihilation installation”
Choose the folder that holds totala1.hpi.
“Not enough space”
Free space under Settings › General › iPhone Storage, or turn off an optional part, then CHECK AGAIN or CONTINUE; what was copied is kept.
“The copy stopped”
A drive, shared folder or the network went away: connect again and tap CONTINUE.
No games appear when searching
Type the host's address on the TCP/IP screen, or build with the multicast networking entitlement.

Updating and removing

To update, run git pull in the open-annihilation folder and build and install again (step 5); your game files, saves and settings stay on the device. To remove the game, press and hold its icon and choose Remove App, which also removes the game files copied into it.

Other platforms

Something not as described? Discord · GitHub issues