简介这是一份面向博弈论与控制论学习者的微分博弈difgames开源实现核心基于哈密顿-雅可比-贝尔曼-伊萨克斯HJBI方程解决连续时间动态系统中的最优策略与纳什均衡求解问题。压缩包共9个文件以C语言源码为主包含6个.c实现文件、1个.h头文件、1份PDF技术文档和1个Shell构建脚本整体仅206KB轻量且易于在Linux环境下编译运行。代码覆盖多个不同驾驶场景的数值求解采用有限差分等离散化方法逼近偏微分方程同时提供图形可视化模块可直观展示博弈动态过程还附带参考文献管理与自动化构建工具。随包PDF对算法原理和优化方法作了深入说明有助于研究者复现核心实验并迁移至自动驾驶、经济决策等更广领域。目前已有238人学习/下载适合具备数学与C语言基础、希望动手探索动态博弈算法的开发者和学生。1. 微分博弈开源引擎当你追我赶变成一套数值求解游戏如果你在某个演示项目里看到两架无人机你追我赶、轨迹像水波一样不断弯折那不是特效是微分博弈引擎在实时求最优轨迹。difgames 是一个把经典微分博弈从教科书方程落成可运行游戏框架的开源项目你定义动力学方程和目标函数引擎自动做数值积分、末端约束求解和实时渲染。面向的人群很明确——研究博弈论与最优控制的应用派、需要追逃算法验证的仿真工程师、想给游戏加上动态决策 AI 的开发者。它不是通用物理引擎而是一个用微分方程驱动游戏逻辑的试验场能跑起来、能改代码、能加规则。2. 架构与技术选型Python NumPy 的微分博弈工程骨架2.1 技术栈取舍为什么不用现成游戏引擎做微分博弈第一反应往往是选一个成熟游戏引擎把角色放进 Unity 或 Godot拖一堆组件上去。拆完 difgames 之后我反而觉得它坚持 Python NumPy Pygame 是有意的取舍。微分博弈的每一帧核心工作不是渲染而是在解一个最优控制问题向前积分若干条候选轨迹、计算每条轨迹的累计代价、比较策略好坏。渲染层面画几个圆点和线段就够了真正的计算压力在数值积分和策略搜索上。Python 在这个场景下的优势是科学计算生态完整。NumPy 负责向量化的状态运算SciPy 的 solve_ivp 可以做自适应步长积分Pygame 只承担把轨迹点画到窗口的活。整个项目依赖很少一条 pip install 就能把运行环境装齐。相比引入整套重型引擎这种轻量组合让核心代码一目了然你打开 core/dynamics.py 看到的是微分方程打开 core/solver.py 看到的是 RK4 积分器不会被场景管理、动画树、物理碰撞组件淹没。difgames 作为开源软件它优先保证的是可读性和可扩展性。渲染层和数值层完全解耦意味着你可以把 Pygame 渲染器换成终端打印、Matplotlib 动画、甚至 WebSocket 推给前端都不影响核心博弈逻辑。游戏引擎固然有完善的 UI 和资源管线但那是给内容制作准备的不是给算法研究准备的。另一个取舍是这样的项目里没有把控制量直接接到角色物理上而是抽象出一层控制输入。追击者和逃逸者都是具有速度模长和转向角速度的质点模型按自行车模型简化处理。这种简化让状态空间保持干净——六维状态两个控制量适合做实时策略搜索同时又不至于简化到失去博弈意义速度大小、转向半径、捕获半径这些参数仍然能直接决定胜负。2.2 目录结构与模块边界拿到源码后建议先看一遍目录结构再跑代码因为项目的模块边界划分得非常规整。difgames/ ├── main.py # 入口组装游戏循环 ├── requirements.txt ├── config/ │ ├── loader.py # YAML 读取与默认值合并 │ ├── default.yaml # 基础参数 │ └── pursuit.yaml # 追逃场景专用参数 ├── core/ │ ├── dynamics.py # 动力学模型状态转移方程 │ ├── objective.py # 目标函数末端代价 过程代价 │ ├── solver.py # RK4 数值积分器 │ ├── policy.py # 采样打靶策略 │ ├── trajectory.py # 轨迹缓存类 │ └── render.py # Pygame 渲染 ├── games/ │ ├── registry.py # 场景注册表 │ ├── pursuit.py # 追逃博弈 │ ├── landing.py # 软着陆最优控制 │ └── flow.py # 流场寻路 └── ui/ ├── hud.py # 参数面板 └── replay.py # 回放记录边界设计的关键在于 core 与 games 的分离。core 里放的是所有博弈场景共用的数值骨架状态怎么变化、代价怎么算、轨迹怎么积分games 里放的是具体场景定义。核心依赖方向是从上往下main.py 依赖 gamesgames 依赖 corecore 不反向依赖任何具体场景。这样新增一个游戏场景时不需要动 solver 和 policy只要在 games 目录里加文件再注册进 registry 即可。config/loader.py 承担了参数装配读取 YAML 时会把用户配置文件与默认配置做深度合并。它做的另一件事是把命令行参数覆盖进配置字典比如--evader_speed 1.2这样的运行时覆盖。这个设计让实验阶段不用反复编辑文件也解释了后面为什么有人改配置不生效——因为命令行参数的优先级更高容易让人误以为 YAML 没被读取。2.3 从入口到渲染一次完整的游戏循环main.py 把整个运行流程压缩到了一个主循环里结构非常清晰读取配置初始化 Pygame创建动力学、积分器、渲染器然后每个循环里依次完成事件处理、策略决策、状态积分、画面绘制。# main.py import sys import pygame from core.dynamics import PursuitEvasionDynamics from core.solver import RK4Solver from core.policy import SamplingPolicy from core.render import GameRenderer from config.loader import load_config def main(): cfg load_config(config/pursuit.yaml) pygame.init() screen pygame.display.set_mode( (cfg[screen_width], cfg[screen_height]) ) clock pygame.time.Clock() dynamics PursuitEvasionDynamics(cfg) solver RK4Solver(dtcfg[dt]) policy SamplingPolicy(dynamics, solver, cfg) renderer GameRenderer(screen, cfg) state dynamics.initial_state(cfg[initial_state]) trajectories {pursuer: [], evader: []} running True while running: for event in pygame.event.get(): if event.type pygame.QUIT: running False controls policy.choose_controls(state) state solver.step(state, controls) trajectories[pursuer].append((state[0], state[1])) trajectories[evader].append((state[3], state[4])) renderer.draw(state, trajectories) pygame.display.flip() clock.tick(cfg[fps]) pygame.quit() if __name__ __main__: main()主循环里 policy.choose_controls(state) 是整局游戏的核心它会同时给出追击者和逃逸者的控制量。注意传入的是当前完整状态而不是双方位置因为采样打靶策略需要基于完整状态位置加航向去预测未来轨迹。控制量算出来后交给 RK4Solver 积分一步得到下一帧状态再把位置塞进轨迹列表供渲染绘制。这种结构最好的一点是每一环都能单独替换。你想测更快的积分器只改 solver想改博弈逻辑只动 policy想换渲染方式renderer 随时可以重写。项目里没有把 AI 决策写进渲染循环也没有把积分逻辑塞进动力学类每个模块的职责都很单一调试时能少踩很多坑。3. 核心模块拆解从动力学 ODE 到追逃轨迹的完整链路3.1 六维状态向量动力学 ODE 建模追逃博弈的状态由追击者和逃逸者各自的平面位置、航向角组成合起来是一个六维向量追击者位置 x_p、y_p追击者航向角 theta_p逃逸者位置 x_e、y_e逃逸者航向角 theta_e。控制量则是两个角速度指令 u_p 和 u_e单位是弧度每秒。# core/dynamics.py import numpy as np class PursuitEvasionDynamics: def __init__(self, cfg): self.v_pursuer cfg[pursuer_speed] self.v_evader cfg[evader_speed] self.max_turn_rate cfg[max_turn_rate] def state_derivative(self, state, controls): state: [x_p, y_p, theta_p, x_e, y_e, theta_e] controls: [u_p, u_e]角速度单位 rad/s x_p, y_p, theta_p, x_e, y_e, theta_e state u_p, u_e controls dx_p self.v_pursuer * np.cos(theta_p) dy_p self.v_pursuer * np.sin(theta_p) dtheta_p np.clip(u_p, -self.max_turn_rate, self.max_turn_rate) dx_e self.v_evader * np.cos(theta_e) dy_e self.v_evader * np.sin(theta_e) dtheta_e np.clip(u_e, -self.max_turn_rate, self.max_turn_rate) return np.array([dx_p, dy_p, dtheta_p, dx_e, dy_e, dtheta_e]) def initial_state(self, cfg): return np.array( [ cfg[x_p0], cfg[y_p0], np.deg2rad(cfg[theta_p0]), cfg[x_e0], cfg[y_e0], np.deg2rad(cfg[theta_e0]), ], dtypefloat, )ODE 是常微分方程形式位置分量对时间的导数等于速度乘航向单位向量航向角对时间的导数直接是控制输入。逐项来看追击者位置变化只依赖自身速度和航向不受逃逸者任何影响两个角色之间唯一的耦合关系发生在目标函数里而不是运动模型里。这是追逃问题的标准建模方式——运动学解耦胜负通过代价函数耦合。np.clip很关键它把控制量限制在最大转向角速度内。采样打靶时策略会生成很大的瞬时角速度如果不做限幅积分出来的轨迹会出现极度不合理的急转弯。做二次开发时如果你发现轨迹像折线一样第一件事检查是不是把 max_turn_rate 调到了非常大甚至没 clip。3.2 目标函数末端距离与转向代价的权衡目标函数决定什么才算好。difgames 把目标函数拆成过程代价和末端代价两部分。追击者的末端代价是最终时刻两架无人机之间的平方距离追得越近代价越小逃逸者的目标相反要让这个距离尽可能大。过程代价是控制量平方和乘一个权重用来压制频繁大幅转向。# core/objective.py import numpy as np class PursuitObjective: def __init__(self, cfg): self.capture_radius cfg[capture_radius] self.turn_penalty cfg[objective_weights][turn_penalty] def terminal_cost(self, state): dist np.hypot( state[0] - state[3], state[1] - state[4], ) return dist * dist def running_cost(self, controls): u_p, u_e controls return self.turn_penalty * (u_p * u_p u_e * u_e)这里用np.hypot而不是sqrt(x^2 y^2)是为了数值稳定性后面避坑章节会专门讲它。末端代价只用平方距离而不是直接返回距离好处是让代价函数在距离远时给更大梯度策略会更激进地朝缩短距离的方向选动作并且平方距离处处可导后续如果要接梯度优化器或者拟牛顿法求解不需要处理零点处不可导的问题。turn_penalty 这个权重是调参时最先要碰的变量。权重太小两个角色会疯狂地来回打方向轨迹像锯齿权重太大双方几乎不敢转弯追上目标的速度会显著变慢逃逸者也会失去闪避能力。常见做法是把 turn_penalty 设在 0.05 到 0.5 之间先跑一局看轨迹形态再微调。3.3 采样打靶策略前看 N 步的决策逻辑如果严格求解微分博弈需要解 Hamilton-Jacobi-Isaacs 方程或者做伴随法双点边值问题工程实现成本很高。difgames 采用了更工程化的思路采样打靶。把每个角色的控制空间离散成若干候选角速度对每个候选动作向前模拟固定帧数评估累计代价选最优的那个。# core/policy.py import numpy as np class SamplingPolicy: def __init__(self, dynamics, solver, cfg): self.dynamics dynamics self.solver solver self.horizon cfg[horizon_frames] self.objective cfg[objective] self.candidate_actions np.linspace( -cfg[max_turn_rate], cfg[max_turn_rate], cfg[num_action_samples], ) self.last_control 0.0 def choose_controls(self, state): u_p self.best_response(state, rolepursuer) u_e self.best_response(state, roleevader) return np.array([u_p, u_e]) def best_response(self, state, role): best_value float(inf) if role pursuer else float(-inf) best_action 0.0 for u in self.candidate_actions: if role pursuer: controls np.array([u, self.last_control]) else: controls np.array([self.last_control, u]) value self.rollout(state, controls) if role pursuer and value best_value: best_value value best_action u if role evader and value best_value: best_value value best_action u if role pursuer: self.last_control best_action else: self.last_control best_action return best_action def rollout(self, state, controls): s state.copy() total_cost 0.0 for _ in range(self.horizon): total_cost self.objective.running_cost(controls) s self.solver.step(s, controls) total_cost self.objective.terminal_cost(s) return total_cost这里有一点要说明追击者选动作时假设逃逸者保持上一帧的控制量逃逸者选动作时反过来假设追击者保持上一帧控制量二者交替决策。严格来说这不是纳什均衡意义上的最优响应但在帧率足够高、每一步决策间隔很短时这种交替近似的效果已经足够接近完美的同时决策。做实时游戏不能为了理论严谨而牺牲帧率采样打靶的价值就在于此。rollout是评估动作好坏的核心。它固定当前控制量向前积分 30 帧累加每帧的过程代价最后把末端代价加进去。horizon 越大策略越有远见但计算量线性增长。num_action_samples 决定候选动作数量默认取 7 个就足够11 个以上会让轨迹更平滑但每帧决策耗时可能肉眼可见地增加。3.4 RK4 积分器与前向模拟采样打靶一次要对整个 horizon 逐帧积分积分器的效率和稳定性直接影响决策质量。项目采用固定步长 RK4而不是简单的欧拉法因为欧拉法在强烈转弯时容易产生数值漂移轨迹会螺旋式地偏离真实解。# core/solver.py import numpy as np class RK4Solver: def __init__(self, dynamics, dt0.02): self.dynamics dynamics self.dt dt def step(self, state, controls): dt self.dt k1 self.dynamics.state_derivative(state, controls) k2 self.dynamics.state_derivative(state 0.5 * dt * k1, controls) k3 self.dynamics.state_derivative(state 0.5 * dt * k2, controls) k4 self.dynamics.state_derivative(state dt * k3, controls) return state (dt / 6.0) * (k1 2 * k2 2 * k3 k4)RK4 的原理是用四个不同位置的斜率加权平均来估计一个步长内的变化比欧拉法多算了三次导数但对光滑系统能提供四阶精度。每帧模拟需要调用多次state_derivative这也是整个项目计算量最大的地方。如果参数配置得大追击者和逃逸者各要 rollout 七条轨迹每条轨迹三十帧每帧四次导数一帧画面差不多要做 1680 次导数运算Python 纯循环跑下来还能接受但已经能感觉到吃力。如果要提升性能最直接的办法是减少 num_action_samples 而不是缩小 horizon。经验值是追击者 5 个候选动作、逃逸者 5 个候选动作配合 30 帧前瞻在普通笔记本上还能稳定跑 60 帧。追求策略质量时再把采样数加大此时最好同时把渲染帧率降到 30。4. 运行配置与实战调参三组参数实验看追逃行为4.1 装依赖、跑场景三步起步项目依赖写在 requirements.txt 里只有四个包不涉及系统级依赖安装过程基本不会有意外。numpy1.24 scipy1.10 pygame2.5 pyyaml6.0建议先建虚拟环境再装避免污染全局 Python。启动命令也非常简单指定场景名即可。cd difgames python -m venv .venv source .venv/bin/activate pip install -r requirements.txt python main.py --scene pursuitWindows 下把激活命令换成.venv\Scripts\activate。运行后屏幕上会出现一个深色窗口追击者用青色圆点表示逃逸者用橙色圆点表示各自的运动轨迹会以半透明尾迹的形式留在画面上。初始位置由 pursuit.yaml 里的x_p0、y_p0、x_e0、y_e0决定默认是追击者在左侧逃逸者在右侧偏上方一点。如果运行时提示找不到 YAML八成是当前工作目录不对。命令行里的路径是相对路径必须在 difgames 根目录下执行不能在 core 目录或 games 目录里执行。这是新手上手最常见的第一个坑。4.2 配置参数速查表pursuit.yaml 里最值得关注的参数有七项直接决定了追逃过程的观感和策略表现。参数默认值作用调大后的表现pursuer_speed1.0追击者速度追得更紧捕获更快evader_speed0.8逃逸者速度逃逸者更容易摆脱追击max_turn_rate2.0最大转向角速度转弯更灵活轨迹更圆horizon_frames30策略前看帧数策略更有远见计算变慢num_action_samples7候选控制量个数策略更平滑计算量增加turn_penalty0.1转向代价权重轨迹更直响应变钝capture_radius0.4捕获判定距离更容易或者更难判定捕获这些参数全部写在default.yaml里pursuit.yaml 只覆盖场景相关的差异项。比如追击者速度放在默认配置里是为了让其余场景也能复用而初始位置和捕获半径属于追逃场景的专属内容。4.3 三组实验直接看到行为差异跑实验不需要改代码用命令行参数覆盖就行。第一个实验把逃逸者速度改成 1.0与追击者完全同速。运行后观察轨迹追击者几乎不可能追上逃逸者双方会逐渐形成一个平行的相对位置关系。原因是追击者采样打靶只能预测有限帧无法在远期追上同速、且每帧都在做最优响应的高机动目标。第二个实验把逃逸者速度降到 0.6。这会让追击者在速度上占据明显优势但如果你直接跑会发现追击者依然要花很长时间才能追到因为它每次只做局部最优决策经常先冲向逃逸者的当前位置等逃逸者转弯后才反应过来调整追击方向。要改善这个现象最好的办法是把 horizon_frames 从 30 提到 60追击者的策略就能看到更远的未来提前切向内切点拦截。第三个实验把 turn_penalty 调成 0.5同时保持速度比不变。轨迹会肉眼可见地变直两个角色都减少转向次数代价是逃逸者的闪避幅度变小追击者更容易用直线逼近。这三个实验做下来很快每次修改后不用重新编译直接重启进程加载新参数即可。如果你想做批量参数扫描可以写一个循环让多个配置交替启动但更高效的做法是直接调用核心模块做离线仿真不启动 Pygame。5. 避坑与排查数值翻车和调参玄学的记录5.1 现象轨迹高频抖动甚至某帧直接飞出去现象是两架无人机的轨迹出现密集的锯齿状抖动严重时某一步位置直接跳到远处整个画面看起来像出了 bug。原因是 dt 过大或者 max_turn_rate 过大导致 RK4 在同一步长内无法准确刻画剧烈变化的航向。固定步长 RK4 在高非线性输入下会变得不稳定尤其是控制量已经撞到 clip 边界时位置误差会逐步累积。解决方法是先降 dt把 0.02 改成 0.01一般抖动立刻消失。如果还抖再同时限制 max_turn_rate不要让转向角速度超过 3.0。别在一开始就追求高精度而把 dt 调到 0.005那会让采样打靶的 rollout 计算量翻倍帧率直接掉一半。5.2 现象追击者速度明明占优却追不上逃逸者现象是追击者速度比逃逸者快了 0.2 以上但整局跑完双方始终保持一段距离谁也追不上谁。原因多半是 horizon_frames 太小追击者每个决策周期只往前看十几帧每次都被逃逸者的突然转弯骗走陷入持续的左右摇摆。这类问题在视觉上非常隐蔽因为看起来追击者确实在努力飞但它做的所有努力都被逃逸者的即时转向抵消了。解决方法是把 horizon_frames 加长到 60 甚至 90让追击者能预测到未来一段距离上的截点。另一个补充手段是给追击者增加视线角引导让采样打靶的候选动作里混入直接指向逃逸者当前位置的基准动作避免策略在局部最优里打转。5.3 现象配置文件改了界面一动没动现象是编辑 default.yaml 或 pursuit.yaml 之后重新运行所有行为和之前完全一样。原因是 config/loader.py 按优先级合并参数命令行参数优先级高于配置文件。如果你用--scene pursuit启动但没覆盖其他参数配置文件应该是会生效的一旦你在命令行里传过--evader_speed 0.8之后再改 YAML 里的 evader_speed 也不会生效因为命令行参数会覆盖掉文件值。解决方法是先确认启动命令里有没有携带相关参数有就删掉或者专门加一个--no-cli-override开关跳过命令行覆盖。这个坑在实验后期特别容易踩建议每次改完配置后用python main.py --scene pursuit --print-config输出一份实际生效的参数。5.4 现象Pygame 窗口掉帧CPU 占用拉满现象是窗口能打开但帧率从 60 掉到十几风扇开始明显提速。原因不是渲染本身而是采样打靶的计算量太大。每次 rollout 对整条轨迹做逐帧积分如果 num_action_samples 是 9、horizon 是 60单帧要做上千次积分Python 纯循环跑不动很正常。再加上渲染层每帧把整条尾迹重新画一遍性能就雪上加霜。解决方法是先降 num_action_samples每个角色保留 5 个候选动作。再把 horizon 降到 30。渲染层可以把轨迹绘制改成只画最近几十个点不要从开局一路画到当前帧。还有一个常见优化是把渲染逻辑放进缓存轨迹点没变化就不重绘背景。5.5 现象代价函数突然出现 NaN策略全部失效现象是跑着跑着整个画面不动了打印状态发现某个位置出现nan之后所有决策都是nan程序彻底崩掉。原因是数值计算里出现了不安全的平方根或角度运算比如sqrt(x * x y * y)在 x 和 y 都是超大浮点数时可能溢出成 infinf 参与后续运算就变成 nan。另一种常见来源是atan2参数为 (0, 0) 时返回角度不确定导致航向角出现异常值。解决方法是把距离计算统一换成np.hypot它在底层做了缩放处理能避免中间值溢出。在initial_state和state_derivative里加一条状态合法性检查如果状态里出现 nan 就立刻打印当前帧号和控制量把崩坏前的参数保留下来分析。6. 二次开发思路新增场景和替换决策器的关键步骤拿到这个项目后最高性价比的改造方向有两个加一个新博弈场景或者把采样打靶策略换成神经网络决策器。新增场景的第一步是复制一个现有场景文件比如把 games/pursuit.py 复制成 games/missile_duel.py然后重写 dynamics 子类。不要直接继承 PursuitEvasionDynamics 硬改因为它的状态向量结构是六维固定的。更干净的做法是新建一个继承 core.dynamics.Dynamics 的类重写state_derivative和initial_state。# games/missile_duel.py import numpy as np from core.dynamics import Dynamics class MissileDuelDynamics(Dynamics): def __init__(self, cfg): self.max_accel cfg[max_accel] def state_derivative(self, state, controls): x, y, vx, vy state ax, ay controls return np.array([vx, vy, ax, ay]) def initial_state(self): return np.array([0.0, 0.0, 10.0, 0.0])第二步是写对应的目标函数。导弹对攻场景的末端代价可以定义为与目标位置的距离和剩余速度的函数过程代价则惩罚过大的过载。第三步是把它注册进 games/registry.py然后新增一个 scene 配置项。核心求解器和采样策略完全不用动因为 Dynamics 基类已经约定好了接口。如果想把采样打靶换成强化学习策略只需要在 games 层加一个策略适配器把采样打靶的choose_controls替换成模型推理。采样 rollout 部分不要删它在训练阶段充当模拟器让模型通过试错学习追逃策略这种方式比直接从真实环境采样的收敛速度快得多。替换决策器的重点是保持接口一致输入完整状态输出控制量。追击者和逃逸者可以各用一个独立模型也可以共享模型但传入不同角色标号。模型输出角速度后要与 max_turn_rate 做 clip这一点容易被忽略导致训练好的策略在仿真里正常一放进实时渲染就出现大幅度抖动。从那以后我每次拆这类开源项目都会先画一遍状态、代价、决策三件套的依赖关系再动手改代码。改完一个新场景也强制跑一次最短参数扫描确认数值稳定后再往上加逻辑。希望这个项目的拆解过程和调参记录能帮到你跑通第一局追逃也祝你改出自己的微分博弈场景。本文还有配套的精品资源点击获取