---

Wumpus World AI Sandbox (Godot C#)

基于 Godot 引擎和 C# 构建的经典人工智能测试环境 —— ** (Wumpus World)** 的现代化复刻与扩展。 本项目不仅是一个可供人类游玩的逻辑解谜游戏，更是一个高度标准化的 AI 算法验证沙盒，内置了 传统逻辑推演算法 (OS Agent) 与 强化学习算法 (RL Agent) 两种不同范式的 AI 供测试和对比。

✨ 核心特性

• 🤖 双核心 AI 驱动：支持无缝切换“基于启发式搜索的逻辑 AI”与“基于 Q-Learning 的强化学习 AI”。
• 🗺️ 绝对有解的地图生成：底层 MapManager 采用“安全联通区”算法，确保每次随机生成的关卡至少存在一条绝对安全的通关路径，避免出现死局。
• 👁️ 真实的感知与记忆系统：代理没有全图视野，只能感知脚下和相邻格子的“微风(Breeze)”与“恶臭(Stench)”，并在大脑中构建记忆地图 (MemoryMapLayer 实时可视化)。
• ⚙️ OpenAI Gym 风格的 API：主控角色被重构为标准的强化学习环境接口，支持离散动作下发 (AgentAction)、步进执行 (Step) 与环境状态回执 (Feedback/Reward)。
• 🎮 人工接管模式：随时可以关闭 Auto 模式，由玩家亲自上阵体验推理的乐趣。

AI 代理详解

1. OS Agent (逻辑推演代理)

一种基于符号逻辑与广度优先搜索 (BFS) 的经典/传统 AI。

• 稳健探索：永远只踏足记忆中确认为“安全”的区域。遇到危险气息立即回退。
• 战术走位与狙击：当闻到两处恶臭时，能够通过求交集 100% 锁定 Wumpus 的精确坐标；并会利用 BFS 自动规划路线，移动到合适的“狙击点”转身放箭。
• 绝境盲狙：当关卡走投无路且只发现一处恶臭时，懂得主动前往未知危险区边缘“盲猜”射击，清理死局。

2. RL Agent (强化学习代理)

一种基于 Q-Learning (时序差分学习) 的无模型强化学习 AI。

• 自我进化：初始状态下宛如“无头苍蝇”（基于 Epsilon-Greedy 策略），通过不断撞墙、掉坑、被吃来进行试错。
• 奖惩机制：
  • 挖到金子：高额奖励 (+100)，成功通关 (+200)。
  • 死亡惩罚：掉坑或遭遇 Wumpus (-200)。
  • 探索奖励：发现新区域 (+10)。
  • 射击反馈：射中 Wumpus 奖励 (+50)，射空浪费扣分 (-10)。
• 严谨的 TD 更新：在动作彻底执行并经过游戏物理层判定存活后，统一结算 Step Reward 并更新 Q-Table。

🏗️ 项目架构

• mainCharacter.cs：核心环境与控制器。负责维护 Agent 状态记忆、执行动作映射、触发物理交互事件并向下发派 Reward。
• MapManager.cs：环境生成与状态查询工具。包含保证必定有解的地图种子生成逻辑，以及处理 Wumpus 死亡/惊吓逃跑的局内逻辑。
• os_agent.cs：在线逻辑推演代理脚本。
• rl_agent.cs：强化学习代理脚本。
• MemoryMapLayer.cs：UI 表现层，将 Agent 脑海中的抽象数组转化为玩家可见的迷宫“战争迷雾”与标记。

🕹️ 游玩与操作指南

运行环境

• Godot 4.x (需支持 .NET / C# 版本)
• .NET SDK 6.0 或更高版本

如何测试 AI？

1. 在 Godot 编辑器中选中 mainCharacter 节点。
2. 在 Inspector（检查器）面板中，确保 Auto 勾选。
3. 修改 Agent Type 属性：
   • 输入 OS 启用逻辑推理 AI。
   • 输入 RL 启用强化学习 AI。
4. 运行游戏观察代理表现。

如何自己游玩？

在 mainCharacter 的 Inspector 中 取消勾选 Auto，使用以下按键控制角色：

• W / A / S / D：上下左右移动
• 鼠标右键：在当前位置挖掘（获取金矿）
• 预设的 shot_up / down / left / right 键位：朝指定方向射击（每局限一箭）

📜 许可证

本项目采用MIT License 开源。您可以自由使用、修改和分发本项目的代码。