The one rule

This is the entire product in one sentence. The planner emits an immutable FPlan. It never ticks. It never holds timers. It never queries the world during execution.

The runtime component (UIntentForgeComponent) owns the plan and pops one action at a time. A dispatcher spawns an executor for the current action and ticks it until terminal. When the executor terminates, the component advances or replans.

If you ever find yourself adding Tick() to the planner or having an executor write the world state directly, stop. The boundary is the entire value of the architecture.

The dispatcher abstraction

Execution is who calls EnterAction / TickAction / ExitAction. Intent Forge ships four dispatcher implementations and you pick one per component via UIntentForgeComponent::DispatchMode:

The StateTree task auto-flips DispatchMode to StateTree on enter and restores the previous DispatchMode value on exit (snapshotted into instance data at enter time), so the dispatcher subsystem never fights the task and deliberate External settings aren't clobbered. Same pattern for BT.

The component contract is identical regardless of dispatcher:

1. Read GetCurrentAction() (FActionHandle).
2. Resolve via GetActionByHandle(Handle)->ExecutorClass.
3. NewObject<>(&Component, ExecutorClass); call EnterAction(Owner, Params).
4. Tick until TickAction returns terminal.
5. ExitAction(Status), then Component->NotifyActionCompleted(Status).
6. Recommended: Component->SetActiveExecutor(...) so the Live Inspector can render progress bars.

If you write an External-mode dispatcher, implement that contract and you're indistinguishable from the built-in ones.

The boundary contract

Whichever dispatcher you choose executes one action at a time on the component's behalf. It is not allowed to decide which action to run, which goal to pursue, or whether to replan. Those decisions belong to the planner + component.

If your graph has 30 nodes deciding behaviour, you're back at a Behavior Tree that decides — defeating the point. The Intent Forge model is one task per agent (or simply DispatchMode=Auto to skip the AI runtime entirely); the planner does the decision-making.

Every dispatcher enforces this by exposing only the minimal component handshake:

• GetCurrentAction() (read)
• GetActionByHandle() (read)
• GetPlanGeneration() (poll; cache the value, compare next tick)
• NotifyActionCompleted() (notify, do not influence the next pick)

The component is the only place that calls the planner, and the planner is const. There is no back-channel from execution to planning except the post-completion NotifyActionCompleted callback, which causes a replan but does not influence which action gets chosen.

Layers

The conceptual view above shows the closed loop. The diagram below calls out the actual class boundaries:

Layers depend downward only. You should be able to use the planner without StateTree or BT (via the dispatcher subsystem, or from a custom AI controller) and ship the core without the debug, BT, or executor modules.

The dispatcher slot is the swap point: UIntentForgeDispatcherSubsystem (Auto, default — works with no AI runtime), FIntentForgeRunActionTask (StateTree), UBTTask_RunIntentForgeAction (Behavior Tree), or your own code (External). The component contract is identical regardless.

Facts

A fact is one named slot in the world state. There are three kinds:

The derived-facts layer is where Families 2 (latched bool) and 4 (EMA smoothing) of the anti-flap toolkit live — see Anti-Flap Toolkit.

Fact identifiers are FNames; the UFactSchemaAsset is the source of truth and catches typos at load time. Gameplay Tags are NOT used as facts — they're used as fact identifiers and categories (the naming convention) but the storage is always typed. Mixing the two would muddy ownership.

Rule of thumb: a fact exists only if at least one precondition or effect uses it. Otherwise it's just data the executor can read directly. Six months into a project, a fact catalog with 200 entries is a sign the rule was broken.

Goals, Actions, and Archetypes

• A Goal declares a target world state (the DesiredState array of preconditions) and a scoring policy (a UIntentGoalConsiderationSet).
• An Action declares preconditions, effects, an ExecutorClass, parameter defaults, and an optional UIntentCostStrategy.
• An Archetype bundles a schema + goals + actions. Assign one to an IntentForge component to give an agent its complete behaviour space.

Designers can swap archetypes at runtime to model role changes (peasant → guard). The component resets world state and forces a replan on archetype change.

The planner

A* over symbolic world state.

• State key: hash of the bool bitset + lexically-sorted scalar facts quantized to 0.01. Object facts don't participate.
• Heuristic: count of unsatisfied predicates in the goal's DesiredState. Admissible if minimum action cost ≥ 1.
• Budgets: MaxPlanDepth (12), MaxNodesExpanded (1024), MaxScalarFactsForHash (16). All configurable on UIntentForgePlannerSubsystem.

Goal selection: score every goal, sort by score then priority, skip already-satisfied goals, try PlanForGoal on each in order, return the first non-empty plan. The planner accepts an optional FPlannerHints struct (carrying the previous goal + momentum bonus) — when supplied, the previous goal gets a multiplicative score bonus and wins exact-score ties. Stateless callers (e.g. test code) pass the no-hints Plan(WorldState, Archetype) overload and see vanilla selection.

Replanning policy

The component decides when to replan. Triggers:

1. State changed — WorldState.StateVersion != LastPlannedStateVersion.
2. Forced — RequestReplan() or NotifyActionCompleted(Failed).
3. Safety net — at least ReplanSafetyNetInterval seconds since last replan.

Throttles:

• Coalescing: N ScheduleNextTickReplan calls inside one frame produce exactly one EvaluateReplan on the next tick, via FTimerManager::SetTimerForNextTick. Spammy state writes are free — they only pay for one replan.
• Min-commitment gate: once an action has started, it can't be preempted for MinActionCommitTime seconds unless RequestReplan has set the internal bBypassCommitGate flag.
• Goal momentum: the currently-active goal gets a +GoalMomentumBonus multiplier when scored (one of five anti-flap families. See the Anti-Flap Toolkit). Switching goals must clear the bonus margin.
• Plan reuse: if the new plan's first action matches the current action, the in-flight executor keeps running.

Dispatch chain

The flowchart below maps the same contract to the actual method calls and life-cycle transitions:

Plan invalidation

When the component replans and the new plan's first action differs from the current step, it bumps PlanGeneration (a monotonic int32 — UHT rejects uint32 in BlueprintCallable signatures, so the API uses the signed variant). Each dispatcher task caches the value it last synced against in its per-instance memory and detects invalidation by comparison:

const int32 ComponentGen = Component.GetPlanGeneration();
if (ComponentGen != Memory.LastObservedPlanGeneration)
{
    // Cancel the in-flight executor, spawn the new one
    Memory.LastObservedPlanGeneration = ComponentGen;
}

The counter is idempotent — multiple observers (the StateTree task, BT task, dispatcher subsystem) can each cache independently without a shared "clear" handshake. The pattern mirrors FWorldState::StateVersion.

Performance contract

Targets that the design holds itself to. There's no CI-enforced benchmark gate yet, but these are the budgets that won't accept regressions:

If you exceed any of these in practice, file an issue with a repro.

Event-driven by construction

UIntentForgeComponent does not tick. There is no TickComponent override; bCanEverTick is false. All work is driven by:

• FTimerManager per sensor — each archetype sensor runs on its own loop timer at its declared SampleInterval. Idle sensors do nothing between samples.
• ScheduleNextTickReplan() on state change — every component-level fact setter (SetFactBool, SetFactScalar, SetFactObject, ClearFactObject), every NotifyActionCompleted, and every RequestReplan call routes through the internal ScheduleNextTickReplan(). Requests coalesce via SetTimerForNextTick — N changes in one frame produce one EvaluateReplan next frame.
• Safety-net timer — a single recurring FTimerHandle calls ScheduleNextTickReplan every ReplanSafetyNetInterval seconds. Catches drift that didn't trigger an explicit event (e.g. an external system mutating FWorldState directly without going through the component).

The result: 100 agents standing idle contribute literally zero per-frame work. The only floor cost is the per-sensor timer overhead, which UE batches efficiently at the timer-manager level.

If you ever need to add a tick, the rule is: it must do bounded work in the no-work case, ideally an early-out under a few cycles. Otherwise use a timer or a state-change event.

Debug & diagnostics toolkit

Intent Forge ships an extensive set of debug primitives, layered from quickest-to-use to deepest. Pick the right tier for the problem.

Live inspection (PIE)

Retrospection (after-the-fact)

Profiling

Editor authoring

Programmatic access

If none of the above fits, the registry exposes the raw agent set:

UIntentForgeWorldSubsystem* Registry = UIntentForgeWorldSubsystem::Get(this);
for (UIntentForgeComponent* Agent : Registry->GetAllAgents())
{
    // ... do whatever inspector / overlay / coordination you need
}

The subsystem is the canonical entry point — never iterate actors directly looking for the component.

What Intent Forge isn't

• Not a replacement for StateTree, Behavior Trees, or hand-written controllers. It sits above them.
• Not a multi-agent coordinator. Per-agent planning only.
• Not networked. Server-authoritative is enforceable but no replication patterns ship today.
• Not a utility AI framework. The goal-scoring layer borrows from utility AI, but the planner is the centerpiece.
• Not genre-coupled. Combat, survival, patrol — none of these are baked into the core.