# Core Concepts

***

## Goal Stacks

A **GoalStack** is a prioritized set of conditions the behavior wants to be true. The planner searches for an action sequence that satisfies **all** conditions in the stack simultaneously.

| Property             | Description                                                    |
| -------------------- | -------------------------------------------------------------- |
| **Goal Stack Name**  | Display name shown in the runtime debug view                   |
| **Goals**            | One or more key=value conditions to satisfy                    |
| **Priority**         | Higher values are tried first when multiple stacks exist       |
| **Is Removable**     | If true, the stack is deleted after successful completion      |
| **Is Interruptible** | If true, a state change mid-execution will trigger re-planning |

***

## Actions

Actions are the building blocks the planner assembles into plans. Each action has:

* **Cost** — A\* search weight. Lower-cost actions are preferred. Can be set dynamically via `SetDynamicCost()`.
* **Requirements** — preconditions evaluated against the merged behavior + world state
* **Effects** — `List<Effect>` applied to the behavior's local state on completion
* **World Effects** — `List<WorldEffect>` applied to a WorldStatesManager category on completion
* **Include On Planning** — when unchecked (`IsIncludeOnPlanning = false`), the action is excluded from planning and `ComputeCost` is never called on it. The action remains visible in the Inspector and GOAP Graph Editor (shown grayed-out) for easy toggling without deletion.

***

## Effect Modes

Both **Effects** and **World Effects** support an **EffectMode** field that controls how the value is applied:

| Mode    | Behaviour                                                      | Example                 |
| ------- | -------------------------------------------------------------- | ----------------------- |
| `Set`   | `state[key] = value` — overwrites the existing value (default) | Set `hasBasket = 1`     |
| `Add`   | `state[key] += value` — increments the existing value          | Add `gold += 10`        |
| `Minus` | `state[key] -= value` — decrements the existing value          | Subtract `stamina -= 5` |

Effect modes are applied consistently at **runtime** (action completion) and during **planner simulation** (A\* state transitions), so the planner always sees the same state changes it will produce at runtime.

***

## States

States are `Dictionary<string, float>` — keys are string names, values are floats (use 0/1 for booleans). They are managed by the `States` class which fires an `OnStateChange(changedKey)` event whenever a value actually changes, triggering automatic re-planning.

`States` can be constructed from a `List<Pair>` for convenience:

```csharp
var state = new States(myPairList);
```

This is used internally by `AIBehavior` to reinitialize behavior state when goal sequences repeat (`RepeatGoalStacks = true`).

***

## Relevance Filtering

Each behavior maintains a `_relevantKeys` set — the union of all goal keys and action requirement/effect/world-effect keys. When a state change fires, the behavior only re-plans if the changed key is in this set. Changes to unrelated keys are silently ignored, reducing unnecessary plan searches in busy scenes.

***

## World States Manager

`WorldStatesRegistry` is a static registry holding all world state categories. Multiple behaviors can share and react to the same categories without coupling to each other. Categories are populated from the `EngineData` asset at startup.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/core-concepts.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.