Saddle
Saddle: A Datapack Debugger for Live Editing(Saddle:用于实时编辑的数据包调试器)
一个 Fabric 模组,它在 Minecraft 中嵌入了 Debug Adapter Protocol 服务器,从而允许从 VS Code(或任何 DAP 客户端)对数据包 .mcfunction 文件进行调试——支持断点、单步执行、时间回溯,以及对函数运行所依赖的游戏状态进行实时检查和编辑。
在 Minecraft 中,“马鞍”让你能够驾驭那些原本自行运行的事物。本模组给数据包的执行套上了“马鞍”:你可以在任意位置让它停下(断点)、让它倒退(时间回溯),并操控它的走向(实时编辑)——而不是只能眼睁睁看着它狂奔而过。
下载
要求
- 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,否则拒绝非回环绑定:由于调试端口允许未经身份验证的命令执行,因此仅应在受信任的网络或通过隧道连接的网络上暴露该端口
快速开始
- 安装该模组(以及 Fabric API)并启动世界或服务器。
- 安装 VS Code 扩展。
- 在 VS Code 中打开你的数据包文件夹,在
.mcfunction 文件中设置断点,然后运行 Attach to Minecraft (Saddle)(或按 F5)。调试控制台和游戏聊天栏都会显示你已连接到哪个世界。
- 在游戏中触发一个函数,可以从 tick 函数或调试控制台触发 —— 或者在
.mcfunction 编辑器中按 Ctrl+Alt+Enter(macOS 为 Cmd+Alt+Enter)/ ▶ 来运行该文件的函数。
- 可选:开启
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
Saddle
Saddle: A Datapack Debugger for Live Editing
A Fabric mod that embeds a Debug Adapter Protocol server in Minecraft, so datapack .mcfunction files can be debugged from VS Code (or any DAP client) — breakpoints, stepping, time travel, and live inspection and editing of the game state your functions run against.
In Minecraft, a saddle is what lets you take the reins of something that otherwise runs on its own. This mod puts a saddle on datapack execution: stop it where you want (breakpoints), back it up (time travel), and steer it (live edits) — instead of watching it gallop by.
Download
Requirements
- Minecraft 26.2 – 26.3, Fabric Loader ≥ 0.19.0, Fabric API, Java 25
- The mod on the side that runs the world: the client for singleplayer, the server for multiplayer
- DAP endpoint:
127.0.0.1:16352 — override with -Dsaddle.host / -Dsaddle.port. Non-loopback binds are refused unless -Dsaddle.allowRemote=true is set: the debug port allows unauthenticated command execution, so only expose it on trusted or tunneled networks
Quick start
- Install the mod (plus Fabric API) and start a world or server.
- Install the VS Code extension.
- Open your datapack folder in VS Code, set breakpoints in
.mcfunction files, and run Attach to Minecraft (Saddle) (or press F5). The Debug Console and game chat both announce which world you attached to.
- Trigger a function in game, from a tick function or the Debug Console — or press Ctrl+Alt+Enter (Cmd+Alt+Enter on macOS) / ▶ in a
.mcfunction editor to run that file's function.
- Optional: turn on
saddle.reloadOnSave (or click Reload on Save in the status bar) to /reload whenever a datapack file is saved.
The rest of this README covers the mod and its protocol; see vscode-extension/README.md for the editor-side feature tour.
How it works
- A mixin into
CommandFunction.fromLines wraps every parsed command entry with a decorator carrying its (function id, source line) origin and records the function source text. Macro ($...) lines are tagged at parse time and wrapped when MacroFunction instantiates them, so they are debuggable too. When no debug client is attached, the runtime overhead per command is one volatile read.
- On a breakpoint/step/pause hit, the server thread is parked inside command execution — the game freezes mid-function with vanilla execution state intact. While parked, the thread serves a task queue, so DAP requests that need game state (variables, evaluate, introspection) still run safely on the server thread.
- Breakpoint paths are mapped to function ids from the
data/<namespace>/function/<path>.mcfunction segment of the file path, so any workspace layout works without configuration. Breakpoints requested on comments or blank lines shift down to the next executable line.
DAP support
| Area |
Requests |
| Lifecycle |
initialize, launch/attach, configurationDone, disconnect |
| Breakpoints |
setBreakpoints, breakpointLocations — plain commands and macro lines; comment/blank lines shift to the next executable line |
| Execution |
continue, next, stepIn, stepOut, pause |
| State |
threads, stackTrace, scopes, variables, setVariable, source |
| Console |
evaluate — runs any command, responding asynchronously so a command that hits a breakpoint never delays the stack view; while suspended it executes in an isolated ExecutionContext. completions serves Brigadier suggestions, so the Debug Console autocompletes like the in-game chat |
| Hover |
evaluate(context: hover) resolves macro arguments ($(name)), entity selectors (@e[...]) and coordinate triples (~ ~2 ~) without executing commands |
| Output |
in-game chat is mirrored to the client as output events: system broadcasts (/say, deaths, joins), player chat, and per-player messages (/tellraw, /msg) |
| Time travel |
stepBack / reverseContinue navigate a recording of executed commands (ring buffer, -Dsaddle.ttd.steps, default 20k). While in the past, the stack, executor, macro arguments and reconstructed scoreboard/storage state are shown for that moment — the scopes keep their live names so expanded rows survive moving between present and history, and the Executor scope carries a (time travel) marker. Forward stepping replays the recording back to the present; continue past the recording resumes live execution. saddle/trace returns the recent execution trace |
Variables ("registers & memory")
Each stack frame exposes live scopes, all reading game state while stopped:
- Executor — command source summary (executor, position, rotation, dimension) plus a lazily expanded, editable NBT tree of the executing entity.
- Macro Arguments — the
$(...) values of the current macro frame.
- Command — the command about to run, with every entity selector resolved to the entities it currently matches (each expandable into live NBT) and every coordinate triple resolved to the block it points at.
- Watched — user-pinned expressions (see below), re-resolved live on every request.
- Scoreboard — every objective with its scores; score values are editable via
setVariable.
- Storage — every command storage id as an editable NBT tree; leaf values accept SNBT via
setVariable. Container previews are size-based ({400 entries}), so browsing large storages stays fast; edits push an invalidated event so the client re-fetches stale rows.
Hovering over $(name), @e[...] or 1 2 3/~ ~2 ~ in a .mcfunction file while stopped shows the same data inline (via the VS Code extension).
Watch & pin expressions
The VS Code WATCH panel, the pinned "Watched" scope (saddle/pin, saddle/unpin, saddle/pins) and the Saddle Watch view all accept:
@e[type=pig] — matched entities, expandable into live NBT
storage <id> [path] / entity <target> [path] / block <x> <y> <z> [path] — live (editable) NBT at the target; <target> is anything /data get entity accepts: a player name, a UUID or a single-entity selector (@s is the executor of the selected frame)
score <objective> [holder] — one score, or the whole objective (editable) when the holder is omitted
scoreboard / storage — every objective / every storage id
$(name) — macro argument of the selected frame; bare coordinate triples resolve to the block they point at
Saddle Watch (real time + editable, no breakpoint required)
The extension adds a Saddle Watch view to the Run and Debug sidebar — one watch panel that does what WATCH and Variables do together, without needing a breakpoint:
- Real time: pinned expressions refresh on a timer (
saddle.liveWatchRefreshInterval, default 1 s) through the stateless saddle/live {expression, path} request, which reads game state on the server thread whether the game is running or suspended — scoreboards tick up live, entity positions move, storage updates as your functions write it.
- Editable: rows backed by scores or NBT show an inline pencil; edits go through
saddle/liveSet {expression, path, name, value} and apply to the live game immediately. Pins that name a single value — score <objective> <holder> or an NBT path such as storage <id> <path> / entity <target> <path> (e.g. added with Add to Saddle Watch) — are editable too: saddle/liveSet without name sets the expression's own value.
- Watch a nested node: right-click an expanded child row (an NBT key or list item, an objective, a score holder, a storage id, a matched entity) and choose Add to Saddle Watch to pin it as its own entry — e.g.
storage mypack:store players.list[0], entity Steve Inventory[0] or score kills Steve. Players are pinned by name; other entities by UUID, the only reference that keeps pointing at the same entity. Every variable that has a live, standalone equivalent reports it as its DAP evaluateName, which also enables VS Code's built-in Add to Watch in the Variables view. Recorded (time-travel) values and block NBT have none: a watch expression cannot name the block's dimension.
- Display names: right-click a pin and choose Rename (or select it and press F2) to show it under a name of your own, e.g.
pig inventory instead of entity 1a2b…-… Inventory. Only the displayed name changes — the pinned expression stays the same and is shown in the tooltip. Names are kept per workspace, so a pin gets its name back when it is pinned again in a later session; clearing the name restores the expression.
Editor integration: run from file & reload on save
- Run Function From File (
saddle/runFunction {path, arguments?, executor?}): runs the function defined by a .mcfunction file. The path resolves exactly like a breakpoint path (data/<namespace>/function/<path>.mcfunction), so any workspace layout works. arguments is the SNBT compound for macro functions — the extension asks for it when the file contains $ lines and remembers the last value per file. executor (setting saddle.runFunctionExecutor, e.g. @p) wraps the call in execute as <executor> at @s run; empty runs it as the server, like the Debug Console. The response is asynchronous, so a function that stops at a breakpoint behaves exactly like one started from the console. Unsaved changes are saved first, and with reload on save the run waits until that reload has finished.
- Reload on save (
saddle/reload): the equivalent of /reload (current packs plus newly discovered, non-disabled ones), answered once the new resources are live. The extension debounces saves of datapack files — pack.mcmeta and anything under data/ in a folder that also holds a pack.mcmeta — so "Save All" triggers a single reload, and reports the outcome in the status bar; the Debug Console logs Saddle: datapacks reloaded. Reloading is refused while execution is stopped at a breakpoint, because the paused function would otherwise run against a swapped function library — continue first. Saddle: Reload Datapacks reloads on demand.
/deploy — ship the map
/deploy (permission level 4) saves the world as a distributable map: builds and command blocks (region files), entities, points of interest, saved data (scoreboards, command storage, maps, …), datapacks and world settings (level.dat) are kept; player data — the players/ folder (inventories, positions, advancements, statistics; also the legacy playerdata/, advancements/, stats/ folders) and the singleplayer owner and last played time (singleplayer_uuid, legacy Player, LastPlayed) recorded in level.dat/level.dat_old — is removed. Until the deployed world is first opened, the singleplayer world list shows no meaningful last played date for it.
Run by a player, /deploy opens a dialog with a destination field and two choices:
- Create Copy (
/deploy copy [path]): flushes the world to disk and writes a cleaned copy to path. Relative paths are created next to the world folder (in singleplayer that is the saves folder, so the copy shows up in the world list); the default is <world>-deploy. The destination must be outside the world and either missing or an empty folder; a failed copy removes what it wrote. The running world is not modified. The copy runs on the server thread so nothing can write to the world mid-copy — the game pauses for as long as the copy takes.
- Apply to This World (
/deploy apply): cleans this world itself. Because the game writes every online player's data again while shutting down, the world is closed first (singleplayer returns to the title screen; a dedicated server stops) and the cleanup runs after the final save.
Only the server console (including rcon and the Debug Console) and the singleplayer owner may copy to an arbitrary path; other operators — e.g. LAN guests with cheats on — are limited to destinations inside the folder that contains the world, and on a singleplayer/LAN world only the owner may apply in place. Both actions are refused while execution is stopped at a breakpoint. Without a player (server console, rcon, the Debug Console), /deploy prints the two subcommands instead of the dialog. The dialog buttons act immediately, without Minecraft's usual "run this command?" prompt: they send custom click actions (saddle:deploy/copy, saddle:deploy/apply) that the server checks for permission level 4 itself.
Custom requests
minecraft/getScoreboard, minecraft/setScore {objective, holder, value}
minecraft/getStorage {id?, path?}, minecraft/listEntities {selector}, minecraft/getEntity {uuid} (includes NBT)
minecraft/getData / minecraft/setData {type: storage|entity|block, target, path, value} — vanilla /data-style access; block targets are "x y z [dimension]"
minecraft/getBlock {pos, dimension?} — block state plus block-entity NBT
saddle/runFunction {path, arguments?, executor?}, saddle/reload — see Editor integration
Building
./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 is unobfuscated, so the buildscript uses the no-remap net.fabricmc.fabric-loom plugin. The mod is built against 26.2 (gradle.properties); pass -Pminecraft_version=26.3 -Pfabric_api_version=<version> to build or runServer against another supported version.
Testing
# 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
The script installs scripts/test-datapack into the world, /reloads, and exercises the full debug loop end to end (141 checks): breakpoints, stepping, time travel (step back / reverse continue / historical state reconstruction), macro breakpoints and macro-argument values, comment-line shifting, live variable read/write (scoreboard, storage NBT, entity NBT), selector/coordinate resolution, hover evaluation, console completions, chat output mirroring, entity/block data requests, evaluate and pause, reload and run-from-file, and /deploy copy. CI runs the same suite against a real dedicated server for every supported Minecraft version (26.2 and 26.3), and pushing a v* tag publishes the jar and vsix as a GitHub Release.
Notes
- Keep the mod and the VS Code extension on matching versions: the mod sends a
saddle/version event on attach and the extension warns when the two drift apart (major.minor).
- On dedicated servers set
max-tick-time=-1: suspending at a breakpoint parks the server thread, which would otherwise trip the watchdog.
- In singleplayer, the internal client may disconnect if the game stays suspended for a long time.
- Stepping past the end of all queued commands leaves the session in the running state until the next breakpoint/pause hit (e.g. the next tick-function command).
Troubleshooting
- Edits don't seem to apply /
data get shows old values. First check the attach announcement: on attach, Saddle prints Saddle: debugger attached to world '…' in the Debug Console and [Saddle] Debugger attached in the game chat. If the chat message does not appear in your world, another Minecraft instance with Saddle owns the port (its log shows Failed to bind DAP server) and your edits are landing in that instance — close it or use -Dsaddle.port to separate them. Also note that a tick function which rewrites a scoreboard/storage every tick will overwrite manual edits as soon as you resume.
- The
Watched/Storage scopes edit live data only. While time-traveling, the same-named scopes show recorded values and are read-only — the (time travel) row in the Executor scope tells you which mode you are looking at.
License
MIT
评论 0
登录后参与评分
还没有评论,来抢沙发吧