Field report: Unity as a Library in a SwiftUI app built with xtool on Linux

[gulian]

Hi, and thanks for xtool. I wanted to know if a real-time Unity scene could live inside a SwiftUI app without a local Mac, and since it worked, here are my notes in case they're useful to you or to anyone trying the same thing.

Short version: it works. xtool 1.24.0 on Linux builds, signs and installs a SwiftUI app that embeds Unity 6 as an .xcframework. The app runs on an iPhone with a 3D scene behind the SwiftUI UI, and it's been smooth in use. A Mac is still needed once, to compile the framework itself, but a GitHub Actions runner does that fine.

The chain

1. Unity 6000.3.28f1 (Windows, iOS module) exports the Xcode project with BuildPipeline.BuildPlayer.
2. A macos-26 runner (Xcode 26.6) compiles the UnityFramework scheme unsigned, copies the export's Data/ folder into the framework, then runs xcodebuild -create-xcframework. About 4 minutes.
3. On Linux, Package.swift declares it as a binary target:

   .binaryTarget(name: "UnityFramework", path: "Vendor/UnityFramework.xcframework"),

4. xtool dev build -c release, then xtool install. Once the framework exists, a Swift-only change takes about 10 seconds to build. The app is around 300 MB.

The framework step:

xcodebuild -project Unity-iPhone.xcodeproj -scheme UnityFramework -configuration Release \
  -sdk iphoneos -destination 'generic/platform=iOS' -derivedDataPath ../dd \
  SKIP_INSTALL=NO CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO build
FW=dd/Build/Products/Release-iphoneos/UnityFramework.framework
rm -rf "$FW/Data" && cp -R export/Data "$FW/Data"
xcodebuild -create-xcframework -framework "$FW" -output UnityFramework.xcframework

On the Swift side:

let ufw = UnityFramework.getInstance()!
ufw.setDataBundleId("com.unity3d.framework")   // Unity looks for Data/ in the framework's bundle
ufw.runEmbedded(withArgc: CommandLine.argc, argv: CommandLine.unsafeArgv, appLaunchOpts: nil)

I then move ufw.appController().rootView into a UIViewRepresentable, hide Unity's own window and call makeKeyAndVisible() on the SwiftUI one. The app talks to the scene with sendMessageToGO. xtool signed the embedded framework without any special handling, which was the part I was least sure about.

Things that bit me

• Unity messages sent too early are lost silently. Anything sent before the scene has loaded disappears without an error, so I resend values periodically.
• Unity logs don't show up in the device log the way Logger output does. That left me debugging from the Swift side.

Both are Unity's behaviour rather than xtool's, but you'll probably hit them if you try this.

One related note on #351: it says local installs aren't affected, but here they were. On an iPhone Duo the app opened in a centred compatibility window until I passed -platform_version with the real SDK version at link time.

What I haven't tested: anything beyond development signing, and only an iPhone Duo has actually run it so far. I also saw the app quit twice right after an install, with no crash report. It stopped happening and I never found the cause, so I can't say whether it's related to any of this.

If some of this is useful for the docs, feel free to use it.

[kabiroberai]

This is great, thanks for sharing. I have WIP changes for Xcode project support + closer parity when packaging, so would be interesting to revisit once those land. Might even be able to skip the xcframework step.

[gulian]

Thanks! Happy to retry the same setup once those changes land, skipping the xcframework step would make this a lot simpler. Feel free to ping me here.