轻量级强化学习足球仿真环境-football_env

课程与竞赛中常需可复现的足球对抗环境，但主流3D方案依赖重、学习和运行成本高。football_env 以“可教学、可实验、可扩展”为目标，用少量依赖在笔记本即可稳定运行，覆盖物理、规则、渲染、控制与奖励，满足课堂演示、算法验证与论文复现实验的需求，并支持“人机对战 + AI 对战”的教学体验。
本项目实现了一个功能完备的2D足球仿真环境，核心功能模块包括：
1. 物理仿真引擎：基于Pymunk库，精确模拟球员和球的刚体动力学，包括碰撞、地面摩擦、旋转和力应用，保证了运动的真实性。
2. 比赛规则引擎：实现了足球比赛的核心规则，包括开球、进球、出界（界外球、角球、球门球）、半场切换和比赛结束等状态的自动判定与管理（为了规则简洁，没有实现出界后球权交换）。
3. 多模式智能体控制：支持三种控制模式：人类键盘控制（WASD、Q/E 旋转、Tab 切人），提供流畅的实时交互体验；状态机AI，一个内置的高级AI，具备拦截预测、团队协作、传切配合和射门决策等复杂战术能力；以及为强化学习预留的AI策略接口。“1/2”数字键手动指定两队冻结状态。
4. 标准化环境接口：遵循Gymnasium API标准，封装成标准的step、reset循环，提供结构化的观测空间和动作空间，便于AI算法的接入与训练。
5. 高效渲染：Pygame 实时画面，包含场地/中圈/球门U形/禁区线、焦点高亮、比分与时间提示及键位提示，便于展示和调试。
6. 演示Demo：默认“A队1人键盘+队友AI、B队全AI”的即开即用演示Demo。

本项目由我独立设计与开发，耗时约2周。
技术栈：后端逻辑采用Python，物理仿真核心为Pymunk，可视化渲染使用Pygame，数值计算依赖NumPy，并采用Gymnasium作为强化学习的标准接口。
项目亮点与难点：
1. 模块化架构：项目采用了清晰的模块化设计，将物理、规则、控制和渲染解耦，易于维护和扩展。
2. 高级战术AI：最大的亮点是实现了一个复杂的StateMachineController。它不仅仅是追球，而是融合了运动学预测、路径规划(NLGL)、动态决策（如压迫、传球、射门时机判断）和团队协作逻辑（如传切二过一、支援跑位），使其成为一个强劲的基线对手与模仿学习目标。
3. 物理参数调优：项目实现中的一个难点在于反复调试物理参数（如摩擦系数、弹性系数、球员速度上限），以在模拟的真实感和AI的可控性之间取得最佳平衡。