# mcfold — Minecraft 折叠层（净室 Python 实现）

按用户 2026-09-25 定向：**净室 Python 实现**，替代 Node/mineflayer 栈，
使产物可打包分发（无 Node 运行时依赖）。

## 架构

```
底层  mcfold（本工程，Python）
       ├─ 按实例文件夹读版本 → 自动选协议（P1 已完成）
       ├─ 声明式 protocol.json 解释器（protodef）
       ├─ 世界模型（chunk/方块，含 mod 注册表）
       └─ 触发截屏 → 调脚手架 → 官方渲染 jar
中间  可包装为不同 agent 的插件
上层  面向 homeagent 的 Go 包装（复用现有 plugin.go 形状）
```

## 关键实测事实（决定设计）

| 事实 | 证据 |
|---|---|
| 实例文件夹 = 完整 MC 客户端安装 | `versions/<id>/<id>.json` + `.jar` |
| 加载器 id **不是**协议版本 | `minecraft-data('1.20.1-forge-47.4.0')` → FAIL，必须走 `inheritsFrom` |
| protocol.json 是**声明式**的 | `varint`/`pstring`/`mapper`/`switch` 全是数据，非代码 |
| 因此协议**不需重写**，只需解释器 | 111 个 play 包由同一份 JSON 驱动 |
| 1.20.1 **不**在网络上传递方块注册表 | codec 仅 6 类，无 block ⇒ mod 方块必须另寻途径 |
| 1.20.2+ 有 configuration 阶段 | 会发 `registry_data` ⇒ mod 方块可行的版本分界 |

## 进度

- [x] **P1** 按文件夹解析版本（`mcfold/version.py`，6 项回归全绿）
- [x] **P2** 声明式 protodef 解释器（`mcfold/protodef.py`）
      真实握手字节解码通过（proto=763 / login success / play 包路由）
- [x] **P3** 最小客户端 + 跨实现互操作（`mcfold/client.py`）
      **Python 客户端 ←→ Node 服务端握手成功**（两边独立实现，最有说服力）

## 已证实的结论

| 结论 | 证据 |
|---|---|
| 协议**不需重写**，只需解释声明式 JSON | 111 个 play 包由同一份 `protocol.json` 驱动 |
| Python 客户端能真连真服 | Node 侧日志 `SERVER_GOT_LOGIN username= PyProbe` |
| 协议号由实例文件夹决定 | `1.20.1/version.json` → 763 |
| 区块格式**必须自己解**（协议层是声明式，但 chunkData 是不透明 buffer） | `protocol.json` 里 chunkData 只声明为 buffer |
| Python 解码器能解独立实现产出的区块 | prismarine-chunk 产样本 → 4/4 方块命中 |
| mod 方块在本机注册表里**显式 unknown**，而非静默错配 | `state 99999 -> unknown(99999)` |

## 进度（续）

- [x] **P4** 区块解析（`mcfold/chunk.py`，11 项回归全绿）
      位打包 / 单值·本地·全局调色板 / 生物群系 section / 世界边界
      **关键行为**：越界 state id ⇒ `unknown(id)`（对照 mineflayer 的静默错配）
- [x] **P5** mod jar 解析（`mcfold/modjar.py`，8 项回归全绿）
      三种加载器真实样本验证（Forge / NeoForge / Fabric）+ 多加载器 jar 诊断
      可提取：mod id / 名称 / 版本 / **方块名清单** / 物品名清单
      **诚实边界**：拿不到 state id（已在摘要里明说，见附录 D）

- [x] **P6** 世界模型（`mcfold/world.py`，7 项回归全绿）
      多区块聚合 / 负坐标定位 / 世界高度边界
      **关键语义**：`unloaded`（没收到）与 `air`（真是空气）**必须可区分**
      mod 方块计入 `unknown_state_ids`，世界摘要带告警

- [x] **P7** 实例层（`mcfold/instance.py`，8 项回归全绿）
      **传入文件夹路径 → 拉起实例 → 读 mod 注册方块表 → 连服**
      含：加载器版本归一化、裸名展开、歧义处理、越界 state id 归因到 mod

## 累计测试

| 套件 | 项数 |
|---|---|
| 版本解析 | 6 |
| protodef | 6 |
| 区块解析 | 11 |
| mod jar | 8 |
| 世界模型 | 7 |
| mod jar | 8 |
| 实例层 | 8 |
| 跨实现互操作 | 2 |
| **合计** | **48** |

统一入口：`./run_tests.sh`