/behavior

name: unity-behavior
description: Drive Unity Behavior behavior graphs and blackboard variables

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Wiring NPC/AI decision logic
• Working with behavior trees/graphs
• Reading/writing blackboard variables
• 搭建 NPC/AI 决策逻辑、使用行为树/行为图、读写黑板变量

Behavior Skills

Unity Behavior (`com.unity.behavior`, validated against 1.0.16) graph asset discovery, agent wiring, and blackboard variable access.

The package is **optional** and is not a declared dependency of UnitySkills. Every skill in this module reaches it through reflection; when it is absent each skill returns the same structured `PACKAGE_NOT_INSTALLED` response pointing at `package_install`.

Operating Mode

• Query skills (`behavior_status`, `behavior_graph_list`, `behavior_graph_info`, `behavior_agent_get`, `behavior_agent_list`, `behavior_blackboard_list`) are `SkillMode.SemiAuto` — they run in all three modes without a grant.
• Mutators (`behavior_graph_create`, `behavior_agent_add`, `behavior_agent_set_graph`, `behavior_blackboard_set`) are `SkillMode.FullAuto` — under **Approval** they need a user grant; under **Auto** / **Bypass** they execute directly.
• No skill in this module carries `SkillOperation.Delete`, so none is auto-forbidden in Approval / Auto mode.

Prerequisites

Install the package first if `behavior_status` reports `installed: false`:

package_install  packageName="com.unity.behavior"

Installation triggers a Domain Reload; wait for it to finish, then call `behavior_status` again before using any other skill in this module.

The two asset types (read this before binding graphs)

A "Behavior Graph" `.asset` file contains **two** objects, and mixing them up is the most common failure:

| Object | Role | Where it lives | |--------|------|----------------| | `BehaviorAuthoringGraph` | Editing representation — nodes, blackboard, story. Main asset. | The `.asset` file itself | | `BehaviorGraph` | Baked runtime graph. What `BehaviorGraphAgent.Graph` actually requires. | Sub-asset nested inside the same file |

Skills in this module always take the **file path** (`graphAssetPath` / `assetPath`) and resolve the correct object internally — you never address the sub-asset directly. `behavior_agent_set_graph` finds the nested `BehaviorGraph` for you and refuses the bind with `RUNTIME_GRAPH_MISSING` when the graph has never been compiled.

Guardrails

**Routing**:

• Behavior graphs / blackboards / `BehaviorGraphAgent`: this module
• Animator state machines: use `animator_*`
• Generic component attach on a GameObject: `component_add` works, but `behavior_agent_add` additionally binds the graph and validates it

**Runtime-first rules**:

• Always call `behavior_blackboard_list` before `behavior_blackboard_set` — the variable name is case-sensitive and the declared CLR type decides which value shapes are accepted.
• Never invent a `graphAssetPath` from memory; get it from `behavior_graph_list`.
• If a skill returns `errorCode: "API_MISMATCH"`, the installed package version has a different member layout than this integration expects. Do **not** retry with different arguments — report the version mismatch and fall back to the Behavior editor window or direct `.asset` text editing.
• A graph created by `behavior_graph_create` is empty apart from the auto-inserted `Start` root. Adding actual behavior nodes requires the Behavior editor window (see Limitations).

Skills

`behavior_status`

Report package availability: `installed`, `version`, which core types resolved, project graph asset count, and scene agent count. Safe to call when the package is missing — this is the one skill that answers instead of erroring.

`behavior_graph_list`

List behavior graph assets with `path`, `guid`, `nodeCount`, `variableCount`, and `hasRuntimeGraph`. Optional `filter` (substring on path), `folder`, `limit`.

`behavior_graph_info`

Structure summary for one graph asset: node count with a per-type breakdown, individual nodes (id / type / position, capped by `maxNodes`), root count, the full blackboard variable list with types and default values, subgraph dependencies, and runtime graph state.

`behavior_graph_create`

Create an empty `BehaviorAuthoringGraph` at `savePath` and force a reimport so Unity bakes the blackboard, the runtime `BehaviorGraph` sub-asset, the debug info sub-asset, and the mandatory `Start` root. Returns `hasRuntimeGraph`; a `warning` is returned when baking did not happen and the graph must be opened once in the editor window.

`behavior_agent_add`

Add a `BehaviorGraphAgent` to a GameObject (`name` / `instanceId` / `path`), optionally binding `graphAssetPath` in the same call. The graph is resolved and validated **before** the component is added, so a bad path never leaves a half-configured agent. Idempotent — an existing agent is reused and reported via `componentAdded: false`.

`behavior_agent_get`

Read one agent: bound graph name and asset path, `isInitialised` / `isStarted` / `isRunning`, the graph's blackboard variables, and the agent-level overrides.

`behavior_agent_set_graph`

Bind `graphAssetPath` to an existing agent. Resolves the nested runtime graph and rejects uncompiled graphs.

`behavior_agent_list`

Every `BehaviorGraphAgent` in the loaded scenes with hierarchy path, bound graph, active/enabled flags, and run state. Optional `graphFilter`, `includeInactive`, `limit`.

`behavior_blackboard_list`

List blackboard variables. Pass `graphAssetPath` to read the **asset's** authoring defaults (`source: "asset"`), or a GameObject locator to read an **agent's** graph variables plus its overrides (`source: "agent"`). One of