JEV 教程：构建您的第一个实时决策 NPC

_

本教程将介绍一个小的 JEV 集成：NPC 接收一个紧凑的 游戏状态，选择一个可执行动作，并通过普通游戏代码执行该行动。这个例子是故意谦虚的。一个可靠的三行动 NPC 比一个状态、权限和 兜底策略 行为不清楚的大型特工所教导的更多。

API 名称和 SDK 详细信息可能因集成而异。架构合约保持不变：游戏拥有真相，JEV 从合法选项中进行选择，执行者在改变世界之前验证 Choice。

最小的有用集成

game state -> state projection -> JEV decision -> validation -> executor -> game state

game state -> state projection -> JEV decision -> validation -> executor -> game state

在 Unity 中，这些片段可能存在于 MonoBehaviour、游戏服务和命令组件中。在虚幻中，它们可能映射到 Actor 或 Mass 处理器、子系统以及游戏能力或行为树任务。名称不同，但所有权边界应保持明确。

第 1 步：设计紧凑型

{ agentId: 'guard-07', role: 'defender', healthRatio: 0.42, objectiveUnderThreat: true, visibleThreats: 1, ammo: 3, healReady: true, stateVersion: 1842 }

{ agentId: 'guard-07', role: 'defender', healthRatio: 0.42, objectiveUnderThreat: true, visibleThreats: 1, ammo: 3, healReady: true, stateVersion: 1842 }

仅包含允许 NPC 知道的信息。这对于潜行和竞技游戏尤其重要：决策模型不应仅仅因为服务器拥有隐藏的敌人位置而接收它们。

步骤 2：定义 动作应该有稳定的名称、显式参数、前提条件和执行路径。对于示例 NPC，该集合可以是 holdPosition、takeCover、 攻击，和撤退。如果弹药为零，则不应发送attack。如果不存在安全封面，则不应发送 takeCover.

[ { name: 'takeCover', coverId: 'wall-a' }, { name: 'attack', targetId: 'raider-02' }, { name: 'holdPosition', locationId: 'relay' } ]

首先保持较小的动作词汇量。目标不是对每次按钮按下进行编码。目标是公开有意义的战术 Choice 并将低级执行留给引擎。

步骤 3：致电 JEV

请求应包含状态预测、可执行动作、NPC 目标以及决策截止日期或请求标识符。响应应标识所选操作，并可能包括参数、置信度或基本原理字段（如果支持）以及它观察到的状态版本。

const decision = await jev.decide({ agent: npc, gameState: projectState(state), legalActions: buildLegalActions(state), objective: 'Protect the relay', stateVersion: state.version });

不要让迟到的回复盲目适用。当请求正在执行时，世界可能已经发生了变化。将响应的状态版本与当前版本进行比较，然后重新验证所选操作。

步骤 4：执行并验证

执行人为最终决定权。它检查该操作是否存在于当前合法操作集中，其目标是否仍然存在，是否允许 NPC 执行操作，以及状态版本对于该操作来说是否太旧。然后它调用正常的移动、能力或行为树代码。

const action = legalActions.find(candidate => candidate.name === decision.name);
if (!action || !matchesParameters(action, decision)) return fallback(state);
return executor.run(action);

即使服务可信，也应该进行验证。它可以防止陈旧状态、竞争条件、架构漂移和与游戏合约不匹配的意外模型输出。

步骤 5：设置决策频率

根据决策而不是渲染循环选择节奏。基于回合的 NPC 可以在回合开始时做出决定。实时战斗人员可能会决定其当前意图何时完成、威胁何时进入感知，或者按照预算计时器（例如每几百毫秒）决定。避免对同一代理提出重叠请求，除非系统明确支持取消和排序。

使用本地编写的策略来立即做出迫不及待的反应，例如在发生碰撞之前停止或尊重服务器端眩晕。 JEV 应该处理有意义的战术 Choice，而不是每次安全检查.

步骤 6：处理延迟、超时和

每个请求都需要一个截止日期。如果截止日期到期，请将 NPC 保留在安全当前操作中或使用确定性 兜底策略。 兜底策略 可以很简单，例如保持位置、移动到掩体、遵循最后的有效意图或运行编写的行为树。根据角色和情况进行选择。

• _超时： 取消或忽略请求并使用兜底策略.无效操作：
• 记录合约失败，重建状态，并使用安全策略.过时状态： 丢弃结果或仅重新验证剩余的操作安全.服务失败：_降级为本地行为而不阻止游戏循环.重复失败：
• 应用退避和表面遥测而不是重试每个框架._步骤 7：测试决策层
• 记录状态投影、可执行动作、响应、验证结果、执行结果、延迟和 兜底策略 原因。针对生命值低、没有弹药、多重威胁、目标丢失、行动中断和导航不可用等情况构建重播案例。当设计人员可以重播产生意外 Choice. 的确切情况时，决策系统变得更容易平衡对于 Unity 和 Unreal 集成，请保持引擎适配器精简。适配器应将引擎状态转换为 JEV 合约，并将经过验证的操作转换回现有的命令或能力系统。这使得核心决策测试无需加载完整关卡即可运行。
• 生产清单_游戏状态 仅包含相关且允许的信息。每项可执行动作都有先决条件和可以执行的所有者它.根据当前权威状态验证响应。请求有截止日期、取消或过时规则，并且退避.兜底策略 行为是为每个 NPC 角色设计的。重播日志使糟糕的决策可重现。延迟、有效性、操作质量和 兜底策略 速率单独监控。_

有关基本概念，请阅读

什么是JEV？

。有关游戏循环和 NPC 设计上下文，请参阅 JEV 游戏 AI

._

• 游戏状态 contains only relevant and permitted information.
• Every Legal Action has preconditions and an owner that can execute it.
• Responses are validated against current authoritative state.
• Requests have deadlines, cancellation or staleness rules, and backoff.
• Fallback behavior is designed for each NPC role.
• Replay logs make poor decisions reproducible.
• Latency, validity, action quality, and 兜底策略 rate are monitored separately.

For the underlying concept, read What Is JEV?. For the game-loop and NPC design context, see JEV Game AI.