unity-behavior

このモジュールのスキルを呼び出す前に： 名前や説明から推測したパラメーターを指定してスキルを呼び出そうとしている場合は、いったん停止し、先にこのファイルを読むか、GET /skills/recommend?includeSchema=true でスキーマを取得してください。recommend／schema からすでにパラメーター定義を取得している場合は、そのまま dryRun に進めます。

トリガー

• NPC／AI の意思決定ロジックを組み込む
• ビヘイビアツリー／グラフを扱う
• ブラックボード変数を読み書きする
• NPC／AI の意思決定ロジックを構築する、ビヘイビアツリー／ビヘイビアグラフを扱う、ブラックボード変数を読み書きする

Behavior スキル

Unity Behavior（com.unity.behavior、1.0.16 に対して検証済み）のグラフアセット検出、エージェントの接続、ブラックボード変数へのアクセスを行います。

このパッケージは任意であり、UnitySkills の依存関係として宣言されていません。このモジュールの各スキルはリフレクションを通じてパッケージにアクセスします。パッケージが存在しない場合、すべてのスキルは package_install を案内する同じ形式の構造化された PACKAGE_NOT_INSTALLED 応答を返します。

動作モード

• クエリスキル（behavior_status、behavior_graph_list、behavior_graph_info、behavior_agent_get、behavior_agent_list、behavior_blackboard_list）は SkillMode.SemiAuto です。許可を与えなくても、3 つすべてのモードで実行されます。
• 変更スキル（behavior_graph_create、behavior_agent_add、behavior_agent_set_graph、behavior_blackboard_set）は SkillMode.FullAuto です。Approval モードではユーザーの許可が必要ですが、Auto／Bypass モードでは直接実行されます。
• このモジュールには SkillOperation.Delete を持つスキルがないため、Approval／Auto モードで自動的に禁止されるスキルはありません。

前提条件

behavior_status が installed: false を返した場合は、先にパッケージをインストールしてください。

package_install  packageName="com.unity.behavior"

インストールすると Domain Reload が発生します。完了するまで待ってから、このモジュールの他のスキルを使用する前に、もう一度 behavior_status を呼び出してください。

2 種類のアセット（グラフをバインドする前にお読みください）

「Behavior Graph」の .asset ファイルには、オブジェクトが2 つ含まれています。これらを混同することが、最もよくある失敗の原因です。

オブジェクト	役割	場所
BehaviorAuthoringGraph	編集用の表現。ノード、ブラックボード、ストーリーを含みます。メインアセットです。	.asset ファイル自体
BehaviorGraph	ベイク済みのランタイムグラフです。BehaviorGraphAgent.Graph が実際に必要とするものです。	同じファイル内にネストされたサブアセット

このモジュールのスキルには常にファイルパス（graphAssetPath／assetPath）を渡します。適切なオブジェクトは内部で解決されるため、サブアセットを直接指定する必要はありません。behavior_agent_set_graph はネストされた BehaviorGraph を検出し、グラフが一度もコンパイルされていない場合は RUNTIME_GRAPH_MISSING を返してバインドを拒否します。

ガードレール

使い分け：

• ビヘイビアグラフ／ブラックボード／BehaviorGraphAgent：このモジュールを使用します
• Animator ステートマシン：animator_* を使用します
• GameObject への汎用コンポーネントの追加：component_add でも可能ですが、behavior_agent_add はグラフのバインドと検証も行います

ランタイム優先のルール：

• behavior_blackboard_set の前に、必ず behavior_blackboard_list を呼び出してください。変数名では大文字と小文字が区別され、宣言された CLR 型によって受け付ける値の形式が決まります。
• graphAssetPath を記憶から推測して作成しないでください。behavior_graph_list から取得してください。
• スキルが errorCode: "API_MISMATCH" を返した場合、インストールされているパッケージのメンバー構成が、この連携が想定しているものと異なります。引数を変えて再試行しないでください。バージョンの不一致を報告し、Behavior エディターウィンドウまたは .asset のテキストを直接編集する方法に切り替えてください。
• behavior_graph_create で作成したグラフは、自動挿入された Start ルート以外は空です。実際のビヘイビアノードを追加するには、Behavior エディターウィンドウを使用してください（「制限事項」を参照）。

スキル

behavior_status

パッケージの利用可否として、installed、version、解決されたコア型、プロジェクト内のグラフアセット数、シーン内のエージェント数を報告します。パッケージが見つからない場合でも安全に呼び出せます。エラーではなく結果を返す唯一のスキルです。

behavior_graph_list

動作グラフのアセットを、path、guid、nodeCount、variableCount、hasRuntimeGraph とともに一覧表示します。任意の filter（パス内の部分文字列）、folder、limit を指定できます。

behavior_graph_info

1 つのグラフアセットの構造の概要を返します。ノード数と種類ごとの内訳、個々のノード（id / type / position、maxNodes で上限を指定）、ルート数、型とデフォルト値を含むブラックボード変数の完全な一覧、サブグラフの依存関係、ランタイムグラフの状態が含まれます。

behavior_graph_create

savePath に空の BehaviorAuthoringGraph を作成し、強制的に再インポートします。これにより、Unity がブラックボード、ランタイムの BehaviorGraph サブアセット、デバッグ情報サブアセット、必須の Start ルートをベイクします。hasRuntimeGraph を返します。ベイクが行われなかった場合は warning が返され、エディターウィンドウでグラフを一度開く必要があります。

behavior_agent_add

GameObject（name / instanceId / path）に BehaviorGraphAgent を追加します。同じ呼び出しで graphAssetPath をバインドすることもできます。コンポーネントを追加する前にグラフを解決して検証するため、不正なパスが原因で設定途中のエージェントが残ることはありません。冪等性があり、既存のエージェントを再利用した場合は componentAdded: false で報告されます。

behavior_agent_get

1 つのエージェントについて、バインドされたグラフ名とアセットパス、isInitialised / isStarted / isRunning、グラフのブラックボード変数、エージェントレベルのオーバーライドを読み取ります。

behavior_agent_set_graph

既存のエージェントに graphAssetPath をバインドします。ネストされたランタイムグラフを解決し、未コンパイルのグラフは拒否します。

behavior_agent_list

読み込まれたシーン内のすべての BehaviorGraphAgent を、階層パス、バインドされたグラフ、アクティブ／有効フラグ、実行状態とともに一覧表示します。任意の graphFilter、includeInactive、limit を指定できます。

behavior_blackboard_list

ブラックボード変数を一覧表示します。graphAssetPath を指定すると、アセットのオーサリング時のデフォルト値（source: "asset"）を読み取ります。GameObject ロケーターを指定すると、エージェントのグラフ変数とオーバーライド（source: "agent"）を読み取ります。どちらか一方が必須です。

behavior_blackboard_set

1 つの変数値を設定します。

パラメーター	意味
variable	変数名。大文字と小文字を区別します。必須です。
value	新しい値。受け付ける形式は宣言された型によって異なります（下記を参照）。
name / instanceId / path	GameObject ロケーター。エージェントレベルのオーバーライドを書き込みます。
graphAssetPath	グラフアセットのデフォルト値を書き込み、ランタイムブラックボードを再ベイクします。再ベイクの手順に失敗した場合、応答に warning が含まれます。

GameObject ロケーターまたは graphAssetPath のいずれかを指定してください。両方が指定された場合は GameObject が優先されます。

戻り値：target（"agent" または "asset"）、variable、type、正規化された value、書き込み先を説明する note。

サポートされている値の型と受け付ける入力形式：

宣言された型	受け付ける value
int / float / double / bool / string	JSON スカラー値、または解析可能な文字列
enum	メンバー名（大文字と小文字を区別しません）
Vector2 / Vector3 / Vector4 / Quaternion	[1,2,3]、{"x":1,"y":2,"z":3}、または "1,2,3"
Color	{"r":1,"g":0,"b":0,"a":1}、[1,0,0,1]、または "#FF0000"
Vector2Int / Vector3Int	float ベクトルと同じ形式。小数部は切り捨てられます
GameObject / Component	Assets/... のプレハブパス、シーンの階層パス、またはシーンオブジェクト名
その他の UnityEngine.Object	Assets/... または Packages/... のアセットパス

存在しない変数を設定すると、利用可能な名前が availableVariables に返されます。

編集モードと再生モード

BehaviorGraphAgent は Init() 時にグラフのプライベートコピーをインスタンス化します。この処理は再生モードでのみ行われます。そのため、読み取りと書き込みの意味が変わります。

• 編集モード — GameObject を指定した behavior_blackboard_set は、エージェントレベルのオーバーライドを書き込みます（インスペクターに表示される内容とまったく同じです）。グラフ変数の読み取りでは、エージェントごとの値ではなく、共有アセットのデフォルト値が返されます。エージェントごとの値は overrides 配列にあります。
• 再生モード — 書き込みは実行中のグラフインスタンスに反映されるため、そのエージェントにのみ即座に適用されます。

このため、behavior_blackboard_list はエージェントの variables と overrides の両方を報告します。

ワークフロー

1. behavior_status — パッケージがインストールされていることを確認します。
2. behavior_graph_list — グラフを探すか、behavior_graph_create で新しいグラフを作成します。
3. Behavior エディターウィンドウでノードグラフを作成します（ノード編集はスクリプト化できません。「制限事項」を参照してください）。
4. behavior_graph_info — ノードのトポロジーを確認し、ブラックボードの仕様を読み取ります。
5. graphAssetPath を指定して behavior_agent_add を実行し、1 回の呼び出しでアタッチとバインドを行います。
6. behavior_blackboard_list — 変数名と宣言された型を正確に読み取ります。
7. behavior_blackboard_set — エージェントごとのオーバーライドを設定するか、graphAssetPath を指定してグラフ全体のデフォルト値を設定します。
8. behavior_agent_list — シーン全体のエージェントの接続状態を確認します。

制限事項

ノードレベルのグラフ編集はサポートされていません。 ビヘイビアーグラフ内のノードを追加、削除、接続、再設定するスキルはありません。これは見落としではなく、意図的な対象外です。

• 作成用のノードグラフは、[SerializeReference] ポリモーフィックな List<NodeModel> として保存されます。これには PortModel の相互参照、埋め込みの SerializableCommandBuffer、バージョン情報が付与された NodeModelInfo キャッシュが含まれます。正しく書き込むには、フィールドを設定するだけでなく、パッケージのコマンド／ディスパッチャーパイプラインを再現する必要があります。
• 編集するたびに、3 つのサブアセット（ランタイムグラフ、ランタイムブラックボード、デバッグ情報）を一貫性のある状態で再ベイクし、VersionTimestamp を同期する必要があります。そうしないと、アセットとベイク済みランタイムグラフの同期がひそかに失われます。
• シリアル化スキーマには明示的にバージョンが付けられており（kLatestSerializationVersion、現在は 3）、1.0.x 系の中でも変更されています。リフレクションを利用したトポロジーの書き込みは、パッチリリースで動作しなくなる可能性があります。

ノードレベルの変更が必要な場合の代替手段：

1. 推奨 — Behavior エディターウィンドウ（Window > AI > Behavior、またはアセットをダブルクリック）でグラフを作成してから、このモジュールを使って内容を確認し、接続します。
2. 何もない状態からトポロジーを構築する代わりに、asset_duplicate で動作確認済みのグラフを複製し、再バインドします。
3. 既存のグラフに対して機械的で反復的な編集を行う場合は、.asset の YAML を直接編集します。最初に yaml-editing のアドバイザリーを読み、managed-reference と fileID のルールを確認してから、behavior_graph_info で再検証してください。

その他の制限事項：

• behavior_graph_create は空のグラフを作成します。ノードの作成には、引き続きエディターウィンドウが必要です。
• ブラックボード変数の作成、名前の変更、型の変更、削除はできません。割り当て可能なのは既存の変数のみです。変数を追加するには、Behavior エディターの Blackboard パネルを使用してください。
• イベントチャネル、サブグラフの動的リンク、ランタイムのシリアル化（Serialize／Deserialize）は公開されていません。
• graphAssetPath に対する behavior_blackboard_set は、その変数にオーバーライドがないすべてのエージェントに対する共有デフォルト値を変更します。
• エージェントのライフサイクル制御（Init／Start／End／Restart）は公開されていません。これらは再生モード中のランタイム処理であり、ゲームコードから扱うのが適切です。

バージョン依存性

型名とメンバー名は、com.unity.behavior 1.0.16 のソースから取得し、公開されている Scripting API と照合しました。パブリックサーフェス（BehaviorGraphAgent、BehaviorGraph、BlackboardReference、Blackboard、BlackboardVariable、VariableModel）は文書化されており、安定しています。オーサリングサーフェス（BehaviorAuthoringGraph、GraphAsset、BlackboardAsset、BehaviorBlackboardAuthoringAsset）はパッケージの内部にあり、名前でアクセスします。パッケージをアップグレードすると、これらの配置が変わる可能性があります。該当するルックアップはすべて null チェックされ、例外をスローする代わりに API_MISMATCH を報告します。behavior_status には、解決された型が正確に表示されます。

---

正確なシグネチャ

正確な名前、パラメーター、デフォルト値、戻り値は、このファイルではなく、GET /skills/schema または unity_skills.get_skill_schema() で定義されています。