C# API and extension guide
Integrate Actors and update scheduling, implement Actions, and understand the blueprint extension boundary.
Component-to-runtime API boundaries
| API | When to call | Responsibility |
|---|---|---|
| PoBDSCharacterComponent.Initialize() | Unity integration | Create/register the character, initialize the Agent and load configuration. |
| UpdateDecisions(long frame, int deltaMs) | Host decision phase | Update perception and decisions. Disable AutoTick when host-managed. |
| UpdateExecution() | Host execution phase | Advance current graph / Actions. |
| Step(long frame, int deltaMs) | Single-character convenience | Run both phases; do not also auto-tick the same frame. |
| Shutdown() | Host teardown | Shut down the Agent and unregister the character. |
| PoBDSAgent.SetFlowGraph / SetBDSConfig | Custom Agent hosts | Assign configuration after proper Actor/Agent initialization. |
Expose Actor capabilities
Derive from PoBDSActor or PoBDSCharacterActor. PoBDSActorAttr, PoBDSProp and PoBDSMethod describe display names, categories and callable members. Keep mutable state on Actor instances. See Actor capabilities for member examples.
using PoBDS.Runtime;
public sealed class GuardComponent : PoBDSCharacterComponent
{
protected override PoBDSCharacterActor CreateCharacter()
{
return new GuardActor(); // Your PoBDSCharacterActor subclass.
}
}Attach GuardComponent, then assign its root graph or BDS. CreateCharacter constructs the instance; the component owns registration, so do not register it twice.
Implement an Action lifecycle
using PoBDS.Runtime;
[ActionCategory("Game/Time", DisplayName = "Wait milliseconds")]
public sealed class WaitMillisecondsAction : PoBDSAction
{
[ActionParam("Duration in milliseconds")]
public PoBDSVar<int> DurationMs = new PoBDSVar<int>(500);
long end;
public override void OnEnter()
{
end = Runner.SimulationClock.ElapsedMilliseconds +
System.Math.Max(0, DurationMs.GetValue());
}
public override void OnUpdate()
{
if (Runner.SimulationClock.ElapsedMilliseconds >= end) Finish();
}
}After compiling, choose Game / Time / Wait milliseconds. The shared parameter contract binds ActionParam fields automatically; Enter records the deadline, Update reads simulation time, and Finish completes this Action.
Common Action members
| Member | Use |
|---|---|
| Agent / Runner / Context | Protected runtime references supplied by initialization. |
| BindingData / OnBindParams() | Bind inputs before Enter. |
| OnEnter / OnUpdate / OnExit | Enter, update and cleanup. |
| Finish() / Fail() | Explicit completion/failure, not automatic on every Update. |
| OnWriteOutputs() | Write custom outputs consistently with caller storage. |
| EveryFrame | Continuous-update configuration; completion remains explicit. |
Serialize configuration
Use PoBDSDataSerializer.SerializeBDSConfig / DeserializeBDSConfig and SerializeFlowGraph / DeserializeFlowGraph for the common binary/legacy format boundary. BDSAsset and FlowGraphAsset wrap editor resources. Renaming JSON to .bytes bypasses that contract.
Extend blueprint nodes
BlueprintGraphModel, IBlueprintHost and BlueprintCanvasView separate projected configuration from canvas interactions. A new node needs typed pins, inline defaults, categorized spawning, runtime behavior, serialization and trace support. Adding a menu item alone does not implement a usable node.
Shared parameter contract
PoBDSActionParameters caches ActionParam fields and properties. The editor generates controls from the same metadata that runtime binds on activation. Scalars, enums and PoBDSVar inputs share validation; missing required values and incompatible types fail explicitly. Keep OnBindParams for additional validation rather than duplicating ordinary field binding. Each Action page lists real defaults and enum options.
Frame stepping multiple Agents
using (PoBDSDebugger.Instance.BeginFrameBatch())
{
foreach (var agent in agents) agent.UpdateDecisions(frame, 20);
foreach (var agent in agents) agent.UpdateExecution();
}BeginFrameBatch returns a value-type scope. F11 pauses after the batch. Real breakpoints still pause immediately: the host must check pause state and retain its Agent cursor, resuming only unfinished work. Prism Rogue provides a host with persistent phase and cursor state.
Execution / BDS pool API
Access the root AI pool through FlowGraphRunner or BDSRunner.SimulationClock.ExecutionPool. Behavior exit returns runners automatically; application code does not return them manually.
| Member | Purpose |
|---|---|
| Capacity | Idle limit per runner kind; defaults to 32. Zero disables caching; lowering the limit trims immediately. |
| CachedFlows / CachedBds | Current idle flow / BDS counts. |
| CreatedFlows / CreatedBds | Cumulative creations; inspect whether repeated preemption keeps creating runners. |
| Clear() | Release idle caches without stopping active behaviors. |
| FlowGraphRunner.ExecutionLease | Increments on each rent; validate a retained reference against its invocation. |
| BDSRunner.HistoryInstanceId | Changes on each child BDS reuse to distinguish debug and history invocations. |
Typed data-pin API
FlowNodeData.DataPorts stores FlowDataPort declarations: Key, Name, Type, EnumType and IsOutput. FlowDataLinks provides stable port keys, type checks and source resolution. Method results remain local to the current flow instance. Runtime builds binding indexes and reads connected values without scanning the whole graph every frame.
Binary BDS persistence
SerializeBDSConfig and SerializeBDSConfigBinary always write versioned, checksummed PBDS binary. Legacy JSON remains readable. BDSAsset / BDSAbilityAsset use native Unity binary .asset files to preserve GUIDs and asset references. Convert existing native assets with PoBDS → Serialize → Convert BDS Assets to Binary; conversion backs up and validates configuration. Binary storage is not encryption.