Interface Player
- All Superinterfaces:
Audience, BossBarViewer, CommandSender, Entity, HoverEventSource<HoverEvent.ShowEntity>, Identified, LivingEntity, ObjectContentsLike, PermissionHolder, Pointered, SchedulerSource, Sound.Emitter, Sound.Source.Provider
A Player reference is not stable across the server lifecycle, as entering the
CONFIGURATION phase (see enterConfigurationPhase()) discards the
underlying player and recreates it, which invalidates every reference held
before that point.
Player references should not be cached, as a reference obtained from an event or lookup is only
guaranteed valid for the duration of that call. Instead, re-fetch by UUID or name via
PlayerManager.get(UUID) or PlayerManager.get(String).
- Since:
- 0.1.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intThe most bytes a cookie can hold, as the client allows. -
Method Summary
Modifier and TypeMethodDescriptionReturns the abilities of this player.activatePostEffect(Key effect) Activates a post effect if it is not already active, adding it to the end of the list.Returns the active post effects, in order.address()Gets the address this player is connected from.attributeBase(TypedKey<Attribute> attribute) Returns the base value set for an attribute.Deactivates every active post effect.Gets the brand the client announced: the name it gives itself, such as that of its mod loader.default CommandSourceReturns the source a command run by this sender starts from.deactivatePostEffect(Key effect) Deactivates a post effect if it is active.Returns the ender chest of this player.Switches this player's connection state from PLAY to CONFIGURATION.intReturns how many experience points take this player from their level to the next.intReturns the experience level of this player.floatReturns how far this player is towards the next level.doubleReturns how high above their feet this player's eyes are, lower while sneaking.gameMode()Returns the current game mode of this player.voidgiveExperience(int points) Gives this player experience points, or takes some with a negative amount; the level follows.voidgiveExperienceLevels(int levels) Gives this player whole levels, or takes some with a negative amount; the experience bar stays as full as it was.default ItemStackheldItem()default Identityidentity()input()Returns the movement keys this player is holding, as last reported by their client.Returns the inventory this player carries; callupdateInventory()after changing it.booleanbooleanChecks whether this player joined through a transfer from another server, rather than by connecting directly.voidDisconnects this player.default Stringname()Returns the name of this sender.default OfflinePlayeroffline()Gets the offline handle for this player's identity.intping()Gets the round-trip time between the server and this player's client.Gets the channels this player's client, and the proxy in front of the server, announced they listen to.profile()Returns the identity and skin of this player.voidResends the command tree to the client, after permissions or registered commands changed.voidresetAttributeBase(TypedKey<Attribute> attribute) Gives an attribute back the base value a vanilla player has.respawn()Respawns this player, exactly as if they had clicked the button on the death screen.CompletableFuture<Optional<byte[]>> retrieveCookie(Key key) Asks this player's client for a cookie, stored by this server or by the one that transferred the player here.intvoidsendPluginMessage(Key channel, byte[] data) Sends a plugin message to this player's client, or to the proxy in front of the server, which reads it on the player's connection.setAbilities(PlayerAbilities abilities) Changes the abilities of this player, on its own thread.setActivePostEffects(SequencedCollection<Key> effects) Replaces the currently active post effects.voidsetAttributeBase(TypedKey<Attribute> attribute, double base) Changes the base value of an attribute for this player.voidsetExperience(int level, float progress) Sets the experience of this player.voidsetGameMode(GameMode gameMode) Changes the game mode of this player.default voidsetHeldItem(@Nullable ItemStack stack) Replaces the stack in the currently selected hotbar slot.voidsetRespawnPoint(@Nullable RespawnPoint point) Sets where this player respawns.default voidsetRespawnPoint(Location location) default voidsetRespawnPoint(World world, Location location) voidsetSelectedSlot(int slot) voidstoreCookie(Key key, byte[] payload) Stores a cookie on this player's client, replacing any cookie stored under the same key.intReturns every experience point this player gained since they last lost their experience.voidSends this player to another server, as/transferdoes.voidUpdates the player's inventory on the client side.default UUIDuuid()Returns the persistent identity of this entity.Methods inherited from interface Audience
clearResourcePacks, clearTitle, closeDialog, deleteMessage, deleteMessage, filterAudience, forEachAudience, hideBossBar, openBook, openBook, openBook, playSound, playSound, playSound, removeResourcePacks, removeResourcePacks, removeResourcePacks, removeResourcePacks, removeResourcePacks, resetTitle, sendActionBar, sendActionBar, sendMessage, sendMessage, sendMessage, sendMessage, sendMessage, sendPlayerListFooter, sendPlayerListFooter, sendPlayerListHeader, sendPlayerListHeader, sendPlayerListHeaderAndFooter, sendPlayerListHeaderAndFooter, sendResourcePacks, sendResourcePacks, sendResourcePacks, sendTitlePart, showBossBar, showDialog, showTitle, stopSound, stopSoundMethods inherited from interface BossBarViewer
activeBossBarsMethods inherited from interface CommandSender
serverMethods inherited from interface Entity
chunk, displayName, entityId, isRemoved, location, remove, server, teleport, teleport, teleport, type, worldMethods inherited from interface HoverEventSource
asHoverEvent, asHoverEventMethods inherited from interface LivingEntity
absorptionAmount, activeEffects, addEffect, armor, armorToughness, clearEffects, damage, effect, equipment, fireTicks, hasEffect, headYaw, heal, health, isAlive, isDead, kill, knockbackResistance, maxHealth, removeEffect, setAbsorptionAmount, setFireTicks, setHeadYaw, setHealthMethods inherited from interface ObjectContentsLike
asObjectContentsMethods inherited from interface PermissionHolder
activeOverrides, hasPermission, hasPermission, invalidatePermissions, isOperator, isPermissionDecided, newGrant, permissionState, permissionState, setOperatorMethods inherited from interface Pointered
get, getOrDefault, getOrDefaultFrom, pointersMethods inherited from interface SchedulerSource
execute, execute, executeDelayed, executeDelayed, isOwnedByCurrentThreadMethods inherited from interface Sound.Source.Provider
soundSource
-
Field Details
-
MAX_COOKIE_SIZE
static final int MAX_COOKIE_SIZEThe most bytes a cookie can hold, as the client allows.- Since:
- 0.1.0
- See Also:
-
-
Method Details
-
refreshCommands
void refreshCommands()Resends the command tree to the client, after permissions or registered commands changed.- Since:
- 0.1.0
-
profile
PlayerProfile profile()Returns the identity and skin of this player.- Returns:
- the identity and skin of this player
- Since:
- 0.1.0
-
offline
Gets the offline handle for this player's identity.- Returns:
- the handle for this player's identity
- Since:
- 0.1.0
-
identity
- Specified by:
identityin interfaceIdentified
-
uuid
-
name
Description copied from interface:CommandSenderReturns the name of this sender.- Specified by:
namein interfaceCommandSender- Returns:
- the name of this sender
-
address
InetAddress address()Gets the address this player is connected from.- Returns:
- the client address
- Throws:
IllegalStateException- if the connection has no resolvable IP address- Since:
- 0.1.0
-
ping
int ping()Gets the round-trip time between the server and this player's client.- Returns:
- the round-trip time in milliseconds
- Since:
- 0.1.0
-
kick
Disconnects this player.- Parameters:
reason- the message shown on the disconnection screen- Since:
- 0.1.0
-
transfer
Sends this player to another server, as/transferdoes.The client leaves this server on its own and connects to
host:port, telling it that it is being transferred. The target server must accept transfers, or the player is turned away there.- Parameters:
host- the hostname or IP address of the target serverport- the port of the target server, from1to65535- Throws:
IllegalArgumentException- ifhostis null orportis out of range- Since:
- 0.1.0
-
isTransferred
boolean isTransferred()Checks whether this player joined through a transfer from another server, rather than by connecting directly.Anything can claim to be a transfer: when it matters, check where the player comes from with your own means.
- Returns:
trueif the client announced a transfer when it connected- Since:
- 0.1.0
-
storeCookie
Stores a cookie on this player's client, replacing any cookie stored under the same key.The client keeps its cookies for the current session only: they follow the player through transfers, so the next server can read them back, and are lost when the player disconnects. The client can send back anything, so sign a cookie (an HMAC with a secret shared by your servers, for instance) when you need to trust it.
- Parameters:
key- the identifier of the cookiepayload- the content of the cookie, at mostMAX_COOKIE_SIZEbytes; it is copied- Throws:
IllegalArgumentException- ifkeyorpayloadis null, or if the payload is larger thanMAX_COOKIE_SIZEbytes- Since:
- 0.1.0
-
retrieveCookie
Asks this player's client for a cookie, stored by this server or by the one that transferred the player here.The future completes on the network thread: do not block it, and hand any work on the world over to the right thread. To check a cookie before the player joins, use
PlayerLoginAttemptEvent.retrieveCookie(Key, Consumer)instead.- Parameters:
key- the identifier of the cookie- Returns:
- a future completed with the content of the cookie, or with an empty optional if the client has none; it completes exceptionally if the player disconnects before answering
- Throws:
IllegalArgumentException- ifkeyis null- Since:
- 0.1.0
-
sendPluginMessage
Sends a plugin message to this player's client, or to the proxy in front of the server, which reads it on the player's connection.Any channel works, without declaring it first. The other side ignores the channels it does not listen to:
pluginChannels()tells which ones it announced.- Parameters:
channel- the channeldata- the content of the message, at mostPluginMessenger.MAX_SENT_SIZEbytes; it is copied- Throws:
IllegalArgumentException- ifchannelordatais null, if the data is too large, or if the channel isPluginMessenger.REGISTERorPluginMessenger.UNREGISTER- Since:
- 0.1.0
- See Also:
-
pluginChannels
-
clientBrand
-
inventory
PlayerInventory inventory()Returns the inventory this player carries; callupdateInventory()after changing it.- Returns:
- the inventory this player carries; call
updateInventory()after changing it - Since:
- 0.1.0
-
enderChest
EnderChestInventory enderChest()Returns the ender chest of this player.- Returns:
- the ender chest of this player
- Since:
- 0.1.0
-
selectedSlot
int selectedSlot()- Returns:
- the hotbar slot (
0-8) currently selected by this player - Since:
- 0.1.0
-
setSelectedSlot
void setSelectedSlot(int slot) - Parameters:
slot- the hotbar slot to select,0-8- Throws:
IllegalArgumentException- ifslotis out of[0, 8]- Since:
- 0.1.0
-
input
PlayerInput input()Returns the movement keys this player is holding, as last reported by their client.- Returns:
- the movement keys this player is holding, as last reported by their client
- Since:
- 0.1.0
-
eyeHeight
double eyeHeight()Returns how high above their feet this player's eyes are, lower while sneaking.- Returns:
- how high above their feet this player's eyes are, lower while sneaking
-
setAttributeBase
Changes the base value of an attribute for this player.The player's client applies it at once: a
movement speedof0stops them from walking, ablock interaction rangeof0from reaching any block. The value is kept until it is reset or the player disconnects, including across respawns and world changes. The client clamps it to the range of the attribute.- Parameters:
attribute- the attribute, seeAttributeKeysbase- the new base value- Throws:
IllegalArgumentException- if the attribute does not exist orbaseis not finite- Since:
- 0.1.0
-
resetAttributeBase
Gives an attribute back the base value a vanilla player has.Does nothing when the base value was not changed.
- Parameters:
attribute- the attribute, seeAttributeKeys- Throws:
IllegalArgumentException- if the attribute does not exist- Since:
- 0.1.0
-
attributeBase
Returns the base value set for an attribute.- Parameters:
attribute- the attribute, seeAttributeKeys- Returns:
- the value given to
setAttributeBase(TypedKey, double), or empty when the attribute has the base value a vanilla player has - Since:
- 0.1.0
-
heldItem
- Returns:
- the stack in the currently selected hotbar slot,
never
null(ItemStack.EMPTYwhen nothing is held) - Since:
- 0.1.0
-
setHeldItem
Replaces the stack in the currently selected hotbar slot.- Parameters:
stack- the new stack,nullis normalized toItemStack.EMPTY- Since:
- 0.1.0
-
experienceLevel
int experienceLevel()Returns the experience level of this player., the number shown above the experience bar- Returns:
- the experience level of this player
- Since:
- 0.1.0
-
experienceProgress
float experienceProgress()Returns how far this player is towards the next level., from0to1excluded: how full the experience bar is- Returns:
- how far this player is towards the next level
- Since:
- 0.1.0
-
totalExperience
int totalExperience()Returns every experience point this player gained since they last lost their experience.- Returns:
- every experience point this player gained since they last lost their experience
- Since:
- 0.1.0
-
experienceForNextLevel
int experienceForNextLevel()Returns how many experience points take this player from their level to the next.As in Vanilla:
7 + 2 * levelbelow level 15,37 + 5 * (level - 15)below level 30,112 + 9 * (level - 30)from there on.- Returns:
- how many experience points take this player from their level to the next
- Since:
- 0.1.0
-
giveExperience
void giveExperience(int points) Gives this player experience points, or takes some with a negative amount; the level follows.- Parameters:
points- how many experience points to give- Since:
- 0.1.0
-
giveExperienceLevels
void giveExperienceLevels(int levels) Gives this player whole levels, or takes some with a negative amount; the experience bar stays as full as it was. Every fifth level reached rings.- Parameters:
levels- how many levels to give- Since:
- 0.1.0
-
setExperience
void setExperience(int level, float progress) Sets the experience of this player.- Parameters:
level- the experience level, not negativeprogress- how far towards the next level, from0to1excluded- Throws:
IllegalArgumentException- iflevelis negative- Since:
- 0.1.0
-
gameMode
GameMode gameMode()Returns the current game mode of this player.- Returns:
- the current game mode of this player
- Since:
- 0.1.0
-
setGameMode
Changes the game mode of this player.- Parameters:
gameMode- the new game mode- Since:
- 0.1.0
-
abilities
PlayerAbilities abilities()Returns the abilities of this player.- Returns:
- the abilities of this player
- Since:
- 0.1.0
-
setAbilities
Changes the abilities of this player, on its own thread.- Parameters:
abilities- the new abilities- Returns:
- a future completing with
trueonce applied, orfalseif the player was removed - Since:
- 0.1.0
-
isAwaitingRespawn
boolean isAwaitingRespawn()- Returns:
truewhile this player is dead and still on the respawn screen- Since:
- 0.1.0
-
respawn
CompletableFuture<Boolean> respawn()Respawns this player, exactly as if they had clicked the button on the death screen.The respawn is queued on the region owning the player and happens on the next tick, so it is safe to call from a
PlayerDeathEventlistener to skip the death screen entirely. The player comes back at their respawn point, or at the world spawn when they have none, and aPlayerRespawnEventis fired as usual.- Returns:
- a future completing with
trueonce the player has actually been moved to their respawn point, orfalseif the respawn was refused (the player is not waiting to respawn or has left the server) or the move to the respawn point failed - Since:
- 0.1.0
-
respawnPoint
@Nullable RespawnPoint respawnPoint()- Returns:
- where this player respawns, or
nullwhen they use the world spawn - Since:
- 0.1.0
-
setRespawnPoint
Sets where this player respawns. The point is saved with the rest of their data and restored on their next login.- Parameters:
point- the point to respawn at, ornullto fall back to the world spawn- Since:
- 0.1.0
-
setRespawnPoint
-
setRespawnPoint
- Parameters:
location- the position to respawn at, in the player's current world- Since:
- 0.1.0
-
enterConfigurationPhase
CompletableFuture<Boolean> enterConfigurationPhase()Switches this player's connection state from PLAY to CONFIGURATION. Useful for resending data synced during the CONFIGURATION phase.- Returns:
- a future completing with
trueonce the player's data is saved and the client has been told to switch, orfalseif the player is already switching, not in play, or cannot be switched - Since:
- 0.1.0
- API Note:
- This removes the player from the world fully and creates them anew,
firing
PlayerQuitEvent,PlayerJoinEvent, and saving their data to disk. Any reference to thisPlayerheld before this call should be considered stale.
-
updateInventory
void updateInventory()Updates the player's inventory on the client side.This is useful when the server has changed the inventory contents, and the client needs to be informed of those changes. This method should be called after any modifications to the player's inventory, such as adding or removing items, to ensure that the client sees the correct state.
- Since:
- 0.1.0
-
activePostEffects
Returns the active post effects, in order.- Returns:
- the active post effects, in order
- Since:
- 0.1.0
-
setActivePostEffects
Replaces the currently active post effects.- Parameters:
effects- the post effect keys, in order- Returns:
- a future completing with
trueif the active post effects changed, orfalseif they were alreadyeffects, the change was cancelled, or the player left first - Since:
- 0.1.0
-
activatePostEffect
Activates a post effect if it is not already active, adding it to the end of the list.- Parameters:
effect- the post effect key- Returns:
- a future completing with
trueif it was activated, orfalseif it was already active, the change was cancelled, or the player left first - Since:
- 0.1.0
-
deactivatePostEffect
Deactivates a post effect if it is active.- Parameters:
effect- the post effect key- Returns:
- a future completing with
trueif it was deactivated, orfalseif it was not active, the change was cancelled, or the player left first - Since:
- 0.1.0
-
clearActivePostEffects
CompletableFuture<Boolean> clearActivePostEffects()Deactivates every active post effect.- Returns:
- a future completing with
trueif any post effect was deactivated, orfalseif none were active, the change was cancelled, or the player left first - Since:
- 0.1.0
-
commandSource
Description copied from interface:CommandSenderReturns the source a command run by this sender starts from.- Specified by:
commandSourcein interfaceCommandSender- Returns:
- the source a command run by this sender starts from
-