Unity Behavior

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:

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 the two is required.

behavior_blackboard_set

Set one variable value.

Provide either the GameObject locator or graphAssetPath; the GameObject wins if both are given.

Returns: target ("agent" or "asset"), variable, type, the normalized value, and a note explaining where the write landed.

Supported value types and accepted input shapes:

Setting an unknown variable returns the available names in availableVariables.