Unity Advent Calendar 2025

@mao_in

Unityゲーム開発者ギルド

【Unity6.3対応版】Unity as a Library で UnityFramework を XCFramework 化して iOS 実機とシミュレーターの両方で動かせるようにする

Last updated at 2025-12-08Posted at 2025-12-07

この記事は Unity Advent Calendar 2025 の7日目の記事です。

はじめに

以前、Unity as a Library (UaaL) で実機 / シミュレーター向けの UnityFramework を XCFramework 化して動かしてみる記事を執筆しました。

しかし、こちらの記事の執筆時点ではシミュレーター向けのビルドが Intel Mac (x86_64) しか対応しておらず、Apple Silicon 向けの arm64-simulator では動作させることができませんでした。

その後も Unity 6 辺りから arm64-simulator 向けのバイナリが含まれるようになったものの、シミュレーター向けにビルドした際にリンクエラーが発生し、依然として上手くいかない状態が続いてました。(詳しくは次章で解説)

そんなある時、Unity 6000.4.0a4 のリリースノートを見ていると、以下の変更が入っていることに気付きました。

Improvements
iOS: Converted iOS, tvOS, and visionOS simulator Unity runtimes to static library framework. Wrapped device static Unity runtime library to framework. Aligned Device and Simulator Unity runtime inclusion in the Xcode project and runtime initialization.
リリースノート: https://unity.com/releases/editor/alpha/6000.4.0a4

こちらの変更内容を見ると、まさに前回悩んでいたところが解消されてそうであり、実際に検証してみたところ、実機 / シミュレーター(arm64-simulator) ともに正常に動作することが確認できたので、本記事では前回記事の続きとして以下の点について簡単に解説していきます。

なぜ今まで動作しなかったのか？
Unity 6.4 (6.3) で何が変わったのか？

また、今回の検証用に新規でサンプルプロジェクトも用意してます。

検証環境

Unity 6000.3.0f1
Xcode 26.1.1
Mac Studio (M1Max): macOS 26.1

なぜ今まで動作しなかったのか?

前回記事でも記載した通り、これまでの Unity ではシミュレーター向けのバイナリは x86_64 で固定されていました。¹

その後、以下のリリースノートの引用に示すように、Unity 6000.0.0f1 および Unity 2022.3.54f1 からは arm64-simulator 向けのバイナリが含まれるようになったので「これで動かせる！」と思いきや...自分の環境では XCFramework 化してシミュレーター向けのビルドを行うと、依然としてリンクエラーが発生する状況となっていました。

Unity 6000.0.0f1
iOS: Added ARM64 Simulator architecture support for iOS and tvOS platforms. (UUM-2238)

Unity 2022.3.54f1
Editor: Added Arm64 Simulator support for iOS/tvOS platforms. (UUM-2238)

シミュレータービルド時に発生するリンクエラー

Showing All Messages
Undefined symbol: static UnityFramework.FrameworkLibAPI.registerAPIforNativeCalls(UnityFramework.NativeCallsProtocol) -> ()
Undefined symbol: type metadata accessor for UnityFramework.FrameworkLibAPI
Undefined symbol: protocol descriptor for UnityFramework.NativeCallsProtocol
Undefined symbol: method descriptor for UnityFramework.NativeCallsProtocol.onChangeIntensityFromUnity(Swift.Float) -> ()
Undefined symbol: method descriptor for UnityFramework.NativeCallsProtocol.registerChangeIntensityDelegate((Swift.Float) -> ()) -> ()
Undefined symbol: method descriptor for UnityFramework.NativeCallsProtocol.onReady() -> ()
Undefined symbol: _OBJC_CLASS_$_UnityFramework
Linker command failed with exit code 1 (use -v to see invocation)

リンクエラーが起きている原因としては、内部的にリンクされている libiPhone-lib というライブラリが以下に示すように実機とシミュレーターで形式が異なっている可能性が挙げられ、さらに言うと後者の方はネイティブプラグイン関連のシンボルを解決することができずにエラーが発生しているものと考えられました。²

実機: libiPhone-lib.a (Static Library)
シミュレーター: libiPhone-lib.dylib (Dynamic Library)

Unity 6.4 から内部構成に変更が入る

改めて Unity 6000.4.0a4 のリリースノートを振り返ると、以下の変更が入っていることがわかります。

Improvements
iOS: Converted iOS, tvOS, and visionOS simulator Unity runtimes to static library framework. Wrapped device static Unity runtime library to framework. Aligned Device and Simulator Unity runtime inclusion in the Xcode project and runtime initialization.
リリースノート: https://unity.com/releases/editor/alpha/6000.4.0a4

【和訳】
iOS：iOS、tvOS、visionOS のシミュレーター向け Unity ランタイムをスタティックライブラリのフレームワークに変更しました。デバイス向けのスタティック Unity ランタイムライブラリをフレームワークとしてラップしました。Xcode プロジェクトおよびランタイムの初期化において、デバイス用とシミュレーター用の Unity ランタイムの導入方法を統一しました。

従来まではシミュレーター向けのライブラリは .dylib 形式であったのに対し、こちらが Static Library Framework に変換された上で、実機向けのライブラリも同様に Framework にラップされるという変更が入っています。

つまり、前回失敗した原因であるダイナミックリンク時のシンボル解決による問題が、スタティックリンクに変わることで解消されている可能性があり、実際に試してみたところ、仮説通りに解消されることが確認できました。

Trampoline ディレクトリの構造比較

例えば従来の形式である Unity 6000.0.63f1 ³ のインストールディレクトリにある /PlaybackEngines/iOSSupport/Trampoline⁴を見ると、以下のように Libraries 以下に関連するライブラリ群が入っていることが確認できます。

Unity 6000.0.63f1 のインストールディレクトリ

/Applications/Unity/Hub/Editor/6000.0.63f1/PlaybackEngines/iOSSupport/Trampoline
├── Classes
├── Info.plist
├── Libraries
│   ├── baselib-dev.a
│   ├── baselib-sim-arm64.a
│   ├── baselib-sim-x64.a
│   ├── baselib-sim-x64arm64.a
│   ├── baselib.a
│   ├── il2cpp-symbols.txt
│   ├── Il2CppOptions.cpp
│   ├── libiPhone-lib-dev.a
│   ├── libiPhone-lib-sim-arm64.dylib
│   ├── libiPhone-lib-sim-x64.dylib
│   ├── libiPhone-lib-sim-x64arm64.dylib
│   ├── libiPhone-lib.a
│   ├── RegisterFeatures.cpp
│   └── RegisterFeatures.h
├── MainApp
├── process_symbols_il2cpp.sh
├── process_symbols.sh
├── Unity-iPhone Tests
├── Unity-iPhone.xcodeproj
└── UnityFramework

一方で、Unity 6000.4.0a4 からは Libraries 以下の内容が変わり、新規で Frameworks というディレクトリが追加されました。
その上で .xcodeproj の Link Binary With Libraries を見ると UnityRuntime.framework がリンクされていることが確認できます。

Unity 6000.4.0a4 のインストールディレクトリ

/Applications/Unity/Hub/Editor/6000.4.0a4/PlaybackEngines/iOSSupport/Trampoline
├── Classes
├── Frameworks
│   ├── UnityRuntime
│   │   └── UnityRuntime.framework
│   ├── UnityRuntime-dev
│   │   └── UnityRuntime.framework
│   ├── UnityRuntime-sim-arm64
│   │   └── UnityRuntime.framework
│   ├── UnityRuntime-sim-x64
│   │   └── UnityRuntime.framework
│   └── UnityRuntime-sim-x64arm64
│       └── UnityRuntime.framework
├── Info.plist
├── Libraries
│   ├── baselib-dev.a
│   ├── baselib-sim-arm64.a
│   ├── baselib-sim-x64.a
│   ├── baselib-sim-x64arm64.a
│   ├── baselib.a
│   ├── Il2CppOptions.cpp
│   ├── RegisterFeatures.cpp
│   └── RegisterFeatures.h
├── MainApp
├── process_symbols_il2cpp.sh
├── process_symbols.sh
├── Unity-iPhone Tests
├── Unity-iPhone.xcodeproj
└── UnityFramework

Unity 6.3 にも同様の変更が入っている

さらに調べると、上記の変更は最近正式リリースされた Unity 6.3 にも同様の変更が入っていることが確認できました。

Unity 6000.3.0f1 のインストールディレクトリ (一部中略)

/Applications/Unity/Hub/Editor/6000.3.0f1/PlaybackEngines/iOSSupport/Trampoline
├── Frameworks
│   ├── libiPhone-lib-sim-arm64
│   │   └── UnityRuntime.framework
│   ├── libiPhone-lib-sim-x64
│   │   └── UnityRuntime.framework
│   └── libiPhone-lib-sim-x64arm64
│       └── UnityRuntime.framework
├── Libraries
│   ├── baselib-dev.a
│   ├── baselib-sim-arm64.a
│   ├── baselib-sim-x64.a
│   ├── baselib-sim-x64arm64.a
│   ├── baselib.a
│   ├── Il2CppOptions.cpp
│   ├── libiPhone-lib-dev.a
│   ├── libiPhone-lib.a
│   ├── RegisterFeatures.cpp
│   └── RegisterFeatures.h
└── ....

ただし、何故かリリースノートや公式ドキュメントのアップグレードガイドには変更が入っている旨が記載されておらず、サイレントに変更が反映されているものとなってそうでした。

とはいえ、一応サンプルプロジェクトのビルドが通ることは確認できたので、記事のタイトルは 6.3 向けとしています。⁵

サンプルプロジェクトについて

今回の調査内容を踏まえて新たにサンプルプロジェクトを作りました。

一応過去記事用のサンプルプロジェクトはあったものの、最後に更新してから時間が経ったので、プロジェクトの整理や x86_64 向けのワークアラウンドの削除などを含めて新規で作り直しています。
(とはいえ、そこまで大きく作りは変わりません)

ちなみに README にも記載してますが、現状 Show Splash Screen を有効にした状態で UaaL として組み込むと正常に動作しない可能性があるので注意。
(こちらについてはバグレポも送っているので、ステータスが変わり次第に更新します)

おわりに

前回記事を書いてから大分経過してしまいましたが、ようやく AppleSilicon でも実機 / シミュレーターの両方で動かすための兆しが見えてきました。

とはいえ、実運用などを含めると見えていない点も多々あるかと思われるので、こういった情報も何か分かり次第に更新していければと思います。

また、もし関連するところで共有できる知見などありましたら、別途記事での解説や、当記事へのコメント・編集リクエストなどを頂けると幸いです

参考リンク

前回記事
- Unity as a LibraryをXCFramework化してiOSの実機とシミュレーターの両方で動かせるようにする
サンプルプロジェクト
- Uaal-Example-iOS-6000
リリースノート
- Unity 6.4 alpha
  - 6000.4.0a4
  - 6000.4.0a5
- Unity 6.3
  - 6000.3.0f1
- Unity 6.0
  - 6000.0.0f1
- Unity 2022 lTS
  - 2022.3.54f1

なので、一応 Rosetta2 経由だと動かすことはできました。 ↩
ひょっとしたらビルド設定の OTHER_LDFLAGS に何かしらの情報を渡せれば上手く行くかもしれませんが、少し粘ってみても上手くいかなかったのと、仮に成功しても黒魔術的で積極採用したくないというのがあったので断念しました。。 ↩
例として Unity 6000.0.63f1 のディレクトリを載せましたが、6000.2.14f1 の方も同様でした。 ↩
Trampoline は恐らくは iOS ビルド時のテンプレートにあたるものかと思われます。(公式情報を見つけられなかったので、間違っていたら教えてください.. ) ↩
恐らくは無いと思いますが、もし今後のバージョンでこっそり変更されて戻っていたら記事のタイトルを更新します... ↩

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up