Player API

import { Player } from 'yeow-api';

Type relationship: Player extends LivingEntity extends Entity — Entity common capabilities (getVelocity(), getFireTicks(), getBoundingBox(), getPassengers(), teleport() etc.) and living capabilities (getHealth()/setHealth(), getMaxHealth(), damage(), setTarget() etc.) are directly available on Player, see Entity API.

Static Methods

Method	Return	Description
Player.get(identifier)	Promise<Player | null>	UUID or name, returns null if offline
Player.getAll()	Promise<Player[]>	All online players

Fields

uuid is a read-only field available from construction; name requires await player.getName() (when the object came from Player.get/an event payload the name is already cached — no round trip). Everything else is read through methods:

Method	Return	Description
getName()	Promise<string>	Player name
getPing()	Promise<number>	Latency (ms)
getGamemode() / setGamemode(v)	Promise<string> / Promise<void>	survival / creative / adventure / spectator
getHealth() / setHealth(v)	Promise<number> / Promise<void>	Health (half hearts)
getFood() / setFood(v)	Promise<number> / Promise<void>	Food level 0-20
getExp() / setExp(v)	Promise<number> / Promise<void>	Progress 0.0-1.0
getLevel() / setLevel(v)	Promise<number> / Promise<void>	Experience level
getSaturation() / getTotalExperience()	Promise<number>	Saturation / total experience
getWorld()	Promise<string>	Current world name
getLocation()	Promise<Location>	Current location
getDisplayName() / setDisplayName(v)	Promise<string> / Promise<void>	Display name
getAllowFlight() / setAllowFlight(v)	Promise<boolean> / Promise<void>	Allow flight
isFlying() / setFlying(v)	Promise<boolean> / Promise<void>	Currently flying
isSneaking() / isSprinting()	Promise<boolean>	Sneaking / sprinting
isOp() / isOnline()	Promise<boolean>	Is OP / online
getBedLocation()	Promise<Location | null>	Bed respawn point
getWalkSpeed() / setWalkSpeed(v)	Promise<number> / Promise<void>	Walk speed 0-1
getFlySpeed() / setFlySpeed(v)	Promise<number> / Promise<void>	Fly speed 0-1
inventory	Inventory	Inventory handle (purely local, no round trip)

Game mode values (gamemode) see Value Domain Appendix · Directly Maintained Enumeration List. Prefer await player.snap() when reading several fields — see Read-only snapshot.

Methods

All return Promise (use await).

Messages

player.sendMessage(msg)             // Promise — msg is plain text or Message object (translatable component)
player.kick(reason?)                 // Promise

msg accepts Message object or plain string:

await p.sendMessage('Welcome back!');                                   // Plain text (MiniMessage)
await p.sendMessage({ text: '<red>You died!</red>' });                // Plain text (equivalent)
await p.sendMessage({ key: 'death.attack.player', args: ['Steve'] }); // Translatable component (client localization)

Title & Sound

player.sendTitle(title?, subtitle?, fadeIn?, stay?, fadeOut?)   // Promise
player.playSound(sound, volume?, pitch?)                        // Promise

// World-level sound see World API
import { playSound } from 'yeow-api';
await playSound('world', 'entity.creeper.primed', 0, 65, 0, 1.0, 1.0);

// Stop sound (Player instance method, symmetric with playSound)
await p.stopSound('block.note_block.pling');
await p.stopAllSounds();

Advancement (Achievement)

player.grantAdvancement(key)                  // Promise<boolean> — Grant all advancement criteria
player.revokeAdvancement(key)                 // Promise<boolean> — Revoke advancement
player.awardCriteria(key, criteria)           // Promise<boolean> — Grant single criterion
player.revokeCriteria(key, criteria)          // Promise<boolean> — Revoke single criterion
player.getAdvancementProgress(key)            // Promise<AdvancementProgress | null>

key is advancement namespace key (e.g., minecraft:story/mine_stone). See Advancement for details.

Experience

player.giveExp(amount)              // Promise

Permissions, Commands & Teleport

player.hasPermission(node)          // Promise<boolean> — Via Yeow permission check (permission check (`onPermissionCheck`) priority, falls back to Paper system if no handler)
player.performCommand(cmd)          // Promise<boolean> — Execute command as player (without / prefix, e.g., 'say hi')
player.teleport(loc)                // Promise

Fake Block (Client Visual)

player.sendBlockChange(loc, block)      // Promise — Client visual only, doesn't change real world

block is Block object or string (same as world.setBlock, string has no state):

await p.sendBlockChange(new Location(0, 80, 0), 'minecraft:stone');
await p.sendBlockChange(new Location(0, 80, 1), Block.of('minecraft:chest', { facing: 'north' }));

Held Items

player.getItemInMainHand()          // Promise<ItemStack | null>
player.getItemInOffHand()           // Promise<ItemStack | null>

player.setItemInMainHand(item)      // Promise — Set main hand (complete ItemStack including meta; null clears)
player.setItemInOffHand(item)       // Promise — Set off hand (same as above)

Returns complete ItemStack (including meta), returns null when hand is empty. ItemStack is pure data (snapshot), see ItemStack for details.

Tab List

player.sendTabHeader(header, footer)    // Promise — Tab list header/footer (MiniMessage; null clears corresponding field)
player.setPlayerListName(name)          // Promise — Tab list display name (null restores default)

ActionBar & Resource Pack

player.sendActionBar(message)       // Promise — message is plain text or Message object
player.sendResourcePack(url, hash?, prompt?, force?)  // Promise — prompt is plain text or Message object

Read-only snapshot (snap())

Fetches the player's common state in a single round trip and returns a frozen PlayerSnapshot. Use it instead of N × await getXxx() when reading several fields (each call is a cross-thread round trip).

const s = await player.snap();
log.info(`${s.name} hp=${s.health}/${s.maxHealth} @${s.location.world} `
    + `${s.location.x},${s.location.y},${s.location.z}`);

Field	Type	Description
uuid / name	string	UUID / player name
online / ping	boolean / number	Online state / latency (ms)
gamemode	string	survival | creative | adventure | spectator
health / maxHealth	number	Current / max health
food / saturation	number	Food level / saturation
exp / level / totalExperience	number	Progress / level / total experience
isOp	boolean	Operator flag
allowFlight / isFlying	boolean	Flight allowed / flying
isSneaking / isSprinting	boolean	Sneaking / sprinting
walkSpeed / flySpeed	number	Walk / fly speed
displayName	string	Display name (legacy text)
location / bedLocation	Location / Location | null	Position (locally built, frozen)
mainHand / offHand	ItemStack | null	Main / off-hand item

Entity fields (a player is an entity, so the snapshot can be used as an EntitySnapshot): type, customName, world, isGlowing, isInvulnerable, isSilent, hasGravity, passengers, vehicle, boundingBox, velocity, fireTicks, ticksLived, isOnGround.

Helpers (all local, zero round trips):

• isAlive() — health > 0
• distanceTo({x,y,z}) / isWithin({x,y,z}, radius)
• toObject() / toJSON() — plain data copy (JSON.stringify works directly)

A snapshot is a copy at one point in time: later state changes are not reflected; writes still go through setters. Call snap() again for fresh values.

Example

const p = await Player.get('Notch');
if (p) {
    await p.setGamemode('CREATIVE');
    await p.setHealth(20);
    await p.setFood(20);
    await p.setExp(0.5);
    await p.setLevel(30);
    await p.setAllowFlight(true);
    await p.setFlying(true);
    await p.sendMessage('<green>Welcome!</green>');
    await p.sendTitle('Hello', 'Welcome to the server');
    await p.playSound('entity.experience_orb.pickup');
    await p.teleport(new Location(0, 80, 0));
}