saddle

模组

· 作者 d1n-0

Saddle:用于实时编辑的数据包调试器

0 本站下载 0 关注 更新于 1 个月前

需要前置:Fabric API

最新 1.2.0 · 26.3 · Fabric

一键开服(送7天)

Saddle

Saddle: A Datapack Debugger for Live Editing(Saddle:用于实时编辑的数据包调试器)

一个 Fabric 模组,它在 Minecraft 中嵌入了 Debug Adapter Protocol 服务器,从而允许从 VS Code(或任何 DAP 客户端)对数据包 .mcfunction 文件进行调试——支持断点、单步执行、时间回溯,以及对函数运行所依赖的游戏状态进行实时检查和编辑。

在 Minecraft 中,“马鞍”让你能够驾驭那些原本自行运行的事物。本模组给数据包的执行套上了“马鞍”:你可以在任意位置让它停下(断点)、让它倒退(时间回溯),并操控它的走向(实时编辑)——而不是只能眼睁睁看着它狂奔而过。

下载

模组 Modrinth · CurseForge · GitHub Releases
VS Code 扩展 Visual Studio Marketplace(或在扩展视图搜索“Saddle”)
源代码与问题反馈 github.com/d1n-0/saddle · Issues

要求

  • Minecraft 26.2 – 26.3,Fabric Loader ≥ 0.19.0,Fabric API,Java 25
  • 运行世界的侧边需安装该模组:单人游戏需在客户端安装,多人游戏需在服务端安装
  • DAP 端点:127.0.0.1:16352 — 可通过 -Dsaddle.host / -Dsaddle.port 覆盖。除非设置了 -Dsaddle.allowRemote=true,否则拒绝非回环绑定:由于调试端口允许未经身份验证的命令执行,因此仅应在受信任的网络或通过隧道连接的网络上暴露该端口

快速开始

  1. 安装该模组(以及 Fabric API)并启动世界或服务器。
  2. 安装 VS Code 扩展。
  3. 在 VS Code 中打开你的数据包文件夹,在 .mcfunction 文件中设置断点,然后运行 Attach to Minecraft (Saddle)(或按 F5)。调试控制台和游戏聊天栏都会显示你已连接到哪个世界。
  4. 在游戏中触发一个函数,可以从 tick 函数或调试控制台触发 —— 或者在 .mcfunction 编辑器中按 Ctrl+Alt+Enter(macOS 为 Cmd+Alt+Enter)/ ▶ 来运行该文件的函数。
  5. 可选:开启 saddle.reloadOnSave(或点击状态栏中的 Reload on Save),以便在保存任何数据包文件时自动执行 /reload。

本 README 的其余部分将介绍该模组及其协议;有关编辑器端的功能导览,请参阅 vscode-extension/README.md。

工作原理

  • 通过混入 CommandFunction.fromLines,每个解析后的命令条目都会被带有其 (function id, source line) 来源信息的装饰器包裹,并记录函数源文本。宏($...)行在解析时被标记,并在 MacroFunction 实例化它们时被包裹,因此它们也可以被调试。当没有调试客户端连接时,每个命令的运行开销仅为一次易失性读取。
  • 在命中断点/单步/暂停时,服务器线程会在命令执行过程中暂停 —— 游戏在函数执行中途冻结,但保留原版执行状态。在暂停期间,该线程会处理任务队列,因此需要游戏状态的 DAP 请求(变量、求值、内省)仍可在服务器线程上安全运行。
  • 断点路径会从文件路径的 data/<namespace>/function/<path>.mcfunction 段映射到 function id,因此无需配置即可适配任何工作区布局。在注释或空行上请求的断点会自动下移到下一可执行行。

DAP 支持

区域 请求
生命周期 initialize, launch/attach, configurationDone, disconnect
断点 setBreakpoints, breakpointLocations —— 普通命令和宏行;注释/空行会下移到下一可执行行
执行 continue, next, stepIn, stepOut, pause
状态 threads, stackTrace, scopes, variables, setVariable, source
控制台 evaluate —— 运行任意命令,异步响应,因此命中断点的命令永远不会延迟堆栈视图;在暂停状态下,它在隔离的 ExecutionContext 中执行。completions 提供 Brigadier 建议,使调试控制台的自动补全功能如同游戏内聊天一样
悬停提示 evaluate(context: hover) 解析宏参数($(name))、实体选择器(@e[...])和坐标三元组(~ ~2 ~),而无需执行命令
输出 游戏内聊天会作为 output 事件镜像到客户端:系统广播(/say、死亡、加入)、玩家聊天以及针对玩家的私聊消息(/tellraw、/msg)
时间回溯 stepBack / reverseContinue 浏览已执行命令的记录(环形缓冲区,由 -Dsaddle.ttd.steps 控制,默认 20k)。在过去的时间点,会显示该时刻的堆栈、执行器、宏参数和重建的记分板/存储状态 —— 作用域保持其实时名称,以便在现在和历史之间移动时展开的行得以保留,Executor 作用域带有 (time travel) 标记。向前单步执行会将记录回放至当前时刻;continue 超出记录范围后恢复实时执行。saddle/trace 返回最近的执行轨迹

变量(“寄存器与内存”)

每个堆栈帧都暴露实时的作用域,所有操作均在暂停时读取游戏状态:

  • Executor — 命令源摘要(执行者、位置、旋转角度、维度)以及一个按需展开且可编辑的执行实体 NBT 树。
  • Macro Arguments — 当前宏帧的 $(...) 值。
  • Command — 即将运行的命令,其中每个实体选择器都已解析为其当前匹配到的实体(每个均可展开为实时 NBT),每个坐标三元组也已解析为其指向的方块。
  • Watched — 用户固定的表达式(见下文),每次请求时重新实时解析。
  • Scoreboard — 所有计分板目标及其分数;分数值可通过 setVariable 进行编辑。
  • Storage — 所有命令存储 ID 作为可编辑的 NBT 树;叶子节点通过 setVariable 接受 SNBT。容器预览基于大小显示(如 {400 entries}),因此浏览大型存储时保持快速;编辑会推送 invalidated 事件,以便客户端重新获取过期的行。

在 .mcfunction 文件中暂停时,将鼠标悬停在 $(name)、@e[...] 或 1 2 3/~ ~2 ~ 上,会以行内方式显示相同的数据(通过 VS Code 扩展)。

Watch & pin expressions

VS Code WATCH 面板、固定的 "Watched" 作用域(saddle/pin、saddle/unpin、saddle/pins)以及 Saddle Watch 视图均支持:

  • @e[type=pig] — 匹配的实体,可展开为实时 NBT
  • storage <id> [path] / entity <target> [path] / block <x> <y> <z> [path] — 目标处的实时(可编辑)NBT;<target> 是 /data get entity 接受的任何内容:玩家名称、UUID 或单实体选择器(@s 是所选帧的执行者)
  • score <objective> [holder] — 单个分数,或在省略持有者时整个目标(可编辑)
  • scoreboard / storage — 所有目标 / 所有存储 ID
  • $(name) — 选定帧的宏参数;裸坐标三元组解析为其指向的方块

Saddle Watch(实时 + 可编辑,无需断点)

该扩展程序向“运行和调试”侧边栏添加了 Saddle Watch 视图——一个兼具 WATCH 和 Variables 功能且无需断点的监视面板:

  • 实时:固定表达式通过定时器刷新(saddle.liveWatchRefreshInterval,默认 1 秒),使用无状态的 saddle/live {expression, path} 请求,该请求在游戏线程上读取游戏状态,无论游戏正在运行还是已挂起——计分板分数实时增加,实体位置移动,存储随着你的函数写入而更新。
  • 可编辑:由分数或 NBT 支持的行显示内联铅笔图标;编辑通过 saddle/liveSet {expression, path, name, value} 发送并立即应用到实时游戏中。命名单个值的固定项——score <objective> <holder> 或 NBT 路径如 storage <id> <path> / entity <target> <path>(例如通过 Add to Saddle Watch 添加)——也是可编辑的:不带 name 的 saddle/liveSet 设置表达式自身的值。
  • 监视嵌套节点:右键单击展开的子行(NBT 键或列表项、目标、分数持有者、存储 ID、匹配的实体)并选择 Add to Saddle Watch 将其固定为自己的条目——例如 storage mypack:store players.list[0]、entity Steve Inventory[0] 或 score kills Steve。玩家按名称固定;其他实体按 UUID 固定,这是唯一能始终指向同一实体的引用。每个具有实时独立等效项的变量都会将其报告为其 DAP evaluateName,这也启用了 VS Code 内置的 Variables 视图中的 Add to Watch。记录的值(时间旅行)和方块 NBT 没有此项:监视表达式无法命名方块的维度。
  • 显示名称:右键单击固定项并选择 Rename(或选中并按 F2)以自定义名称显示,例如用 pig inventory 代替 entity 1a2b…-… Inventory。仅更改显示的名称——固定的表达式保持不变并在工具提示中显示。名称按工作区保存,因此当在后续会话中再次固定时,固定项会恢复其名称;清除名称会恢复为表达式。

Editor integration: run from file & reload on save

  • Run Function From File (saddle/runFunction {path, arguments?, executor?}):运行由 .mcfunction 文件定义的函数。路径解析方式与断点路径完全相同(data/<namespace>/function/<path>.mcfunction),因此适用于任何工作区布局。arguments 是宏函数的 SNBT 复合体——当文件包含 $ 行时,扩展程序会要求提供它,并按文件记住最后一个值。executor(设置 saddle.runFunctionExecutor,例如 @p)将调用包装在 execute as <executor> at @s run 中;为空则作为服务器运行,类似于调试控制台。响应是异步的,因此在断点处停止的函数行为与从控制台启动的函数完全相同。未保存的更改会先保存,并且启用保存后重载时,运行会等待该重载完成。
  • Reload on save (saddle/reload):相当于 /reload(当前数据包加上新发现且未禁用的数据包),在新资源生效后才返回结果。扩展程序对数据包文件的保存进行了去抖处理——即 pack.mcmeta 以及在同一文件夹中包含 pack.mcmeta 的 data/ 下的所有内容——因此“全部保存”触发单次重载,并在状态栏报告结果;调试控制台日志显示 Saddle: datapacks reloaded。当执行在断点处暂停时,拒绝重载,因为暂停的函数随后将对交换后的函数库运行——请先继续。Saddle: Reload Datapacks 按需重载。

/deploy — 部署地图

/deploy(权限等级 4)将世界保存为可分发的地图:保留建筑、命令方块(区域文件)、实体、兴趣点、已保存数据(记分板、命令存储、地图等)、数据包和世界设置(level.dat);移除玩家数据——即 players/ 文件夹(物品栏、位置、进度、统计信息;以及传统的 playerdata/、advancements/、stats/ 文件夹)和记录在 level.dat/level.dat_old 中的单人游戏所有者及上次游玩时间(singleplayer_uuid,传统 Player、LastPlayed)。在被部署的世界首次打开之前,单人游戏列表不会显示其有意义的上次游玩日期。

由玩家运行时,/deploy 会打开一个包含目标路径字段和两个选项的对话框:

  • 创建副本 (/deploy copy [path]):将世界刷盘并写入清理后的副本到 path。相对路径会在世界文件夹旁边创建(在单人游戏中即存档文件夹,因此副本会显示在世界列表中);默认值为 <world>-deploy。目标路径必须位于世界之外,且要么不存在,要么为空文件夹;复制失败时会删除已写入的内容。正在运行的世界不会被修改。副本操作在服务端线程上运行,因此在复制期间无法向世界写入任何内容——游戏会在复制持续期间暂停。
  • 应用到当前世界 (/deploy apply):清理当前世界本身。由于游戏在关闭时会重新写入每个在线玩家的数据,因此会先关闭世界(单人游戏返回主菜单;专用服务器停止),然后在最终保存后执行清理。

只有服务器控制台(包括 rcon 和调试控制台)以及单人游戏所有者可以复制到任意路径;其他操作员——例如开启作弊的局域网客人——仅限于目录内的目的地,并且在单人/局域网世界中,只有所有者才能就地应用。当执行在断点处停止时,两种操作均被拒绝。如果没有玩家参与(服务器控制台、rcon、调试控制台),/deploy 会打印两个子命令而不是对话框。对话框按钮立即生效,没有 Minecraft 通常的“运行此命令?”提示:它们发送自定义点击操作(saddle:deploy/copy、saddle:deploy/apply),服务端会自行检查这些操作的权限等级 4。

自定义请求

  • minecraft/getScoreboard、minecraft/setScore {objective, holder, value}
  • minecraft/getStorage {id?, path?}、minecraft/listEntities {selector}、minecraft/getEntity {uuid}(包含 NBT)
  • minecraft/getData / minecraft/setData {type: storage|entity|block, target, path, value} —— 原版 /data 风格的访问;方块目标格式为 "x y z [dimension]"
  • minecraft/getBlock {pos, dimension?} —— 方块状态加上方块实体 NBT
  • saddle/runFunction {path, arguments?, executor?}、saddle/reload —— 参见 编辑器集成

构建

./gradlew build                     # mod jar in build/libs/

cd vscode-extension                 # extension .vsix
npx --yes @vscode/vsce package
code --install-extension saddle-debug-*.vsix

Minecraft 26.x 未混淆,因此构建脚本使用无重映射的 net.fabricmc.fabric-loom 插件。模组基于 26.2 构建(gradle.properties);传递 -Pminecraft_version=26.3 -Pfabric_api_version=<version> 以针对其他受支持版本进行构建或 runServer。

测试

# first time only: accept the EULA and disable the tick watchdog
mkdir -p run
printf 'eula=true\n' > run/eula.txt
printf 'max-tick-time=-1\nonline-mode=false\npause-when-empty-seconds=0\n' > run/server.properties

./gradlew runServer                 # terminal 1
python3 scripts/dap_smoke_test.py   # terminal 2

该脚本将 scripts/test-datapack 安装到世界中,执行 /reload,并全面练习完整的调试循环(141 项检查):断点、单步执行、时间旅行(回退单步/反向继续/历史状态重建)、宏断点和宏参数值、注释行移位、实时变量读写(记分板、存储 NBT、实体 NBT)、选择器/坐标解析、悬停评估、控制台补全、聊天输出镜像、实体/方块数据请求、评估与暂停、重载和从文件运行,以及 /deploy copy。CI 针对每个支持的 Minecraft 版本(26.2 和 26.3)在真实的专用服务器上运行相同的套件,推送 v* 标签会将 jar 和 vsix 发布为 GitHub Release。

注意事项

  • 保持模组和 VS Code 扩展版本匹配:模组在附加时发送 saddle/version 事件,当两者出现偏差(主版本.次版本)时,扩展会发出警告。
  • 在专用服务器上设置 max-tick-time=-1:在断点处挂起会暂停服务端线程,否则这会触发看门狗。
  • 在单人游戏中,如果游戏长时间处于挂起状态,内部客户端可能会断开连接。
  • 单步执行完所有排队命令的末尾会使会话保持在运行状态,直到命中下一个断点/暂停(例如下一个 tick-function 命令)。

故障排除

  • 编辑似乎未应用 / data get 显示旧值。 首先检查附加公告:在附加时,Saddle 在调试控制台中打印 Saddle: debugger attached to world '…',在游戏聊天中打印 [Saddle] Debugger attached。如果聊天消息未出现在 你的 世界中,则另一个拥有 Saddle 的 Minecraft 实例占用了端口(其日志显示 Failed to bind DAP server),而你的编辑落入了该实例——关闭它或使用 -Dsaddle.port 将它们分开。还要注意,每刻重写记分板/存储的 tick 函数会在你恢复后立即覆盖手动编辑。
  • Watched/Storage 作用域仅编辑实时数据。在进行时间旅行时,同名作用域显示记录的值且为只读——Executor 作用域中的 (time travel) 行告诉你当前查看的是哪种模式。

许可证

MIT

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源