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 提供显示名、分类和可调用成员。角色状态放在角色实例里,不要放在静态配置定义上。完整成员示例见 角色能力章节。
using PoBDS.Runtime;
public sealed class GuardComponent : PoBDSCharacterComponent
{
protected override PoBDSCharacterActor CreateCharacter()
{
return new GuardActor(); // Your PoBDSCharacterActor subclass.
}
}将 GuardComponent 挂到角色对象后,选主节点流或 BDS 配置。CreateCharacter 只创建实例,生命周期注册由组件完成;不要再手动重复注册。
扩展 Action:可运行的生命周期示例
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 页面。
多个角色的帧单步
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 时更新,避免历史与调试绑定到另一轮调用。 |
类型化数据针脚 API
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 转换,自动备份并校验。二进制存储本身不等于加密。