# Overview

**Bee Labs** | Version 1.3

A GC-optimized, inspector-friendly GOAP (Goal-Oriented Action Planning) system for Unity.

***

GOAP Engine lets your AI agents automatically plan and execute sequences of actions to reach their goals — without hand-crafting state machines or behaviour trees. The planner uses **A\* search** to find the cheapest valid action chain from the current world state to the desired goal state.

**Key features:**

* Inspector-based setup — configure goals, actions, and states without writing extra code
* **AIBehavior / AIAgent separation** — `AIBehavior` is the GOAP brain; `AIAgent` is the navigation/movement body. Clean separation of planning logic from pathfinding.
* GC-optimized planner with flat array states, object pooling, and plan caching
* Reactive re-planning triggered by state change events (no polling)
* **Relevance-based re-planning** — only re-plans when the changed state key is relevant to the behavior's goals or actions; unrelated changes are ignored
* Flexible preconditions (`==`, `!=`, `>`, `<`, `>=`, `<=`) on action requirements
* **Effect modes** — effects can `Set`, `Add`, or `Minus` the current state value, both at runtime and during planner simulation
* World state categories shared across multiple behaviors
* **Async (threaded) planning** — `StepPlanAsync()` dispatches the A\* search to a background ThreadPool thread; main thread only snapshots state via `BeginPlan()`; `IsPlanning` property exposes in-flight status
* **Dynamic action costs** — distance-based or context-based costs evaluated before each planning cycle
* **Multi-target navigation** — actions automatically pick the nearest/best target from multiple candidates
* **Automatic resource locking** — binders are locked when claimed during planning and released automatically on action completion or interruption
* **Shared targets** — mark a `TargetBinder` as shared to allow multiple behaviors to target it simultaneously (locking disabled)
* **Target wait timeout** — actions can hold the plan and poll for an available binder before giving up and trying another goal
* **TargetBinder component** — attach to any world object to make it discoverable by specific behaviors and actions
* **Sensor system** — `RangeSensor` and `LineOfSightSensor` components poll the environment at configurable intervals and write directly into `State`, triggering reactive re-planning automatically
* **Premade action library** — eight ready-to-use shooter enemy actions (`PatrolAction`, `ChaseAction`, `FireWeaponAction`, `TakeCoverAction`, `ReloadAction`, `InvestigateAction`, `AlertAction`, `PickUpAction`) with documented extension hooks
* **Character system** — optional `GOAPENGINE_CHARACTER` integration layer: `Character`, `CharacterAbility` base, and plug-in abilities for movement, weapons, pickups, health, input, animation, IK, HUD, navigation, and camera
* **BehaviorPreset ScriptableObject** — shareable behavior configuration with per-behavior runtime overrides
* Action Creator editor window for boilerplate-free action scaffolding
* **DSL expressions** — configure requirements and effects with compact strings like `"health > 50"` or `"ammo -= 1 if playerInSight == 1 and ammo > 0"`
* **Conditional effects** — effects can have multi-condition guards (`And`/`Or`) applied both during planning simulation and at runtime
* **Parametric actions** — a single action class can be configured with multiple named float parameters from the Inspector, eliminating repetitive subclassing
* **Plan ordering** — enforce action ordering with a name DSL (`"UseItem[After]Cover"`, `"Fire[After]Reload(0)(1)"`) with optional seed and trigger values, without any planner changes
* **Goal Evaluator** — supply a custom A\* scoring function via `AIBehavior.GoalEvaluator` to bias planning toward urgency, distance, or any game-specific metric
* **`IncludeOnPlanning` flag** — disable an action from planning without removing it from the Inspector list; shown grayed-out in the GOAP Graph Editor
* **GOAP Graph Editor** — visual graph of the full action/goal/state dependency network; runtime overlay with live state values, play-mode highlighting, undo/redo node moves, and a built-in inspector panel with subclass field support and "Edit Script" shortcut


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://beelabs-dev.gitbook.io/beelabs-docs/goap-engine/goap-engine.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.