ZOA AI Framework

IBehaviorNode

interface

The entire runtime contract for a behaviour tree node: three members, so the tree kernel stays engine-free and testable in a plain fixture.

• BehaviorId Id { get; }
• BehaviorState Evaluate(IAiContext context)
• void Reset()

IBehaviorNodeChildren

interface

Opt-in topology accessor implemented by composites and decorators. Inspection surfaces walk tree shape through this rather than reflecting into private fields; a node that does not implement it is a leaf.

• IReadOnlyList<IBehaviorNode> Children { get; }

IAiContext

interface

Everything a node is allowed to see during evaluation: identity, blackboard, current behaviour, frame delta, and this tick's sensor samples.

• string EntityId { get; }
• IAiBlackboard Blackboard { get; }
• BehaviorId CurrentBehavior { get; }
• float DeltaTime { get; }
• IReadOnlyList<AiSensorData> GetSensorData(AiSensorType sensorType)

IAiBlackboard

interface

Typed string-keyed state store shared between nodes for the life of an agent.

• void Set<T>(string key, T value)
• bool TryGet<T>(string key, out T value)
• bool Remove(string key)
• bool Contains(string key)
• IReadOnlyCollection<string> Keys { get; }

IAiService

service

Engine-free registry of agents and their trees. Use it when you want to own tick scheduling yourself rather than letting each AiAgent tick itself.

• void RegisterAgent(string entityId, IBehaviorNode behaviorTree)
• void UnregisterAgent(string entityId)
• void TickAgent(string entityId, float deltaTime)
• void TickAll(float deltaTime)
• BehaviorState GetAgentState(string entityId)
• event AgentStateChangedEventHandler AgentStateChanged
• event BehaviorCompletedEventHandler BehaviorCompleted

BehaviorState

enum

Idle, Running, Success, Failure, Suspended. Composites branch on these; Running keeps a multi-tick action alive across frames.

BehaviorTreeResolver

class

Compiles a BehaviorTreeDefinition asset into a live IBehaviorNode hierarchy. Composites and decorators become real nodes; leaves become DefinitionActionLeaf carrying their archetype id forward.

• static IBehaviorNode Resolve(BehaviorTreeDefinition definition)

BehaviorNodeArchetypeRegistry

class

Static catalogue of every placeable node kind across ten categories. The graph editor builds its toolbox from this and the resolver reads port config from it.

• static IReadOnlyList<BehaviorNodeArchetype> All { get; }
• static IReadOnlyDictionary<BehaviorNodeCategory, IReadOnlyList<BehaviorNodeArchetype>> ByCategory { get; }
• static BehaviorNodeArchetype Get(string id)

BehaviorTreeRegistry

class

Resolves BehaviorTreeDefinition assets by their authored TreeId, so serialised level data can say 'spawn archetype X with tree patroller' without holding an asset reference. Case and whitespace insensitive; duplicates keep the first and log an error.

• static BehaviorTreeRegistry BuildFromCollection(IEnumerable<BehaviorTreeDefinition> trees)
• bool TryGet(string treeId, out BehaviorTreeDefinition tree)
• IReadOnlyList<BehaviorTreeDefinition> All { get; }

AiAgent

component

The runtime agent. Owns health, the blackboard and context, the compiled tree, tick scheduling with phase jitter, damage intake through IDamageReceiver, and corpse configuration on death. Implements IAiSaveable.

• void Initialize(AiAgentConfig config, BehaviorTreeDefinition treeDef, Transform playerTarget, IFoundryEventBus eventBus = null)
• void Tick(float deltaTime)
• void SetTarget(Transform target)
• void SetTacticalConfig(TacticalConfig tactical)
• void SetFrozen(bool frozen)
• void ReceiveAlert(Vector3 alertPosition)
• float Receive(in DamageContext ctx)
• IBehaviorNode BehaviorRoot { get; }
• IAiContext Context { get; }
• BehaviorState LastBehaviorState { get; }
• event Action<AiAgent> OnDeath

IAiDefinitionActionExecutor

interface

The seam between data-only leaf nodes and concrete gameplay. One method takes an archetype id and a parameter map and returns the tick's BehaviorState.

• BehaviorState Execute(string nodeId, string archetypeId, IReadOnlyDictionary<string, string> parameters, IAiContext context)

AiDefinitionActionExecutor

component

The Unity implementation. Holds the locomotion, combat, animation, audio and coordination bridges on the agent and dispatches each archetype id to concrete work against them.

• void Bind(AiAgent agent)
• void ApplyConfig(AiAgentConfig config)
• void ResolveReferences()

AiRuntimeBlackboardKeys

class

The reserved key names the runtime writes and authored trees read. Reach for these constants rather than typing the strings, especially the tactical set.

• TargetTransform, TargetPosition, Health, HealthPercent, AmmoCount
• Alert, AlertPosition, LastHeardPosition, InvestigationPoint, CoverPosition, Faction
• VantagePoint, LosBreakPoint, CoverReservation, CoverAnchorPosition

AiPerceptionSensor

component

Per-agent vision, hearing and proximity sampling with a memory window. Short-circuits itself once the batched perception service takes ownership of the agent.

• void Sample(Transform self, Transform target, IAiContext context)
• void ApplyConfig(AiAgentConfig config)
• void TryRegisterBatchPerception(AiAgent agent)

IAiPerceptionBatchService

service

Scene-wide batched perception. Owns all line-of-sight raycasts through RaycastCommand.ScheduleBatch on pre-allocated buffers, with an adaptive tick rate that falls off as the agent count rises.

• void RegisterAgent(AiAgent agent, AiPerceptionConfig config)
• void UnregisterAgent(AiAgent agent)
• bool IsRegistered(AiAgent agent)
• void Tick(float deltaTime)
• int RegisteredAgentCount { get; }
• int LastBatchSize { get; }
• float CurrentTickInterval { get; }

IPerceptionService

service

Cross-package sighting memory plus stateless cone and audibility checks. Lets mission triggers and squad logic ask what an observer last knew without referencing the sensor that produced it.

• bool CanSee(Transform observer, Transform target, float fovDeg, float range, LayerMask losMask)
• bool CanHear(Vector3 observer, Vector3 source, float radius, float minVolume)
• void RecordSighting(GameObject observer, GameObject target, Vector3 at)
• bool TryGetLastKnown(GameObject observer, GameObject target, out Vector3 position, out float realtimeSeconds)
• void ClearObserver(GameObject observer)

IAiSpawnService

service

Zone-driven spawn coordination. Tick-driven so tests can advance simulated time deterministically; the AiSpawnTickPump drives it in production.

• void RegisterZone(AiSpawnZone zone)
• void ActivateZone(AiSpawnZone zone)
• void DeactivateZone(AiSpawnZone zone)
• void Tick(float deltaTime)
• void DespawnAll()
• IReadOnlyList<AiAgent> ActiveAgents { get; }
• event Action<AiAgent, AiSpawnZone> AgentSpawned
• event Action<AiAgent, AiSpawnZone> AgentKilled

ICoverProvider

service

Reservation-aware cover resolution against CoverPointAnchor components. Called from behaviour tree leaves at up to about 30 Hz across every live agent, so implementations are expected to use a spatial grid rather than a linear scan.

• bool TryRequestCover(Vector3 from, Vector3 awayFromThreat, GameObject agent, out CoverReservation reservation)
• void ReleaseCover(CoverReservation reservation)
• IReadOnlyList<CoverPointAnchor> AllInRadius(Vector3 from, float radius)
• void Tick(float deltaTime)

ITacticalEvaluator

service

Scores standing positions against a target using per-role VantageWeights, and finds the nearest position that breaks line of sight for disengaging.

• VantageScore ScoreVantage(Vector3 candidate, Vector3 target, GameObject fromAgent, in VantageWeights weights, LayerMask losBlockingMask)
• Vector3? FindBestVantage(GameObject agent, Vector3 target, float searchRadius, in VantageWeights weights, LayerMask losBlockingMask)
• Vector3? FindNearestLosBreak(GameObject agent, Vector3 fromTarget, float searchRadius, LayerMask losBlockingMask)

ISuppressionTracker

service

Per-agent near-miss pressure with decay. Crossing the registered threshold flips the suppressed flag and raises an event; immune agents still accumulate pressure but never read as suppressed.

• void RegisterAgent(GameObject agent, float threshold, bool suppressionImmune)
• void RecordNearMiss(GameObject agent, Vector3 origin, float severity)
• float GetPressure(GameObject agent)
• bool IsSuppressed(GameObject agent)
• event Action<SuppressionEvent> SuppressionChanged

TacticalConfig

struct

Per-archetype role tuning serialised inside AiAgentDefinition. Drives vantage weighting, reposition timing, retreat threshold and suppression immunity from one block.

• TacticalRole Role; bool PreferHighGround; float RepositionUnderFireSeconds
• float RetreatHealthThreshold; float SuppressionThreshold; float StealthBias
• bool IsSuppressionImmune { get; }
• VantageWeights ResolveVantageWeights()
• static TacticalConfig DefaultAssault / DefaultSniper / DefaultSupport / DefaultScout / DefaultBoss

AiLocomotionController

component

Movement bridge for the movement archetypes. Prefers NavMeshAgent and falls back to transform movement, and keeps the per-leaf state that makes dynamic patrol and circle-strafe read as continuous motion rather than teleporting between random offsets.

• Vector3 CurrentDestination { get; }
• float CurrentSpeed { get; }

AiCombatController

component

Combat bridge with a distance-based accuracy model: full base accuracy inside the falloff start, linear decay to a floor at the falloff end, plus a muzzle-height line-of-sight check so partial cover blocks shots. Owns ammo and reload timing.

AiWeaponHolder

component

Holds one equipped weapon and exposes range, damage per shot, fire rate and ammo so combat behaviour follows the weapon rather than the agent config. The definition is typed as UnityEngine.Object so the AI package takes no dependency on the weapon package.

AiAnimationBridge

component

Animator bridge with state-edge gating. Every mutator caches its last applied value and skips no-op writes, and triggers carry a cooldown, so a leaf that returns Running for many ticks does not restart the clip from frame zero each time.

AiAudioBinder

component

Plays audio events through AudioEventPlayer and emits a matching stimulus onto AiSoundStimulusBus on every call, so anything an agent does that makes noise is automatically audible to other agents' hearing sensors.

AiFacingController

component

Per-frame idle facing toward the perceived target while the agent is alert and not actively pathing. It sits outside the behaviour tree, because where an agent looks while standing still is not a decision the tree needs to make.

AiSoundStimulusBus

class

Static, short-lived sound channel read by hearing sensors. Stimuli carry position, intensity, radius, expiry and an optional source entity id, and expired entries are pruned in place.

• static void Emit(Vector3 worldPosition, float intensity, float radius, float lifeSeconds = 0.75f, string sourceEntityId = "", string soundId = "")

AiAgentBatchScheduler

component

Scene-level time slicer for crowds. Disables per-agent auto tick and evaluates at most MaxAgentsPerSlice agents per step, rescanning the scene on an interval.

• void RefreshAgents()

BehaviorNodeTracer

class

Opt-in per-node last-state and evaluation-count recorder. Near-zero cost when disabled; the debug HUD enables it while open so it can render tree state without re-evaluating nodes.

• static bool Enabled
• static void Record(IBehaviorNode node, BehaviorState state)
• static void Clear()

AiRagdoll

component

Builds AiHitboxLimb colliders from the humanoid rig for region-targeted damage, and on death disables the animator and raycast-settles the corpse onto the terrain so the death pose lies flush with the ground.

AgentKilledEvent

struct

The canonical kill signal on the event bus, alongside AgentSpawnedEvent and AgentDamagedEvent. Carries the archetype id, an opaque instance discriminator, the position, and optionally the killer and victim GameObjects. Killer is null for unattributed deaths such as environmental damage.

IAiSaveable

interface

Save and restore contract implemented by AiAgent. Captures identity, pose, health and liveness into an AiAgentSaveState; behaviour tree execution state is not captured, and the tree restarts from the root on restore.

• string UniqueId { get; }
• AiAgentSaveState CaptureState()
• void RestoreState(AiAgentSaveState state)

BehaviorTreeDefinition

asset

The authored tree. A TreeId, a description, a root node id, and a flat list of BehaviorNodeData holding archetype id, parameters, child ids and graph position. Created via Assets, Create, ZOA, AI, Behavior Tree Definition.

• string TreeId
• string RootNodeId
• List<BehaviorNodeData> Nodes
• BehaviorNodeData FindNode(string nodeId)

AiAgentDefinition

asset

The archetype. Combat and locomotion stats, tick and sensor intervals, perception ranges, an optional model prefab with animator controller and avatar, the TacticalConfig block, and the death and corpse-loot policy. ToRuntime produces a mutable AiAgentConfig so the asset is never mutated at play time. Created via Assets, Create, ZOA, AI, Agent Definition.

• string AgentTypeId; string BehaviorTreeId
• float MaxHealth, MoveSpeed, AttackRange, DetectionRange, AttackDamage, AttackCooldown
• float TickInterval, SensorTickInterval, VisionRange, VisionFovDegrees, HearingRange, HearingThreshold, WanderRadius
• TacticalConfig Tactical; AiDeathBehaviorMode DeathBehaviorMode; bool AutoBuildRagdollOnDeath
• InventoryDefinition CorpseInventoryDefinition; int CorpseLootRolls; IReadOnlyList<SerializedCorpseLootEntry> CorpseLootPool
• AiAgentConfig ToRuntime()

AiSpawnerDefinition

asset

One spawn rule. A weighted roster of archetype plus tree plus optional prefab, a cadence of initial count, per-tick count and interval, a live cap and a lifetime total, a faction tag stamped on each spawned agent, and an optional respawn delay once every agent from the budget is dead. Created via Assets, Create, Tools, ZOA, AI, Spawner.

• string SpawnerId; IReadOnlyList<RosterEntry> Roster
• int SpawnsPerTick, InitialSpawnCount, MaxAlive, TotalToSpawn; float SpawnInterval
• bool AutoActivate; string FactionTag; float RespawnAfterAllDeadSeconds