Skip to content

ScriptableObject Workflow

Everything in the RGS GOAP Framework is authored as a ScriptableObject. This page explains why, how the pieces fit together, and the Slot/Key system that makes actions reusable.

Why ScriptableObjects?

ScriptableObjects (SOs) are Unity assets that live in your Project folder. The framework uses them for all AI configuration because:

  • Shareable — One strategy SO can be used by every agent that needs that behavior. No duplication.
  • Designer-friendly — Non-programmers can create, configure, and wire AI in the Inspector without touching code.
  • Serialized — All configuration survives Play mode, scene changes, and version control.
  • Decoupled — Strategies, sensors, and beliefs don't know about specific agents. They read from the blackboard and operate on capabilities.

Extension Points

The framework provides six extension points. Each is a ScriptableObject you create and configure via the GOAP Hub editor.

Extension Base Class What It Does
Strategy BaseGoapActionStrategy Executes an action's behavior (move, attack, animate)
Post-Process BaseGoapPostProcess Runs after a strategy succeeds (set keys, clear memory, wait)
Sensor GoapSensorSO Reads world state into the blackboard at intervals
Belief GoapBeliefSO Evaluates a blackboard condition for the planner (returns true/false)
Signal SendSignalStrategy<T> Sends typed messages between GameObjects
Score Modifier GoapScoreModifier Adjusts action cost or goal priority dynamically via AnimationCurve

All extensions are created via Unity's Create menu under RGS > GOAP > ....

Tip

Use the [CreateAssetMenu] attribute on your custom strategies, sensors, and beliefs so they appear in the Create menu.

The Brain Hierarchy

A Brain (GoapBrainSO) is the top-level container for an agent's AI. Here's how the pieces nest:

Brain (GoapBrainSO)
├─ Keys (typed blackboard key definitions)
├─ Sensors (what the agent can perceive)
├─ Key Manifest (Slot → Key wiring)
├─ States (GoapBehavioralState[])
│  ├─ State: Patrol
│  │  ├─ Actions (with strategies, preconditions, effects, costs)
│  │  ├─ Goals (with priorities and desired conditions)
│  │  └─ Beliefs (boolean evaluators)
│  ├─ State: Alert
│  │  ├─ Actions
│  │  ├─ Goals
│  │  └─ Beliefs
│  └─ ...
└─ Transitions (belief-driven FSM transitions between states)

Each Behavioral State has its own set of actions, goals, and beliefs. The planner only considers the actions and goals in the current state, keeping the search space small.

Slots and Keys

The Slot/Key system is what makes actions reusable across different agent types.

The Problem

Imagine a "Move To Target" action. A guard agent might store the target position in a key called Key_IntruderPosition, while a pet agent stores it in Key_OwnerPosition. Without abstraction, you'd need two separate action assets — one for each key name.

The Solution: Slots

Slots are abstract key references. An action doesn't reference a specific blackboard key directly. Instead, it references a Slot (e.g., Slot_TargetPosition). The Brain's Key Manifest then wires each slot to a concrete key:

Slot (on the Action) Key (Guard Brain) Key (Pet Brain)
Slot_TargetPosition Key_IntruderPosition Key_OwnerPosition
Slot_IsAtTarget Key_NearIntruder Key_NearOwner

The same "Move To Target" action asset works in both brains — only the Key Manifest wiring differs.

How It Works

  1. Actions reference Slots in their settings (e.g., TargetKeyId points to a Slot).
  2. Sensors declare output Slots via GetOutputs(). Each output is mapped to a blackboard key in the Brain.
  3. The Key Manifest in the Brain maps every Slot to a concrete Key.
  4. At runtime, when a strategy reads settings.TargetKeyId, the framework resolves it to the concrete key via the manifest.

Warning

If a Slot is not wired to a Key in the manifest, the strategy will read default/fallback values from the blackboard. The GOAP Hub's validation system catches unwired slots before you enter Play mode.

Creating Assets

Here's the typical workflow for setting up a new agent's AI:

1. Create Keys

Create > RGS > GOAP > Blackboard > Slot

Keys are typed references (Bool, Float, Vector3, Integer, Object, String) that the blackboard stores. Create one for each piece of data your agent needs.

2. Create Beliefs

Create > RGS > GOAP > Beliefs > {type}

Beliefs are stateless evaluators. Choose from 9 built-in types (Bool Check, Proximity, Health Threshold, etc.) or create custom ones.

3. Create Actions

Actions combine:

  • A Strategy SO that defines the behavior
  • Preconditions — beliefs that must be true to use this action
  • Effects — beliefs that this action makes true
  • A Cost (used by A* to find the cheapest plan)
  • Optional Post-Processes that run after success

4. Create Goals

Goals define:

  • Desired State — conditions the planner tries to satisfy
  • Priority — higher priority goals are preferred
  • Validity Conditions — beliefs that must be true for the goal to be considered
  • Optional Score Modifiers for dynamic priority

5. Create States and Wire the Brain

Group your actions and goals into behavioral states. Add transitions between states driven by beliefs. Open the GOAP Hub to wire everything visually and map Slots to Keys in the Key Manifest.

Key Namespaces

When writing custom extensions, you'll use these namespaces:

using RGS.GOAP.Core;             // GoapAgent, GoapBlackboard, SerializableGuid, GoapActionStatus
using RGS.GOAP.Core.Interfaces;   // IGoapAgentContext, IActionStrategy
using RGS.GOAP.Core.Strategies;   // BaseGoapActionStrategy, BaseStrategySettings, BaseGoapPostProcess
using RGS.GOAP.Core.Burst;        // SerializableGuid
using RGS.GOAP.Core.Tags;         // TagMask128
using RGS.GOAP.Sensors;           // OpticalSensorSO, AuditorySensorSO, SphereSensorSO, WaypointSensorSO

What's Next