Pooltool

A Python billiards sandbox simulator emphasizing realistic physics, published in JOSS.

基本信息

核心技术点

物理引擎架构

Pooltool 的物理引擎采用事件驱动架构，将碰撞解析与轨迹演化分离：

PhysicsEngine
├── resolver: Resolver        # 碰撞事件解析（可插拔）
├── (evolve: 硬编码轨迹演化)   # 滑动/滚动/旋转轨迹

核心碰撞模型 (pooltool/physics/resolve/models.py)：

关键解析模块 (pooltool/physics/resolve/)：

• ball_ball/ — 球-球碰撞解析
• ball_cushion/ — 球-岸碰撞解析
• ball_pocket/ — 球-袋口碰撞
• stick_ball/ — 球杆-球碰撞（v0.6.0 升级为一级事件）
• sphere_half_space_collision.py — 球-半空间碰撞底层算法
• stronge_compliant.py — Stronge -compliant 模型实现
• transition/ — 状态转换（滑动→滚动→纯滚动）

四次方程求解器

v0.6.0 引入 Algorithm 1010 (Orellana & De Michele, 2020) 四次方程解析求解器，碰撞时间逐对实时计算，替代预计算。

事件系统

• pooltool/events/ — 事件抽象层 (datatypes, factory, filter, utils)
• 事件优先级系统处理同时碰撞（如 Newton's Cradle 连续接触）
• 支持 simulate_with_snapshots() 捕获每一步模拟内部状态

数学库

• pooltool/ptmath/ — 四元数与旋转数学工具
• pooltool/ai/aim/ — 瞄准算法
• pooltool/ai/pot/ — 进球路径计算

支持的游戏类型

架构模块

pooltool/
├── physics/       # 物理引擎（resolve/evolve/）
├── objects/      # 游戏对象（ball/ball/cue/table/）
├── game/         # 游戏状态与规则
├── ruleset/      # 规则实现（eight_ball/nine_ball/snooker/...）
├── system/       # 渲染系统
├── events/      # 事件驱动框架
├── serialize/   # 存档序列化（msgpack/h5）
├── ai/           # AI 瞄准与进球
├── ani/          # 动画
├── evolution/    # 演化相关
├── config/       # 配置
├── utils/        # 工具
├── main.py       # 入口
└── interact.py   # 交互接口

sandbox/ 目录包含大量示例：

• break.py — 开球
• break_forever.py — 无限开球
• newtons_cradle.py — 牛顿摆
• custom_table.py — 自定义球台
• parallel_playback.py — 并行回放

依赖栈

对公司 AI 游戏的参考价值

技术亮点

• v0.6.0 最新变更（2026-03）：Stronge Compliant 替代 Mathavan 2010 成为默认；Poetry → uv 构建系统迁移；快照系统；四次方程解析求解
• 发布于 JOSS：@article{Kiefl2024, doi = {10.21105/joss.07301}}
• 科学支撑：物理模型引用 Billiards.colostate.edu (Dr. Alciatore) 技术证明与 peer-reviewed 论文
• 多平台：sys_platform 分支处理 macOS (Panda3D 1.10.x) vs 其他平台 (Panda3D 1.11.x dev)