游戏 AI / 系统课时
把游戏 API 接到动作执行器
把游戏 API 接到动作执行器
GOAP 动作本身只描述“想做什么”,真正让 NPC 移动、交互、攻击或拾取的代码通常已经存在于游戏系统中。本篇建立一层动作执行器,把规划动作映射到稳定的游戏 API,并在执行完成后把新的世界状态反馈给规划系统。
学习目标
- 设计 GOAP 动作与游戏 API 之间的适配边界
- 用统一执行器映射移动、交互、攻击和拾取动作
- 让执行结果能够驱动后续状态更新与重新规划
为什么不要让 GOAP 直接调用底层对象
如果规划器直接操作角色控制器、武器组件和物品对象,规划逻辑会迅速绑定具体引擎实现。更稳定的方式是增加 Action Executor:规划器只产生动作名和参数,执行器负责调用已有游戏 API,并把成功、失败和完成事件转换成规划器能理解的结果。

设计动作执行接口
执行器至少需要三个输入:动作类型、动作参数和当前运行上下文。输出则统一成 started、running、succeeded、failed 等结果。这样不同游戏 API 即使返回值完全不同,也能被转换成统一的 GOAP 执行语义。
例如,规划器产生 move_to 时只需要提供目标位置;执行器调用移动系统并持续等待到达条件。attack 可以传入目标 ID 和技能 ID;pickup 则传入物品 ID。规划器不需要知道底层对象是组件、Actor 还是实体。
下面是一个可独立运行的 Python 片段示例,用字典模拟已有游戏 API,重点演示“动作 → API → 统一结果”的适配方式。
from dataclasses import dataclass
@dataclass(frozen=True)
class ActionRequest:
name: str
params: dict
class GameApi:
def move_to(self, position: tuple[int, int]) -> bool:
return position == (10, 5)
def attack(self, target_id: str) -> bool:
return target_id == "enemy-01"
def pickup(self, item_id: str) -> bool:
return item_id == "potion-01"
class ActionExecutor:
def __init__(self, api: GameApi) -> None:
self.api = api
def execute(self, request: ActionRequest) -> str:
if request.name == "move_to":
ok = self.api.move_to(request.params["position"])
elif request.name == "attack":
ok = self.api.attack(request.params["target_id"])
elif request.name == "pickup":
ok = self.api.pickup(request.params["item_id"])
else:
return "failed:unknown_action"
return "succeeded" if ok else "failed:game_api"
executor = ActionExecutor(GameApi())
print(executor.execute(ActionRequest("move_to", {"position": (10, 5)})))
print(executor.execute(ActionRequest("attack", {"target_id": "enemy-01"})))
print(executor.execute(ActionRequest("pickup", {"item_id": "missing"})))预期输出
succeeded
succeeded
failed:game_api真实项目中,GameApi 应该替换成已有移动、战斗、交互和背包服务。执行器不应复制这些系统的业务规则,而应该负责适配参数、处理生命周期和统一结果。
处理动作完成后的状态回写
一次动作成功不代表规划就结束了。例如 pickup 成功后,世界状态至少要从 item_available=true 更新为 item_available=false,并增加角色已有物品这一事实。更新完成后,规划器才能基于新状态继续寻找下一步动作。
因此执行链通常是“规划动作 → 执行器调用 API → 游戏系统产生结果 → 状态适配器写回事实 → 必要时重新规划”。失败也要回写原因,例如目标消失、路径不可达或资源不足。否则规划器会不断重试同一个已经失败的动作。
让接口保持稳定
动作层的稳定边界应该是业务语义,而不是底层类名。推荐把 move_to、interact、attack、pickup 等作为长期稳定的动作契约,把路径系统、战斗组件或物品仓库的更换隐藏在执行器内部。
同时避免让执行器直接修改 GOAP 内部节点。执行器只返回明确结果和必要事件,状态适配器负责转换为规划事实。这样当游戏 API 发生替换时,通常只需要修改适配层,已有动作定义与规划逻辑仍可继续复用。