c3a57256ac
三件事，其中后两件是实测查出来的。
## ① McfoldBridge：「同包直调」在 intermediary 下失效 ⇒ 改反射
原来把桥类放进 `net.minecraft.client.renderer` 包，靠**同包**访问
GameRenderer 的 package-private 方法。这个技巧只在 **named** 下成立：
named 桥与 GameRenderer 同在 net.minecraft.client.renderer ⇒ 同包 ✅
intermediary GameRenderer → net.minecraft.class_757（包变成 net.minecraft）
桥仍在 net.minecraft.client.renderer ⇒ 异包 ❌
⇒ IllegalAccessError: McfoldBridge tried to access method
'void net.minecraft.class_757.method_34538(...)'
★ **包名本身也被 remap**，所以「靠包名对齐」切换命名空间就断了。
反射 + 语义名（McfoldNames）与命名空间无关，是唯一两态都通的形态。
（gen_1_21 本来就为 loadEffect 用了反射，现在两处统一。）
## ② Sodium 通知：装载地形渲染的 mod 现在能看见了（根因三层，逐层实测）
**症状**：装了 Sodium 后画面只有天空、chunks=0，而 blockinfo 能正确读出
方块 ⇒ 数据在，只是它不知道。
**三层根因（每层都有实测数据）**：
┌ ① mixin 永不命中
│ Sodium 挂在 replaceWithPacketData 内 @At(INVOKE onChunkLoaded, AFTER)
│ 而 1.20.1 该方法**内部不调** onChunkLoaded（在 getChunk/drop 里各有一处）
│ ⇒ 它的 ChunkTracker 从未被告知任何区块
│ 【修】notifyRenderTracker() 补通知
│
├ ② 反射签名错
│ ChunkTrackerHolder.get 的参数是 **ClientLevel** 不是 Level
│ 第三参数是**位掩码 int** 不是 ChunkStatus 对象（签名 (III)V）
│
└ ③ ★ status 值错（真正的那道坎）
Sodium 的语义：
FLAG_HAS_BLOCK_DATA = 1 FLAG_HAS_LIGHT_DATA = 2 FLAG_ALL = 3
而 ChunkTracker.updateMerged 的 2×2 邻域判定是
`四邻 status 按位与 == 3` （字节码 :54 iand / :71 iconst_3）
⇒ 传 1：1&1&1&1=1 ≠ 3 ⇒ 全部判成"凑不齐 2×2"
⇒ chunkReady 恒 0、loadQueue 恒空、画面无地形
传 3：3&3&3&3=3 == 3 ⇒ 25 个 2×2 组就绪 ⇒ 重建队列有 25 项
（我们确实有光照数据：注入时跑了 light.runLightUpdates()）
**实测对比**（同一场景 7×7=49 区块）：
传 1: chunkStatus=49 chunkReady=0 loadQueue=0 colors=4748
传 3: chunkStatus=49 chunkReady=25 loadQueue=25 colors=113546
★ 走反射 + 类不存在时静默跳过 ⇒ 不装 Sodium 时零影响。
这不是"给某个 mod 打补丁"：注入路径缺了"区块已就绪"广播，
补上它对所有依赖该事件的 mod 都有效。
**同时广播官方的 level.onChunkLoaded(pos)** —— 与网络包路径等价的那一步。
## ③ hideGui：截图场景关掉 HUD
走**官方选项** `options.hideGui`（= 游戏里 F1），不改渲染代码 ——
GameRenderer.render 里就是 `if (!options.hideGui) gui.render(...)`。
为什么要关：截图只关心画面，HUD 是噪声，而且它给 distinctColors
掺一大块固定像素（实测污染判据）。
两个世代后端都加了 hideGui；Python 侧 set_view(hide_gui=...)。
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 方块可行的版本分界 |
进度
- P1 按文件夹解析版本（
mcfold/version.py，6 项回归全绿） - P2 声明式 protodef 解释器（
mcfold/protodef.py） 真实握手字节解码通过（proto=763 / login success / play 包路由） - 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) |
进度（续）
-
P4 区块解析（
mcfold/chunk.py，11 项回归全绿） 位打包 / 单值·本地·全局调色板 / 生物群系 section / 世界边界 关键行为：越界 state id ⇒unknown(id)（对照 mineflayer 的静默错配） -
P5 mod jar 解析（
mcfold/modjar.py，8 项回归全绿） 三种加载器真实样本验证（Forge / NeoForge / Fabric）+ 多加载器 jar 诊断 可提取：mod id / 名称 / 版本 / 方块名清单 / 物品名清单 诚实边界：拿不到 state id（已在摘要里明说，见附录 D） -
P6 世界模型（
mcfold/world.py，7 项回归全绿） 多区块聚合 / 负坐标定位 / 世界高度边界 关键语义：unloaded（没收到）与air（真是空气）必须可区分 mod 方块计入unknown_state_ids，世界摘要带告警 -
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