企业官网建设流程全解析

“靠近可交互物，按一下键，门开了”——策划文档里这行字，落到 UE5 + GAS 的工程里，通常会裂变成十几个问题：谁来发现这个可交互物，谁来显示提示，提示走 UI 还是走 Actor，按键之后是交互者执行能力还是被交互者执行能力，联机时这个提示该在客户端算还是服务器算，两个玩家同时抢一个箱子怎么办。Lyra 示例工程里的 Interaction 模块，价值不在于它写了多少代码，而在于它把这堆问题切成了几块互不粘连的职责。这篇就围绕 UE5 Lyra 交互系统（Interaction 模块）的架构设计与实现，把它拆到能照着复刻的程度。

这篇适合三类人看：正在用 GAS 做项目、想给角色加一套通用交互框架的开发者；已经抄过 Lyra 但交互提示时灵时不灵的同行；以及想把交互系统从“每个 Actor 写一遍蓝图”升级成“一次实现、处处复用”的团队。我会先讲清楚职责怎么切，再讲清楚数据怎么流，然后给一份可以直接落地的最小实现，最后把扫描频率、网络时序、排序规则这些真正会咬人的细节摊开讲。代码片段基于 Lyra 的 C++ 实现思路，类名和字段名以你手上的引擎版本为准，不同版本之间有小幅调整，但架构没变。

1. 先看清交互系统的需求边界

1.1 交互系统里其实有三个角色，不是一个

绝大多数人第一次做交互，脑子里只有两个东西：玩家和门。于是很自然地写出“玩家进入触发器 → 显示提示 → 按键 → 开门”这条线，所有逻辑塞进门蓝图。这个做法在单机小 Demo 里能跑，一旦项目里出现箱子、NPC 对话、载具上车、机关拉杆，你就会发现门蓝图里的那套逻辑要复制二十遍，而且每份都有细微差别。

Lyra 的处理方式是把这件事拆成三个角色。第一个是交互者（Instigator / Avatar），也就是玩家控制的角色，它负责发现周围有什么能交互、把候选列表整理好、把“当前选中项”告诉 UI、接收按键输入。第二个是交互目标（Interactable Target），也就是门、箱子、NPC，它负责回答一个问题：“在我当前状态下，我能提供哪些交互选项？”注意是“哪些”，不是“能不能”，因为一个目标可能同时提供“开门”和“撬锁”两个选项。第三个是执行者，也就是真正改动游戏状态的那段逻辑，在 Lyra 里它被抽象成一个 GameplayAbility，挂在目标自己身上。

这三个角色分开之后，好处立刻显现：新增一种可交互物，你只需要让它实现接口并给它一个能力，交互者的扫描代码一行都不用改；换一套 UI 皮肤，只需要重新监听消息，扫描逻辑一行都不用改；想让某个交互只在夜晚出现，改目标的能力条件即可。这就是职责切分的价值，也是我认为 Lyra 这个模块最值得学的地方。

1.2 为什么不能用一个 Actor 蓝图硬怼到底

有人会问，我把提示 UI 也放进 Actor，把按键检测也放进 Actor，不也一样能跑？能跑，但代价在后期集中爆发。最典型的问题是提示的显示逻辑会碎掉。假设你有三十种可交互物，每种都在自己身上创建 Widget、自己算距离、自己判断玩家是否看向自己，那么屏幕上同时出现三个提示的时候，谁在上谁在下、谁该被隐藏、玩家按 E 到底触发哪一个，就变成了三十份代码之间的博弈。

第二个问题是输入归属混乱。UE 的输入最终是落到 PlayerController 和 Pawn 上的，让每个可交互物去监听按键，本质上是在跟输入系统对着干，Enhanced Input 的上下文优先级、输入映射、以及 GAS 的 AbilityInputTag 机制全部用不上。

第三个问题是网络。提示文本如果在服务器生成再复制给客户端，会有一帧到几帧的延迟，玩家会看到提示“跳出来”；而如果放在客户端生成，那每个客户端都要知道目标的当前状态，这就要求状态本身是复制的。Lyra 选择的是“客户端本地扫描 + 目标状态从 ASC 读取”的组合，这个选择必须有清晰的职责边界才成立。

1.3 Lyra 给出的切分原则，一句话概括

我把它总结成一句话：交互者是“探测器 + 展示器”，交互目标是“选项提供者”，能力是“状态修改器”，消息总线是“三者之间的唯一通道”。探测器只做碰撞查询和排序，不关心门是木头的还是铁的；选项提供者只回答“我现在能干什么”，不关心谁来干；能力负责改状态，不关心提示长什么样；UI 只订阅消息，不关心数据从哪来。

这个原则带来的一个隐性收益是可测试性。你可以写一个纯逻辑的测试 Actor，让它实现接口、返回固定的选项，然后验证交互者的排序和选中逻辑是否正确，完全不需要摆一个真实的门。也可以单独给门的能力写 GameplayAbility 测试，不需要真的有个玩家跑过去按 E。这种解耦在项目中期会救命。

注意：切分原则不是让你把简单东西做复杂。如果你做的是一次性解谜关卡，两个可交互物，直接写蓝图完全没问题。这套架构的收益随“可交互物种类 × 交互选项数量”增长，种类少的时候它就是过度设计。

2. Interaction 模块的架构拆解

2.1 核心类型清单与它们之间的数据流

先把 Lyra 这套东西涉及的类型摆出来，心里有个地图。核心是一个结构体、一个查询结构、一个接口、一个构建器、一个能力类，外加消息子系统和 UI 控件。

• FInteractionOption：一个“交互选项”，描述“对哪个目标、用哪个能力、显示什么文字、打什么标签”。
• FInteractionQuery：一次查询的上下文，携带交互者和 Avatar，目标可以据此做条件判断。
• IInteractableTarget：可交互目标实现的接口，唯一职责是往构建器里塞选项。
• FInteractionOptionBuilder：收集器，负责把目标产出的选项收进数组，并做基础校验。
• ULyraGameplayAbility_Interact：交互者身上的能力，负责扫描、收集、排序、选中、广播、触发。
• UGameplayMessageSubsystem：消息总线，能力和 UI 之间唯一的通信路径。

数据流是这样的：交互能力激活后，按固定频率做一次球形重叠查询，拿到周围一批 Actor；对每个 Actor（及其组件）判断是否实现了IInteractableTarget；实现了就调用它的GatherInteractionOptions，把FInteractionQuery和构建器传进去；目标在函数里决定要不要加选项、加几个、文字写什么、目标是哪个 ASC 的哪个能力句柄；构建器把选项汇总回能力；能力排序、取第一个作为当前选中项；如果有变化，通过消息总线广播出去；UI 监听到消息，刷新提示；玩家按键，能力拿到当前选中项，去激活目标身上的那个能力。

2.2 FInteractionOption 为什么长这样

这个结构体的字段设计很能说明问题。它大致包含：交互目标 Actor、目标的能力系统组件指针、目标能力的句柄、交互标签、提示文本。五个字段，每一个都对应一个架构决策。

带目标 Actor，是因为 UI 可能需要把提示锚定在目标头上（世界空间 Widget），或者需要高亮目标。带目标 ASC 指针，是因为执行交互时得有地方去激活能力，而能力不在交互者身上，在目标身上。带能力句柄，是为了避免字符串查找或者按类查找，直接用句柄激活，快且准。

带交互标签，是为了排序和分类。Lyra 里交互标签通常挂在Interaction这个根下面，比如主要交互、次要交互，能力在执行时可以用标签做ActivationBlockedTags判断，UI 也可以用标签决定显示哪种按键图标。带提示文本，是因为文本内容只有目标自己知道——“打开木门”和“撬开木门”是同一扇门在不同状态下的两种文案，交互者不该去猜。

USTRUCT(BlueprintType) struct FInteractionOption { GENERATED_BODY() UPROPERTY(BlueprintReadWrite) TObjectPtr<AActor> InteractionTarget = nullptr; UPROPERTY(BlueprintReadWrite) TObjectPtr<UAbilitySystemComponent> TargetAbilitySystemComponent = nullptr; UPROPERTY(BlueprintReadWrite) FGameplayAbilitySpecHandle TargetAbilityHandle; UPROPERTY(BlueprintReadWrite) FGameplayTag InteractionTag; UPROPERTY(BlueprintReadWrite) FText InteractionText; };

这里有个我踩过的坑：别把提示文本做成 FString。项目一旦要出海，FText 是唯一能直接进本地化流水线的类型，中途从 FString 改 FText 会牵连所有 UI 绑定和表格配置。Lyra 从第一天就用 FText，这个细节值得抄。

2.3 扫描与收集：GatherInteractionOptions 的调用链

GatherInteractionOptions是整个模块的核心扩展点。它的签名大概是接收一个const FInteractionQuery&和一个FInteractionOptionBuilder&，返回 void。目标在里面做的事情非常自由：可以什么都不加（表示当前不可交互），可以加一个，也可以加多个。

关键在于条件判断全部下沉到目标。门锁着的时候不加选项，或者加一个“需要钥匙”的禁用选项；NPC 在战斗中不加对话选项；宝箱被开过了就不加。交互者完全不知道这些规则，它只负责把收集到的选项整理出来。这种“目标自治”的设计，让新增交互类型的成本降到最低。

FInteractionOptionBuilder在这里承担了一个容易被忽略的职责：兜底填充目标 Actor。目标在写选项时经常懒得填InteractionTarget，构建器在收选项时如果发现这个字段是空的，就用接口所属的 Actor 补上。同理，如果目标没填 ASC，构建器可以从 Actor 上找。这种“宽容收集、严格使用”的策略，让蓝图侧的接入成本变得很低。

实际实现里还有一个细节值得注意：同一个 Actor 上可能有多个组件都实现了接口。比如一辆车，车身组件提供“上车”，后备箱组件提供“打开后备箱”。扫描时不能只判断 Actor 是否实现接口，要遍历组件、找所有实现者、逐个调用。Lyra 的思路是通过一个辅助函数把 Actor 上的所有IInteractableTarget实现者收集成TScriptInterface数组，再统一处理。

2.4 消息总线：为什么 UI 不该直接引用能力

Lyra 用UGameplayMessageSubsystem来连接能力和 UI，而不是让能力去FindWidget或者让 Widget 去GetAbilitySystemComponent拉数据。这个选择看起来绕，实际解决了一个很现实的问题：UI 的生命周期和角色的生命周期不一致。

角色死亡、重生、切关卡、打开背包，UI 会被销毁重建，但能力对象可能还活着；反过来，UI 已经创建好了，能力还没授予。如果两边直接持有指针，就得处理各种空指针和失效引用。消息总线的好处是：能力只管广播，广播的时候没人在听也无所谓；UI 只管监听，监听的时候没消息来就保持默认状态。两边都不需要知道对方存不存在。

具体到实现，能力在选中项发生变化时广播一条带FInteractionOption的消息，UI 在NativeOnActivated里注册监听、在NativeOnDeactivated里反注册。这里有个顺序问题：一定要在 UI 激活后再注册，如果在构造阶段注册，UI 还没显示就可能收到消息并尝试更新控件，容易出空引用。Lyra 的控件基类提供了一套激活/反激活的钩子，把注册反注册放在这里最稳。

3. 关键实现细节：从扫描到执行的完整链路

3.1 能力的激活时机与定时刷新

交互能力挂在角色身上，通过输入标签触发。它一激活就开始干活：先做一次立刻扫描，然后设置一个定时器，按固定间隔重复扫描。为什么不用 Tick？因为 Tick 每帧执行，而交互提示完全不需要 120Hz 的刷新率，用定时器能把开销压到可控范围，也方便统一调整。

定时器的间隔在 Lyra 里是一个很短的固定值（0.1 秒量级），这个数值的选择逻辑是：玩家的移动速度大概是每秒几百单位，0.1 秒移动几十单位，提示的切换感觉是“跟手”的；如果放到 0.3 秒，快速跑过一排可交互物时，提示会明显滞后，玩家会觉得“按了没反应”。但间隔也不能无限小，因为每次扫描都是一次球形重叠查询，开销随周围碰撞体数量增长。

能力在结束时（比如角色死亡、被眩晕打断）必须清掉定时器，这是最常见的泄漏点。我见过不止一个项目，交互能力被打断后定时器还在跑，角色死了提示还在闪。稳妥做法是在EndAbility里统一清理，并且用一个FTimerHandle成员做判空保护。

void ULyraGameplayAbility_Interact::ActivateAbility(...) { Super::ActivateAbility(...); UpdateInteractableOptions(); if (UWorld* World = GetWorld()) { World->GetTimerManager().SetTimer( UpdateTimerHandle, this, &ThisClass::UpdateInteractableOptions, UpdateInterval, true); } } void ULyraGameplayAbility_Interact::EndAbility(...) { if (UWorld* World = GetWorld()) { World->GetTimerManager().ClearTimer(UpdateTimerHandle); } Super::EndAbility(...); }

3.2 目标筛选、排序与“当前选中项”

扫描拿到一批 Actor 之后，不是全部都能用。第一层过滤是接口实现，第二层是距离和朝向，第三层是可见性。Lyra 的做法偏简单：球形重叠 + 距离排序，谁近选谁。实际项目里我建议补上朝向点积和遮挡检测，否则会出现“玩家背对着门，屏幕中间却提示按 E 开门”这种出戏的情况。

朝向过滤的实现不复杂：拿到目标位置，减掉角色位置，归一化，和角色的前向向量点积，低于阈值（比如 0.3，约 72 度半角）就丢弃。遮挡检测用一条LineTraceSingleByChannel，从摄像机或者角色眼睛位置打到目标，如果中间被墙挡住就丢弃。这两条加起来会多两次查询开销，但只在候选列表非空时执行，实际开销很小。

排序规则我建议做成两级：先按交互标签的优先级分组，主要交互永远排在次要交互前面；组内再按距离升序。这样玩家面对一个既能“开门”又能“撬锁”的目标时，默认选中的永远是主要交互，符合直觉。Lyra 的实现里对选项做了排序并取第一个作为CurrentOption，我在此基础上加了一个“保持选中稳定性”的处理：如果上一帧的选中项还在候选列表里，且距离变化不大，就不要切换，避免玩家跑动时提示在两扇门之间反复横跳。

3.3 真正执行交互：为什么是激活目标的能力

这是 Lyra 设计里最容易被误解的一点。玩家按下交互键，交互能力做的事情不是“自己执行开门逻辑”，而是拿着TargetAbilityHandle去TargetAbilitySystemComponent->TryActivateAbility(...)。也就是说，能力是在门身上跑的，不是在玩家身上跑的。

这个设计的合理性在于状态归属。门是开是关，这个状态属于门；开门消耗一把钥匙，钥匙可能来自玩家，但扣除钥匙这件事应该由门的能力来协调（门知道要扣谁的钥匙，因为交互者信息在上下文里）。如果让玩家的能力去改门的状态，玩家的能力就得知道门的内部实现，耦合就回来了。

但这里有个必须提醒的坑：跨 ASC 激活能力时，句柄的有效性在网络环境下不保证。客户端的 ASC 和服务器端的 ASC，其能力规格数组的索引可能不同，客户端拿到的句柄传给服务器后可能解析到另一个能力，甚至解析失败。Lyra 的示例代码在单机和局域网下能跑，但在真实项目里我建议改成更稳的做法：交互时只发一个 Server RPC，带上“目标 Actor + 交互标签”，由服务器根据标签去目标的 ASC 上查找对应的能力规格，再激活。

// 更稳的写法：服务器按标签解析，不依赖客户端句柄 void UMyInteractAbility::ServerTriggerInteraction_Implementation(AActor* TargetActor, FGameplayTag InteractionTag) { if (!IsValid(TargetActor)) return; UAbilitySystemComponent* TargetASC = UAbilitySystemGlobals::GetAbilitySystemComponentFromActor(TargetActor); if (!TargetASC) return; for (const FGameplayAbilitySpec& Spec : TargetASC->GetActivatableAbilities()) { if (Spec.GetDynamicSpecSourceTags().HasTagExact(InteractionTag)) { TargetASC->TryActivateAbility(Spec.Handle); return; } } }

3.4 输入绑定与 UI 提示刷新

输入这一层，Lyra 用的是 Enhanced Input + AbilityInputTag 的组合。交互能力配置一个输入标签（比如InputTag.Ability.Interact），角色的输入组件把这个标签和具体的 InputAction 关联起来，按下时调用 ASC 的输入按下接口，由 ASC 转发给监听该标签的能力。好处是输入和能力解耦：换按键只改映射，不动能力代码。

UI 这一层，监听消息后要做三件事：有选项时显示提示并设置文本和按键图标，没有选项时隐藏，选项变化时更新。文本直接用FInteractionOption.InteractionText，按键图标可以根据InteractionTag查一张数据表，不同标签配不同的图标。这里有个体验细节：提示的出现和消失最好带一点过渡，直接开关会闪，尤其是快速跑过一排物体的时候。用 CommonUI 的激活动画或者简单的透明度插值都能缓解。

还有一个容易被忽略的点：提示的锚点。屏幕中下方的固定提示适合大多数情况，但如果目标是可拾取的小物件，固定提示玩家不知道指的是哪个。稳妥做法是同时做世界空间的高亮（描边或者图标），固定提示只负责“按什么键”，高亮负责“对谁按”。

4. 手把手复刻：最小可运行交互系统

4.1 工程准备与必备模块

先在工程里确认依赖齐全。你需要 GameplayAbilities、GameplayTags、EnhancedInput、UMG、CommonUI 这几个模块。.Build.cs里加上对应项，别等编译报错再一个个补。

接着把标签规划好。我建议至少四个：Interaction（根标签）、Interaction.Primary、Interaction.Secondary、以及每个具体交互类型的标签，比如Interaction.Primary.Open、Interaction.Primary.Pickup。消息标签单独一个：Message.Interaction.Updated。标签规划看起来是小事，实际决定了后面排序、图标映射、能力查找能不能写干净。

4.2 定义交互接口与选项结构

接口的设计要点是“只暴露必要信息”。GatherInteractionOptions只需要查询上下文和构建器，不需要返回值，不需要知道调用者是谁。为了让蓝图也能实现，用BlueprintNativeEvent或者提供一个蓝图可覆写的事件转发。

UINTERFACE(MinimalAPI, BlueprintType) class UInteractableTarget : public UInterface { GENERATED_BODY() }; class IInteractableTarget { GENERATED_BODY() public: UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "Interaction") void GatherInteractionOptions(const FInteractionQuery& InteractQuery, FInteractionOptionBuilder& OptionBuilder); };

构建器我建议做成一个带引用的轻量类，持有目标接口和外部数组的引用，AddInteractionOption里做三件事：校验目标 Actor 非空（空则用接口所属 Actor 填）、校验能力句柄有效、塞进数组。不要在这个函数里做排序，排序统一放在扫描端做，职责更清楚。

4.3 实现交互扫描能力

扫描能力的骨架就是前面说的：激活时立刻扫一次，然后定时扫。扫描函数里做球形重叠，用OverlapMultiByObjectType或者OverlapMultiByChannel，查询参数里把自身和队友（如果需要）忽略掉。拿到结果后逐个 Actor 找接口，逐个接口调GatherInteractionOptions。

这里有个性能细节值得说：重叠查询的结果数组要复用。每次扫描都新建一个TArray<FOverlapResult>会造成频繁的内存分配，改成成员变量、每次Reset()复用，在一个有几十个角色的场景里能减少可观的 GC 压力和分配开销。这是那种“不写也能跑，写了才知道差别”的优化。

扫描完成后做排序、取当前项、比对上一次的当前项，变了就广播。广播的时候不要广播整个列表，除非 UI 需要显示多个选项；大多数游戏只需要一个“当前交互”，广播单个选项更省事。如果确实要做环形菜单那种多选项 UI，再广播数组。

4.4 实现可交互物与目标的执行能力

以门为例。门 Actor 上挂一个 AbilitySystemComponent（如果门没有其他 GAS 需求，可以用一个极简的 ASC 子类），授一个开门能力。门自己实现IInteractableTarget，在GatherInteractionOptions里判断：如果门已经开着，不加选项或者加一个“关门”选项；如果门锁着且玩家没钥匙，加一个“需要钥匙”的禁用项；否则加“开门”。

开门能力本身做三件事：播放动画、改门的开关状态、把状态复制给客户端。状态改完记得让交互者那边重新扫描或者让门主动通知，否则提示文本可能还停留在“开门”。最简单的做法是能力结束时让交互者刷新一次，或者给门加一个状态变化的事件，交互者在扫描时自然读到新状态。

箱子、NPC 同理。区别只在于能力的内容：箱子是“销毁 Actor + 给玩家加物品”，NPC 是“打开对话 UI”。都是能力，都是挂在目标身上，交互者代码一行不改。

4.5 UI 监听与提示显示

做一个UInteractionPromptWidget，继承UCommonActivatableWidget。在NativeOnActivated里注册消息监听，NativeOnDeactivated里反注册。收到消息后更新文本和图标，没收到就隐藏。

void UInteractionPromptWidget::NativeOnActivated() { Super::NativeOnActivated(); if (UGameplayMessageSubsystem* Bus = UGameplayMessageSubsystem::Get(this)) { ListenerHandle = Bus->RegisterListener<FInteractionOption>( TAG_Message_Interaction_Updated, this, &ThisClass::OnInteractionUpdated); } } void UInteractionPromptWidget::NativeOnDeactivated() { if (UGameplayMessageSubsystem* Bus = UGameplayMessageSubsystem::Get(this)) { Bus->UnregisterListener(ListenerHandle); } Super::NativeOnDeactivated(); }

这类 Widget 建议做成“常驻但可折叠”的，别每次有交互就创建销毁，控件创建在 UI 上的开销比想象中大。常驻之后，显示隐藏只是改可见性，开销可控，动画也更好做。

4.6 网络与联机验证

联机验证清单很短但每一条都要过：客户端能不能看到提示（本地扫描应该在客户端跑）、服务器能不能真正执行（能力必须在服务器有权限）、两个客户端看到的目标状态是否一致（目标 ASC 的状态要复制）、目标被销毁后提示是否及时消失（加有效性检查）。

用 PIE 开两个客户端最快。一个客户端操作，观察另一个客户端看到的世界状态；再观察两个客户端各自的提示是否一致。如果发现只有主机能看到提示，八成是扫描能力被限制在了服务器执行，检查能力的 NetExecutionPolicy。如果发现提示能显示但按了没反应，八成是目标能力没有正确授予或者句柄解析失败，看日志里的能力激活失败原因。

5. 参数、性能与网络：那些文档不写的细节

5.1 扫描半径与刷新频率怎么定

这两个参数直接决定手感。扫描半径的经验值：略大于角色的交互意愿范围。玩家看到门，觉得“我走过去应该能开”，这个距离大概是两三个身位，换算成 UE 单位大约 200 到 350。半径太大，玩家会在离门很远的地方就看到提示，感觉诡异；半径太小，玩家必须贴着门站，操作别扭。

刷新频率的经验值：0.1 秒。低于 0.05 秒意义不大，因为玩家感知不到，反而把开销翻倍；高于 0.2 秒在快速移动时会有明显滞后。如果项目里有大量可交互物，建议做成“半径内没有候选时降频，有候选时升频”的自适应策略，大部分时间角色周围空无一物，没必要一直高频扫描。

5.2 多人环境下的带宽与预测

交互提示是纯客户端表现，不需要复制，这一点必须守住。如果服务器把“当前可交互目标”复制给客户端，每个玩家每 0.1 秒就有一份数据，十几个人的场景下带宽会很可观，而且延迟会导致提示闪烁。

真正需要复制的只有状态：门是开是关、箱子是否被打开、NPC 是否可对话。这些状态放在目标的 ASC 上，用 GameplayEffect 或者复制属性来表达，天然就能同步。客户端扫描时读到的就是本地已复制的状态，提示自然一致。

抢占问题也要考虑。两个玩家同时按 E 开一个箱子，服务器必须只让一个成功。做法是在能力里加一个“占用”标记（GameplayTag 或者复制布尔），激活时先检查再占位，成功后清理。不要指望客户端的判断，客户端只能做提示层面的禁用，最终裁决一定在服务器。

5.3 性能开销与优化清单

交互系统的开销主要来自三块：重叠查询、接口遍历、UI 刷新。按优先级排，优化手段如下。

• 重叠查询改用对象类型过滤，只查Interactable通道的对象，别把整个世界都查一遍。
• 查询结果数组复用，避免每次分配。
• 接口遍历时先判断 Actor 是否实现接口，再遍历组件，避免无谓的组件循环。
• UI 刷新做脏检查，文本和图标没变就不更新控件，UMG 的 SetText 在频繁调用时也会产生开销。
• 能力被打断时清理定时器，避免幽灵扫描。

6. 常见问题排查速查表

6.1 提示完全不出现

按链路顺序排查：能力有没有被授予（看 ASC 的 ActivatableAbilities 列表）、输入标签有没有配对（看输入组件绑定）、能力有没有激活成功（看日志）、扫描有没有命中（加一条 DrawDebugSphere 看范围，加日志看重叠结果数量）、目标有没有实现接口（Implements<UInteractableTarget>()）、GatherInteractionOptions有没有真的加选项、消息有没有广播（监听端加日志）、UI 有没有注册监听（激活顺序问题）。

这条链上任何一环断了都会表现为“没有提示”，所以别凭感觉猜，从前往后一条条打日志，五分钟能定位。

6.2 提示有，但按键没反应

这是第二高频问题。可能性有几个：当前选项的句柄无效（目标能力没授予）、目标 ASC 为空（Actor 没挂 ASC 或者接口里没填）、能力激活被阻塞（ActivationBlockedTags命中了冷却或状态标签）、网络权限问题（客户端发起的激活没到服务器）、输入被 UI 吃掉（有 UI 在焦点上，输入模式没切回 Game）。最后这条特别隐蔽，打开背包后忘了切输入模式，角色就变成“看不见提示也没反应”。

6.3 联机状态不同步

最典型的表现是：A 玩家开了门，B 玩家看到的门还是关的，但 B 走过去按 E 提示“已开门”。这说明提示读的是本地状态，而状态没复制。检查目标 ASC 的复制设置、能力的执行策略（改状态的能力必须能在服务器执行）、以及状态是用属性还是用标签表达的（标签复制需要 ASC 的ReplicationMode配置正确）。

还有一种情况是“B 玩家能开一扇已经开过的门”。这是服务器端缺少二次校验，能力激活时没检查当前状态。记住一条：任何交互能力在服务器激活时，都要重新校验一次前置条件，别信客户端传来的任何状态。

7. 我在这套架构上踩过的几个坑

第一个坑是把交互能力做成了“交互者执行一切”。早期为了省事，让玩家的能力直接改门的状态，结果门的动画、音效、碰撞开关全塞进玩家能力里，玩家能力越来越臃肿，而且 NPC 交互、载具交互的逻辑互相打架。改成目标能力之后，每个交互物自己的逻辑回到自己身上，玩家的能力只剩扫描和触发，清爽太多。

第二个坑是提示文本用 FString，项目做到一半要出海，返工改了三十多个地方。这个教训很直接：文本类型的决定要在一开始做。

第三个坑是扫描频率跟着帧率走。早期用 Tick 扫描，在高端机上 144 帧跑得飞起，在低端机上 30 帧就开始卡顿，因为每帧都在做重叠查询。改成定时器之后曲线平滑了，也顺便解决了“不同机器提示灵敏度不一样”的玄学问题。

第四个坑是忘了清理监听。UI 销毁了但消息监听没反注册，能力一广播就崩。后来统一规定：所有RegisterListener必须成对出现在激活/反激活钩子里，代码评审时专门看这一条。

这套交互系统真正跑顺之后，新增一种可交互物的成本大概是：写一个能力、实现一个接口函数、配一条标签，二十分钟。这个投入产出比，是我愿意在项目早期就把它搭起来的理由。后面要扩展长按交互、交互进度条、条件解锁、多人协作交互，都只是在这个骨架上加东西，不需要推倒重来。