命令支持状态
适用场景
在依赖某条原版命令、selector 或特殊实体行为之前，用本页确认当前 profile 的解析、行为等级和可观察副作用。
前置条件
先确定目标 Minecraft version profile；同名命令在不同 profile 中可能不存在，或采用不同的 unsupported 策略。
最小可运行示例
运行 java -jar cli/build/libs/datapack-sandbox-cli.jar commands --version 26.2，获取与下方矩阵同源的版本化命令目录。
完整能力
默认 profile：Minecraft Java 26.2，兼容 profile 覆盖到 1.20.4。
这个沙盒不嵌入原版服务端。“支持”在这里的意思是：命令会按沙盒当前建模的数据包可见状态执行，并产生确定性结果。网络、权限、世界生成、客户端 UI、红石、实体 AI、完整战斗系统和真实服务端生命周期都不在运行时范围内。
未支持的原版根命令默认不会导致运行失败。默认策略是 warn：记录 warning 输出事件并继续执行。需要严格验证时，可以用 CLI --unsupported error、清单 "unsupported": "error" 或 API UnsupportedFeatureMode.ERROR；想静默跳过则用 ignore。检查命令生成器输出时，run --strict 和 check --strict 会同时启用 unsupported error 和直接缺失资源引用失败；check --strict 还会在执行前校验 manifest schema。
状态说明
| 状态 | 含义 |
|---|---|
| 支持 | 主要数据包可见行为已经实现。 |
| 部分支持 | 对本地测试有用的行为已经实现，但原版副作用不完整。 |
| 空操作 | 命令会被接受和记录，但沙盒没有对应的可变原版状态。 |
| 未支持 | 未实现；按当前 unsupported 策略处理。 |
行为等级
| 等级 | 含义 |
|---|---|
exact | 文档覆盖的行为目标是与原版可观察结果一致。 |
modeled | 沙盒使用确定性的洁净室模型覆盖数据包可见行为。 |
observed-noop | 命令会被接受并产生输出或诊断，但真实副作用有意缺省。 |
unsupported | 命令交给当前 unsupported 策略处理。 |
CLI 可以导出按版本裁剪后的命令目录，供脚本、文档和 CI 使用：
bash
java -jar cli/build/libs/datapack-sandbox-cli.jar commands
java -jar cli/build/libs/datapack-sandbox-cli.jar commands --docs
java -jar cli/build/libs/datapack-sandbox-cli.jar commands --docs --output docs/command-catalog.md
java -jar cli/build/libs/datapack-sandbox-cli.jar commands --check docs/command-support.md
java -jar cli/build/libs/datapack-sandbox-cli.jar commands --check docs/command-support.zh-CN.md
java -jar cli/build/libs/datapack-sandbox-cli.jar commands --json --version 26.2
java -jar cli/build/libs/datapack-sandbox-cli.jar commands --json --output build/command-catalog.json --version 26.21
2
3
4
5
6
7
2
3
4
5
6
7
commands --check 会校验按版本裁剪后的每个根命令都出现在文档中，并带有匹配的行为等级。Gradle check 生命周期会通过 standalone jar smoke task 同时运行英文和中文文档检查。
原版命令矩阵
| 命令 | 状态 | 行为等级 | 已实现形式 / 沙盒行为 |
|---|---|---|---|
advancement | 部分支持 | modeled | grant、revoke、test；grant/revoke 支持 only、from、through、until 和 everything，会记录结构化 changed criterion 输出并可供 execute store result 使用；test 会记录通过数量和逐玩家结果 payload；每个玩家独立记录进度；奖励支持 function、loot、XP 和 recipe，并记录 advancement reward 结构化输出。 |
attribute | 部分支持 | modeled | get、base get、base set、base reset、modifier add、modifier remove 和 modifier value get；get 命令会记录结构化 data 输出，供断言和 execute store result 使用；modifier 状态会进入 snapshot 和实体 NBT。 |
ban、ban-ip、banlist | 空操作 | observed-noop | 记录请求的封禁目标/IP、原因或列表过滤器为结构化 debug 输出；不存储封禁列表状态。 |
bossbar | 部分支持 | modeled | add、remove、list、get、set；修改命令和 get 都会记录结构化 data 输出，供断言和 execute store result 使用；状态进入 snapshot，不模拟客户端 UI。 |
clear | 部分支持 | modeled | 从沙盒玩家背包移除匹配物品，支持 JSON/SNBT-lite NBT 和 components payload 过滤，记录 matched/removed 数量；maxCount=0 作为只查询不删除的检查。 |
clone | 部分支持 | modeled | 复制稀疏世界中的方块状态和方块实体 NBT，并记录结构化复制/变化位置输出；不执行更新、掉落或重叠区物理。 |
damage | 部分支持 | modeled | 降低实体或玩家生命值，结构化输出支持 at、by、from 上下文，会为自定义伤害来源暴露已加载的 damage_type JSON 元数据，发出沙盒 damage/death advancement 事件，并记录生命值变化；display、marker、interaction、Marker 模式盔甲架和带 Invulnerable 的实体拒绝伤害；不计算盔甲、无敌帧、死亡掉落和完整战斗规则。 |
data | 部分支持 | modeled | 支持带可选数值 scale 的 get，以及 merge、modify、remove，目标支持 storage、entity、block；写入类操作会记录结构化前后输出；path 支持字段、正/负数字索引和简单对象匹配；modify 支持 value、from 和 string 来源；append/prepend/insert 会拒绝已存在的非列表目标而不是覆盖它；顶层 NBT 字段经过 schema 校验。 |
datapack | 部分支持 | modeled | `list [available |
debug、jfr、perf | 空操作 | observed-noop | 接受 action/参数 token 并记录结构化 debug 输出；不模拟 profiling 和 flight recording。 |
defaultgamemode | 支持 | modeled | 存储世界默认游戏模式，并记录结构化前后输出。 |
difficulty | 支持 | modeled | 存储并报告世界难度，并记录结构化前后输出。 |
dialog | 未支持 | unsupported | 不模拟客户端 dialog UI 或 dialog 选择状态；按配置的 unsupported 策略处理。 |
deop、op | 空操作 | observed-noop | 记录请求的权限目标为结构化 debug 输出；不存储权限状态。 |
effect | 部分支持 | modeled | give、clear；更新玩家效果状态并触发相关 advancement 事件，也会更新非玩家实体 active effects，并通过 snapshot 和 ActiveEffects NBT 暴露；记录可用于 report/assertion 的结构化输出。 |
enchant | 部分支持 | modeled | 向玩家选中物品和非玩家实体主手装备写入附魔组件；命中已加载资源时会在结构化输出中暴露 enchantment JSON 元数据，并记录修改后的物品用于 report/assertion；不检查可附魔性。 |
execute | 部分支持 | modeled | 支持 as、at、`on target |
experience、xp | 部分支持 | modeled | add、set、query；玩家 points 与 levels 分开存储；修改和 query 命令都会记录结构化 data 输出，供断言和 execute store result 使用。 |
fetchprofile | 未支持 | unsupported | 不执行网络 profile 查询；按配置的 unsupported 策略处理。 |
fill | 部分支持 | modeled | `fill <from> <to> <block[state]{nbt}> [replace |
fillbiome | 部分支持 | modeled | 为显式方块范围记录 biome 覆盖，并记录结构化变化位置输出；同一批显式覆盖可被 execute if biome 和 predicate location_check 的 biome 条件读取；不模拟区块 biome 容器或生成效果。 |
forceload | 部分支持 | modeled | add、remove、remove all、query、query <pos>；记录强加载 chunk 坐标，并为修改和 query 记录结构化输出。 |
function | 支持 | modeled | function <id>。 |
gamemode | 支持 | modeled | gamemode <mode> [targets]；更新沙盒玩家游戏模式，并记录结构化前后输出。 |
gamerule | 部分支持 | modeled | 存储任意 gamerule 字符串值，并为修改/query 记录结构化输出；不执行具体游戏规则副作用。 |
give | 部分支持 | modeled | 向玩家背包添加物品，记录可用于 report/assertion 的结构化输出；物品含匹配组件且命中已加载资源时会暴露 equipment asset、banner pattern、instrument、jukebox song 和 armor trim material/pattern 元数据；触发 inventory advancement 事件；item argument 支持沙盒 JSON/SNBT-lite NBT 和 components payload。 |
help | 部分支持 | modeled | 输出命令根节点和基础沙盒帮助。 |
item | 部分支持 | modeled | `replace entity |
kick | 空操作 | observed-noop | 记录请求的踢出目标和消息为结构化 debug 输出；不移除真实网络会话。 |
kill | 支持 | modeled | 移除选中的沙盒实体，并记录可用于 report/assertion 的结构化目标输出；目标维度命中已加载资源时会暴露 dimension 元数据；玩家执行上下文会为非玩家目标触发 killed_entity advancement 事件。 |
list | 支持 | modeled | 报告沙盒玩家及 UUID。 |
locate | 部分支持 | modeled | 接受 biome、structure、poi；虚空世界中报告没有结果。 |
loot | 部分支持 | modeled | 支持 give、insert、spawn、replace entity、replace block，并记录可用于 report/assertion 的结构化 loot 输出；spawn 会在当前执行维度创建 item 实体，命中已加载资源时会暴露 dimension 元数据；replace entity 可写入玩家背包、当前主手、enderchest.* 槽和非玩家实体装备槽；source 支持 loot <table>、fish <table> <pos> [tool]、mine <pos> [tool]，以及实体声明 DeathLootTable 时的 kill <target>；还支持沙盒上下文 source：entity <table> <target>、block <table> <pos> [tool]、equipment <table> <target> <slot>；entry 覆盖 item、嵌套 loot table、group、alternatives、sequence，以及带嵌套/optional 值的 item tag，其中 expand=false 会输出整个 tag，expand=true 会把 tag 内物品作为展开候选参与选择；常用函数覆盖 count、item id、discard、components/custom data、工具组件复制、实体名称复制、确定性附魔组件、工具附魔数量奖励、damage、name 和 lore。 |
me | 支持 | modeled | 记录为 chat 输出事件；命中已加载的命令 chat type 时会暴露 chat_type JSON 元数据。 |
msg、tell、w | 支持 | modeled | 记录为私聊输出事件；命中已加载的命令 chat type 时会暴露 chat_type JSON 元数据。 |
pardon、pardon-ip | 空操作 | observed-noop | 记录请求的 pardon 目标/IP 为结构化 debug 输出；不存储封禁列表状态。 |
particle | 部分支持 | observed-noop | 记录为 visual 输出事件；不模拟客户端粒子。 |
place | 部分支持 | modeled | place structure <id> [pos] 和 place template <id> [pos] [rotation] [mirror] [integrity] [seed] 会把已加载的沙盒结构 JSON 资源（worldgen/structure 中带 blocks/entities 或 palette-style blocks）以及 worldgen/structure、structure、structures 目录里的二进制结构 NBT 资源展开到 sparse world，并记录实际变化的方块和实体；二进制 NBT 资源会在结构化输出中暴露 sourceFormat=binary-structure-nbt。结构 JSON 可引用 worldgen/processor_list 资源执行 block_ignore、protected_blocks、jigsaw_replacement、capped、nop 和带 block/tag 谓词的 rule 替换 processor；template placement 支持确定性的 none/90 度旋转、front_back/left_right 镜像和 integrity 过滤。place jigsaw <pool> <target> <maxDepth> [pos] 会解析已加载的 worldgen/template_pool single/legacy/list/feature 结构元素，主池没有可落地元素时会跟随 fallback pool，应用元素 processor，并放置选中的结构或 feature；当 maxDepth > 1 时，还会沿结构里的 jigsaw block pool connector 做确定性方向偏移展开，并在 payload 中暴露 jigsawConnections 方便调试连接链路。place feature <id> [pos] 会解析已加载的 worldgen/placed_feature/worldgen/configured_feature simple_block、block_column、确定性 disk/vegetation_patch/tree/basalt_columns/delta_feature/lake/spring_feature/block_pile/glowstone_blob/forest_rock/netherrack_replace_blobs/chorus_plant/replacement/selector/random_patch/flower JSON 和 sparse-world ore target，在命令位置周围放置或替换一个或多个方块。缺失或不支持的资源仍记录结构化 worldgen intent，placed=false。 |
playsound | 部分支持 | observed-noop | 记录为 sound 输出事件。 |
publish | 空操作 | observed-noop | 接受 allowCommands、gamemode 和 port，把请求的 LAN publish 设置记录为结构化 debug 输出；不执行真实网络发布。 |
random | 部分支持 | modeled | value、roll、reset；使用确定性的沙盒随机序列状态，默认混入 world seed，显式 reset seed 时优先使用 reset 值；value/roll/reset 会记录结构化序列状态输出，供断言和 execute store result 使用。 |
recipe | 部分支持 | modeled | give、take；支持对已加载数据包 recipe 使用 *，更新玩家 recipe 集合并记录 changed 数量和实际变更的 recipe id 列表。 |
reload | 空操作 | observed-noop | 原版命令会记录结构化 no-op payload；REPL 工具命令 reload 会真正重载数据包并保留世界状态。 |
return | 支持 | modeled | 结束当前 function；支持 return <value>、return fail 和 return run <command>，用于 function 条件和 store result 测试。 |
ride | 部分支持 | modeled | 记录载具和乘客关系，并记录结构化 mount/dismount 输出；不模拟控制或物理。 |
rotate | 部分支持 | modeled | 更新 yaw/pitch，并记录结构化前后旋转输出。 |
save-all、save-off、save-on | 空操作 | observed-noop | 记录请求的存档生命周期动作，包括 save-all flush，为结构化 debug 输出；不修改真实文件保存模式。 |
say | 支持 | modeled | 记录为 chat 输出事件；命中已加载的命令 chat type 时会暴露 chat_type JSON 元数据。 |
schedule | 部分支持 | modeled | `schedule function <id> <time> [append |
scoreboard | 部分支持 | modeled | objectives 支持 add、remove、list、modify、setdisplay；modify 会记录 display name、render type 和 display-auto-update 元数据，display slot 会进入 snapshot，修改会记录结构化输出；players 支持 set、add、remove、get、reset、list、enable、operation；players get 会记录结构化 data 输出，供断言和 execute store result 使用。 |
seed | 支持 | modeled | 报告确定性的沙盒 seed。 |
setblock | 部分支持 | modeled | 修改稀疏世界方块状态和方块实体 NBT，并记录结构化前后方块输出；位置参数支持局部坐标；不执行邻居更新。 |
setidletimeout | 空操作 | observed-noop | 校验并记录请求的 idle timeout 分钟数为结构化 debug 输出；不模拟玩家空闲踢出。 |
setworldspawn | 部分支持 | modeled | 存储世界出生点和角度，并记录结构化出生点输出；命中已加载资源时会暴露 dimension 元数据。 |
spawnpoint | 部分支持 | modeled | 存储玩家出生点和角度，并记录结构化目标输出；命中已加载资源时会暴露 dimension 元数据。 |
spectate | 部分支持 | modeled | 设置旁观模式并记录目标；不模拟客户端镜头状态。 |
spreadplayers | 部分支持 | modeled | 确定性地把选中实体分布到中心附近；不实现原版碰撞/队伍算法。 |
stop | 空操作 | observed-noop | 记录结构化 debug 生命周期请求；宿主进程仍然控制运行时，不会被沙盒命令停止。 |
stopsound | 部分支持 | observed-noop | 记录为 sound 输出事件。 |
stopwatch | 未支持 | unsupported | 不模拟原版 stopwatch 状态；按配置的 unsupported 策略处理。 |
summon | 部分支持 | modeled | 在当前执行维度创建带位置、tag 和 schema 校验 NBT 的实体，并记录可用于 report/assertion 的结构化创建输出；命中已加载资源时会暴露 dimension/dimension_type 元数据，以及 cat/chicken/cow/frog/painting/pig/wolf 等实体 variant 元数据。display 会校验方块/物品/文本内容、变换、渲染属性、成组变换/样式插值和传送插值；盔甲架会校验 Pose、Marker、Small、ShowArms、NoBasePlate、DisabledSlots；marker 保留任意复合 data；interaction 会建模 width/height/response、最近攻击/右击记录、命中箱和关系目标。派生渲染状态与命中箱进入实体 snapshot 的 special；不执行客户端绘制或实体 AI。 |
swing | 未支持 | unsupported | 不模拟客户端挥手动画；按配置的 unsupported 策略处理。 |
tag | 支持 | modeled | add、remove、list。 |
team | 部分支持 | modeled | add、remove、list、join、leave、empty、modify；记录结构化队伍/成员/选项输出，不执行 gameplay 副作用。 |
teammsg、tm | 支持 | modeled | 记录为 team chat 输出事件；命中已加载的命令 chat type 时会暴露 chat_type JSON 元数据。 |
test | 未支持 | unsupported | 不提供原版 game test 执行环境；按配置的 unsupported 策略处理。 |
teleport、tp | 部分支持 | modeled | 坐标传送支持局部坐标、可选旋转、facing 和当前执行维度；目标实体传送会复制目标位置、维度和旋转；display 的 teleport_duration 会产生确定性的 snapshot 渲染位置插值，而 selector 会立即使用服务端目标位置；记录可用于 report/assertion 的结构化移动输出，命中已加载资源时会暴露 from/to dimension 元数据。 |
tellraw | 支持 | modeled | 解析 JSON text component 并记录输出事件。 |
tick | 部分支持 | modeled | query、rate、freeze、unfreeze、step、sprint、stop；更新沙盒 tick 状态，可推进 tick，并记录结构化状态/推进输出用于调试。 |
time | 部分支持 | modeled | set、add、`query daytime |
title | 支持 | modeled | clear、reset、title、subtitle、actionbar、times 输出事件。 |
transfer | 部分支持 | observed-noop | 记录请求的 host、port、目标玩家和接受的语法为结构化 debug 输出；不执行真实网络/server transfer。 |
trigger | 部分支持 | modeled | `trigger <objective> [add |
unpublish | 未支持 | unsupported | 不模拟 LAN 发布状态；按配置的 unsupported 策略处理。 |
version | 未支持 | unsupported | 不模拟原版 version report 命令行为；按配置的 unsupported 策略处理。 |
waypoint | 未支持 | unsupported | 不模拟 waypoint 传输或客户端 UI；按配置的 unsupported 策略处理。 |
weather | 部分支持 | modeled | clear、rain、thunder；存储状态，并记录结构化天气输出。 |
whitelist | 空操作 | observed-noop | 接受 add、remove、list、on、off、reload，记录请求的 whitelist 动作为结构化 debug 输出；不存储白名单状态。 |
worldborder | 部分支持 | modeled | get、set、add、center、damage、warning；存储状态，并记录可断言的结构化修改/query 输出。 |
输出命令
输出命令会产生确定性的 OutputEvent。这些事件可以在 snapshot、REPL、run、check --verbose 和代码测试 API 中读取：
- chat：
say、me、msg、tell、w、teammsg、tm、tellraw - title：
title - sound：
playsound、stopsound - visual：
particle - data：modeled 命令的结构化状态和 query 输出
- debug：manifest/工具辅助输出，以及
debug、jfr、perf、transfer、publish、stop、ban、whitelist等 profiling/网络/生命周期/服务器管理类 observed-noop 请求 - worldgen：
place - warning：未支持或 no-op 命令提示
JSON text component 支持 text、score、selector、translate、keybind、基础 nbt、extra 和常见格式字段。沙盒会同时保存纯文本和分段 metadata，例如颜色、粗体、斜体等。
选择器（Selector）
已实现 selector：@s、@a、@p、@e、@n。
已实现选项：type、tag、name、gamemode、team、nbt、predicate、scores、advancements、level、x_rotation、y_rotation、limit、sort、distance、x、y、z、dx、dy、dz。
- score 和等级过滤支持
scores={kills=1..,deaths=..0}、level=..5这类整数范围； - advancement 过滤按玩家当前进度支持整体完成或 criterion 布尔匹配；
- NBT 过滤使用包含式对象匹配和数值等值比较；
- predicate 过滤会把候选实体作为
this上下文，并用候选实体的位置/维度交给已加载数据包 predicate 引擎评估，支持!取反； - 旋转过滤支持带符号数值范围；
sort=random使用基于原点的确定性顺序，便于重复测试。
未支持的 selector 选项会按当前 unsupported 策略产生诊断或 warning。
特殊实体
从 1.20.4 到 26.2 的全部内置 profile 都会建模以下特殊实体 NBT：
| 实体 | 已建模状态与行为 |
|---|---|
block_display、item_display、text_display | 校验展示内容和通用 display 字段，接受分解形式或 16 数字矩阵变换。分解变换中的平移/缩放使用线性插值，左右旋转四元数使用归一化最短弧 SLERP；矩阵输入按元素线性插值。阴影/文本样式状态按 tick 成组推进，teleport_duration 对渲染姿态做线性插值；命令读取的逻辑位置会立即到达目标。 |
armor_stand | 校验并保存 Pose、Marker、Small、ShowArms、NoBasePlate、Invisible、DisabledSlots；snapshot 暴露有效姿态以及普通/小型/Marker 命中箱。Marker 模式拒绝定向攻击、交互和伤害。 |
marker | 保存任意复合 data，可继续充当 selector/计分板逻辑锚点，暴露零尺寸不可交互命中箱，并拒绝伤害。 |
interaction | 校验 width、height、response、attack、interaction；定向玩家事件记录 UUID/timestamp，暴露命中箱和 response，并供 execute on target / execute on attacker 使用。 |
实体 snapshot 会把派生状态放在 entities[*].special：display 包含 renderTransformation、renderPosition、插值进度、cullingBox、零尺寸游戏 hitbox 和已保存内容；盔甲架和 interaction 则包含有效游戏命中箱。定向玩家事件表示客户端已经解析好的一次命中；沙盒不会从玩家视线做 raycast，也不绘制客户端模型或文本。
世界与 NBT 说明
- 初始世界是稀疏虚空。
- 方块只有在显式放置、fixture 定义或从存档导入后才存在。
- 方块和实体 NBT 写入会使用生成的 vanilla mcdoc schema 校验；未知顶层自定义字段会失败。
- 玩家 NBT 可读但不可通过
data写入；视图包含当前非空主手SelectedItem，玩家状态应通过命令或事件改变。 - 不模拟实体 AI、重力、红石、方块更新、破坏方块掉落和完整战斗系统。
沙盒专用 CLI/REPL 命令
下表是 Gradle 防漂移检查使用的精简命令目录。它只标记工具入口和行为等级，不再承载完整用法：
| 工具入口 | 行为等级 | 权威说明 |
|---|---|---|
event player <name> <type> ... | modeled | 玩家事件 |
inspect <target> | modeled | REPL 调试 |
load | modeled | REPL 调试 |
trace <on|off|status> | modeled | 报告与可观测性 |
diff last | modeled | REPL 调试 |
rerun last | modeled | REPL 调试 |
exit | modeled | REPL 调试 |
quit | modeled | REPL 调试 |
本节原有的工具命令、运行参数、断言简写和 artifact 附录已经按任务拆分：
- 使用方式和完整参数见 CLI 参考。
- 持久世界中的
inspect、trace、diff last、rerun last与重载流程见 REPL 调试。 - trace、outputs、snapshot diff、coverage 和 report 的格式与筛选规则见 报告与可观测性。
- Manifest steps/assertions 的类型化字段见 Manifest 参考。
这里保留原标题，确保已有深链接仍能到达新的权威入口。
限制
矩阵描述的是洁净室沙盒的可观察模型，不承诺完整原版副作用；网络、权限、客户端 UI、世界生成、红石、实体 AI 和完整战斗仍在范围外。