ReGoap

通用的 C# GOAP（目标导向行动规划）库，附带 Unity3D 示例和辅助类。

该库非常通用；如果不包含 Unity 文件夹，您可以在任何游戏引擎中使用它。

1. 快速入门
2. 详细入门
   1. GOAP 简介
   2. 如何在 Unity3D 中使用 ReGoap
      1. 如何实现自定义 ReGoapAction
      2. 如何实现自定义 ReGoapGoal
      3. 如何实现自定义 ReGoapSensor
3. 调试
4. 拉取请求

---

快速入门

首先查看这里的 Unity FSM 示例。

此示例在 Unity 中使用 ReGoap 库，并结合一个简单的有限状态机（FSM）来处理宏观行为逻辑（大多数游戏中，三个 FSM 状态就足够了：空闲、移动到目标、播放动画）。

要使用它，请创建一个新的 Unity 项目，打开项目文件夹，进入 Assets 目录，并将整个仓库克隆到该目录中：

git clone https://github.com/luxkun/ReGoap.git

（在 Windows 上，您也可以通过命令行或任何 Git 客户端完成相同的操作，或者直接点击“克隆或下载”然后选择“下载 ZIP 文件”）

此外，您也可以直接下载最新版本的 Unity 包，不过其中可能不包含最新的更改，下载链接为这里，或在Unity 资源商店获取。

---

详细入门

GOAP 简介

（如果您只想使用该库并希望先了解示例，请跳至 如何使用 ReGoap）

在介绍如何在您的游戏中使用此库之前，让我先解释一下 GOAP 系统的工作原理。引用 Jeff Orkin 的话：

目标导向行动规划（简称 GOAP，与 soap 押韵）是一种简化的 STRIPS 类规划架构，专为游戏中自主角色行为的实时控制而设计。

简单来说，它的作用就是找到一个行动计划（一系列动作），以实现所选目标的要求。

您需要理解的主要概念包括：状态、动作、目标、记忆 和 传感器。

状态

是世界的一种描述，在本库中，状态被表示为字符串到对象的字典（Dictionary<string, object>）。

请参阅此文件中的 ReGoapState 类：https://github.com/luxkun/ReGoap/blob/master/ReGoap/Core/ReGoapState.cs

示例：'isAt': 'enemy', 'isWarned': true, 'hasWeapon': true

动作

可以定义为一组前提条件和效果，这些就是智能体（AI 角色，以下简称“智能体”）可以执行的动作。

前提条件是指执行该动作所需的条件，用状态来描述；而效果则是动作产生的结果，同样用状态来描述。

示例：

• ‘开门’：[前提：{'nearDoor': true, 'doorUnlocked': true}，效果：{'doorOpened': true}]
• ‘近战攻击’：[前提：{'weaponEquipped': true, 'isAt': 'enemy'}，效果：{'hurtEnemy' true}]
• ‘前往敌人’：[前提：{'enemyInLoS': true, 'canMove': true}，效果：{'isAt': 'enemy'}]
• ‘装备武器’：[前提：{'hasWeapon': true}，效果：{'weaponEquipped': true}]
• ‘巡逻’：[前提：{'canMove': true}，效果：{'isPatrolling': true}]

重要提示：不支持假的前提条件。 重要提示：动作完成后，其效果不会自动写入记忆中。这是有意为之的行为，因为在大多数游戏中，您通常会希望通过记忆或传感器来设置这些变量。如果您需要，可以在自定义的 ReGoapAction 中重写 Exit 方法，手动将效果写入记忆中，具体示例如下。

目标

可以定义为一组要求，用状态来描述，这基本上就是智能体应该完成的任务。

示例：

• ‘击杀敌人’：{'hurtEnemy': true}
• ‘巡逻’：{'isPatrolling': true}

记忆

是智能体的记忆，智能体所知道和感知的一切都应存储在这里。记忆还可以包含多个传感器，这些传感器在本库中作为记忆的辅助工具。记忆的主要职责是构建并持续更新“世界”状态。

传感器

是记忆的辅助工具，负责处理特定范围内的信息。

示例：

• 视线传感器（检测是否有敌人在视野内）
• 听觉传感器（检测是否听到敌人的声音，当然您也可以创建一个综合的敌人传感器，同时包含视线传感器和听觉传感器）

现在您应该已经了解了 GOAP 库的作用以及适用场景。如果您仍有疑问或想进一步深入了解这一领域，建议阅读 Jeff Orkin 的相关论文：http://alumni.media.mit.edu/~jorkin/

如何在 Unity3D 中使用 ReGoap

1. 在你的 Unity 项目中克隆此仓库。 命令行：

git clone https://github.com/luxkun/ReGoap.git

2. 为你的智能体创建一个 GameObject。
3. 添加一个 ReGoapAgent 组件，并为其命名（你需要创建一个继承自 ReGoapAgent 或实现 IReGoapAgent 接口的类）。
4. 添加一个 ReGoapMemory 组件，并为其命名（你需要创建一个继承自 ReGoapMemory 或实现 IReGoapMemory 接口的类）。
5. [可选 | 根据需要重复] 添加你自己的传感器类，该类应继承 ReGoapSensor 或实现 IReGoapSensor 接口。
6. [根据需要重复] 添加你自己的类，该类应继承 ReGoapAction 或实现 IReGoapAction 接口（请谨慎选择该行动应具备的前提条件和效果），并通过重写 Run 函数来实现行动逻辑。此函数将由 ReGoapAgent 调用。
7. [根据需要重复] 添加你自己的类，该类应继承 ReGoapGoal 或实现 IReGoapGoal 接口（请明智地选择目标状态）。
8. 在任意 GameObject 上（不要放在智能体上！）添加一个 ReGoapPlannerManager（你需要创建一个继承自 ReGoapPlannerManager 的类），它将负责所有的规划工作。
9. 开始游戏吧 :-)

还有什么呢？其实没什么了，这个库会自动处理所有规划任务：选择完成目标的动作，并依次执行第一个、第二个……直到完成。你只需要实现自己的动作和目标即可。

在接下来的段落中，我将解释如何创建自己的类（但对于大多数行为来说，你只需实现 GoapAction 和 GoapGoal 即可）。

如何实现自己的 ReGoapAction

请查看此示例中的动作：https://github.com/luxkun/ReGoap/tree/master/ReGoap/Unity/FSMExample/Actions

查看 ReGoapAction 的实现，了解你可以重写的函数：https://github.com/luxkun/ReGoap/blob/master/ReGoap/Unity/ReGoapAction.cs

你需要通过实现 IReGoapAction 接口或继承 ReGoapAction 来实现自己的 ReGoapAction。请明智地选择泛型类型，它们必须在整个智能体的所有类中保持一致。通常情况下，string, object 是最通用的类型；而 int/enum, object 虽然同样通用，但更为轻量。

对于简单的实现，你只需这样做：

public class MyGoapAction : ReGoapAction<string, object>
{
    protected override void Awake()
    {
        base.Awake();
        preconditions.Set("myPrecondition", myValue);
        effects.Set("myEffects", myValue);
    }
    public override void Run(IReGoapAction<string, object> previous, IReGoapAction<string, object> next, ReGoapState<string, object> settings, ReGoapState<string, object> goalState, Action<IReGoapAction<string, object>> done, Action<IReGoapAction<string, object>> fail)
    {
        base.Run(previous, next, goalState, done, fail);
        // 在这里编写你自己的游戏逻辑
        // 当完成时，无论是在本函数内还是外部，调用 done 或 fail 回调函数，这些回调函数会被 ReGoapAction 自动保存为 doneCallback 和 failCallback。
        doneCallback(this); // 这将通知 ReGoapAgent 该行动已成功完成，并继续执行行动计划
        // 如果行动失败，则调用 failCallback(this)，ReGoapAgent 会自动使整个计划失效，并请求 ReGoapPlannerManager 重新制定计划。
    }
}

如前所述，ReGoapAction 默认不会将效果写入内存，但内存系统需要检查效果是否确实已完成。如果你希望在行动结束时设置效果，可以在你的 ReGoapAction 实现中添加以下代码：

    public override void Exit(IReGoapAction<string, object> next)
    {
        base.Exit(next);

        var worldState = agent.GetMemory().GetWorldState();
        foreach (var pair in effects) {
            worldState.Set(pair.Key, pair.Value);
        }
    }

你还可以让前提条件和效果根据下一个行动的前提条件/效果动态变化。例如，这就是你在智能体中处理 GoTo 行动的方式。

请查看 FSMExample 以了解如何操作：https://github.com/luxkun/ReGoap/blob/master/ReGoap/Unity/FSMExample/Actions/GenericGoToAction.cs

如何实现自己的 ReGoapGoal

这相对简单，大多数目标只需重写 Awake 函数，以添加你自己的目标状态（目标）。

无论如何，请查看 ReGoapGoal 的定义：与所有其他类一样，你需要从头开始实现自己的类，方法是实现 IReGoapGoal 接口或继承 ReGoapGoal：https://github.com/luxkun/ReGoap/blob/master/ReGoap/Unity/ReGoapGoal.cs

同时，请查看此示例中的目标：https://github.com/luxkun/ReGoap/tree/master/ReGoap/Unity/FSMExample/Goals

public class MyGoapGoal : ReGoapGoal<string, object>
{
    protected override void Awake()
    {
        base.Awake();
        goal.Set("myRequirement", myValue);
    }
}

注意：如果你希望智能体能够自动感知目标是否可用，请务必使用 ReGoapGoalAdvanced。

如何实现自己的 GoapSensor

请在此处查看 GoapSensor 的基础类：https://github.com/luxkun/ReGoap/blob/master/ReGoap/Unity/GoapSensor.cs

更多示例请参阅：https://github.com/luxkun/ReGoap/tree/master/ReGoap/Unity/FSMExample/Sensors

与往常一样，你需要通过继承 ReGoapSensor 或实现 IReGoapSensor 接口来实现自己的传感器类。

public class MySensor : ReGoapSensor<string, object>
{
    void FixedUpdate()
    {
        var worldState = memory.GetWorldState();
        worldState.Set("mySensorValue", myValue); // 同样，myValue 可以是任何值……毕竟这是 GoapState :)
    }
}

注意：在使用传感器时，请务必使用 ReGoapMemoryAdvanced，因为基础类不会自动检查和更新传感器数据。

---

调试

当然，你可以使用自己喜欢的编辑器对智能体进行调试。

不过，ReGoap 提供了一个非常实用的 Unity 智能体调试工具（https://github.com/luxkun/ReGoap/blob/master/ReGoap/Unity/Editor/ReGoapNodeEditor.cs 和 https://github.com/luxkun/ReGoap/blob/master/ReGoap/Unity/Editor/ReGoapNodeBaseEditor.cs）。要使用它，只需点击 Unity 菜单中的 Window，然后选择 ReGoap Debugger，一个 Unity 窗口将会打开，这就是智能体调试器。

现在，当你在场景中点击任意智能体（仅在运行时有效）时，窗口会自动更新，显示智能体的“思考”内容（当前世界状态、所选目标和当前计划、可能的目标、可能的动作、可以做什么以及不能做什么——快试试吧！）。

---

拉取请求

我们欢迎任何拉取请求，但在提交之前，请务必运行 Unity 测试（菜单 Window -> Editor Tests Runner -> Run All），并保持一致的代码风格。

ReGoap 快速上手指南

ReGoap 是一个通用的 C# GOAP（目标导向行动规划）库，专为游戏 AI 设计。虽然它提供了 Unity3D 的示例和辅助类，但核心库是引擎无关的，可适用于任何支持 C# 的游戏引擎。

环境准备

• 系统要求：支持 .NET Standard 或 .NET Framework 的环境。
• 前置依赖：
  • 游戏引擎：推荐使用 Unity3D（官方提供了完整的示例和编辑器调试工具）。若使用其他引擎，仅需引用核心库代码。
  • 版本控制：安装 Git（用于克隆仓库）。
  • 语言版本：确保项目支持 C# 泛型及字典操作。

安装步骤

方式一：通过 Git 克隆（推荐，获取最新代码）

1. 打开终端或命令行工具。
2. 进入你的 Unity 项目 Assets 目录（或其他希望存放库的目录）。
3. 执行以下命令克隆整个仓库：

git clone https://github.com/luxkun/ReGoap.git

提示：如果你只需要核心库而不需要 Unity 特定功能，可以只复制 ReGoap/Core 文件夹到你的项目中。

方式二：下载发布包

• GitHub Releases：访问 ReGoap Releases 下载最新的 Unity Package。
• Unity Asset Store：在 Unity 资源商店搜索 "ReGoap" 或直接访问页面下载（版本可能略滞后于 GitHub）。

基本使用

以下是在 Unity3D 中构建一个简单 AI 代理（Agent）的最小化流程。

1. 场景设置

1. 在场景中创建一个空的 GameObject，命名为 Agent。
2. 为 Agent 添加自定义的脚本组件（需继承自库中的基类）：
   • ReGoapAgent：AI 的核心控制器。
   • ReGoapMemory：存储世界状态（World State）。
   • (可选) ReGoapSensor：用于实时更新记忆（如感知敌人）。
3. 在场景中任意位置创建一个空 GameObject，命名为 PlannerManager。
4. 为其添加自定义脚本组件 ReGoapPlannerManager（全场景只需一个，负责统筹规划）。

2. 代码实现示例

你需要创建三个核心类来定义 AI 的行为逻辑。以下是基于 string, object 泛型的最简实现：

A. 定义动作 (ReGoapAction)

动作包含“前提条件”（Preconditions）和“效果”（Effects）。

using ReGoap.Core;
using ReGoap.Unity;

public class MoveToEnemyAction : ReGoapAction<string, object>
{
    protected override void Awake()
    {
        base.Awake();
        // 设置前提：必须能看到敌人且可以移动
        preconditions.Set("enemyInLoS", true);
        preconditions.Set("canMove", true);
        
        // 设置效果：执行后位于敌人处
        effects.Set("isAt", "enemy");
    }

    public override void Run(IReGoapAction<string, object> previous, IReGoapAction<string, object> next, 
        ReGoapState<string, object> settings, ReGoapState<string, object> goalState, 
        Action<IReGoapAction<string, object>> done, Action<IReGoapAction<string, object>> fail)
    {
        base.Run(previous, next, goalState, done, fail);
        
        // --- 在此处编写具体的游戏逻辑 (如调用寻路系统) ---
        // 模拟移动过程...
        
        // 逻辑完成后，必须调用回调通知规划器
        doneCallback(this); 
    }
}

B. 定义目标 (ReGoapGoal)

目标是 AI 想要达到的世界状态。

using ReGoap.Core;
using ReGoap.Unity;

public class AttackEnemyGoal : ReGoapGoal<string, object>
{
    protected override void Awake()
    {
        base.Awake();
        // 目标状态：已经伤害到敌人
        goal.Set("hurtEnemy", true);
    }
}

C. 定义传感器 (ReGoapSensor) - 可选但推荐

传感器负责持续更新内存中的世界状态。

using ReGoap.Core;
using ReGoap.Unity;

public class VisionSensor : ReGoapSensor<string, object>
{
    void FixedUpdate()
    {
        var worldState = memory.GetWorldState();
        // 检测逻辑：假设有一个方法能判断是否看到敌人
        bool seesEnemy = CheckLineOfSight(); 
        worldState.Set("enemyInLoS", seesEnemy);
    }
    
    private bool CheckLineOfSight() { /* 实现检测逻辑 */ return false; }
}

3. 运行与调试

1. 将上述脚本挂载到对应的 GameObject 上。
2. 点击 Unity 编辑器顶部的 Window -> ReGoap Debugger 打开调试窗口。
3. 进入 Play 模式，选中场景中的 Agent。
4. 在调试窗口中，你可以实时查看 AI 的“思维过程”：当前世界状态、选定的目标、生成的行动计划以及可用的动作列表。

注意：默认情况下，动作执行完毕后不会自动将“效果”写入内存。如果需要自动写入，请在你的 Action 类中重写 Exit 方法并将 effects 应用到 agent.GetMemory().GetWorldState()。