FUnityでUI Toolkitが動かない原因はAssembly Definition！エラー解消までの記録【図解付き】

🏁 はじめに

FUnityのUI（block.uxml）を表示しようとしても、
Unityエディター上で何も出ない・スクリプトがMissingになる…
そんなトラブルに悩まされていました。

原因を突き止めたところ、
FUnityパッケージ側にAssembly Definition（アセンブリ定義）を追加していなかったことが原因でした。

この記事では、
なぜそれで解決したのかを、図付きで分かりやすくまとめます。

💥 発生した症状

FUnityのリポジトリ構成は次のようになっています：

FUnity/
 ├── package.json
 ├── Runtime/
 │   ├── UI/
 │   │   └── BlockElement.cs
 │   └── Core/
 ├── UXML/
 │   └── block.uxml
 └── USS/
     └── block.uss

FUnityProject 側ではこのパッケージを参照しています：

FUnityProject/
 ├── Assets/
 │   ├── FUnity/
 │   │   └── FUnityUIInitializer.cs
 └── Packages/
     └── manifest.json

Unityエディターを起動しても…

• 「FUnity UI」オブジェクトの UIDocument に Source Asset（block.uxml）が設定されない
• 「The referenced script (Unknown) on this Behaviour is missing!」
• 「Can't add script component 'FUnityUIInitializer' because the script class cannot be found」

などのエラーが発生していました。

🔍 原因の正体：Assembly Definition が無い！

Unityでは、スクリプトをどのアセンブリ（コンパイル単位）に属させるかを
Assembly Definition (.asmdef) ファイルで管理しています。

🔸 問題点

• FUnityパッケージには package.json はあるが、*.asmdef が存在しない
• そのため、Runtime/UI/BlockElement.cs がどのアセンブリにも属せず、
  Assembly-CSharp.dll にも含まれない
• 結果、FUnityProject側から参照できず、
  UIDocument にUXMLやスクリプトが紐づかない

⚙️ 解決策：FUnity.Runtime.asmdef を追加！

① Runtimeフォルダで右クリック → 「Create > Assembly Definition」

② ファイル名を「FUnity.Runtime」に変更

③ Inspectorで Namespace を設定（任意）

④ JSON構造の中身は次のようになります👇

{
  "name": "FUnity.Runtime",
  "rootNamespace": "FUnity",
  "references": [],
  "optionalUnityReferences": [],
  "includePlatforms": [],
  "excludePlatforms": [],
  "allowUnsafeCode": false,
  "overrideReferences": false,
  "precompiledReferences": [],
  "autoReferenced": true,
  "defineConstraints": [],
  "noEngineReferences": false
}

🔁 再インポート後の変化！

Unityエディターを再起動すると…

• ✅ FUnity.UI.BlockElement が正しく認識される
• ✅ block.uxml が UI Document の Source Asset に自動で設定
• ✅ [UxmlElement] 属性も正しく機能
• ✅ FUnityUIInitializer が正常にアタッチ可能に！

🎉 ついに block.uxml がエディター上に表示されました！

🧠 仕組みの解説

Unityのアセンブリ分離構造：

FUnityProject から FUnity.Runtime にあるクラスを参照するには、
アセンブリ参照を明示的に設定する必要があります。

🧩 参照関係の図解

+---------------------+
| FUnityProject       |
|  (Assembly-CSharp)  |
|     ↓               |
| [参照設定あり]      |
+---------------------+
          │
          ▼
+---------------------+
| FUnity.Runtime      |
|  (BlockElement.cs)  |
+---------------------+

この設定によって、
UIDocument がパッケージ内の VisualTreeAsset と BlockElement を
正しくリンクできるようになります。

✅ まとめ

💬 感想

このトラブルを通して改めて感じたのは、

「Unityパッケージ開発では asmdef が必須」
ということです。

特に、FUnityのように
「パッケージを別リポジトリで開発して、Unityプロジェクトから参照する構成」では、
asmdefが無いと確実に依存関係が崩れます。

🧱 今後の展開

今後は、

• FUnity.Runtime.asmdef（ランタイム側）
• FUnity.Editor.asmdef（エディタ拡張側）

の2つを明確に分けて、
よりモジュール化された構成にしていく予定です。

🪄 次回予告

次回は、
FUnityManager（キャラクターやステージを管理する基盤） を設計します。
Scratchの「緑の旗」ボタンをUnityで再現していきます！