PlayerScriptObject

Represents a player or console command caller, exposing usernames, UUIDs, NBT data, messaging, permissions, and per-player persistence. Obtain it from player events or through server.get_player().

View the source: PlayerScriptObject

Methods

player.check_permission(permission)

Returns a bool if the player has the specified permission. This is used internally for validating permissions of @player.on_alias events

• Permission tree order is: server > op > anyone. Custom permissions are independent of defaults, must be granted explicitly with player.set_permission(), and will return False by default

• These are arbitrary permissions for moderating auto-mcs commands, and have no relation to Bukkit permissions

Parameters	Type	Description
permission*	str	The permission name

player.set_permission(permission, enable=True)

Sets a custom permission for @player.on_alias events. Any value other than the default permissions of 'anyone', 'op', or 'server'. Names are enforced lowercase with no leading/trailing space

• Custom permissions are independent of defaults, and must be granted explicitly with this method.

• These are arbitrary permissions for moderating auto-mcs commands, and have no relation to Bukkit permissions

Parameters	Type	Description
permission*	str	The permission name
enable	bool	Enable or disable the permission. Defaults to True

player.log(message, color="gray", style="italic", hyperlink=None)

Sends a private message to the chat of the player with formatting support. Useful for command feedback with a @player.on_alias event

• player.log_success(), player.log_warning(), and player.log_error() methods can also be used, and only require the message parameter

Parameters	Type	Description
message*	str	Content to log to the player
color	str	Minecraft color ID, all values for /tellraw are accepted; see all color IDs
style	str	Can be 'normal', 'italic', 'bold', 'strikethrough', 'underlined', or 'obfuscated'. Defaults to 'italic'
hyperlink	str	URL to make the message a clickable hyperlink (1.7.2+)

Attributes

Note

Most properties are read-only. Exclusively, player.gamemode or player.dimension can be assigned, as defined below

Attribute	Type	Description
player.name	str	The player’s current username
player.uuid	str / None	The player’s current UUID (None for <1.7.2)
player.ip_address	str / None	Currently connected IP address, or None if the player is offline
player.playtime	timedelta / None	Returns the delta between when the player logged in, to the use of player.playtime. Returns None if the player is offline
player.is_server	bool	True if this object was created from the console; this will be True if the console sends a command to a @player.on_alias event, for example
player.is_online	bool	True if this player is connected to the server; this will be False if the console sends a command to a @player.on_alias event, for example
player.is_operator	bool	True if this object has operator permissions; This will be True if the console sends a command to a @player.on_alias event, for example
player.position	CoordinateObject	The player’s current position in X, Y, and Z coordinates; when assigned to a variable or persistence, it will stay a CoordinateObject. This can be referenced in a string (such as a command) with player.position or player.position.x, player.position.y, and player.position.z
player.rotation	CoordinateObject	The player’s current rotation in X, and Y values; when assigned to a variable or persistence, it will stay a CoordinateObject. This can be referenced in a string (such as a command) with player.rotation or player.rotation.x and player.rotation.y
player.motion	CoordinateObject	The player’s current motion in X, Y, and Z values; when assigned to a variable or persistence, it will stay a CoordinateObject. This can be referenced in a string (such as a command) with player.motion or player.motion.x, player.motion.y, and player.motion.z
player.spawn_position	CoordinateObject	The player’s spawn position in X, Y, and Z coordinates; when assigned to a variable or persistence, it will stay a CoordinateObject. This can be referenced in a string (such as a command) with player.spawn_position or player.spawn_position.x, player.spawn_position.y, and player.spawn_position.z
player.health	int	The player’s current health; generally a value of 0-20, but can be higher depending on attributes
player.hunger_level	int	The player’s current hunger level; value of 0-20
player.gamemode	str	The player’s current gamemode; writable for online players with player.gamemode = 'survival' from Beta 1.8 onward. Possible values include 'survival', 'creative', 'adventure', and 'spectator' on 1.8+
player.xp	float	The player’s current XP level
player.on_fire	bool	True if the player is on fire
player.is_flying	bool	True if the player is flying
player.is_sleeping	bool	True if the player is sleeping
player.is_drowning	bool	True if the player is drowning
player.hurt_time	int	Determines if the player was hurt recently (in ticks); any value above 0 yields invincibility until it reaches 0 again
player.death_time	int	How long since the player died (in ticks)
player.dimension	str	The dimension that the player is currently in; writable for online players with player.dimension = 'overworld' in Minecraft 1.13 and later. Vanilla values are 'overworld', 'the_nether', or 'the_end', while custom dimension IDs may work on modded distributions
player.active_effects	dict	Parsed effect data keyed by effect name; available fields depend on Minecraft version. Speed, for example can be accessed with player.active_effects['speed']['duration']
player.inventory	InventoryObject	Provides organized access to selected items, hotbar, armor, inventory slots, and item/NBT operations; see InventoryObject for more details
player.persistent	dict	Persistent variable storage for saving player-specific data between server restarts, or script reloads; assigning or updating a key retains it in the engine’s persistent state until changed or deleted. This data is scoped to the referenced player and server, and does not persist between different servers

Caution

Persistent data is saved on a normal shutdown or script reload. A crash or forced process termination may leave recent changes unwritten

Note

Versions prior to 1.13 load NBT from playerdata.dat, which is only updated every couple of minutes or so. Any version between 1.8-1.13 will execute save-all to force updated data. 1.13 and later retrieves all of the most recent NBT data