メインコンテンツまでスキップ

2026-10-20 ワールドを Basis に移植する際の注意点

念のため書き添えますが、以下の文章はすべて手書きによるものです。

いくつかの結論は、ワールドの移植作業の一環として AI エージェントが遭遇した挫折から導き出されています。

全般​

  • Basis は異なるレイヤーを使用している可能性がある:
    • レイヤー設定が正しくない RenderTarget カメラでは、アバターやオブジェクトが映らないことがあります。
    • これは RenderTarget カメラ、リフレクションプローブ、ミラー設定、レイキャスト、およびその他の物理システムに影響する可能性があります。
  • 複数のプレイヤーが同じ名前を持つ可能性がある:
    • 表示名は一意ではないため、インデックスとして使用することはできません。
    • 同様に、サーバーが複数クライアントでの参加を許可していることが多いため、複数のプレイヤーが同じ DID キーを持つ可能性があります。
  • プレイヤー名にタグが含まれている可能性がある:
    • プレイヤー名にカスタマイズされたタグが含まれている場合があり、TextMeshPro などのリッチテキストフィールドでの表示が難しくなることがあります。
  • デフォルトでは、Interactable はトリガーではなく、VR コントローラーのグリップ（Grab）で起動する:
    • デフォルトでは、Interactable とのインタラクションにトリガーキーは使用されません。
  • Constraint は自動的に Basis Constraint に変換される:
    • これにより、元の Constraint を参照しているシステムが失敗することがあります。

ゲームプレイへの影響​

  • ジャンプの高さはアバターの身長に比例する:
    • 小さなアバターを使用しているプレイヤーは、固定のワールド空間ジャンプ高さを想定して設計されたプラットフォームを飛び越えられないことがあります。
    • 大きなアバターを使用しているプレイヤーは、固定のワールド空間ジャンプ高さを想定して設計された障害物を飛び越えてしまうことがあります。
  • コライダーはアバターの身長に比例する:
    • 本来なら歩いて渡れるはずの小さな隙間から、小さなアバターのプレイヤーが落下してしまうことがあります。
    • 本来なら落下するはずの割れ目を、大きなアバターのプレイヤーが平然と歩いて渡ってしまうことがあります。

仕様が不明確な点​

  • 1 フレーム内に複数回テレポートすると、テレポート後の位置が不正確になる可能性がある:
    • テレポート直後にプレイヤーの位置を取得しても、テレポート前と同じ値が返されることがあります。
    • この副作用により、2 回目のテレポート後の最終的な位置が正しくなくなる可能性があります。
  • VR プレイヤーの位置が不明確な場合がある:
    • VR プレイヤーの位置を取得しても、ロコモーションコライダーの最下部の位置が反映されないことがあります。
    • 代わりに、アバターのキャリブレーション時の初期プレイエリア位置が反映される場合があり、完全にオフセットしている可能性があります。
  • ローカルプレイヤーのトリガーコライダーが不明確:
    • ローカルプレイヤーが衝突イベントで使用できる信頼性の高いトリガーコライダーを持っているかどうかは不明です。

ビジュアル​

  • URP 対応を謳うシェーダーが、必ずしも Adaptive Probe Volumes をサポートしているとは限らない:
    • Basis はデフォルトで URP と Adaptive Probe Volumes を使用しており、ライトプローブ（Light Probes）は使用されません。
    • URP 対応を謳うシェーダーであっても、Adaptive Probe Volumes をサポートしていない場合があり、その場合は光を正しくサンプリングできません。
  • デフォルトのフォントマテリアルがすべてを透過して表示される:
    • この問題を避けるには、新しいフォントマテリアルを作成し、Text や TextMeshPro コンポーネントに割り当ててください。
  • 面積ゼロの三角形がプローブを壊す可能性がある:
    • ライトプローブを使用する動的オブジェクトが異常に明るくなったり、ワールドに四角いアーティファクトが発生したりする場合、エミッシブマテリアルを持つワールドメッシュに面積ゼロの三角形が存在する可能性があります。
    • これは通常、URP への移行に伴い Bakery ライトマッパーから離れる際に発生することがあります。
  • マテリアルに影響を与える Animator やコードは URP 用に更新する必要がある:
    • URP マテリアルのプロパティは、BIRP 時代のものとは異なるプロパティ名でアニメーションさせたり設定したりする必要がある場合があります。

Cilbox VM​

  • UI ボタンはスクリプトを直接呼び出すのではなく、コールバックを登録すべき:
    • イベントをトリガーするには button.onClick.AddListener(OnEraseAllClicked) を使用してください。
  • テスト済みでない限り、bool 配列の使用は避ける:
    • bool 配列は Cilbox でいくつかのバグを引き起こすようで、現時点では避けるべきです。
    • エラー例：
      • Privilege failed for System.Array.Empty generic argument 0 type
      • CilboxException: Error: Could not find reference to: [mscorlib][System.Array]
  • テスト済みでない限り、Vector4 から Vector3 への暗黙のキャストは避ける:
    • エラー例：
      • AmbiguousMatchException: Ambiguous match found

AI エージェントによる支援​

以下は、AI エージェントを使用して移植を統括しようとする場合にのみ適用されます。

  • 元のコンポーネントからプログラム変数（シリアライズされたフィールド）を最初に抽出する必要があることを AI に伝える:
    • AI による移植では、元のコンポーネント内のプログラム変数が特殊な方法でシリアライズされていることを理解できない場合があります。
    • AI はまず元のコンポーネントに含まれる特殊なシリアライズデータを抽出し、それを移植後の Cilbox コンポーネントに再適用する必要があります。
    • また、AI はシリアライズされた AnimationCurve フィールドのコピーに苦労する場合があるため、AI には AnimationCurve に特に注意を払わせる必要があります。
    • 上記に失敗した場合、AI がフィールドの値を推測しようとするリスクがあり、これは好ましくありません。
      • これが発生した場合は、修復しようとするよりも、前の時点からやり直すべきです。
  • AI はネットワークや Cilbox の問題の自律的なデバッグにおいて非常に有能である:
    • Claude Sonnet および Claude Opus モデル（2026年10月）を使用したところ、ネットワークテストを含む問題を自律的にデバッグできることがわかりました。
    • これらのモデルは、問題が Cilbox 自体のバグ（または Basis 本体のバグ）によって引き起こされていることを認識し、それを回避することも可能です。
    • プレイモードでテストを実行するよう AI に指示する:
      • AI は Cilbox スクリプトをプレイモードで実行し、Cilbox の動作が意図通りであることを確認する必要があります。
      • Cilbox には、プログラムの構造が健全に見えても実行時にのみ明らかになる未知のバグが含まれていることがあります。
    • 実際のサーバー（ローカルホスト）と 2 つのクライアントでネットワークテストを実行するよう AI に指示する:
      • AI はネットワークの挙動が意図通りであることを自律的にテストし、予期しない状況をデバッグできるはずです。
  • AI エージェントで移植を行う際は、AI が一つずつ取り組めるようにタスクの順序付きリストを作成する:
    • 移植を単一の指示として実行すると、AI が指定されていない順序で操作をインターリーブし、その大部分が不完全または不満足な状態になるリスクがあります。
    • また、AI が移植の状態を把握し続けている限り、タスク間でコンテキストをクリアしても構いません。
    • 以下はタスクリストの要約された例です。一部のタスクはさらなるコンテキストで明確にする必要があり、一部はあなたには当てはまらない場合があります：
  • BIRP シェーダーを使用するマテリアルを URP シェーダーに変換する。
    • （シェーダーの URP への変換、特定の URP シェーダーへの移行、または両方の目に描画されるようにカスタムシェーダーが SPS-I をサポートしていることの確認など、追加の指示が必要になる場合があります）
  • Bakery のライトを Unity のライトに変換し、プレハブに含まれるライトも必ず確認する。
  • ライトマッピングの設定を Bakery から Unity GPU ライトマッパーに変換する。
  • 元のものを複製して、Basis Scene コンポーネントをシーンに追加する。
  • 後で使用するためにすべてのプログラム変数を抽出する。
  • 非エディタースクリプトをすべて、以前に抽出したプログラム変数の助けを借りて、可能な限り忠実に Cilbox と Basis に変換する。
    • GetTrackingData のすべての変換に対してユーティリティ関数を作成し、後で頭と手の回転に対する補正をグローバルに適用して、元のすべての呼び出し元に影響を与えられるようにする。
  • オブジェクトプール（プレイヤーごとにスポーンされるオブジェクトのグループ）を特定し、Cilbox での同等機能を考案する。
  • BIRP マテリアルをターゲットにしていた Animator や Cilbox スクリプトのアニメーションを、URP マテリアルの対応するプロパティをターゲットにするように修正する。
  • シーンオブジェクトとスクリプトを Basis Framework のレイヤーを使用するように変換する。
  • フィールドや Cilbox スクリプトの参照を含め、すべての Unity Constraint を Basis Constraint に変換する。
  • Basis のネットワークモデルを最大限に活用するように Cilbox スクリプトを改善する。
    • メッセージパッシングの変装としてオブジェクトの状態転送を使用していた元のスクリプトの箇所を特定し、直接メッセージパッシングを使用するように変更する。

余談ですが、私の環境では、ネットワーク上に予備の Windows ゲーミングデスクトップマシン（モニターなし）を用意し、 メインマシンの操作を妨げることなく Claude Code が接続して必要なタスクを実行できるようにしました。

これらのタスクの多くは人間の介入なしに数時間かかる場合があるため、その間メインの作業マシンは通常通り稼働させておきたいと思うでしょう。