Build the iOS app yourself with Xcode

The iOS app is the same Tauri 2 project as the desktop launcher, built for iPhone and iPad. This page is for contributors and for players who want to build the IPA themselves instead of taking ours. If you only want to play, install the official app – see iPhone/iPad: install with AltStore/SideStore.

The commands on this page are the ones the CI runs (.github/workflows/ci.yml job launcher-ios, release.yml jobs iOS and iOS engine, .github/workflows/ios-engine.yml). The CI never signs the app – it builds an unsigned IPA, and AltStore/SideStore sign it with the user's Apple ID when installing.

What is where

Requirements

The app needs iOS 15 (minimumSystemVersion in tauri.ios.conf.json). The CI sets IPHONEOS_DEPLOYMENT_TARGET=15.0 for the app, because the Swift packages of the plugins use APIs from iOS 14 on; the engine itself is built for 14.0.

Build the IPA

git clone https://github.com/theredstonee/TRS-Launcher.git
cd TRS-Launcher
pnpm install
rustup target add aarch64-apple-ios
brew install ldid cmake

pnpm generate

bash scripts/ios-project.sh

export IPHONEOS_DEPLOYMENT_TARGET=15.0
bash scripts/ios-unsigned-ipa.sh release build/TRS-Launcher-app.ipa

JAVA8_HOME=$(/usr/libexec/java_home -v 1.8) bash scripts/ios/build-engine.sh build/engine-ios

bash scripts/ios/package-ipa.sh build/TRS-Launcher-app.ipa build/engine-ios build/TRS-Launcher.ipa

Run it from Xcode with your own Apple ID

You can also start the app straight from Xcode on a connected iPhone and sign it with your own team (a free Apple ID works as "Personal Team"). This is handy for working on the interface. Two things to know:

• The app has no game engine this way – starting an instance reports that the engine is missing. Sign-in, social, wardrobe, modpacks and everything else work.
• The CI never signs with a team, so we haven't tested this path.

export IPHONEOS_DEPLOYMENT_TARGET=15.0
bash scripts/ios-unsigned-ipa.sh debug build/TRS-Launcher-debug.ipa

open src-tauri/gen/apple/*.xcodeproj

Make it your own app

• Bundle ID: AltStore/SideStore sign the IPA with your Apple ID, so you don't have to change anything for that. For Xcode, change the bundle ID there (see above).
• Don't change identifier in src-tauri/tauri.conf.json. It is shared with Android, where the Kotlin package and the Rust code depend on it – the Android build then stops (see Build the Android app yourself). An iOS-only identifier in tauri.ios.conf.json might work, but we haven't tested it.
• Keep the background task ID dev.theredstonee.trslauncher.push-poll as it is: it appears both in src-tauri/Info.ios.plist and in the push plugin's Swift code, and iOS only runs tasks listed in the Info.plist.

What still works in your own build, according to the code:

• Microsoft sign-in uses the device-code sign-in (you type a code on Microsoft's page) – it doesn't depend on the bundle ID.
• TRS services (friends, chat, capes, TRS API) talk to the same API; there is no check of the app or its signature.
• Links like trs-launcher://pack/<code> use the same scheme in every build.
• Updates: your build isn't connected to our AltStore/SideStore source. Update it by building and installing again.

If something breaks in your own build, please report it.

Run the checks

The same checks as the CI:

pnpm generate
cd src-tauri
IPHONEOS_DEPLOYMENT_TARGET=15.0 cargo clippy --workspace --target aarch64-apple-ios -- -D warnings
# game plugin for iOS, Rust and its Swift package (job "iOS engine"):
IPHONEOS_DEPLOYMENT_TARGET=14.0 cargo build -p tauri-plugin-trs-game --target aarch64-apple-ios

Troubleshooting

"Build-Phase tauri ios xcode-script nicht gefunden"

scripts/ios-unsigned-ipa.sh switches off that build phase the first time it runs – a second run doesn't find it any more and stops with this message. The CI always starts with a fresh project. Locally, delete the generated project and create it again:

rm -rf src-tauri/gen/apple
bash scripts/ios-project.sh

Errors about the deployment target or iOS 14 APIs

Set IPHONEOS_DEPLOYMENT_TARGET=15.0 before building the app (14.0 for the engine plugin check) – the Swift packages need at least iOS 14.

The app closes right after opening

If you built the Rust library by hand, you probably left out --features tauri/custom-protocol – then the app waits for a dev server on localhost:3000. Use scripts/ios-unsigned-ipa.sh, which always sets it.

"JDK 8 fehlt (JAVA8_HOME setzen)" or "JAVA8_HOME ist kein JDK 8"

The engine's Java part needs exactly a JDK 8. Install one and point JAVA8_HOME to it.

"ldid fehlt (brew install ldid)"

package-ipa.sh signs with ldid: brew install ldid.

"vendored Datei weicht von Upstream ab"

A file under ios/Engine/vendor/amethyst-ios differs from the pinned Amethyst-iOS commit. Only the patched files listed in that folder's UPSTREAM.md may differ – undo your change or update the list.

The game closes right after starting

Almost always JIT is not on. See Enable JIT. The engine log is in the Files app under On My iPhone → TRS Launcher (trs-engine.log).

Minecraft 26.3 doesn't start

26.3 is not supported on iOS yet (the engine has no SDL3 support there). Use 26.2 or older.

"Unable to verify app" after a week

The 7 days of the free Apple ID are over. Refresh the app in AltStore/SideStore, or run it from Xcode again.

License and name

TRS Launcher is free software under the GNU General Public License v3.0 (LICENSE, copyright notices in NOTICE). You may build, change and share the app. If you share an IPA, the GPL requires that you share it under the same license and make the complete source code of exactly that build available, including your changes. The iOS engine is based on Amethyst-iOS (GPL-3.0) and ships more third-party parts; their license texts are copied into the app (licenses/engine) and listed in NOTICE – keep them.

The repository has no separate trademark rules. Still: if you hand out your own build, give it its own name and bundle ID so nobody mistakes it for the official TRS Launcher, and point people to your source code – not to our support.

Next steps