| name | minecraft-commands-scripting |
| description | Write and debug Minecraft Java 26.x and 1.21.x commands, selectors, execute chains, scoreboards, NBT, and RCON scripts. Use for command-only work; use minecraft-datapack for complete datapack structures. |
Minecraft Commands & Scripting Skill
Command Syntax Conventions
<required> — required argument[optional] — optional argument(a|b|c) — choose one... — repeating / multiple- Coordinates:
~ = relative offset, ^ = local (look-direction)
Routing Boundaries
Use when: the task is raw command chains, scoreboards, selector logic, or RCON command scripting.Do not use when: creating or editing full datapack structures and registries (minecraft-datapack).Do not use when: behavior depends on Java plugin or mod code (minecraft-plugin-dev/minecraft-modding).
Bundled References And Examples
- Execute cheat sheet:
references/execute-cheat-sheet.md
- Selector cheat sheet:
references/selector-cheat-sheet.md
- Example scripts:
scripts/examples/arena-countdown.mcfunction, scripts/examples/stopwatch-podium.mcfunction, scripts/examples/rcon-backup-warning.sh (one-time setup commands are called out in comments when needed)
Use the cheat sheets when you need fast command recall without scanning this whole
skill file. The example scripts are meant to be copyable starting points, not toy snippets.
Target Selectors
Base selectors
| Selector | Targets |
|---|
@a | All online players |
@e | All loaded entities |
@p | Nearest player to executor |
@r | Random online player |
@s | Executing entity |
@n | Nearest entity of any type (1.21+) |
Selector arguments (full reference)
@e[
type=minecraft:zombie, # entity type (prefix ! to negate)
type=!minecraft:player,
name=Herobrine, # custom name (exact)
name=!Bob, # not named Bob
distance=..10, # max 10 blocks away
distance=5..10, # 5-10 blocks away
x=0,y=64,z=0, # origin for AABB
dx=15,dy=5,dz=15, # AABB dimensions (x/dx/dy/dz required together)
scores={kills=1..,deaths=..5}, # score conditions (..N = max, N.. = min)
tag=vip, # has scoreboard tag
tag=!banned, # does NOT have tag
team=red, # on team "red"
team=!blue, # not on team "blue"
team=, # no team
gamemode=survival, # (survival|creative|adventure|spectator)
gamemode=!spectator,
level=30.., # XP level range
x_rotation=-90..-45, # pitch range (looking up = -90)
y_rotation=-45..45, # yaw range (facing south = 0)
nbt={Inventory:[{id:"minecraft:diamond"}]}, # NBT match
predicate=mypack:my_predicate, # predicate match
sort=(nearest|furthest|random|arbitrary),
limit=1,
]
The execute Command
Full subcommand chain syntax — subcommands must come before run:
execute
[as <entity>]
[at <entity>]
[in <dimension>]
[positioned (<xyz> | as <entity> | over <heightmap>)]
[rotated (<yaw> <pitch> | as <entity>)]
[facing (<xyz> | entity <entity> (eyes|feet))]
[anchored (eyes|feet)]
[if|unless (block|blocks|biome|data|dimension|entity|loaded|predicate|score|items)]
[store (result|success) (score|storage|entity|block|bossbar) ...]
run <command>
Context modifiers
# Change executor
execute as @a run say I am @s
# Change position and rotation to entity
execute at @e[type=minecraft:zombie] run particle minecraft:flame ~ ~ ~ 0.5 0.5 0.5 0.1 5
# Change both executor and position
execute as @a at @s run particle minecraft:heart ~ ~1 ~ 0.3 0.3 0.3 0.01 3
# Change dimension
execute in minecraft:the_end run say Running in The End
# Absolute position
execute positioned 0.0 100.0 0.0 run setblock ~ ~ ~ minecraft:beacon
# Relative to entity
execute as @a at @s positioned ~ ~2 ~ run setblock ~ ~ ~ minecraft:glass
# Local coords (^ = forward/up/right relative to rotation)
execute as @a at @s anchored eyes run particle minecraft:end_rod ^ ^ ^1 0 0 0 0 1
Conditional execution
# if block
execute if block 0 64 0 minecraft:diamond_block run say Found diamond block
# if blocks — compare two regions
execute if blocks 0 0 0 9 9 9 100 0 100 all run say Regions match
# if entity (existence check)
execute if entity @a[tag=boss] run say Boss is online
execute unless entity @a[gamemode=creative] run say No creative players
# if score
execute if score @s kills matches 10.. run say Ten or more kills
execute if score PlayerA points > PlayerB points run say A beats B
execute if score @s points = @s max_points run say Max score!
# if data (NBT path existence/value)
execute if data entity @s SelectedItem.tag.custom run say Has custom tag
execute if data storage mypack:config active run say Config is active
execute if data block 0 64 0 Items run say Chest has items
# if predicate
execute if predicate mypack:is_raining run say It is raining
# if loaded (chunk loaded check)
execute if loaded 0 64 0 run say Chunk is loaded
# if biome
execute if biome ~ ~ ~ minecraft:jungle run say You're in a jungle
# if dimension
execute if dimension minecraft:overworld run say In overworld
# if items (1.21+)
execute if items entity @s weapon.mainhand minecraft:diamond_sword run say Holding diamond sword
execute if items block 0 64 0 container.0 minecraft:diamond run say Diamond in container slot 0
Storing results
# Store arithmetic result into score
execute store result score @s my_score run data get entity @s Health
# Store success (1 if command succeeded, 0 if not)
execute store success score @s result_flag run kill @e[type=minecraft:bat,limit=1]
# Store into block entity NBT (example: command block SuccessCount)
execute store result block 0 64 0 SuccessCount int 1 run data get entity @a 1
# Store into storage
execute store result storage mypack:data player_count int 1 run execute if entity @a
# Store into entity NBT
execute store result entity @s Air short 1 run data get entity @s Air
# Store into bossbar
execute store result bossbar minecraft:health value run data get entity @s Health
Scoreboards
# Create objectives
scoreboard objectives add kills playerKillCount # player kill counter (kills BY players)
scoreboard objectives add zombie_kills minecraft.killed:minecraft.zombie # kills of a specific mob type
scoreboard objectives add deaths deathCount
scoreboard objectives add xp experienceLevel
scoreboard objectives add jumps minecraft.custom:minecraft.jump # 1.13+ stat format
scoreboard objectives add playtime minecraft.custom:minecraft.play_one_minute # 1.13+ stat format
scoreboard objectives add points dummy # manual control only
scoreboard objectives add health health
# Display
scoreboard objectives setdisplay sidebar points
scoreboard objectives setdisplay list kills
scoreboard objectives setdisplay belowname health
scoreboard objectives setdisplay sidebar.team.red points # team-specific sidebar
# Remove / rename objective
scoreboard objectives remove points
scoreboard objectives modify points displayname {"text":"Score","color":"gold"}
scoreboard objectives modify points rendertype (integer|hearts)
# Player scores
scoreboard players set @s points 0
scoreboard players add @s points 10
scoreboard players remove @s points 5
scoreboard players reset @s points
scoreboard players reset @s * # reset all objectives
scoreboard players enable @s ability # for trigger objectives
# Operations (both sides must have the score set)
scoreboard players operation @s points += @s bonus # add
scoreboard players operation @s points -= @s penalty # subtract
scoreboard players operation @s points *= @s multiplier # multiply
scoreboard players operation @s points /= @s divisor # integer divide
scoreboard players operation @s points %= @s modulus # modulo
scoreboard players operation @s points >< @s temp # swap
scoreboard players operation @s max = @s temp # set to max of both
scoreboard players operation @s min = @s temp # set to min of both
# Special fake player names (start with # for hidden players)
scoreboard players set #max points 100
scoreboard players set #config.difficulty points 2
NBT Path Syntax
# Entity root
data get entity @s
# Compound key access
data get entity @s Health
data get entity @s Inventory
data get entity @s Pos[0] # 1st element of Pos list
data get entity @s Inventory[0] # 1st inventory slot
data get entity @s Inventory[{id:"minecraft:diamond"}] # match compound
# Nested path
data get entity @s Brain.memories."minecraft:home".value.pos
data get entity @s ActiveEffects[0].Id
# Block entity
data get block 0 64 0
data get block 0 64 0 Items
data get block 0 64 0 Items[{Slot:0b}].Count
# Storage
data get storage mypack:data config.difficulty
data get storage mypack:data player_list
# Modify operations
data modify entity @s Health set value 20.0f
data modify entity @s CustomName set value '{"text":"Boss"}'
data modify storage mypack:tmp result set from entity @s Health
data modify storage mypack:out names append from entity @e[type=!player] CustomName
# Remove NBT
data remove entity @s ActiveEffects
data remove storage mypack:data temp
Item and Inventory Commands
# Give items
give @s minecraft:diamond 5
give @s minecraft:diamond_sword[minecraft:enchantments={levels:{"minecraft:sharpness":5}}]
# Clear items
clear @s minecraft:dirt
clear @a # clear entire inventory
clear @s minecraft:diamond 3 # remove exactly 3 diamonds
# Item (1.17+) — modify items in slots
item replace entity @s weapon.mainhand with minecraft:golden_sword[minecraft:custom_name='{"text":"Divine Blade"}']
item replace block 0 64 0 container.0 with minecraft:diamond 1
item replace entity @s hotbar.0 from entity @s hotbar.1 # copy slot
item modify entity @s weapon.mainhand mypack:add_lore # apply item modifier
# Slot identifiers for players:
# weapon.mainhand, weapon.offhand
# head, chest, legs, feet
# hotbar.0 .. hotbar.8
# inventory.0 .. inventory.26
# container.0 .. container.N (for block entities)
Bossbar
bossbar add mypack:boss_hp {"text":"Dragon HP","color":"dark_purple"}
bossbar set mypack:boss_hp max 200
bossbar set mypack:boss_hp value 150
bossbar set mypack:boss_hp color (pink|blue|red|green|yellow|purple|white)
bossbar set mypack:boss_hp style (progress|notched_6|notched_10|notched_12|notched_20)
bossbar set mypack:boss_hp players @a
bossbar set mypack:boss_hp visible true
bossbar get mypack:boss_hp value
bossbar remove mypack:boss_hp
Teams
team add redteam {"text":"Red Team","color":"red"}
team join redteam Steve
team leave @a
team modify redteam friendlyFire false
team modify redteam color (aqua|black|blue|dark_aqua|dark_blue|dark_gray|dark_green|dark_purple|dark_red|gold|gray|green|light_purple|red|white|yellow)
team modify redteam prefix {"text":"[RED] ","color":"red"}
team modify redteam nametagVisibility (always|hideForOtherTeams|hideForOwnTeam|never)
team modify redteam collisionRule (always|never|pushOtherTeams|pushOwnTeam)
team list
team remove redteam
Text Components (tellraw / title / books)
tellraw JSON text
# Plain text
tellraw @a {"text":"Hello World","color":"green"}
# Multiple components (array)
tellraw @a [{"text":"Hello ","color":"white"},{"selector":"@s","color":"gold"},{"text":"!","color":"white"}]
# Translatable text
tellraw @a {"translate":"block.minecraft.diamond_block","color":"aqua"}
tellraw @a {"translate":"commands.give.success.single","with":[{"text":"1"},{"translate":"item.minecraft.diamond"},{"selector":"@p"}]}
# Clickable / hoverable
tellraw @a {"text":"Click here","color":"aqua","clickEvent":{"action":"run_command","value":"/say hi"},"hoverEvent":{"action":"show_text","contents":"Run /say hi"}}
# Keybind display
tellraw @a {"text":"Press ","extra":[{"keybind":"key.jump","color":"yellow"},{"text":" to jump."}]}
# NBT display
tellraw @a {"nbt":"Health","entity":"@s","interpret":false}
# Score display
tellraw @a {"score":{"name":"@s","objective":"points"}}
Formatting codes (text component)
| Field | Values |
|---|
color | black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white, #RRGGBB |
bold | true/false |
italic | true/false |
underlined | true/false |
strikethrough | true/false |
obfuscated | true/false |
font | resource location (e.g., minecraft:default) |
Title commands
title @a title {"text":"ROUND START","color":"gold","bold":true}
title @a subtitle {"text":"Fight!","color":"red"}
title @a actionbar {"text":"Time: 60s","color":"yellow"}
title @a times 10 70 20 # fade-in, stay, fade-out ticks
title @a clear
title @a reset
Schedule
# Schedule a function to run once after N ticks
schedule function mypack:delayed_grant 100t
# Schedule repeating (append = don't cancel existing)
schedule function mypack:repeating 20t replace # replace existing schedule
schedule function mypack:repeating 20t append # add alongside existing
# Clear scheduled function
schedule clear mypack:delayed_grant
Attribute Commands
# Get base/current value
attribute @s minecraft:generic.max_health get
attribute @s minecraft:generic.movement_speed get
# Set base value
attribute @s minecraft:generic.max_health base set 30.0
attribute @s minecraft:generic.attack_damage base set 10.0
# Add modifier
attribute @s minecraft:generic.movement_speed modifier add 12345678-1234-1234-1234-123456789abc "speed_boost" 0.1 add_multiplied_total
# Remove modifier
attribute @s minecraft:generic.movement_speed modifier remove 12345678-1234-1234-1234-123456789abc
# Get modifier value
attribute @s minecraft:generic.movement_speed modifier value get 12345678-1234-1234-1234-123456789abc
# Modifier operations: add_value, add_multiplied_base, add_multiplied_total
Effects, Particles, Sounds
# Effects
effect give @s minecraft:speed 60 2 true # 60 seconds, level III, hide particles
effect give @a minecraft:resistance 9999 4
effect clear @s minecraft:speed
effect clear @s # clear all effects
# Particles
particle minecraft:flame 0.0 65.0 0.0 0.5 0.5 0.5 0.01 20
particle minecraft:block minecraft:stone 0.0 65.0 0.0 0 0 0 0 1
# Sounds
playsound minecraft:entity.player.levelup master @s ~ ~ ~ 1.0 1.0
playsound minecraft:block.note_block.bell record @a ~ ~ ~ 1.0 0.5
# playsound <sound> <source> <targets> [x] [y] [z] [volume] [pitch] [minVolume]
# source: (master|music|record|weather|block|hostile|neutral|player|ambient|voice)
stopsound @a * minecraft:music.game
stopsound @s
World and Environment Commands
# Time
time set day
time set noon # 6000
time set night # 13000
time set 0
time add 1000
time query daytime
# Weather
weather clear 6000
weather rain 12000
weather thunder 6000
# Gamerules (1.21.10 and earlier camelCase names)
gamerule doDaylightCycle false
gamerule doMobSpawning false
gamerule keepInventory true
gamerule spawnRadius 0
gamerule playersSleepingPercentage 0 # one player can skip night
gamerule universalAnger true
# Gamerules (1.21.11+ registry IDs)
gamerule minecraft:advance_time false
gamerule minecraft:spawn_mobs false
gamerule minecraft:keep_inventory true
gamerule minecraft:respawn_radius 0
gamerule minecraft:players_sleeping_percentage 0
gamerule minecraft:universal_anger true
# Difficulty
difficulty peaceful
difficulty easy
difficulty normal
difficulty hard
# Setworldspawn
setworldspawn 0 64 0 0.0 # 1.21.8 and earlier: x y z angle
setworldspawn 0 64 0 0.0 0.0 # 1.21.9+: x y z yaw pitch
# Spawnpoint per player
spawnpoint @s ~ ~ ~ 0.0 # 1.21.8 and earlier: x y z angle
spawnpoint @s ~ ~ ~ 0.0 0.0 # 1.21.9+: x y z yaw pitch
# forceload
forceload add 0 0 31 31 # keep chunks 0,0 to 31,31 loaded
forceload remove 0 0 31 31
forceload query 0 0
RCON Scripting
Connect to a Minecraft server remotely using RCON (enable in server.properties):
# server.properties
enable-rcon=true
rcon.password=your_password
rcon.port=25575
RCON is unencrypted. Keep the port bound to a trusted private network, VPN, or
localhost, and inject the password through a protected secret rather than a
command-line argument.
Bash RCON script (using 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
mcrcon "say Server backup starting in 5 minutes"
sleep 300
mcrcon "save-off"
mcrcon "save-all flush"
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)
players = response.split(": ")[1].split(", ") if ": " in response else []
print(f"Online players: {players}")
Common Scripting Patterns
Player join setup (in load.mcfunction + tag listeners)
# Give new players a starter kit tag
scoreboard objectives add initialized dummy
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"}
Death counter + respawn
# tick.mcfunction — check deaths
execute as @a[scores={deaths=1..}] run function mypack:on_death
function mypack:on_death
scoreboard players reset @s deaths
scoreboard players add @s total_deaths 1
Proximity detection
# 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
Math tricks (no fractions in scoreboards)
# 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
References
