IntentForge — Concepts¶

This document explains the core design decisions and why the plugin is shaped the way it is. If something in the codebase looks surprising, the answer is probably here.

The one rule: the planner does not execute¶

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 (the dispatcher is not the brain)¶

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.

Concretely, whether you author a StateTree, a Behavior Tree, or custom Blueprint AI on top of the Run Intent Forge Action task / dispatcher, observe these rules:

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) - IsCurrentActionStale() / ClearCurrentActionStale() (poll) - 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¶

  Sensors / Perception adapters
            │ write into
            ▼
       FWorldState  ◄── owned by ──┐
            │                       │
            ▼                       │
  UIntentForgePlannerSubsystem  ◄───┤
   pure function: returns FPlan     │
            │                       │
            ▼                       │
  UIntentForgeComponent ────────────┤
   - keeps current plan + step
   - decides when to replan
            │ exposes current action handle
            ▼
  Dispatcher (selected by DispatchMode):
   - UIntentForgeDispatcherSubsystem  (Auto, default)
   - FIntentForgeRunActionTask        (StateTree)
   - UBTTask_RunIntentForgeAction     (BehaviorTree)
   - your code                        (External)
   spawns the right UIntentActionExecutor, ticks, reports terminal
            │
            ▼
        Game world

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.

Facts¶

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

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() (renamed from ForceReplan in v0.34; the old name is a deprecated forwarder) 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 bForceReplan bypass 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¶

Component sets CurrentAction = Plan.Steps[CurrentStepIndex].Action
       │
       ▼
StateTree task notices via GetCurrentAction()
       │
       ▼
Task creates NewObject<UIntentActionExecutor>(Component, Action->ExecutorClass)
       │
       ▼
Executor.EnterAction(OwnerActor, Action->DefaultParams)
       │
       ▼ tick loop
Executor.TickAction(DeltaTime) → Running / Succeeded / Failed
       │
       ▼ terminal
Executor.ExitAction(status)
       │
       ▼
Component.NotifyActionCompleted(status)
       │
       ▼ on Succeeded: apply effects, increment index, fire next step
       ▼ on Failed:    clear plan, force replan next tick

Plan invalidation while a step is running¶

When the component replans and the new plan's first action differs from the current step, it sets an internal stale flag. The StateTree task polls IsCurrentActionStale() once per tick. On a stale signal it calls CancelAction on the live executor, then spawns the new executor inline.

This polling handshake avoids a StateTree-level transition for what should be a local concern.

Performance contract¶

Targets that the design holds itself to. We don't have CI-enforced benchmarks yet, but these are the budgets we won't accept regressions against:

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 ScheduleNextTickReplan() (renamed from the private RequestReplan in v0.34 when the public method took that name). 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¶

IntentForge 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 IntentForge 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 in 0.x.
• 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.