|
|
d2b4c5029d
|
M4:事件层(可按需排空的日志 + 游标)+ 16 项判据
新增 mcfold/events.py:EventLog(环形缓冲 + seq + 游标)
- 不做回调式推送:LLM 是回合制的,回调会让事件在两次观察之间静默丢失
- drain(limit) 只取本轮、剩余留待下次(不丢)
- 细分层(block_changed❌y:z)独立可查,不污染粗粒度流
- render_events() 输出紧凑文本行,省 token
session 接线:block_change / multi_block_change / chat / damage /
entity spawn·move·destroy / held_item_slot,并加 chat()/command() 发送
修的真 bug:
- dropped 恒 0:deque(maxlen=) 丢元素无声 ⇒ 改手动计数(事件丢了必须说)
- 事件键 to_state_id 与渲染器的 to 不一致 ⇒ 显示 None,改为解出方块名;
from 区分「未加载/界外」而非裸 None
- run_tests.sh 只数 ✓ 不数 ★ ⇒ 判据少报(98 修正为 110)
实测:/setblock 后事件正确报 grass_block→stone→air,与状态层一致
判据:110 项全通过;4 项变异全部被抓
|
2026-09-26 12:27:28 +08:00 |
|
|
|
40b2e1d60f
|
M3:状态层(服务端真状态)+ 包流灌入 + 14 项判据
新增:
- mcfold/state.py WorldState / WorldGeometry / PlayerView / Entity
- mcfold/session.py StateSession:connect() 走完 login→configuration→play,
pump() 把包落进状态,on() 留 M4 事件口
修的真 bug:
- unload_chunk 协议顺序是 chunkZ 在前、chunkX 在后;按 x 先读会坐标互换,
卸载永不命中 ⇒ 区块只增不减(状态撒谎)
设计立场(防越界):
- 只陈述观察、不做决策(nearby_blocks 给统计不给「该挖哪个」)
- 未知 ≠ 没看见:认不出的 state id 显式记账,绝不静默映射成别的方块
- 超范围拒绝并说明,不静默缩小
- 几何从服务端 dimension_type 吸收,不写死 24/384
实测:11 注册表 / 9 区块 / 生命 20 饥饿 20 / 列剖面 bedrock→dirt→grass_block
判据:91 项全通过;4 项变异全部被抓(含「变异空操作 ⇒ 假绿」的核对)
|
2026-09-26 12:21:18 +08:00 |
|
|
|
547f4beb7e
|
M1+M2:1.21.1 构建跑通 + 协议客户端进 play 阶段
M1(构建):
- build.sh 编译 CP 加入 $OUT/fabric/*.jar,解决 net.fabricmc.* 找不到
- gen_1_21 内联 Sodium 通知改为委托共用 RenderCompat,补 reportRenderCompat
- 1.21.1 全量七步构建产物齐备(classes-intermediary.jar / names*.json / srg / inheritance.map)
M2(协议):
- login_start 按协议数据发 UUID(1.21 必填;1.20 可选)
- login_acknowledged / serverbound 包 id 改为查表,不再写死 0x00
- send() 实现压缩帧格式(varint(dataLen)+数据,小包不压)
- configuration 双向协商:发 settings、回 select_known_packs、拒 resource_pack
- protodef 补 bitflags / entityMetadataLoop / count(ctx引用) / compareTo 路径表达式
- NBT 读取器由占位符改为真实现(anonymousNbt 支撑 registry_data)
- 坏包容错:长度前缀是帧层权威,解不开整包丢弃并布告,不断流
实测:login→configuration(11 注册表)→play,位置 (5.5,-60.0,-0.5),map_chunk×9
判据:protodef 6→13 项(含线上真实 entity_metadata 字节回归);全量 77 项通过
|
2026-09-26 12:15:48 +08:00 |
|
|
|
480fe8e225
|
M0 完成:空白测试服(vanilla 1.21.1 / 0 mods)
## 为什么不用现役服(用户定向)
> 我觉得可以起一个空白新服用来测试功能,而不是用现在的服。
理由不只是"干净",而是**可预期**:
现役 `/home/minecraft` 是 world 15G + 64 mods + neoforge ——
任何协议层改动都可能污染它,且**测不出边界**(模组太多、状态太杂)。
我们要验的是**协议与行为**:已知方块集、已知出生点、可重置的世界。
## 形态
store/vanilla-1.21.1/server/ 内容根 jar + 配置 + world
runtime/test-server/ 运行期 server.log / server.pid
- **vanilla 1.21.1**,0 mods(协议最干净,先验协议再逐个加 mod 验差异)
- **超平坦 + 固定种子** `mcfold-test-2026`(地形可预测)
- creative / peaceful / 无怪物 / 无结构 / spawn-protection=0
- **端口 25566**(避开现役 25565)
- server.jar 下载后**校验 sha1**(`59353fb...`,实测一致)
## mcfold/server.py:起停 + 探活
`python3 -m mcfold.server {start,stop,status,reset}`
★ **status 是协议级探活**(Server List Ping,state=1),不是"端口开着就算活":
必须回出 version / protocol / motd 才算真起来。
实测:`1.21.1 protocol 767 players 0/4 motd=mcfold test server`
## tests/test_server.py(4 项,默认套件)
✓ 配置生成一致 —— ★ 守护一个真实踩过的坑:
properties 里写**行内注释**(`k=v # 注释`)会被解析成值的一部分。
我第一版 `level-type=minecraft\:flat \# 超平坦` 就是这样坏掉的
(服务端把它当成值,且 spawn-protection 也回到默认)。
⇒ 生成器**不写行内注释**,这条判据守它。
✓ 三层隔离(内容根 vs 运行期;日志不落内容根)
✓ 端口避让(25566 ≠ 现役 25565)
✓ **协议级探活**(起服时验 protocol == 767;没起服则跳过,不误报)
## 变异验证(工程纪律 #2:判据必须能失败)
把 `PROTOCOL = 767` 改成 `999` ⇒ `test_status_proves_protocol` **变红**
("协议号不符:767 != 999"),还原后恢复绿。
⇒ 这条判据不是恒绿。
## 测试
./run_tests.sh → **70 项**(原 66 + 本套件 4),0 失败
|
2026-09-26 11:12:40 +08:00 |
|
|
|
51ee57e556
|
实例创建接口(Python 层)+ 后端透传新参数
## ① mcfold/instances.py —— Python 提供「建实例」接口
用户定向(2026-09-26):
> 这个文件夹内容也是 python 层创建的,而不是标准游戏目录。
> 即 python 提供创建实例的接口(含 mod/插件的实例,内部有对应目录,
> 插件 mod 放在目录中就会被加载)。
所以实例是**我们定义的目录**,不是一份 MC 客户端安装:
create_instance(name, version=, loader=, mods=[], force=False) → Path
list_instances() → [实例摘要]
find_content_root(version, loader) → 共享只读那层
- 实例内部:`instance.json`(自述)+ **mods/ shaderpacks/ resourcepacks/
datapacks/**(★ agent 的接口面,放进去即生效)+ config/ saves/ logs/
options.txt(MC/加载器自己写的运行时产物)
- **不在实例里建 versions/libraries/assets** —— 那些属于内容根(只读共享)。
放进实例会让「同一版本多实例」变成多份副本,也把「实例私有/版本公有」
的边界糊掉。
- 实例名白名单 `^[A-Za-z0-9._-]{1,64}$`(它要进路径)
- 已存在时**报错而非默默复用**,并提示「换名字 = 装不同 mod 的方式」
★ 这与已有的三层口径一致(mcview/lib/versions.cjs:59/61):
store/<loader>-<version>/ · instances/<name>/ · runtime/<name>/
## ② base.py 三个修正
**(a) cwd 缺省改为 game_dir** —— 版本隔离漏洞:
渲染进程的 cwd 原是仓库根,而 Sodium 等会往 cwd 写 config/
⇒ 实测 config/sodium-mixins.properties 落进了 mcfold 仓库根。
这些产物属于**实例**。已改为 `cwd=self.cwd or self.game_dir`。
**(b) 命名空间按 client jar 形态自动判** —— 原先硬编码 `named`:
官方 obf jar + 加载器 ⇒ intermediary(mod 的 mixin 能解析)
client-named.jar ⇒ named(仅裸启动可用)
实测:named 下 42 个 mod 的 464 处 mixin 全部找不到目标。
**(c) 新增 names_file 参数** —— 把 names.json 路径透给后端
(B 方案的 extern 参数在 Python 侧的可入口)。
|
2026-09-26 10:18:26 +08:00 |
|
|
|
652a460405
|
加 .gitignore,并把 28 个运行期产物移出版本库
## 为什么
35534b1 把 logs/*.log.gz(10 个)与 __pycache__/*.pyc(18 个)
一起提交了,而仓库**根本没有 .gitignore** —— 那不是手误,是缺一道门。
已 `git rm --cached` 那 28 个(磁盘文件保留,只是不再跟踪)。
## 覆盖三类
① 运行期产物:logs/ *.log.gz __pycache__/ .pytest_cache/ …
② **加载器/mod 的运行时配置**:config/ shaderpacks/ options.txt saves/
datapacks/ resourcepacks/
★ 这类属于**实例**,不属于仓库。实测踩过:Sodium 往**进程 cwd**
写了 config/sodium-mixins.properties,落进了仓库根。
根因已修(base.py:cwd=self.cwd or self.game_dir,让运行时产物
落进实例目录),这里再兜一层。
③ 构建缓存:.mcfold-tools/ build/ dist/ *.egg-info/
|
2026-09-26 10:17:14 +08:00 |
|
|
|
8b1fc9289d
|
Fabric 加载器路线跑通并落地验证(launcher="fabric",6/6 绿)
上个会话把 `launcher="fabric"` 写进了后端,却**没有留下任何可重跑的验证** ——
「经加载器能起来」这件事只活在对话里。本次把它变成可复算的。
## 机制(路线 C,不是 LOADERS.md 原来写的 A/B)
A/B 都假设「游戏由 Loader 起」。但 `Knot.init()` 是 public 的:它做完
「发现 mod → 建 KnotClassLoader → 应用 mixin → invokeEntrypoints(preLaunch)」
后**返回**,不进入官方主循环(那在 GameProvider.launch())。
⇒ `knot.loadIntoTarget("McfoldRenderServer")` 把我们的服务端注入同一个
KnotClassLoader —— **mod 生态与我们的控制权同时拿到,不必把服务改写成 mod**。
## 主要改动
### ① `RenderBackend._fabric_classpath()` —— 组装从用户手里移到后端
两个变换是实测必需、且用户不该自己拼的机械操作:
- 剔除 1.20.1 自带的 asm(9.2 与 9.6 两版并存)—— 否则 Knot.<clinit> 抛
"duplicate ASM classes found on classpath"
- 追加 Fabric 的 8 个库(asm×5 / sponge-mixin / intermediary / fabric-loader)
库来源改为内容根 `.mcfold/fabric/`(原在 /tmp/fab,tmpfs 且违反版本隔离)。
实测 67 条 → 去 7 asm + 加 8 fabric = 68 条。
### ② `tests/test_loader_render.py`(新增,6 项)
✓ 启动架构与世代正交(动态子类,不写 N 个类)
✓ 两个架构可枚举
✓ classpath 组装(67→68:去 7 asm,加 8 fabric)
✓ 非 asm 库原样保留(去 asm 是外科手术,不是重写)
✓ **Fabric 加载器真启动并渲染**(KnotClassLoader / chunks=10..25 / colors=4391..4547)
✓ **Fabric 拒绝不兼容 mod** ← 反向对照:缺 fabric-api 的 Explorify 被拒
最后一条是**两条路线的可判差异**:零加载器是「无脑注册」,不知道 mod 要
fabric-api;Fabric 会。没有它,"加载器真的介入了"这句话就没有反面证据。
### ③ `run_tests.sh` —— 慢套件改为列表驱动 + 全跳过不再报绿
- SLOW 列表含 test_render_bridge / test_loader_render(默认不跑)
- ★ 全部跳过的套件**不算绿**:报"跳过 N 项"而非计入通过数 ——
否则"没测"会被读成"测过了"。
## 验证
./run_tests.sh → 62 项(2 个慢套件标 ⊘)
./run_tests.sh --with-render → **76 项全绿**
(62 单元 + test_render_bridge 8 + test_loader_render 6)
## 仍未做
Iris 光影真实加载(加载器已通,未验过一次 shader pack)
forge / neoforge 后端(gen_1_20 / gen_1_21 均待设计)
|
2026-09-26 07:12:41 +08:00 |
|
|
|
a1ce560c05
|
修复渲染联测的两个阻断缺陷(之前 5/7 → 现 7/7)
## ① natives 必须平铺,不能保留包路径
natives-linux jar 里的路径是 `linux/x64/org/lwjgl/<module>/lib*.so`,
而 LWJGL 经 java.library.path / LD_LIBRARY_PATH 按**文件名**找库 ——
嵌套一层的目录它找不到。实测:
UnsatisfiedLinkError: Failed to locate library: liblwjgl.so
at RenderSystem.<clinit> → Tesselator.<clinit>
build.sh 原来直接 `unzip -d $OUT/natives`(保留包路径)⇒ 产物不可用。
改为解到临时目录再 `find -name '*.so' -exec cp` 平铺。
(已用新逻辑重铺 store/vanilla-1.20.1/.mcfold/natives,7 个 .so 在根下。)
## ② api_notes 应为 staticmethod
35534b1 把世代分派改成类级调用后,`api_notes` 仍是实例方法,
测试里 `Gen_1_20.api_notes()` 直接 TypeError。它不读 self ⇒ 一律 staticmethod。
这也是它能"不启动后端就做世代对照"的前提。
## ③ classpath.txt 的语义写进注释
它**只含第三方 libraries**;client-named.jar 与 classes/ 由使用方拼接
(build.sh:88 自己拼,测试/后端从各自路径取)。
在 build.sh 里注明,避免下一个人以为它是"完整运行 classpath"。
## 验证
./run_tests.sh → 62 项全绿
.mcfold classpath + 平铺 natives → 渲染联测 **7/7 全绿**
(injected=49 chunks=31 colors=11714 / placed=1003716 chunks=25 colors=4540)
|
2026-09-26 06:53:30 +08:00 |
|
|
|
35534b1564
|
feat: get_block_info —— 方块信息查询(Java 侧回答,Python 只路由)
新增 cmd=blockinfo(两代后端编译通过、实测):
返回 block 名(含 mod 方块)、stateId、属性、isAir/isSolid、
光照/硬度、贴图缺失的程序化判据、是否来自 mod。
★ 修掉一个真实缺陷(附录 D 的语义区分落到了实处):
未加载区块原先返回 void_air(known=true),实测发现两个 API 都不可用:
- ClientLevel.hasChunk() 反编译实测**恒返回 true**
- ChunkSource.hasChunk() 走 getChunk(...,false),而 ClientChunkCache
覆写后在该参数下返回 emptyChunk(占位,非 null)⇒ 也恒 true
正解:getChunk(..., requireChunk=**false**) 判 null
(反编译:return requireChunk ? emptyChunk : null;)
⇒ 现在未加载明确回 known=false + reason=chunk_not_loaded
实测(1.20.1):
草地 → minecraft:grass_block props={'snowy':'false'} missing=False
原木 → minecraft:oak_log props={'axis':'y'}
空气 → minecraft:air
远处 → known=false reason=chunk_not_loaded ← 与空气区分
实测(1.21.1 + mod):
mts:mtsofficialpack.fancydirt_block mod=True tex=mtsofficialpack:block/fancydirt
createbigcannons:steel_block mod=True tex=createbigcannons:block/steel_block
⇒ mod 方块同样能查到正确贴图名与 fromMod 标记
顺带修 gen_1_21 两处世代差异(ChunkStatus 换包、bridge 编译顺序)。
测试:69 项全绿(新增 test_get_block_info 6 条判据)
|
2026-09-26 00:24:29 +08:00 |
|
|
|
16f2e04fff
|
架构重构:差异全部下移到 Java,Python 只做路由
用户口径:差异放在 Java 层,Python 相当于路由。
下移到 Java(新增 cmd=setblocks):
Python 只发 RLE([[stateId,count],...]),Java 用官方 API 完成
调色板组装 / 位打包 / 官方序列化 / 入 cache / 渲染。
★ 意外收益:走 ClientboundLevelChunkPacketData(chunk).getReadBuffer()
+ replaceWithPacketData(...) 这条官方路径,两代签名完全一致
⇒ 原先的 Storage.chunks 反射注入**整段删掉**。
新增 cmd=capacity:世界尺寸(sectionsCount/minSection/defaultBiome)
由运行时回答,Python 不再硬编码 24/-4(1.16 时代是 16/0)。
Python 侧删除(防回归,见 test_import_surface):
render_bridge.py(旧桥,无世代概念)
render._pack/_long_array/_encode_paletted/_encode_chunk/_varint
anvil.encode_block_section/encode_chunk_payload/save_chunk_to_payload
合计 454→374 行(render.py)、300→177 行(anvil.py)
保留在 Python(都是「不随版本变」的知识):
RLE 压缩(rle_encode/rle_decode,具名可测)
存档读取(region/NBT)
方块名→id 的路由(查询在 Java)
NDJSON 协议
测试:62 项单元 + 6 项渲染联测全绿
新测试反映新架构:RLE 边界、运行时容量、世代分派、新路径渲染
test_anvil 里原有 8 项协议位打包测试已删(那已下移到 Java,
由两代后端各自的编译验证覆盖)
新增 scaffold/ARCHITECTURE.md(分层原则 + 加新世代步骤 + 防回归清单)
|
2026-09-25 19:21:45 +08:00 |
|
|
|
253146cffe
|
gen_1_21 实测启动成功 + provision 工具
决定性验证:gen_1_21 后端在 1.21.1 上收到 {"event":"ready"}
⇒ 世代分派架构成立:同一套 Python 层,两个独立编译的 Java 后端
运行时发现第 12 处世代差异(编译期看不出):
1.20.x registryAccess 是可变 LayeredRegistryAccess → 事后反射替换
1.21.x registryAccess 是 final RegistryAccess$Frozen → 反射抛
"Can not set final field"
处理:gen_1_21 改为先载注册表 → 经 CommonListenerCookie.receivedRegistries
传入 → 再构造 listener。比 1.20 的反射做法更干净。
新增 mcfold/provision.py(从官方 manifest 装任意版本,版本无关):
- 跳过音频资源:1.21.1 实测 3911 条里跳过 3744 条
- natives 两种形态都认(1.21 起是独立库条目,非 classifiers)
- 实测 1.21.1:274 文件 / 200MB / 32s / 0 失败
|
2026-09-25 18:35:28 +08:00 |
|
|
|
8c7d5b9d38
|
世代分派体系:Python 层 switch + 各世代独立编译的 Java 后端
用户定向:在 python 层写 switch,调用不同 java 后端(而非一个文件里 switch)。
新增:
mcfold/backends/{__init__,base,gen_1_20,gen_1_21}.py 后端体系与分派
scaffold/java/gen_1_20/ 对 1.20.x client jar 编译
scaffold/java/gen_1_21/ 对 1.21.1 client jar 编译(✅ 实测编译通过)
scaffold/java/VERSION-DIFFS.md 实测差异全表
判据:DeltaTracker 类是否存在(1.21 引入,正是 render 签名变化的根源)
⇒ 比硬编码版本号稳
实测差异共 11 处(21 个检查点里 13 个跨世代完全一致):
setLevel / GameRenderer.render / countRendered* / createPackRepository /
ResourceLocation 构造 / enableDataFixerOptimizations(移除) / User 构造 /
ChunkStatus 包路径 / ClientPacketListener 构造(参数个数语义都变) /
loadEffect(变 private)
为什么必须分后端:DeltaTracker 在 1.20.x jar 中不存在,
两代调用无法共存于一份源码(实测编译报 cannot find symbol)。
1.21.1 反混淆已验证(29MB named jar,DeltaTracker 3 处)
|
2026-09-25 18:21:08 +08:00 |
|
|
|
34ed70ab53
|
修复视距不生效 + 接入统一测试
视距(用户报「无法调整视距?」)——根因是三处不同步:
1. options.renderDistance 本地设置(原先只设了这个)
2. options.setServerRenderDistance 服务端下发上限(getEffectiveRenderDistance = min(两者))
3. ClientChunkCache.updateViewRadius storage 半径
第三处最关键:官方只在收到服务端半径包时才调它(ClientPacketListener:2316),
我们不连服 ⇒ Storage.inRange 用旧半径判定,超出区块被**静默丢弃**。
另一个前置:加载半径必须跟随视距。视距 12 只喂 3 圈数据,
画面看起来就像没生效(最容易误判的坑)。
实测(同相机同存档):
视距 4 → 注入 81 渲染 55 色彩 15226
视距 12 → 注入 595 渲染 447 色彩 18477
画面差异显著:RD=12 能看到延伸到地平线的森林与完整海岸线。
(sample-render-distance-{4,12}.png)
测试:新增 tests/test_anvil.py(13 项,存档/NBT/编码)
tests/test_render_bridge.py(3 项,桥协议+合成渲染+真实存档渲染)
run_tests.sh 改为默认跑单元测试、--with-render 跑联测
合计 61 项全绿(原 48 + 13)
|
2026-09-25 17:47:58 +08:00 |
|
|
|
391d452c85
|
P9:Python 包装层 —— 真实存档 → 官方渲染器 → 出图
新增两模块:
mcfold/anvil.py 存档读取(region/NBT)+ 区块编解码工具
mcfold/render_bridge.py 桥:常驻 Java 渲染器进程,NDJSON 协议
mcfold/render.py 对外入口:WorldRenderer(存档→画面)
scaffold/McfoldRenderServer.java Java 侧服务端(常驻,NDJSON)
实测(真实存档 mc-test,DataVersion 3465=1.20.1):
injected=81 unknownBlocks=0 uniqueSpecs=111
loadedChunks=81 chunksRendered=60 distinctColors=11585
画面:草地/沙滩/树/水/天空/太阳/HUD(sample-real-save-render.png)
★ 分工落在实处(附录 D 的结论变成代码):
存档 palette 是**方块名**(minecraft:oak_log[axis=y]),网络载荷要 **state id**,
名字→id 的权威映射只有客户端注册表有 ⇒ 新增 resolve 命令,
Java 侧用 BlockStateParser.parseForBlock 解析(实测 111 种全中,0 unknown)
踩坑(本轮新发现):
1. level.dat 有两种布局(8字节头+zlib / 直接 gzip)—— 实测本机是后者
2. section 索引 ≠ 绝对 Y:存档用 -4..19,载荷用 0..23(少这步 → readerIndex 越界)
3. 注入前必须 set_viewport,否则 ClientChunkCache.inRange 丢弃区块
4. setPos 不会更新实体区块归属,要 setPosRaw + updateViewCenter
5. 生物群系只影响着色,用统一 plains 不影响「能渲染出世界」
6. camera 回包要用 JsonArray,字符串会被 Python tuple() 按字符拆开
性能:启动 66s(GL+资源重载),之后每帧渲染 ~1s(含 100 帧 tick)
|
2026-09-25 17:33:41 +08:00 |
|
|
|
5038c7f679
|
feat(mcfold): P7 实例层(传入文件夹→拉起实例→读mod注册方块表→连服,含端到端验证)+ 统一测试入口
|
2026-09-25 14:36:21 +08:00 |
|
|
|
b0182de8c7
|
feat(mcfold): P6 世界模型(多区块聚合/负坐标定位/unloaded与air语义分明/mod降级统计)
|
2026-09-25 14:33:26 +08:00 |
|
|
|
85ad7e580e
|
feat(mcfold): P5 mod jar 解析(三种加载器+多加载器诊断+方块名提取,含诚实边界标注)
|
2026-09-25 14:32:39 +08:00 |
|
|
|
40c5739cae
|
feat(mcfold): P4 区块解析(位打包/三种调色板分支/注册表显式降级)+ prismarine 真实数据交叉验证
|
2026-09-25 14:25:34 +08:00 |
|
|
|
a4914b932e
|
feat(mcfold): 最小客户端 + 跨实现互操作测试(Python 客户端握手 Node 服务端成功)
|
2026-09-25 14:12:06 +08:00 |
|
|
|
fc5a1aae91
|
feat(mcfold): 声明式 protodef 解释器(原生类型+阶段作用域+switch/mapper/bitfield),真实握手字节验证通过
|
2026-09-25 14:10:40 +08:00 |
|
|
|
22cdee35e3
|
feat(mcfold): P1 按实例文件夹解析版本(inheritsFrom 归一化 + 加载器判定)+ 回归测试
|
2026-09-25 14:06:55 +08:00 |
|