minecraft-commands-scripting

Minecraft 命令与脚本技能

编辑前，先检查具体的 Minecraft 版本和执行环境（聊天栏、函数、命令方块或 RCON）。严格遵循请求范围，只使用相关示例。查看最新发行说明，确认语法是否因版本而异。

命令语法约定

• <必需> — 必需参数
• [可选] — 可选参数
• (a|b|c) — 从中选择一个
• ... — 重复 / 多个
• 坐标：~ = 相对偏移，^ = 局部坐标（视线方向）

适用范围

• 适用于：任务涉及原生命令链、计分板、选择器逻辑或 RCON 命令脚本时。
• 不适用于：创建或编辑完整的数据包结构和注册表（minecraft-datapack）时。
• 不适用于：逻辑依赖 Java 插件或模组代码（minecraft-plugin-dev/minecraft-modding）时。

随附参考资料和示例

• 执行命令速查表：references/execute-cheat-sheet.md
• 选择器速查表：references/selector-cheat-sheet.md
• 示例脚本：scripts/examples/arena-countdown.mcfunction、scripts/examples/stopwatch-podium.mcfunction、scripts/examples/rcon-backup-warning.sh（需要时，会在注释中标出一次性设置命令）

需要快速查找命令而不想通读整个技能文件时，请使用速查表。根据需要复制并修改示例脚本。

---

命令参考

相关命令类别请参阅 references/command-reference.md。其中包含物品组件、属性、文本事件、游戏规则和 26.x 世界时钟的版本适用范围。请勿批量运行示例代码块；每个代码块都演示一项单独的操作。

RCON 脚本

使用 RCON 远程连接 Minecraft 服务（在 server.properties 中启用）：

# server.properties
enable-rcon=true
rcon.password=your_password
rcon.port=25575

RCON 未加密。请将端口绑定到可信的专用网络、VPN 或 localhost，并通过受保护的密钥注入密码，而不是将其作为命令行参数。

Bash RCON 脚本（使用 mcrcon）

#!/usr/bin/env bash
set -euo pipefail

: "${MCRCON_PASS:?inject MCRCON_PASS from a protected secret}"
export MCRCON_HOST="${MCRCON_HOST:-127.0.0.1}"
export MCRCON_PORT="${MCRCON_PORT:-25575}"

restore_saves() {
    mcrcon "save-on" >/dev/null || true
}
trap restore_saves EXIT INT TERM

# Send command
mcrcon "say Server backup starting in 5 minutes"
sleep 300
mcrcon "save-off"
mcrcon "save-all flush"

# Backup world
rsync -av /path/to/server/world/ /backups/world_$(date +%Y%m%d_%H%M%S)/

mcrcon "save-on"
trap - EXIT INT TERM
mcrcon "say Backup complete!"

Python RCON

import os

from mcrcon import MCRcon

with MCRcon("localhost", os.environ["MCRCON_PASS"], port=25575) as mcr:
    response = mcr.command("list")
    print(response)
    # "There are 3 of a max of 20 players online: Steve, Alex, Notch"
    
    players = response.split(": ")[1].split(", ") if ": " in response else []
    print(f"Online players: {players}")

---

常见脚本模式

首次加入时设置（加载和 tick 函数）

# load.mcfunction: create the objective
scoreboard objectives add initialized dummy

# tick.mcfunction: detect players who have not been initialized
execute as @a unless score @s initialized matches 1 run function mypack:on_first_join

# on_first_join.mcfunction
scoreboard players set @s initialized 1
give @s minecraft:stone_sword
give @s minecraft:bread 16
tellraw @s {"text":"Welcome! Here's a starter kit.","color":"green"}

死亡计数器 + 重生

# tick.mcfunction — check deaths
execute as @a[scores={deaths=1..}] run function mypack:on_death

# on_death.mcfunction (separate file)
scoreboard players reset @s deaths
scoreboard players add @s total_deaths 1

距离检测

# Check if any player is within 5 blocks of a location
execute if entity @a[x=10,y=64,z=10,distance=..5] run function mypack:player_nearby

数学技巧（计分板不支持小数）

# Multiply @s.value by 1.5 using integer math (×3 then /2)
scoreboard players operation @s result = @s value
scoreboard players operation @s result *= #three constants
scoreboard players operation @s result /= #two constants
# Set #two and #three on load:
# scoreboard players set #two constants 2
# scoreboard players set #three constants 3

---

参考资料

• Minecraft Wiki — 命令：https://minecraft.wiki/w/Commands
• Minecraft Wiki — 目标选择器：https://minecraft.wiki/w/Target_selectors
• Minecraft Wiki — NBT 格式：https://minecraft.wiki/w/NBT_format
• Minecraft Wiki — 原始 JSON 文本：https://minecraft.wiki/w/Raw_JSON_text_format
• Minecraft Wiki — 计分板：https://minecraft.wiki/w/Scoreboard
• Execute 命令 Wiki：https://minecraft.wiki/w/Commands/execute