跳到主要内容
版本:Next

工厂 NPC 排队:对象池、Token 门控与 StateTree 的分工

「一群 NPC 排队通过一个出入口」看起来是个寻路问题,实际是三件事叠在一起:实体的生命周期(谁存在)、资源的名额(谁能进)、个体的行为(进去以后做什么)。三者混在一个 Actor 的 Tick 里写,规模一上去必然失控。

本文的类名与子系统接口按 UE5 稳定结构描述,具体 API 签名随版本微调;落地时以当前版本的 AIController.h、StateTreeComponent.h、SmartObjectSubsystem.h 为准。

先划清三层职责​

层负责不该负责典型载体
实体层NPC 是否存在、是否可见、是否参与碰撞业务规则对象池 + APawn/ACharacter
名额层谁能进入、进入顺序、超时释放具体行为队列管理器(WorldSubsystem)
行为层进入后做什么、失败怎么办名额分配StateTree / 行为树
交互层停在哪个点、用什么姿势排队顺序SmartObject

分层的判据很简单:把「出入口容量从 1 改成 3」这件事,只应该改动一层。 如果需要改状态树、改 Actor、还要改 UI,说明职责没切开。

实体层:对象池的回收契约​

工厂场景里 NPC 会反复进出视野,SpawnActor / Destroy 的代价(构造、注册组件、GC 压力)远高于复用。池化不难,难的是回收干净:

void UVMPawnPool::Release(APawn* Pawn)
{
if (!IsValid(Pawn)) return;

// 1. 行为层先退出:状态树 Stop,避免异步任务在池里继续跑
if (UStateTreeComponent* ST = Pawn->FindComponentByClass<UStateTreeComponent>())
{
ST->StopLogic(TEXT("PoolRelease"));
}

// 2. 定时器必须清空:残留的 lambda 会捕获已回收的 Pawn
Pawn->GetWorldTimerManager().ClearAllTimersForObject(Pawn);

// 3. 解绑委托:池化对象最隐蔽的泄漏源
Pawn->OnDestroyed.RemoveAll(this);

// 4. 物理与渲染状态复位
Pawn->SetActorEnableCollision(false);
Pawn->SetActorHiddenInGame(true);
Pawn->SetActorTickEnabled(false);
Pawn->SetActorLocation(FVector(0.f, 0.f, -100000.f));

FreeList.Add(Pawn);
}

回收契约要写成清单,并且和 Acquire 一一对应:

Acquire 做的事Release 必须做的事
SetActorHiddenInGame(false)置回 true
绑定 OnDestroyed / 伤害委托RemoveAll
启动 StateTreeStopLogic 并等异步任务结束
SetTimer 做巡逻间隔ClearAllTimersForObject
注册到 AI 感知系统从感知系统注销

漏掉任意一条的症状都不一样(隐形 NPC、幽灵定时器、AI 感知里堆着死引用),但都表现为「跑久了变卡」而不是立刻崩。

名额层:Token 门控​

容量必须由一个唯一权威持有,放在 UWorldSubsystem 里最稳妥——它随关卡创建销毁,不需要网络复制也能在服务端统一裁决。

USTRUCT()
struct FQueueTicket
{
GENERATED_BODY()

UPROPERTY() TWeakObjectPtr<APawn> Pawn;
UPROPERTY() double RequestTime = 0.0;
UPROPERTY() int32 Priority = 0; // 越小越优先,普通 NPC = 100
};

class UVMTrafficGate : public UWorldSubsystem
{
public:
bool TryAcquire(APawn* Pawn, int32 Priority, double Now);
void Release(APawn* Pawn);
void Tick(float DeltaTime); // 由 Subsystem 的 TickFunction 驱动,不依赖某个 Actor

private:
TArray<FQueueTicket> Waiting; // 按 Priority 再按 RequestTime 排序
TSet<TWeakObjectPtr<APawn>> Holding;
int32 Capacity = 3;
};

三个必须显式处理的问题:

问题不处理的后果处理方式
公平性远处的 NPC 永远抢不到,近处的反复插队排序键用 (Priority, RequestTime),不用距离
饥饿高优先级请求持续到来,普通 NPC 等一辈子等待时间超过阈值自动升优先级(aging)
死锁持 token 的 NPC 被销毁/传送/卡住持有超时强制回收 + EndPlay 时主动 Release

死锁是实战里最先出问题的一条。最省事的兜底是在 EndPlay 里无条件释放,再加一个持有超时:

void UVMTrafficGate::Tick(float DeltaTime)
{
const double Now = GetWorld()->GetTimeSeconds();

for (auto It = Holding.CreateIterator(); It; ++It)
{
APawn* Pawn = It->Get();
if (!IsValid(Pawn) || Now - HoldStart.FindRef(*It) > MaxHoldSeconds)
{
ReleaseInternal(*It); // 注意:这里不能调用会再次加锁的公共 Release
It.RemoveCurrent();
}
}
}

行为层:为什么把状态交给 StateTree​

同一个「排队」状态,写进 Tick 里会变成一堆 if (bWaiting && !bArrived && ...);写成行为树,节点顺序本身就在表达逻辑,但改一个分支要重编译资产。StateTree 的价值在两点:状态与转移是数据,以及任务(Task)可以被条件(Condition)门控。

需求Tick 式写法StateTree 写法
新增「缴费」环节加一个 bool 和一个分支加一个 State + Enter/Exit 条件
中途放弃排队到处判断 bCancelled一个全局 Transition 到 Abort
调试当前在做什么打断点看变量运行时高亮当前 State
策划调整顺序改代码改资产

一个够用的状态划分:

关键是**「等待名额」必须是一个独立 State,而不是 Approach 里的循环**。这样超时、优先级提升、放弃都能作为转移条件表达,不需要在移动逻辑里塞标志位。

与 SmartObject 的接缝​

SmartObject 负责「在哪、以什么姿势交互」,不负责「谁先来」。正确的接法:

  1. 名额层拿到名额后,才允许请求 SmartObject
  2. 用 FSmartObjectRequestFilter 限定可用的标签(如 Slot.Queue),避免抢到别人的工位
  3. Claim 成功后持有 FSmartObjectClaimHandle,离开时必须 Release
  4. Claim 失败要回退到名额层释放,否则名额被占着却没人用

第 4 条是最常见的漏写:Claim 失败只是 return,token 永远不释放,几分钟后整个出入口卡死。

失败模式速查​

现象最可能的原因查什么
NPC 挤在门口重叠名额容量与实际物理容量不一致Gate 的 Capacity 与门宽/碰撞半径
排队久了全部静止感知没刷新、Wait 状态没有转移条件StateTree 运行时的当前 State
越跑越卡池化对象没解绑委托、定时器残留Release 是否完整执行
偶发卡死Claim 失败未释放 tokenGate 的 Holding 数量是否等于 Capacity
客户端看到 NPC 瞬移名额裁决在服务端,位置复制频率太低复制频率与预测(见「属性复制与 RPC」)

一句话总结​

实体用池、名额用门、行为用树。 三层的边界清楚了,「容量从 1 改成 3」就只是改一个数字;边界糊了,任何需求变更都会变成同时改五个文件。