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 scaffold —— 用官方客户端渲染，但不跑客户端
目标（用户 2026-09-25 定向）：不起完整客户端，把 MC 的渲染能力抽出来， 用我们自己的世界数据驱动它出图。
实测结论（2026-09-25 全绿）
客户端 jar 是 ProGuard 全量混淆的（LevelRenderer 叫 fjv），
所以「抽渲染器」的第一步必须是反混淆。全部关卡已验证：
| 关卡 | 证据 | 结果 |
|---|---|---|
| 反混淆 | client-named.jar；javap 读出 LevelRenderer |
✅ |
| GL 离屏 | Xvfb + llvmpipe → OpenGL 4.5 core | ✅ |
| 渲染栈初始化 | new Minecraft(cfg) 完成初始化，不进主循环 |
✅ |
| 资源重载 | 22 个 listener；ModelManager/FontManager/Dispatcher 全 ok | ✅ |
| 注册表 | 客户端自带 data/ → dimension_type=4 |
✅ |
| 区块注入 | 81 chunks → countRenderedChunks=29 |
✅ |
| 真实世界渲染 | 草地+原木+树叶+天空+HUD 文字，distinct colors=1450 |
✅ |
见 sample-world-render.png。
为什么渲染器不能独立 new
反编译（Vineflower）实测签名：
LevelRenderer(Minecraft, EntityRenderDispatcher, BlockEntityRenderDispatcher, RenderBuffers)
renderLevel(PoseStack, float, long, boolean, Camera, GameRenderer, LightTexture, Matrix4f)
全挂在 Minecraft 单例上 ⇒ 不能 new LevelRenderer() 独立用。
正确形态是「初始化 MC 渲染栈，但不跑主循环」。
权威序列
初始化（反编译 net.minecraft.client.main.Main）：
SharedConstants.tryDetectVersion(); // 漏了 → "Game version not set"
SharedConstants.enableDataFixerOptimizations();
Bootstrap.bootStrap();
RenderSystem.initRenderThread();
RenderSystem.beginInitialization();
Minecraft mc = new Minecraft(gameConfig);
RenderSystem.finishInitialization();
渲染一帧（反编译 Minecraft.render()）：
RenderSystem.clear(16640, ON_OSX);
mainRenderTarget.bindWrite(true);
gameRenderer.render(partialTick, nanos, true);
mainRenderTarget.unbindWrite();
mainRenderTarget.blitToScreen(w, h);
window.updateDisplay();
踩过的坑（全部有实测证据）
- 漏
tryDetectVersion()→DataFixers.<clinit>抛Game version not set FolderData参数顺序 =(gameDirectory, resourcePackDirectory, assetDirectory, assetIndex)—— 写错则icons/icon_16x16.png404- assetIndex 要用落盘名（
1.20.1）而非version.json的assetIndex.id（5） —— MCLC 按version.number落盘 LoadingOverlay必须摘 → 否则永远渲出 Mojang 加载屏ReceivingLevelScreen（"Joining world..."）必须清 → 否则客户端认为未进世界- 必须跑
mc.tick()→ 区块网格重建队列靠 tick 推进（不跑则countRenderedChunks=0） reloadResourcePacks()不可 join（等主循环 → 死锁）； 正解是直接调各 listener 的 publicreload()，barrier 同步返回、 apply 用Runnable::run（主线程即渲染线程）GameRenderer.reloadShaders包私有 → 同包 bridge 调用- 读像素必须绑 FBO（
glBindFramebuffer(target.frameBufferId)+GL_COLOR_ATTACHMENT0）；bindRead()路径实测读到的是残留缓冲 - 判据要锐利：
non-black=100%会被红底加载屏骗过；distinct colors才区分得出「加载屏(199) vs 世界(1450)」
注入世界数据
LevelChunk chunk = new LevelChunk(level, new ChunkPos(cx, cz));
chunk.setBlockState(new BlockPos(lx, y, lz), Blocks.GRASS_BLOCK.defaultBlockState(), false);
// ★ 放进 ClientChunkCache.Storage.chunks（反射 getIndex）
// ★ 光照：LightEngine.queueSectionData(SKY/BLOCK, SectionPos, DataLayer 全15)
// ★ 触发重建：levelRenderer.allChanged() + 每帧 mc.tick()
与 mcfold Python 客户端的接口：ClientChunkCache.replaceWithPacketData(...)
接收的正是 map_chunk 包原始字节 —— Python 客户端收到的就是它，
可零转换直通；或用 Python 解码后的方块写入 LevelChunk。
注册表：state id ↔ 方块名（mod 支持的关键）
BuiltInRegistries.BLOCK.size() // 1003
Block.BLOCK_STATE_REGISTRY.size() // 24135
Block.stateById(1003) // note_block[instrument=xylophone,note=7,powered=false]
BuiltInRegistries.BLOCK.getKey(state.getBlock())
★ 更正附录 D 的一个错误结论：1003 → note_block 不是静默误映射
—— note_block 有 800 个状态，1003 真的落在其范围内。真客户端给的是完整状态
（instrument/note/powered），这正是 1.20.1 上 mod 方块语义的唯一权威来源。
构建
./build.sh /path/to/store/vanilla-1.20.1 1.20.1
视距（render distance）
★ 三处都要设，缺一则视距不生效（全部实测）：
mc.options.renderDistance().set(rd); // 本地设置
mc.options.setServerRenderDistance(rd); // 模拟服务端下发的上限
level.getChunkSource().updateViewRadius(rd); // ClientChunkCache 的 storage 半径
为什么第三处必需：官方只在收到服务端半径包时才调 updateViewRadius
（ClientPacketListener.java:2316）。我们不连服，所以必须自己调 ——
否则 Storage.inRange 用旧半径判定，超出的区块被静默丢弃。
★ 加载半径必须跟随视距：视距设 12 但只喂 3 圈数据， 画面看起来就像视距没生效（这是最容易误判「设了没用」的坑）。
实测对比（同一相机、同一存档）：
| 视距 | 注入区块 | 渲染区块 | distinctColors |
|---|---|---|---|
| 4 | 81 | 55 | 15226 |
| 12 | 595 | 447 | 18477 |
见 sample-render-distance-4.png / sample-render-distance-12.png。
雾（fog）也由同一处驱动：GameRenderer.renderLevel 每帧取
options.getEffectiveRenderDistance() * 16 传给 FogRenderer.setupFog。