PoBDS文档
Englishv1.0.0
POBDS / 15

C# API 与扩展指南

通过实际接口接入角色、更新调度和自定义 Action,并了解节点扩展需要实现哪些部分。

从组件到执行器的 API 边界

API何时使用职责
PoBDSCharacterComponent.Initialize()Unity 对象接入时创建角色、注册到角色管理器、初始化 Agent,载入所选配置。
UpdateDecisions(long frame, int deltaMs)宿主固定步长的决策阶段更新感知和 BDS 决策。宿主接管时关闭 AutoTick。
UpdateExecution()该帧执行阶段推进当前节点流 / Action。
Step(long frame, int deltaMs)单角色直接推进顺序调用上述决策与执行;不要与 AutoTick 重复使用。
Shutdown()宿主销毁 / 退出时关闭 Agent 并注销角色。
PoBDSAgent.SetFlowGraph / SetBDSConfig自行管理 Agent 的项目指定运行配置;先初始化 Actor 与 Agent 生命周期。

扩展角色:属性与方法

继承 PoBDSActor 或 PoBDSCharacterActor,使用 PoBDSActorAttr、PoBDSProp、PoBDSMethod 提供显示名、分类和可调用成员。角色状态放在角色实例里,不要放在静态配置定义上。完整成员示例见 角色能力章节。

C#
using PoBDS.Runtime;

public sealed class GuardComponent : PoBDSCharacterComponent
{
    protected override PoBDSCharacterActor CreateCharacter()
    {
        return new GuardActor(); // Your PoBDSCharacterActor subclass.
    }
}

将 GuardComponent 挂到角色对象后,选主节点流或 BDS 配置。CreateCharacter 只创建实例,生命周期注册由组件完成;不要再手动重复注册。

扩展 Action:可运行的生命周期示例

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();
    }
}

编译后在 Action 分类菜单选择 Game / Time / Wait milliseconds。DurationMs 的字面量或绑定在 OnBindParams 中读取;OnEnter 建立截止时间,OnUpdate 使用逻辑时钟推进,Finish 表示本 Action 完成。

Action 常用成员

成员用途
Agent / Runner / Context受保护运行引用;系统 Initialize 后提供,不要自行 new 临时 Runner。
BindingData / OnBindParams()读取配置参数;在 Enter 前绑定。
OnEnter / OnUpdate / OnExit进入、持续更新、退出清理。
Finish() / Fail()显式结束或失败;不是每个 OnUpdate 的默认操作。
OnWriteOutputs()实现自定义输出写回;与调用方结果存储保持一致。
EveryFrame持续更新配置;完成逻辑仍由 Action 自己负责。

配置序列化 API

使用 PoBDSDataSerializer 的 SerializeBDSConfig / DeserializeBDSConfig、SerializeFlowGraph / DeserializeFlowGraph 统一处理 PBDS 二进制与旧数据兼容;BDSAsset 和 FlowGraphAsset 提供编辑资源封装。不要在业务代码中另写一套 JSON 改扩展名的导出。

扩展节点与界面

基础蓝图层使用 BlueprintGraphModel、IBlueprintHost、BlueprintCanvasView;业务文档负责投影配置和写回连接,画布负责交互。新增节点时同时定义类型化引脚、默认输入、菜单分类、运行语义、序列化和调试 trace。仅加菜单条目并不等于可运行节点。

统一参数契约

PoBDSActionParameters 缓存 ActionParam 字段和属性,编辑器由同一份元数据生成参数面板,运行时在进入时绑定。支持标量、枚举和 PoBDSVar,必填与类型错误会明确失败。OnBindParams 可保留额外校验,不必重复手写每个常规字段绑定。枚举可选值、真实默认值和参数截图见各 Action 页面。

多个角色的帧单步

C#
using (PoBDSDebugger.Instance.BeginFrameBatch())
{
    foreach (var agent in agents) agent.UpdateDecisions(frame, 20);
    foreach (var agent in agents) agent.UpdateExecution();
}

BeginFrameBatch 返回值类型作用域,不产生作用域对象分配;F11 在整批结束后暂停。真实断点仍会立即停住,宿主需要检查暂停状态并保存角色游标,恢复时只执行未完成部分。Prism Rogue 展示了保留阶段和游标的实际宿主。

Execution / BDS 对象池 API

从 FlowGraphRunner 或 BDSRunner 的 SimulationClock.ExecutionPool 访问当前根 AI 的对象池。行为退出时自动回收,不需要业务代码手动归还。

成员用途
Capacity每类空闲缓存上限,默认 32;设为 0 关闭缓存,缩小时立即裁剪。
CachedFlows / CachedBds当前空闲节点流 / BDS 执行器数量。
CreatedFlows / CreatedBds本池累计创建数,用于判断频繁打断后是否仍在增长。
Clear()释放空闲缓存,活跃行为继续运行。
FlowGraphRunner.ExecutionLease每次从池取出时递增;外部持有执行器引用时校验本次调用身份。
BDSRunner.HistoryInstanceId每次复用子 BDS 时更新,避免历史与调试绑定到另一轮调用。

FlowNodeData.DataPorts 保存 FlowDataPort 声明,包含 Key、Name、Type、EnumType 与 IsOutput。FlowDataLinks 提供稳定端口键、类型检查和数据来源解析。方法返回值在当前节点流实例内保存,不写入角色全局。运行时构建绑定索引后读取连接值,不在每帧扫描整张图。

BDS 二进制保存

SerializeBDSConfig 与 SerializeBDSConfigBinary 始终写入带 PBDS 文件头、版本和校验值的二进制;旧 JSON 仅保留读取兼容。BDSAsset / BDSAbilityAsset 使用 Unity 原生二进制 .asset,以保留 GUID 和资源引用。已有原生资源可用 PoBDS → Serialize → Convert BDS Assets to Binary 转换,自动备份并校验。二进制存储本身不等于加密。

支持多个关键词与 / 路径组合 · Enter 打开第一项 · Esc 关闭