Player Tasks

Player-related operations. All tasks are sent via the task channel.

---

Lookup

player.get

Find an online player by UUID or player name.

• Request: { "identifier": "<uuid|name>" }
• Returns: { "uuid": "<uuid>", "name": "<name>" } | null

player.getAll

Get all online players.

• Request: {}
• Returns: [{ "uuid": "<uuid>", "name": "<name>" }, ...]

---

Property Read/Write

In the following tasks, uuid is the player UUID string.

Basic Properties

Task	Request	Returns
player.getPing	{ "uuid": "<uuid>" }	number (ms)
player.getGamemode	{ "uuid": "<uuid>" }	"creative" | "survival" | "adventure" | "spectator"
player.setGamemode	{ "uuid": "<uuid>", "value": "<gamemode>" }	true
player.getHealth	{ "uuid": "<uuid>" }	number
player.setHealth	{ "uuid": "<uuid>", "value": <double> }	true
player.getFood	{ "uuid": "<uuid>" }	number
player.setFood	{ "uuid": "<uuid>", "value": <int> }	true
player.getExp	{ "uuid": "<uuid>" }	number (0.0-1.0)
player.setExp	{ "uuid": "<uuid>", "value": <float> }	true
player.getLevel	{ "uuid": "<uuid>" }	number
player.setLevel	{ "uuid": "<uuid>", "value": <int> }	true
player.getSaturation	{ "uuid": "<uuid>" }	number
player.getTotalExperience	{ "uuid": "<uuid>" }	number

Boolean Properties

Task	Request	Returns
player.isOp	{ "uuid": "<uuid>" }	boolean
player.isOnline	{ "uuid": "<uuid>" }	boolean
player.isFlying	{ "uuid": "<uuid>" }	boolean
player.setFlying	{ "uuid": "<uuid>", "value": <boolean> }	true
player.isSneaking	{ "uuid": "<uuid>" }	boolean
player.isSprinting	{ "uuid": "<uuid>" }	boolean
player.getBedLocation	{ "uuid": "<uuid>" }	{ "x","y","z","yaw","pitch","world" }
player.getAllowFlight	{ "uuid": "<uuid>" }	boolean
player.setAllowFlight	{ "uuid": "<uuid>", "value": <boolean> }	true

Speed Properties

Task	Request	Returns
player.getWalkSpeed	{ "uuid": "<uuid>" }	number
player.setWalkSpeed	{ "uuid": "<uuid>", "value": <float> }	true
player.getFlySpeed	{ "uuid": "<uuid>" }	number
player.setFlySpeed	{ "uuid": "<uuid>", "value": <float> }	true

Location and World

Task	Request	Returns
player.getWorld	{ "uuid": "<uuid>" }	string (world name)
player.getLocation	{ "uuid": "<uuid>" }	{ "x": <double>, "y": <double>, "z": <double>, "yaw": <double>, "pitch": <double>, "world": "<name>" }
player.teleport	{ "uuid": "<uuid>", "x": <double>, "y": <double>, "z": <double>, "yaw": <double>, "pitch": <double>, "world": "<name>" }	true
player.sendBlockChange	{ "uuid": "<uuid>", "x": <double>, "y": <double>, "z": <double>, "world": "<name>"?, "blockType": "<key>", "state": { ... }? }	true
player.getDisplayName	{ "uuid": "<uuid>" }	string
player.setDisplayName	{ "uuid": "<uuid>", "value": "<name>" }	true

---

Interaction

Messages and Notifications

Task	Request	Returns	Description
player.sendMessage	{ "uuid": "<uuid>", "message": <Message> }	true	Sends a message (message is a Message object or plain text)
player.sendActionBar	{ "uuid": "<uuid>", "message": <Message> }	true	Sends an action bar message (same as above)
player.sendTitle	{ "uuid": "<uuid>", "title": "<text>", "subtitle": "<text>", "fadeIn": <int>, "stay": <int>, "fadeOut": <int> }	true	Sends title/subtitle (MiniMessage). fadeIn/stay/fadeOut are in ticks (default 10/70/20); pass null to title/subtitle to clear the respective field
player.playSound	{ "uuid": "<uuid>", "sound": "<key>", "volume": <float>, "pitch": <float> }	true	Plays a sound effect (sound is a Paper Sound enum name, e.g. block.note_block.pling)
player.stopSound	{ "uuid": "<uuid>", "sound": "<key>" }	true	Stops a specified sound. sound is resolved by registry key (e.g. minecraft:block.note_block.pling); returns an error for unknown sounds (will not accidentally stop all sounds)
player.stopAllSounds	{ "uuid": "<uuid>" }	true	Stops all sounds
player.kick	{ "uuid": "<uuid>", "reason": "<text>" }	true	Kicks the player
player.giveExp	{ "uuid": "<uuid>", "amount": <int> }	true	Grants experience points
player.hasPermission	{ "uuid": "<uuid>", "permission": "<node>" }	boolean	Checks a permission. permission is a node string; also accepts an object { "node": "<node>" } (consistent with the permission object format used in command registration); goes through the permission check (onPermissionCheck) ecosystem event first, falls back to Bukkit if unhandled
player.performCommand	{ "uuid": "<uuid>", "command": "<cmd>" }	boolean	Executes a command as the player (without the / prefix, e.g. say hi; counterpart to the server command.dispatch (console))

Message Object (Translatable Component)

Payloads involving text (such as the message field) accept a Message object or a plain string:

// 可翻译组件 + 纯文本兜底（key 与 text 可同时存在）
{ "key": "death.attack.player", "args": ["Steve", "Zombie"], "text": "§cSteve 被 Zombie 杀死了" }
// 纯文本（MiniMessage/legacy 解析）
{ "text": "<red>你死了</red>" }
// 纯字符串等价于 { "text": "<string>" }

Field	Type	Description
key	string	Minecraft translation key (e.g. death.attack.player); when present, constructs a translatable component
args	array	Translation arguments: string / number / nested Message (optional)
text	string	Plain text fallback (used when key is absent; both are passed when present alongside key)

Implementation note: All implementations must at least support the text field (plain text); key/args are for translatable component support. When both key and text are present, both are passed (key for localization, text as a cross-implementation forwarding fallback).

Resource Pack

Task	Request	Returns	Description
player.sendResourcePack	{ "uuid": "<uuid>", "url": "<url>", "hash": "<sha1>", "prompt": <Message>, "force": <boolean> }	true	Prompts the client to download a resource pack. hash is a SHA-1 hex string; prompt is a Message object or plain text

Held Items

Task	Request	Returns	Description
player.getItemInMainHand	{ "uuid": "<uuid>" }	ItemStack | null	Reads the main hand item; returns null when empty
player.getItemInOffHand	{ "uuid": "<uuid>" }	ItemStack | null	Reads the off hand item; returns null when empty
player.setItemInMainHand	{ "uuid": "<uuid>", "item": <ItemStack | null> }	true	Sets the main hand item (full ItemStack with meta; null clears it)
player.setItemInOffHand	{ "uuid": "<uuid>", "item": <ItemStack | null> }	true	Sets the off hand item (same as above)

Tab List / Border (2026-08-13)

Task	Request	Returns	Description
player.sendTabHeader	{ "uuid": "<uuid>", "header": "<text>"?, "footer": "<text>"? }	true	Tab list header/footer (MiniMessage; null clears the respective field)
player.setPlayerListName	{ "uuid": "<uuid>", "name": "<text>"? }	true	Tab list display name (null restores default)

ItemStack return format (pure data, values are a snapshot at the time of reading):

{
  "type": "minecraft:diamond_sword",
  "amount": 1,
  "meta": {
    "displayName": "Sharp Sword",
    "lore": ["A very sharp sword"],
    "customModelData": 100,
    "unbreakable": true,
    "enchantments": { "minecraft:sharpness": 5 }
  }
}

---

Snapshot

A snapshot merges several single-field reads into one round trip: the implementation reads everything on the game thread once and returns a read-only copy. The copy reflects the state at read time — later changes are not reflected on it.

player.snap

• Request: { "uuid": "<uuid>" }
• Returns: an object (fields below); an error object if the player is offline

Shared entity fields (identical field-by-field with entity.snap): uuid, type, name, customName, world, location, isGlowing, isInvulnerable, isSilent, hasGravity, passengers, vehicle, boundingBox, velocity, fireTicks, ticksLived, isOnGround, health, maxHealth, isDead.

Player-specific fields:

Field	Type	Description
online	boolean	Online state
ping	number	Latency (ms)
gamemode	string	survival / creative / adventure / spectator
food	number	Food level 0-20
saturation	number	Saturation
exp	number	Progress 0.0-1.0
level	number	Experience level
totalExperience	number	Total experience
isOp	boolean	Operator flag
allowFlight	boolean	Flight allowed
isFlying	boolean	Flying
isSneaking	boolean	Sneaking
isSprinting	boolean	Sprinting
walkSpeed	number	Walk speed
flySpeed	number	Fly speed
displayName	string	Display name (legacy text)
bedLocation	object | null	Bed respawn point (location object)
mainHand / offHand	object | null	Held items (same shape as inventory items; null when empty)

Value object shapes:

• Location object (location / bedLocation / spawnLocation): { "x", "y", "z", "yaw", "pitch", "world" }
• Bounding box (boundingBox): { "minX", "minY", "minZ", "maxX", "maxY", "maxZ" }
• Velocity (velocity): { "x", "y", "z" }

Text Formatting Conventions

All message, title, subtitle, displayName, prompt, reason fields that accept text support:

• MiniMessage format (starting with <)
• Legacy § section separator format (backward compatible)

For format rules and lists covering value domains (game modes, sounds, potion effects, enchantments, ItemFlags, damage types, etc.), see the Values Appendix.