UT2004-FPSBots-AI

基于 POGAMUT 插件的 Unreal Tournament 2004 多智能体强化学习项目。

A multi-agent reinforcement learning project for Unreal Tournament 2004, built on the POGAMUT platform.

项目简介

本项目在 UT2004 游戏环境中搭建了一个 Java 编写的多智能体强化学习系统, 能够实现人机对战以及机器人之间的自主对战。

• 采用 FALCON (Fusion Architecture for Learning, COgnition and Navigation) 算法作为单智能体执行策略
• 采用 迁移学习 实现多智能体之间的动作建议 (Action Advice)
• 完成了智能体的状态设计、动作设计、奖励函数设计以及多智能体间状态读取与通信
• 实验结果表明方案能够显著提高 AI 的游戏水平和学习效率

功能特性

• 多种 Bot 变体: 专家 AI、FALCON 单智能体、事件驱动型、多智能体协作
• 基于 ART (Adaptive Resonance Theory) 的在线增量学习
• Q-Learning 与 FALCON 的融合策略
• 支持 Deathmatch 和 CTF 游戏模式
• 经验回放 (Experience Replay) 机制
• 可配置的状态/动作/奖励空间
• Docker 全栈部署支持

架构概览

UT2004 Game Server (ucc-bin + GameBots2004)
        |
        | TCP :3001 (GameBots Protocol)
        |
   POGAMUT Framework (Java)
        |
   +----+----+----+----+
   |    |    |    |    |
 Expert FALCON Event Multi-Agent
  Bot    Bot   Bot    Bot

核心组件:

组件	说明
POGAMUT 3.7.0	UT2004 Java bot 开发框架, 提供感知-决策-行动接口
FALCON	基于 ART 网络的在线 Q-Learning 算法
GameBots2004	UT2004 mod, 暴露 TCP 控制接口供外部程序控制 Bot
Multi-Agent	多智能体共享状态与动作建议机制

Bot 变体

类	说明
vs1.HunterBot	专家 AI (默认), 基于规则的高水平 Bot
vs1.wang_et_al	FALCON 单智能体, 定时步进学习
vs1.wang_et_al2	事件驱动 FALCON, 取消固定时间步
vs1.wang_et_al3	多智能体, 支持动作建议的迁移学习
Hunters.HunterBot_EMFALCON	EM-FALCON 变体
Hunters.HunterBot_BPN	BPN (Back-Propagation Network) 变体
Hunters.HunterBot_BASELINE	基线对照 Bot
Hunters.MirrorBot4	镜像 Bot, 模仿观察对象的行为

快速开始

Docker 方式 (推荐)

前置条件: Docker, Docker Compose, UT2004 Linux 专用服务器文件

# 1. 将 UT2004 Linux 服务器文件放到 ut2004-server-files/ 目录
cp -r /path/to/ut2004-linux-server ./ut2004-server-files

# 2. 启动全栈
docker-compose up --build

# 3. 自定义 Bot 类型
BOT_CLASS=vs1.wang_et_al docker-compose up --build bot

本地方式

前置条件: JDK 8, Maven (3.6.x 推荐), UT2004 (Steam), POGAMUT 3.7.0 安装器

# 1. 安装 POGAMUT
java -jar PogamutUT2004Installer-3.7.0.jar

# 2. 配置 Maven (settings.xml 添加 POGAMUT 仓库)
# 参见 docker/bot/settings.xml

# 3. 构建
mvn clean package

# 4. 启动 UT2004 服务器 (Windows)
startGamebotsDMServer.bat

# 5. 运行 Bot
java -jar target/hunter_1-0.0.1-SNAPSHOT.one-jar.jar

详细部署指南请参阅 docs/deployment-guide.md。

项目结构

ut2004-fpsbots-ai/
├── src/main/java/
│   ├── vs1/                 # 实验入口 (HunterBot, wang_et_al 系列)
│   ├── AGENTS/              # 多智能体模块 (Mirror, ART, 感知数据)
│   ├── AI/                  # FALCON 训练与变体
│   ├── Bots/                # Bot 状态管理与经验回放
│   ├── FALCON/              # FALCON 核心算法 (ART + Q-Learning)
│   ├── Hunters/             # Hunter Bot 各变体实现
│   ├── Settings/            # 参数配置与常量
│   └── cz/.../utils/        # POGAMUT UCC 包装器
├── docker/
│   ├── bot/                 # Bot 容器 (Dockerfile + Maven settings)
│   └── ut2004-server/       # UT2004 服务器容器
├── docker-compose.yml       # 全栈编排
├── pom.xml                  # Maven 构建配置
└── docs/                    # 项目文档
    ├── system-design.md     # 系统设计
    ├── api-reference.md     # API 参考
    └── deployment-guide.md  # 部署指南

文档

• 系统设计文档 - 架构设计、FALCON 算法、多智能体机制
• API 参考 - 核心模块、关键类、配置参数
• 部署指南 - Docker/本地部署、POGAMUT 安装、故障排查

技术栈

• 语言: Java 8
• 构建: Maven 3.6.x
• 框架: POGAMUT 3.7.0
• 游戏: Unreal Tournament 2004
• 算法: FALCON (ART + Q-Learning), Fusion ART, MLP, Actor-Critic
• 容器: Docker, Docker Compose

参考资料

• POGAMUT 官网
• POGAMUT 安装器
• FALCON 论文 - Ah-Hwee Tan
• Unreal Tournament 2004

License

本项目仅供学术研究与教育使用。UT2004 及 POGAMUT 版权归各自所有者。