PoBDSDocs
简体中文v1.0.0
POBDS / 15

C# API and extension guide

Integrate Actors and update scheduling, implement Actions, and understand the blueprint extension boundary.

Component-to-runtime API boundaries

APIWhen to callResponsibility
PoBDSCharacterComponent.Initialize()Unity integrationCreate/register the character, initialize the Agent and load configuration.
UpdateDecisions(long frame, int deltaMs)Host decision phaseUpdate perception and decisions. Disable AutoTick when host-managed.
UpdateExecution()Host execution phaseAdvance current graph / Actions.
Step(long frame, int deltaMs)Single-character convenienceRun both phases; do not also auto-tick the same frame.
Shutdown()Host teardownShut down the Agent and unregister the character.
PoBDSAgent.SetFlowGraph / SetBDSConfigCustom Agent hostsAssign 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.

C#
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

C#
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

MemberUse
Agent / Runner / ContextProtected runtime references supplied by initialization.
BindingData / OnBindParams()Bind inputs before Enter.
OnEnter / OnUpdate / OnExitEnter, update and cleanup.
Finish() / Fail()Explicit completion/failure, not automatic on every Update.
OnWriteOutputs()Write custom outputs consistently with caller storage.
EveryFrameContinuous-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

C#
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.

MemberPurpose
CapacityIdle limit per runner kind; defaults to 32. Zero disables caching; lowering the limit trims immediately.
CachedFlows / CachedBdsCurrent idle flow / BDS counts.
CreatedFlows / CreatedBdsCumulative creations; inspect whether repeated preemption keeps creating runners.
Clear()Release idle caches without stopping active behaviors.
FlowGraphRunner.ExecutionLeaseIncrements on each rent; validate a retained reference against its invocation.
BDSRunner.HistoryInstanceIdChanges on each child BDS reuse to distinguish debug and history invocations.

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.

Combine keywords with / · Enter opens first result · Esc closes