Contents
BONELAB MODの全体像と前提
ここではMOD全体の構成と設計上の注意点、公式情報の確認先を整理します。まずは配布物の役割と必須確認事項を理解してください。
MODの構成要素
MODは通常「コード（DLL）」「アセット（AssetBundle または Addressables）」「メタ情報（manifest/README/CHANGELOG等）」で構成されます。
コードはランタイムロジックを、アセットは見た目や配置データを、メタ情報は互換性や導入手順を担います。
- コード（DLL）：MelonLoader 等のローダーで読み込まれる Mono/.NET アセンブリです。
- アセット：プラットフォーム別にビルドした AssetBundle または Addressables データです。
- メタ情報：配布時に必須となる manifest.json、README、CHANGELOG など。
設計のポイント
設計は「分離」と「明示的依存管理」を優先します。コードとアセットを切り分け、loader／SDKバージョンをmanifestに明記します。
- コードとアセットを独立させる（DLL 単体で動作させて切り分け検証）。
- プラットフォーム別アセットバンドル（Windows / Android(ARM64)）を用意する。
- 依存する SDK／ローダー名と最小バージョンは manifest に記載する。
公式情報の参照先（必ず確認）
SDKやローダー、ツールは更新が頻繁です。配布前に公式ドキュメントとリリースノートを確認してください。代表的な参照先は次の通りです。
- Marrow SDK（公式リポジトリ／リリースを GitHub で検索・参照）: https://github.com/search?q=marrow+sdk+bonelab
- MelonLoader（PC向けローダー）: https://github.com/LavaGang/MelonLoader
- Unity Addressables / BuildPipeline ドキュメント: https://docs.unity3d.com/Manual/AssetBundlesIntro.html 、 https://docs.unity3d.com/ScriptReference/BuildPipeline.BuildAssetBundles.html
- adb（Android CLI）: https://developer.android.com/studio/command-line/adb
- SideQuest（Quest ファイル転送ツール）: https://sidequestvr.com/#/download
- Oculus / Meta 開発者向け情報: https://developer.oculus.com/
- mod.io（配布先の一例）: https://mod.io/
必ず上の公式ページで最新の互換情報を確認してください。
必要ソフトと推奨バージョン一覧
開発に必要な主要ツールと、選定時に確認すべきポイントを示します。バージョンは実際に使う SDK／ローダーの推奨に従って固定してください。
推奨ツールと確認ポイント
各ツールは公式のダウンロード／リリースノートを参照して組み合わせを決めてください。
- Unity：Marrow SDK の推奨バージョンに合わせる。例: Unity 2019.4 LTS または 2020.3 LTS（例示）。Android Build Support と ARM64 対応を必須で有効化すること。
- Visual Studio：2019/2022 を推奨。Class Library は .NET Framework 4.x をターゲットにすることが多い。
- Marrow SDK：配布先のリポジトリ／リリースノートを確認。
- MelonLoader：PC向けローダー。リリースページでゲーム対応状況を確認（https://github.com/LavaGang/MelonLoader/releases）。
- Quest 向けローダ（例: コミュニティの BML 等）：正式名称と公式リポジトリを必ず確認すること。
- その他：adb / SideQuest / Oculus Developer Hub / git / Git LFS / mod.io / Unity Addressables 等。
バージョン運用の注意点
互換性トラブルを避けるため、次を運用ルールにしてください。
- 依存バージョンは manifest.json に明示する（例：loader.min_version）。
- リリースごとに Git タグや GitHub Releases を作成する。
- メジャー／マイナー更新は別ブランチで検証する。
開発環境の構築（Unityプロジェクト作成〜アセンブリ設定）
この章では、Unity プロジェクトの初期設定、SDK導入、.asmdef と Visual Studio 側の DLL 作成手順を実務的に説明します。順序通り実行すると再現性が高まります。
Unityプロジェクト作成とSDK導入
まずは Unity Hub で SDK 推奨バージョンの Unity を用意し、プロジェクトを作成します。以下が実用的な手順です。
- Unity Hub で推奨バージョンをインストールし、新規 3D プロジェクトを作成します。
- Player Settings > Other Settings で「API Compatibility Level」を .NET 4.x に設定します。
- Android（Quest）用に「Android Build Support」、IL2CPP と ARM64 を追加しておきます。
- Marrow SDK を導入する方法は UnityPackage／git サブモジュール／UPM のいずれかです。例（git サブモジュール）:
- git submodule add
Packages/MarrowSDK - サンプルシーンを読み込み、コンソールのエラーがないことを確認します。
- Addressables を使う場合は Window > Asset Management > Addressables > Groups で初期化し、ラベル方針を決めます。
SDK の導入方法はリポジトリ毎に異なるため、必ず公式手順に従ってください。
アセンブリ定義（.asmdef）とVisual StudioのClass Library設定
アセンブリ管理と外部 DLL の取り扱いは互換性で重要です。手順を守ってください。
- Unity 側
- Assets 内にスクリプト用フォルダを作り、右クリック > Create > Assembly Definition で .asmdef を作成します。
- SDK のアセンブリ名（例: Marrow.SDK）を .asmdef の参照に追加します。
-
Editor スクリプトは必ず Editor フォルダに置きます。
-
Visual Studio 側（DLL を外部でビルドする場合）
- Visual Studio で「Class Library (.NET Framework)」プロジェクトを作成し、Target Framework を .NET Framework 4.x（例: 4.7.2）に設定します。
- Unity の UnityEngine.dll 等を参照に追加する。パス例:
- Windows: C:\Program Files\Unity\Hub\Editor\
\Editor\Data\Managed\UnityEngine.dll - または UnityEngine.CoreModule.dll 等、環境によって差があります。
- Windows: C:\Program Files\Unity\Hub\Editor\
- 参照のプロパティで「Copy Local」を false にします（UnityEngine を配布物に含めないため）。
- 出力設定: Any CPU、Release ビルドで ModName.dll を生成します。PDB はデバッグ時に用いるが配布は任意。
- 出力DLLは Unity 側で Plugins/ または Mods フォルダへ置き、Unity Editor 上でコンパイルエラーが出ないことを確認します。
注意点: .NET Standard でビルドすると一部ローダー互換に影響する場合があります。ローダーのドキュメントに従ってターゲットを選んでください。
サンプルチュートリアル：SpawnableまたはカスタムNPCの作成ワークフロー
ここでは最小限の Spawnable を作る具体的手順を示します。コードとAssetBundleの組合せで実機検証まで行えるようにします。
Spawnable作成の手順（概略）
以下は最低限の再現性のある手順です。各工程の細部はプロジェクトに合わせて調整してください。
- Unity でサンプルシーンを開き、既存の Spawnable サンプル Prefab を複製します（サンプルを改変する形で作業）。
- Prefab に MeshRenderer、Collider、Rigidbody を追加し、物理パラメータ（Mass、Drag 等）を実機想定で設定します。
- SDK が提供する Spawnable 相当のコンポーネント（SDKドキュメントに記載のコンポーネント）をアタッチしてプロパティを設定します。
- 軽量な C# スクリプトを作成し、Prefab にアタッチします（下記コード例参照）。
- Prefab を AssetBundle に含めるか、Addressables グループに登録してラベルを付与します。
- AssetBundle を該当プラットフォーム（Windows / Android-ARM64）でビルドします。
C#コード例（MelonLoader 用のエントリと Spawnable の概念例）
まず MelonLoader 用の基本的なエントリ例（PC向け、正確な API 名は MelonLoader ドキュメント参照）:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
// MelonLoader の基本例（PC向け） using MelonLoader; using UnityEngine; public class MyMod : MelonMod { public override void OnApplicationStart() { MelonLogger.Msg("MyMod loaded"); } } |
次に、Spawnable に付ける簡易な MonoBehaviour 例（SDK の具体的な base class や登録API は必ず公式ドキュメントに合わせて置換してください）:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
using UnityEngine; public class SimpleSpawnable : MonoBehaviour { void Awake() { Debug.Log("Spawnable Awake"); } // SDK の Spawn コールバックに合わせて実装すること public void OnSpawn() { GetComponent<Renderer>().material.color = Color.green; } public void OnPickup() { Debug.Log("Picked up"); } } |
注意: Marrow SDK 固有のベースクラス名や登録メソッドはリポジトリの API ドキュメントを参照し、上記の MonoBehaviour を SDK の推奨形式に合わせてラップ／登録してください。
AssetBundle の設定（Inspector での設定）
- Prefab を選択し、Inspector の下部で AssetBundle 名を設定します（例: mymod.spawnables）。
- Addressables を使う場合は Addressables グループに追加し、ラベル名を決めます。
ビルド・パッケージングとPC／Meta Questへの導入手順
ビルド手順と導入例を示します。AssetBundle のビルドスクリプトや manifest、Quest への adb コマンド等の具体例を含みます。
AssetBundle と Addressables のビルド API例
AssetBundle をスクリプトでビルドする基本例です。プラットフォーム切替を行ってからビルドしてください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
// Editor/BuildAssetBundles.cs using UnityEditor; using UnityEngine; public static class AssetBundleBuilder { [MenuItem("Build/Build AssetBundles (Windows & Android)")] public static void BuildAll() { string outWin = "Build/AssetBundles/Windows"; string outAndroid = "Build/AssetBundles/Android_ARM64"; if (!System.IO.Directory.Exists(outWin)) System.IO.Directory.CreateDirectory(outWin); EditorUserBuildSettings.SwitchActiveBuildTarget(BuildTargetGroup.Standalone, BuildTarget.StandaloneWindows64); BuildPipeline.BuildAssetBundles(outWin, BuildAssetBundleOptions.None, BuildTarget.StandaloneWindows64); if (!System.IO.Directory.Exists(outAndroid)) System.IO.Directory.CreateDirectory(outAndroid); EditorUserBuildSettings.SwitchActiveBuildTarget(BuildTargetGroup.Android, BuildTarget.Android); // PlayerSettings > Other Settings で Scripting Backend = IL2CPP、Target Architectures に ARM64 を設定してください BuildPipeline.BuildAssetBundles(outAndroid, BuildAssetBundleOptions.None, BuildTarget.Android); Debug.Log("AssetBundles built."); } } |
Addressables の場合は Unity の Addressables ウィンドウから「Build > Build Player Content」を使うか、Addressables API でビルドします。API 呼び出しはバージョン差があるため公式ドキュメントを参照してください（例: AddressableAssetSettings.BuildPlayerContent() 等）。
公式ドキュメント: https://docs.unity3d.com/Manual/com.unity.addressables.html
manifest.json のテンプレート（配布用）
配布パッケージに含める manifest.json の最小例です。loader 名やバージョンなどは実際の値に置換してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "name": "MySpawnable", "version": "1.0.0", "author": "YourName", "description": "小さな Spawnable のサンプル MOD", "game_versions": { "bonelab": ">=0.3.0" }, "loader": { "name": "MelonLoader", "min_version": "0.5.0" }, "entry_assembly": "MySpawnable.dll", "assets": { "windows": "assetbundles/Windows/mymod", "android_arm64": "assetbundles/Android_ARM64/mymod" }, "dependencies": [] } |
このフォーマットは配布テンプレートの一例です。配布先（mod.io 等）やローダーの仕様に合わせて拡張してください。
PC（Steam）への導入手順（例）
- MelonLoader を公式手順でゲームフォルダに導入する（https://github.com/LavaGang/MelonLoader/releases）。
- Steam のゲームフォルダを開き、Mods フォルダを作成します（例:
/Mods）。 - Mods 内に MySpawnable.dll と manifest.json、assetbundles フォルダを配置します。
- ゲームを起動し、MelonLoader のログやゲームログで DLL が読み込まれているか確認します。
Meta Quest への導入（adb / SideQuest / Oculus Developer Hub）
Quest への導入はデバイス側の開発者モードとローダーの対応が前提です。PC経由での転送とログ取得を強く推奨します。
- 接続例（Wi‑Fi 接続）:
- adb devices
- adb tcpip 5555
- adb connect
- パッケージ名の検索:
- adb shell pm list packages | grep -i bonelab
- ファイル転送（例: ゲームのアプリデータ内に Mods 配置する場合。パスはローダー/ゲームによる）:
- adb push Mods/MySpawnable /sdcard/Android/data/
/files/Mods/MySpawnable - ログ取得（Android/Quest）:
- adb logcat -v time Unity:D *:S > logcat.txt
- 特定タグで絞る場合はタグ名に合わせて変更してください。
SideQuest のファイルマネージャや Oculus Developer Hub のファイル転送機能も利用できます。デバイスの開発者モードを有効にする操作やポリシーに関しては Meta の開発者向けドキュメントを参照ください。
重要な注意: デバイスのサイドローディングや開発者モードはアカウントやサポートポリシーに影響する可能性があります。必ず Meta の規約と BONELAB の EULA を確認し、リスクを理解した上で実行してください。
動作確認・デバッグ・互換性管理・配布（最終チェックリストと対処集）
動作確認とトラブルシュート、配布時の実務的チェックリストをまとめます。典型的なエラーと対応策も列挙します。
ログ取得とデバッグの実務
実機ログとローカルログの両方を確認してください。主な取得手順は次の通りです。
- PC（Windows）のログ:
- Unity ビルドでは Player.log（%USERPROFILE%\AppData\LocalLow\
\ \Player.log 等）を確認する。 - MelonLoader のログはリポジトリの指示に従う（通常はゲームフォルダ内の MelonLoader 関連ファイル）。
- Quest（Android）のログ:
- adb logcat -v time Unity:D *:S > logcat.txt
- 追加で adb logcat で該当プロセスの PID を指定して絞り込むことも有効。
- PDB を用意すれば、Visual Studio でプロセスアタッチしてネイティブ/マネージド両方のデバッグが可能です（PCのみ）。
典型的なエラーと対処法
よくある症状と具体的対応を簡潔にまとめます。
- TypeLoadException / MissingMethodException
- 原因: DLL が異なる SDK／ローダーの型定義にリンクされている。
- 対処: ローダーと SDK のバージョンを合わせて再ビルド、参照の Copy Local を false に設定。
- NullReferenceException（ロード時）
- 原因: AssetBundle が見つからない、ロード順が不適切。
- 対処: パス・ラベルを確認、DLL 単体で起動して切り分け、Addressables の初期化を待つ実装にする。
- 起動直後のクラッシュ
- 原因: ネイティブ依存やローダー不整合。
- 対処: 最小構成（他MOD全外し）で起動、ローダーの互換性を確認、ログのクラッシュスタック追跡。
問題切り分けの基本は「最小構成で動かす」ことです。まずは自分のDLLだけで動くかを確認してください。
互換性管理と運用ルール
運用効率を上げるための方針例です。
- manifest に最小対応バージョン（SDK/Loader）を明記する。
- major/minor ごとにブランチを分けて検証する。
- CI（GitHub Actions 等）で Windows/Android 用の自動ビルドを構築する。
- 配布は ZIP にまとめ、GitHub Releases や mod.io で配布する。
配布テンプレート（README・CHANGELOG の最小構成）
README.md の最小構成例：
- タイトル（MOD名、バージョン）
- 概要（1〜2 文）
- 必要環境（ゲームバージョン、SDK/Loader と最小バージョン）
- インストール手順（PC/Quest 別）
- ファイル一覧（DLL、assetbundles、manifest.json）
- 既知の問題と回避策
- ライセンス（使用素材の権利情報、第三者アセットの扱い）
manifest.json の例は前節参照。CHANGELOG は semver に沿って短く記述してください。
法的注意（配布前に確認すべき点）
配布時は以下を必ず確認してください。
- 他者の著作物（音楽、モデル、テクスチャ）を無断で含めないこと。
- ゲーム本体や有料コンテンツの不正配布は禁止されます。
- オンライン対戦やマルチプレイでのチートにつながる機能は配布しないこと。
- BONELAB の EULA、Meta/Oculus の開発者ポリシーを参照し、違反の有無を確認すること（公式サイト参照）。
違反が疑われる場合、配布プラットフォームやアカウントにペナルティが生じる可能性があります。
まとめ
作業を短く整理します。まずは最小構成で成功させ、段階的に拡張してください。
- コード（DLL）とアセット（AssetBundle/Addressables）を明確に分離すること。
- SDK とローダー（MelonLoader／Quest向けローダ等）のバージョン整合を manifest に明記すること。
- Visual Studio は .NET Framework 4.x でビルドし、UnityEngine を参照しても Copy Local=false にすること。
- AssetBundle はプラットフォーム毎にビルドし、Addressables の場合は Build Player Content を利用すること。
- Quest への導入は PC 経由で adb / SideQuest / Oculus Developer Hub を使い、ログ取得と最小構成の切り分けを行うこと。
- 配布前に BONELAB の EULA、Meta/Oculus ポリシーを確認し、権利関係に問題がないことを確認すること。
最後に：開発中は必ず公式ドキュメントと各ツールのリリースノートを参照し、互換性を確認してからリリースしてください。