SkyCraft存档与排错:快照回滚、日志诊断与开发测试台
SkyCraft存档与排错:快照回滚、日志诊断与开发测试台
SkyCraft 是一个把《上古卷轴5》和《我的世界》融合的实验性项目:用 Minecraft 的物理、背包和方块,在 Skyrim 的世界里奔跑、挖掘和战斗。它由一个 SKSE 插件和一个 Fabric mod 通过共享内存协作,两个游戏都不被重写。正因为两边各管一套存档,SkyCraft 的存档机制和排错方式对新手来说容易踩坑。本文带你完整看懂:镜像世界如何回滚快照、三个关键日志文件怎么读、以及开发者如何在没有 Skyrim 的情况下搭建测试台。
镜像世界:你的方块、挖掘与背包存在哪里
SkyCraft 的存档分两层,理解这一点是排错的前提:
- Skyrim 层(权威存档):角色、NPC、任务、时间天气都由 Skyrim 自己保存。你按 Esc 菜单保存、用 F9 快速读档,都是 Skyrim 的常规操作。
- Minecraft 层(镜像世界):一个由 mod 自动创建的"虚空"生存世界,隐藏在你电脑后台运行。你放置的方块、挖掉的 Skyrim 地形(草皮、石头、矿脉、基岩)、TNT 炸出的弹坑,全部保存在这个 Minecraft 世界里。它的核心逻辑见 fabric/src/client/java/dev/skycraft/client/MirrorWorld.java 与 fabric/src/main/java/dev/skycraft/world/SkyDig.java。
几个关键事实(来自 README.md):
| 行为 | 实际发生了什么 |
|---|---|
| 正常退出 Skyrim | Minecraft 随之退出,保留它上一次自动保存的内容(每几分钟一次) |
| 关闭 Minecraft(不关 Skyrim) | 控制权交还给 Skyrim;Minecraft 侧保留最后自动存档 |
| 存档位置 | %LOCALAPPDATA%\SkyCraft 目录(Prism、登录态、Minecraft 文件和 SkyCraft 世界都在这里) |
快照回滚:读旧存档时构建如何还原
docs/DESIGN.md 第 11 节定义了理想的保存/加载方案:每个 Skyrim 存档携带一个 saveId,存档时 Minecraft 侧把镜像世界(很小的稀疏区域)和玩家数据快照在该 id 下;加载旧存档时恢复对应快照——于是"回到三小时前的河木镇"时,你当时拆掉的地形和背包也会一致地回滚。
目前版本的现状与限制,务必知道:
- 挖掘是真实的、随 Minecraft 世界持久化的:暂停菜单左上角(按 O)的 Skyrim destruction: On/Off 只能关掉继续挖,已经挖的坑不会自己长回来。
- 回滚粒度取决于自动存档间隔:Minecraft 每几分钟自动保存一次,极端情况下可能丢失最近几分钟的挖掘/放置。重要工程想"定格",可以先在 Skyrim 侧正常存档。
- 所有 Skyrim 室内空间共用同一个 Minecraft 世界:在一个室内放的方块,可能在另一个室内同一坐标出现。这是已知限制,排错时别当成方块"丢失"。
- 想彻底重置 Minecraft 侧,删除
%LOCALAPPDATA%\SkyCraft即可(这会同时移除 Minecraft 文件和登录态,下次启动重新下载并登录)。
日志诊断:三个文件定位 90% 的问题
出问题时按顺序看这三个文件,几乎总能找到答案:
1. SkyCraft.log —— SKSE 插件主日志
路径:Documents\My Games\Skyrim Special Edition\SKSE\SkyCraft.log。日志初始化逻辑在 skse/src/main.cpp,每行都带时间戳并即时落盘。
想报 bug 前,在 skse/SkyCraft.ini 里打开详细诊断(每秒多行计时、相机、战斗、光照日志):
[Debug]
bDiagnostics = 1
还有一个隐藏技巧:在 SkyCraft.log 旁边放一个空的 skycraft_nocontact 文件,可以切换方块的诊断显示(见 skse/src/WorldRender.cpp)。
2. latest.log —— Minecraft 侧日志
卡在 "SkyCraft: starting Minecraft..." 时,一分钟后游戏会在角落告诉你属于哪种情况:
- Prism 还在忙:Alt-Tab 过去看它是在下载、等待登录还是报错;
- Minecraft 已退出:看
%LOCALAPPDATA%\SkyCraft\Prism\instances\SkyCraft\.minecraft\logs\latest.log; - Minecraft 在运行但无响应:这是需要上报的 bug,请同时附上两份日志。
3. SkyCraft_crash.dmp —— 崩溃转储
Skyrim 崩溃时,崩溃处理器会往 SkyCraft.log 写入异常码、出错模块+偏移和完整调用栈(前 48 帧),并在同目录写出 minidump 供开发者分析,实现见 skse/src/CrashLog.cpp。报 crash 时把 SkyCraft.log + SkyCraft_crash.dmp + latest.log 三件套一起提交。
开发测试台:没有 Skyrim 也能跑通整个链路
项目自带一套"假 Skyrim"测试台,把共享内存协议完整模拟出来(协议布局定义在 protocol/skycraft_protocol.h,Java 侧镜像在 fabric/src/main/java/dev/skycraft/link/Proto.java):
- tools/fake_skyrim.py:SKSE 插件的替身。创建共享内存、铺一块平地+楼梯+1/8 缓坡的碰撞场,然后脚本化地"移动、打假 NPC、被假 NPC 反击、放方块、射箭、丢东西走上去捡",并把叠加层渲染存成 PNG 供肉眼核对。
- tools/fake_guest.py + tools/run_guest.ps1:在一台电脑上模拟"房主 + 访客"两个 Minecraft 客户端测试多人同步,访客会被自动"跟随"在房主旁边。
- tools/test_mc.sh:一键把
fake_skyrim.py和开发版 Minecraft 一起拉起来,跑完自动打印两侧的关键日志与崩溃信息。 - 只读观测工具:tools/tick_monitor.py(监控物理 tick 卡顿)、tools/trace_motion.py(记录玩家运动如何传到 Skyrim,诊断相机抖动)、tools/probe_feet.py(查看脚下碰撞体素)、tools/dump_collision.py(解码碰撞环缓冲)。
开发循环的核心命令:
fabric/gradlew runClient:启动一个" Skyrim 关闭后仍存活"的开发版 Minecraft;- 单测在 fabric/src/test/java/dev/skycraft/world/SkyRayTest.java 和 fabric/src/test/java/dev/skycraft/world/TriColliderTest.java,验证射线与三角形碰撞的核心数学;
- 设置
SKYCRAFT_DEPLOY_DIR后,每次构建插件会自动复制到 Mod Organizer 的mods\SkyCraft目录,省去手动拷贝。
排错速查清单
- 卡"starting Minecraft..." → 先 Alt-Tab 看 Prism 窗口;再看 Minecraft
latest.log;确认你拥有 Minecraft: Java Edition。 - 画面正常但物理不对 → 用
tick_monitor.py/probe_feet.py判断是 tick 卡顿还是碰撞数据问题;相机/身体抖动用trace_motion.py出 CSV 分析。 - 崩溃 → 收集
SkyCraft.log、SkyCraft_crash.dmp、latest.log三件套,并开启bDiagnostics = 1复现一次。 - 存档异常 → 优先在 Skyrim 侧保存/读档;记住 Minecraft 侧只有"几分钟前的自动存档",重要修改前先落一份 Skyrim 存档。
- 与别的 MOD 冲突 → 接管相机的 MOD(Improved Camera SE、SmoothCam、True Directional Movement)与 SkyCraft 互斥,必须二选一。
SkyCraft 仍处于早期实验阶段,官方也明确建议"随时备份你的存档"。掌握了镜像世界的存档分层、日志三件套和这套开发测试台,无论是日常排障还是参与开发,你都能快速定位问题所在。
