# GeWu

**Repository Path**: studyzy/GeWu

## Basic Information

- **Project Name**: GeWu
- **Description**: 格物
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 格物 GeWu

面向中文用户的 2D 物理沙盒，功能域对标 **Algodoo**，基于 **Godot 4.7** 构建。

> 名字出自《大学》"格物致知"。清末以"格致学"译 physics，与"探究物理"精确对应。
> 不含 algo / phun / doo 元素，与 Algodoo / Algoryx 商标族无近似风险。

---

## 现在能做什么

**打开并游玩 Algodoo 官方场景，也能从零创作。**

```bash
cd project
godot --headless --path . --import      # 首次运行必须，建立资源缓存
godot --path .                          # 启动编辑器
```

启动后右侧是 **100 个官方场景列表**，点一个立刻打开。

| 你想要的 | 怎么做 |
|---|---|
| 看官方场景 | 右侧列表点选 |
| 一笔搞定所有工具 | `K` 速写整合：画形状＝多边形/方/圆（按住变形），直线穿物＝擦除，末端急转＝切割，画叉＝固定，物内小圈＝轴承，带环的线＝弹簧，连线＝链条，圈住＝选择 |
| 画图形 | `X` 矩形 / `C` 圆 / `P` 多边形 / `B` 画笔 |
| 搭机械 | `H` 轴 / `F` 固定 / `S` 弹簧 / `G` 齿轮 / `N` 链条，选中轴后可开电机 |
| 施力与轨迹 | `O` 推进器 / `D` 拖曳施力 / `E` 轨迹笔 |
| 玩水 | 选中物体 → 编辑菜单 → 液化成水 |
| 玩光学 | `L` 激光笔；官方 `Prism.phz` 看彩虹 |
| 调贴图 | `U` 纹理工具（拖动平移 / Shift 旋转 / Ctrl 缩放） |
| 切割 | `T` 画线切物体；画闭合形状可挖洞 |
| 合并形状 | 选中 2 个物体 → 编辑 → 合并形状（并集/交集/相减）|
| 撤销 | `Ctrl+Z` |
| 保存 | 文件 → 保存为 .phz… |

详见 [交付说明](docs/00-交付说明.md)。

### 实测数据

| 指标 | 结果 |
|---|---|
| 官方场景解析 / 装配 | **100 / 100** |
| 几何体还原 | box 1472、circle 3822、polygon 1304、plane 329 —— **100%** |
| 齿轮咬合 | A: -12.36 rad/s，B: +12.29 rad/s（方向相反） |
| 弹簧收敛 | 理论平衡点误差 **0.99%** |
| 焊接刚性 | 相对漂移 **0 m**（PinJoint2D 对照漂 0.0224 m） |
| 棱镜色散 | 红紫分离角 **12.86°**（解析值 13.03°） |
| 水流体 | 体积保持 **1.00**（PBF 求解），不穿透容器 |
| 切割 / CSG | 切 4×2 矩形得两半各 4 米²；挖洞 16→15 米²；并/交/差全部正确 |
| 场景基准 | 8 / 8 代表性官方场景端到端通过 |
| Thyme 脚本 | `thyme.cfg` 原文示例全部可跑 |
| 全量测试 | 单元 14 + 集成 7 + 语料 4 + Rust 116，**全绿** |

---

## 目录结构

```
GeWu/
├── docs/                         全部中文文档
│   ├── 00-交付说明.md            如何运行、操作、已知限制
│   ├── 01-plan.md                复刻计划（含对上一版分析的 6 处修正）
│   ├── 02-algodoo-scene-format.md  .phz / .phn 格式规范
│   ├── 05b-physics-curriculum-index.md  **教学知识点文档总索引（从这里进）**
│   ├── 06-kp-primary-science.md  小学科学知识点 60 条 + Algodoo 可行性
│   ├── 07-kp-junior-physics.md   初中物理知识点 89 条 + Algodoo 可行性
│   ├── 08-kp-high-school-physics.md 高中物理知识点 66 条 + Algodoo 可行性
│   ├── 09-algodoo-capability-map.md  **能力证据表 + 215 条总索引 + Demo 路线图**
│   ├── 10-official-scenes-index.md   100 个官方场景实测物理构成
│   ├── m0-report.md              M0 阶段实测报告（场景导入）
│   ├── m1-report.md              M1 阶段实测报告（编辑器与撤销）
│   └── m2-report.md              M2 阶段实测报告（约束族）
├── project/                      Godot 4.7 工程
│   ├── src/phn/                  .phn 解析（词法 / 解码 / 解析 / 加载）
│   ├── src/scene/                实体模型、几何工具、渲染
│   ├── src/edit/                 命令模式与撤销栈
│   ├── src/tools/                绘制 / 选择变换 / 约束工具
│   ├── src/physics/              刚体同步、关节构建与管理
│   ├── src/ui/                   编辑器与播放器
│   ├── tests/                    单元 / 集成 / 语料回归
│   └── assets/data/gbk_map.bin   GBK → Unicode 映射表（Godot 无内置 GBK 解码）
├── rust/                         Rust 核心算法（GDExtension 用，不用 C/C++）
│   └── gewu-core/
│       ├── src/gbk.rs            GBK 编解码
│       └── src/phn/              .phn 解析器
└── tools/
    ├── algodoo-survey/           把 Algodoo 资源转成结构化数据
    ├── unpack_scenes.py          .phz 批量解包（Rust 回归测试用）
    └── gen_gbk_table.py          生成 Rust 版 GBK 表
```

---

## 技术选型

| 关注点 | 选择 | 说明 |
|---|---|---|
| 引擎 | Godot 4.7 | MIT 许可 |
| 脚本 | GDScript | 界面、工具、场景装配 |
| 核心算法 | **Rust** | 场景解析、几何运算、未来的物理求解器与流体；**不用 C/C++** |
| 2D 物理 | Godot PhysicsServer2D | 先用内置，M2 精度不够再上自研 |
| 场景格式 | `.phz`（ZIP）+ `.phn`（码页感知文本） | 见 [格式规范](docs/02-algodoo-scene-format.md) |

---

## 快速开始

### 1. 准备 Algodoo 资源（可选）

播放器默认读取本机解压的 `Algodoo.app/Contents/Resources/scenes`。
这些文件**不入库**（体积大、版权归 Algoryx），见 `.gitignore`。

### 2. 结构化 Algodoo 素材

```bash
python3 tools/algodoo-survey/survey.py "Algodoo.app/Contents/Resources/scenes"
python3 tools/algodoo-survey/extract_lang.py "Algodoo.app/Contents/Resources/data/language/简体中文.cfg"
```

产物在 `tools/algodoo-survey/out/`，其中 `fields.csv` 与 `sim_defaults.csv` 是实现属性的权威清单。

### 3. 跑测试

```bash
# Godot 侧（100 个场景）
project/tests/run_all.sh

# Rust 侧
cd rust && cargo test
# 真实语料回归（需要先解包）
python3 tools/unpack_scenes.py /tmp/gewu_scenes
GEWU_SCENES=/tmp/gewu_scenes cargo test --manifest-path rust/Cargo.toml --test corpus
```

---

## 路线图

| 里程碑 | 内容 | 状态 |
|---|---|---|
| M0 | 场景导入 + 装配 + 物理播放 | ✅ 完成 |
| M1 | 画笔 / 圆 / 矩形 / 多边形 + 撤销重做 | ✅ 完成 |
| M2 | 约束族：轴、固定、弹簧、电机、链条、齿轮 | ✅ 完成 |
| M3 | 流体（SPH） | ✅ 完成（PBF 求解，体积保持 1.00） |
| M4 | 材质 / 调色板 / 贴图 + 场景导出 | ✅ 完成 |
| M5 | 光学（激光、折射、反射）与电路 | ✅ 完成 |
| M6 | Thyme 脚本 | ✅ 完成 |
| M7 | 基准对照与调参 | ✅ 完成（8/8 场景端到端通过） |
| M8 | 工具层补齐：齿轮 / 链条 / 推进器 / 轨迹笔 / 纹理 / 拖曳 + 工具选项面板 | ✅ 完成（21/21 工具，898 条新断言）|

## 编辑器（M1 + M2）

```bash
godot --path project
```

| 按键 | 工具 | 说明 |
|---|---|---|
| Q / M / W / R | 选择 / 移动 / 旋转 / 缩放 | 点选、框选（SHIFT 追加）、拖动变换 |
| X / C / A | 矩形 / 圆 / 平面 | 拖拽绘制，SHIFT 画正方形或 15° 吸附 |
| P / B / E | 多边形 / 画笔 / 轨迹笔 | 自由笔迹；轨迹笔挂在物体上记录运动路径 |
| H / F / S | 轴 / 固定 / 弹簧 | 约束族：点物体接背景，弹簧拖拽连接 |
| G / N | 齿轮 / 链条 | 齿轮拖半径、链条拖路径；各自**一条**撤销记录 |
| O / D | 推进器 / 拖曳 | 推进器恒定力；拖曳在播放中施力（可拖重心、可锁旋转） |
| U | 纹理 | 左拖平移、Shift+左拖旋转、Ctrl+左拖缩放 |
| L / T | 激光笔 / 切割 | 拖放激光，画线切物体 |
| 空格 | 播放 / 暂停 | |
| Ctrl+Z / Ctrl+Y | 撤销 / 重做 | |
| Delete | 删除选中 | |

> 橡皮擦没有快捷键——Algodoo 里 `E` 是循迹绘图器，橡皮擦本身无键位，本项目与官方保持一致。
> 每个工具自己的参数（链条节距、齿轮齿数、推进器推力、轨迹寿命、拖曳强度、纹理角度）在
> 左上角**工具选项**面板里，随当前工具切换。

## 测试

```bash
project/tests/run_all.sh          # 全量（需要 Algodoo.app 语料）
tools/preflight.sh                # 与 CI 完全相同的检查（不需要语料）
```

四组：单元（15 个脚本）、集成（12 个脚本）、M0 语料回归（4 个）、Rust（140 项）。
当前**全部通过**。

### 语料依赖

官方场景语料（`Algodoo.app/Contents/Resources/scenes`）**有版权、不入库**。

- **本地开发**：把 `Algodoo.app` 放在仓库根目录，或设 `GEWU_SCENES=<场景目录>`
- **CI**：没有语料，依赖语料的测试会**优雅跳过**（`tests/framework/test_corpus.gd` 统一处理）

> 为什么要在意这个：语料缺失时测试如果报错退出而不是跳过，CI 就永远是红的。

### CI

`.github/workflows/ci.yml`，三个并行 job：

| Job | 内容 |
|---|---|
| **Rust 测试** | `cargo test --workspace --all-targets`、`cargo fmt --check`、`cargo clippy -D warnings` |
| **Godot 测试** | 安装 Godot 4.7.2 headless → 导入资源 → 逐脚本跑单元+集成 → 主场景启动检查 |
| **代码规范** | 每个 `.gd`/`.rs` 源文件头部必须有中文注释；所有文本文件必须是合法 UTF-8 |

另有 `ci-status` job 汇总三个结果，设置分支保护时只需勾这一项。

**push 前建议先跑 `tools/preflight.sh`** —— 它做的是完全相同的事，
避免"推上去才发现 fmt 没过"的来回。

---

## 三个必须知道的事实

1. **Algodoo 的物理内核是 AGX Dynamics（商业引擎）**，`physics::` 只是玩法层封装。
   所以"逐位复刻数值"不可行，目标是核心体验对等。
2. **`scene.phn` 不是 UTF-8**。非 ASCII 字符写成 `\xNN;`，NN 是系统码页字节；
   简体中文 Windows 上是 GBK。中文场景的标题、贴图名全靠这条规则解码。
3. **`checksums.txt` 不是标准 CRC32**（296 条记录匹配数为 0）。导入器只做存在性检查，
   真正的一致性由 ZIP 中央目录负责。

---

## 合规

- 本项目是**个人学习性复刻**，不主张净室。
- Algodoo 的材质贴图、语言词条版权归 Algoryx，**不随本项目分发**；
  仓库内只保留从官方资源提取出来的"规格"（字段表、参数表、词条基线）。
- **GUI 图标**（`project/assets/skin/gui/`，37 张）目前直接复用本机 Algodoo 2.2.4
  `skins/default/gui` 的原图，目的是让没装 Algodoo 的平台（Windows）也能显示真图标。
  裁切归一化步骤见 `docs/25-gui-spec.md`「图标来源」。这批图是**临时占位**，
  后续换成自有素材时保持文件名不变即可，代码不用动。
- 若未来商业化，须替换全部美术与文案素材，并重写为规格驱动实现。