一个无限网格、多状态、规则可调的元胞自动机交互式演示。 Python（numpy 向量化）负责元胞自动机演化计算，浏览器端用 WebGPU 绘制 彩色圆点，前后端通过 WebSocket 以增量 diff 通信。
-orange){kind=icon}
2D 平面（z=0）与 3D 立体（Moore 26/18/6 邻域）均可演化的元胞自动机演示。 支持经典生命游戏、HighLife、Brian's Brain、Cyclic 等 8 种内置规则， 以及出生/存活/衰变参数全可调的自定义规则。
| 需求 | 实现方式 |
|---|---|
| 🧮 无限大小 | 稀疏存储：只保存活细胞（死亡细胞不占内存）；引擎坐标范围 ±2^20-1 格（约 ±100 万），配合 key 编码（每轴 21 位 int64）实现超大范围漫游 |
| 🎨 彩色圆点 | WebGPU instanced quad 渲染，每个细胞一个圆点，颜色按状态映射（状态 1..7 固定调色板，>=8 自动 HSV 循环色相） |
| ⚙️ 可调整元胞行为 | 参数化规则模型 + 8 个内建预设 + 规则编辑器（出生/存活数、状态数 k、衰变模式全部可调） |
| 🚀 不卡顿 | 引擎全向量化（无 Python 循环）；通信只传增量 diff；渲染单次 draw 调用批量完成 |
| 🧪 多状态规则 | 支持 Brian's Brain（三态）、Cyclic（任意 k 态）等带衰变规则 |
环境要求：Python 3.12（conda 推荐）、支持 WebGPU 的浏览器 （Chrome 113+ / Edge 113+ / Firefox 126+ / Safari 18+）。
# 1. 创建 conda 环境（自动探测 conda 位置，含未加入 PATH 的安装）
python scripts/setup_env.py
# 或直接双击 run.bat（一键完成创建 + 启动，Windows）
# 2. 启动服务器
conda activate ca-web
python backend/server.py
# 3. 浏览器打开
# http://127.0.0.1:8000| 操作 | 功能 |
|---|---|
| 左键拖动 | 平移视口（无限漫游） |
| 右键单击 | 绘制细胞（快捷绘制） |
| 右键拖动 / Shift+左键拖动 | 旋转视角 |
| Ctrl+左键单击 / 拖动 | 绘制 / 擦除（画笔模式与状态可调） |
| 滚轮 | 缩放（锚点为光标） |
| 空格 / S | 播放-暂停 / 单步演化 |
| 拖拽边界角点手柄 | 调整有限空间边界（设置后边界外细胞无法存活） |
| 顶部工具栏 | 播放控制、速度（1–120 ticks/s）、画笔、统计 |
| 右侧面板 | 预设规则、规则编辑器、图案库、操作提示 |
| 预设 | 规则 | 邻居 | 描述 |
|---|---|---|---|
| 稳定聚集体 | B5/S678 | Moore 26 | 经典三维演化，支持稳定立体块结构 |
| 活跃聚集体 | B45/S5678 | Moore 26 | 更活跃的变体，结构更丰富 |
| 相邻聚集体 | B4/S345 | Moore 18 | 面+边邻居（不含体对角），含复制行为 |
| 蔓延粒子 | B2/S | Moore 26 | 雪花般蔓延，无稳定结构 |
| 迷宫纹理 | B3/S123 | Moore 26 | 3D 迷宫纹理 |
| 镜像对称 | B3456/S3456 | Moore 6 | 自互补法则，图案镜像对称 |
| 脉冲波 | 三态衰变（Brian's Brain） | Moore 6 | 脉冲信号三维传播 |
| 循环螺旋 | 六态循环（Cyclic） | Moore 6 | 旋转的三维螺旋波 |
默认规则为稳定聚集体（B5/S678 · Moore 26）。除预设外，右侧面板的规则编辑器 可自由组合出生/存活数、状态数 k 与衰变模式，构造自定义规则。
┌─────────────────────────── 浏览器（WebGPU 渲染） ───────────────────────────┐
│ main.js ── 画布交互 / 渲染循环 / 原点迁移同步 │
│ wsClient.js ── WebSocket 客户端 + 前端稀疏存储（CellStore） │
│ renderer.js ── WebGPU instanced quad 圆点渲染（WGSL 着色器） │
│ camera.js ── 3D 轨道相机（旋转 / 平移 / 缩放） │
│ ui.js ── 规则编辑器 / 控制面板 │
└──────────────────────────────────┬──────────────────────────────────────────┘
│ WebSocket（JSON 增量 diff）
┌──────────────────────────────────┴──────────────────────────────────────────┐
│ backend/server.py ── FastAPI：静态文件 + WebSocket 会话管理 │
│ backend/engine.py ── numpy 向量化稀疏引擎（无限网格演化） │
│ backend/rules.py ── 参数化规则模型 + 预设注册表 │
└─────────────────────────────────────────────────────────────────────────────┘
- 稀疏引擎：
coords/states平行数组只存活细胞。每个 tick 分四阶段全向量化： 候选集生成（活细胞按邻居偏移展开 + 去重）→ 邻居计数（坐标编码为 int64 key +searchsorted集合判定）→ 状态转移（查表）→ 边界外活细胞强制死亡。 - 增量 diff 通信：每 tick 只传状态变化的细胞（坐标 + 新旧状态）， 附容量上限（50k/tick），超限自动暂停防网络拥塞。
- 大范围坐标：坐标经 key 编码（每轴 21 位 int64）后支持 ±2^20-1 格范围， 远超可视需求；前端用 double 精度直接存储绝对世界坐标，无需浮点迁移。
- 单 draw 调用渲染：所有细胞拼进一个实例缓冲（stride 12B），
一次
draw(6, N)完成，GPU 顶点上限 64K（超限截断显示，UI 警告）。 - 容量保护：活细胞总数超过上限（默认 20 万）时自动回滚到上一 tick 快照并暂停，避免后端与网络被拖垮。
cellular-automaton/
├── backend/
│ ├── engine.py # numpy 向量化引擎（稀疏网格 + diff 生成）
│ ├── rules.py # 规则模型（BSRule / DecayRule）+ 8 个预设
│ ├── patterns.py # 2D 经典图案 + 3D 立体图案库
│ ├── server.py # FastAPI 服务器（静态文件 + WebSocket）
│ └── __init__.py
├── frontend/static/
│ ├── index.html # 页面骨架
│ ├── css/style.css # 样式
│ └── js/
│ ├── main.js # 入口：组装 + 交互 + 渲染循环
│ ├── camera.js # 3D 轨道相机（旋转 / 平移 / 缩放）
│ ├── renderer.js # WebGPU 渲染器（WGSL 着色器内嵌）
│ ├── wsClient.js # WebSocket 客户端 + 前端稀疏存储
│ └── ui.js # 界面控制
├── docs/protocol.md # WebSocket 消息协议
├── scripts/setup_env.py # conda 环境自动创建
├── tests/test_engine.py # 引擎单元测试（25 项，覆盖 2D/3D/衰变/边界/容量回滚）
├── environment.yml # conda 环境定义
└── run.bat # 一键启动脚本（Windows）
# 运行单元测试
conda activate ca-web
python -m pytest tests/ -v欢迎提交 Issue 与 Pull Request。项目无打包/构建步骤、无 lint 配置，
改动请保持同样的极简风格；新增引擎行为请附单元测试
（见 tests/test_engine.py），并在提交前通过 python -m pytest tests/ -v。
客户端 → 服务器：
init / set_rule / play / pause / step / clear /
set_cells / place_pattern / set_boundary / reseed / set_tps
服务器 → 客户端：
init（全量快照）/ diff / draw_diff（增量变化）/ stats / paused /
error / rule_ack / clear_ack / boundary_ack / status
详见 docs/protocol.md。