Player

Namespace Mc.Scripting · Kind struct (readonly)

public readonly struct Player : IEquatable<Player>

A handle to a connected player. Blittable (usable in events and ECS components).

Remarks

A handle stays valid only while the player is online: after he leaves it goes stale. Stale handles fail safe: reads return defaults, actions do nothing (see Player.IsOnline). A player who rejoins gets a new handle. All members must be called on the tick thread.

Constructors

Member	Description
Player(Entity entity)	Wraps an entity that is a player.

Constructor

public Player(Entity entity)

Wraps an entity that is a player.

Parameters

Name	Type	Description
entity	Entity	The player entity.

Fields

Member	Description
readonly Entity Entity	The underlying ECS entity.

Entity

public readonly Entity Entity;

The underlying ECS entity.

Properties

Member	Description
double Absorption { get; set; }	The golden hearts of absorption in half hearts.
IReadOnlyList<string> ActiveEffects { get; }	The keys of the effects the player has.
string Address { get; }	The client’s address as the server sees it (“127.0.0.1:50321”), empty for a stale handle.
int Air { get; set; }	The remaining air in ticks (300 is full; below 0 the player drowns).
bool AllowFlight { get; set; }	Whether the player may fly (creative mode sets it automatically).
IReadOnlyList<string> Channels { get; }	The channels the player’s client registered (minecraft:register), in the order it sent them.
Component? DisplayName { get; set; }	The name the server shows for this player where vanilla uses Player.getDisplayName: the join and leave lines, the chat sender, death and advancement messages (the team format applies to it).
double Exhaustion { get; set; }	The exhaustion, 0..40: at 4 the saturation (or food level) drops by one.
int ExperienceLevel { get; set; }	The experience level shown in the HUD.
double ExperienceProgress { get; set; }	The progress to the next level, 0..1 (the green bar).
int FireTicks { get; set; }	The ticks the player will keep burning (0 when not on fire).
float FlySpeed { get; set; }	The flying speed, 0..1 (default 0.05).
int FoodLevel { get; set; }	The food level, 0..20 (the hunger bar; below 7 sprinting stops, at 0 the player starves).
GameMode GameMode { get; set; }	The player’s game mode.
double Health { get; set; }	Health in half hearts (20 is full).
ItemStack HeldItem { get; }	The stack in the player’s main hand (empty for a stale handle).
PlayerInventory Inventory { get; }	The player’s inventory: slots, hotbar, armor, off hand and the cursor (PlayerInventory).
bool Invulnerable { get; set; }	Whether the player takes no damage (creative mode sets it automatically).
bool IsFlying { get; set; }	Whether the player is flying (creative or spectator flight, or Player.AllowFlight).
bool IsGliding { get; }	Whether the player is gliding with elytra.
bool IsNone { get; }	Whether this is the “no player” handle.
bool IsOnGround { get; }	Whether the player is on the ground.
bool IsOnline { get; }	Whether the player is connected and in the play state.
bool IsSneaking { get; }	Whether the player is sneaking (crouching).
bool IsSprinting { get; }	Whether the player is sprinting.
bool IsSwimming { get; }	Whether the player is swimming.
int Latency { get; }	The round trip time to the client in milliseconds (-1 for a stale handle).
string Locale { get; }	The client’s language, e.g.
Location Location { get; }	Position and rotation in the player’s world.
double MaxHealth { get; }	The maximum health (the attribute value, 20 by default).
string Name { get; }	The player’s name, empty for a stale handle.
int PermissionLevel { get; }	The vanilla operator level of the player (0-4, from ops.json); 0 for an offline handle.
Vec3d Position { get; }	The player’s position (feet), default for a stale handle.
double Saturation { get; set; }	The saturation, 0..Player.FoodLevel: the buffer that is used up before the food level drops.
int TotalExperience { get; }	The total experience points ever collected (drives the score on the death screen).
Uuid Uuid { get; }	The player’s profile id, default for a stale handle.
float WalkSpeed { get; set; }	The walking speed, 0..1 (default 0.1).
World World { get; }	The dimension the player is in (the overworld for a stale handle).
static Player None { get; }	The “no player” handle.

Absorption

public double Absorption { get; set; }

The golden hearts of absorption in half hearts.

ActiveEffects

public IReadOnlyList<string> ActiveEffects { get; }

The keys of the effects the player has.

Address

public string Address { get; }

The client’s address as the server sees it (“127.0.0.1:50321”), empty for a stale handle.

Air

public int Air { get; set; }

The remaining air in ticks (300 is full; below 0 the player drowns).

AllowFlight

public bool AllowFlight { get; set; }

Whether the player may fly (creative mode sets it automatically).

Channels

public IReadOnlyList<string> Channels { get; }

The channels the player’s client registered (minecraft:register), in the order it sent them. Empty for a stale handle.

DisplayName

public Component? DisplayName { get; set; }

The name the server shows for this player where vanilla uses Player.getDisplayName: the join and leave lines, the chat sender, death and advancement messages (the team format applies to it). Null when none is set, and then the profile Player.Name is shown. Set it to null to clear it. Not persisted: it is cleared when the player leaves, so a plugin that keeps nicknames sets it again on join. The profile name stays the key of commands, the scoreboard and the click and insertion text of chat. Stale handles: reads give null, writes do nothing.

Exhaustion

public double Exhaustion { get; set; }

The exhaustion, 0..40: at 4 the saturation (or food level) drops by one.

ExperienceLevel

public int ExperienceLevel { get; set; }

The experience level shown in the HUD. Setting resets the progress within the level.

ExperienceProgress

public double ExperienceProgress { get; set; }

The progress to the next level, 0..1 (the green bar).

FireTicks

public int FireTicks { get; set; }

The ticks the player will keep burning (0 when not on fire). Setting 0 extinguishes.

FlySpeed

public float FlySpeed { get; set; }

The flying speed, 0..1 (default 0.05).

FoodLevel

public int FoodLevel { get; set; }

The food level, 0..20 (the hunger bar; below 7 sprinting stops, at 0 the player starves).

GameMode

public GameMode GameMode { get; set; }

The player’s game mode. Setting it fires PlayerGameModeChangeEvent (a handler may cancel it).

Health

public double Health { get; set; }

Health in half hearts (20 is full). Setting is clamped to 0..Player.MaxHealth; 0 kills the player through the normal death handling.

HeldItem

public ItemStack HeldItem { get; }

The stack in the player’s main hand (empty for a stale handle).

Inventory

public PlayerInventory Inventory { get; }

The player’s inventory: slots, hotbar, armor, off hand and the cursor (PlayerInventory). A stale handle (a player who left) gives an inventory with no slots.

Invulnerable

public bool Invulnerable { get; set; }

Whether the player takes no damage (creative mode sets it automatically).

IsFlying

public bool IsFlying { get; set; }

Whether the player is flying (creative or spectator flight, or Player.AllowFlight). Setting it only works while Player.AllowFlight is true.

IsGliding

public bool IsGliding { get; }

Whether the player is gliding with elytra.

IsNone

public bool IsNone { get; }

Whether this is the “no player” handle.

IsOnGround

public bool IsOnGround { get; }

Whether the player is on the ground.

IsOnline

public bool IsOnline { get; }

Whether the player is connected and in the play state.

IsSneaking

public bool IsSneaking { get; }

Whether the player is sneaking (crouching).

IsSprinting

public bool IsSprinting { get; }

Whether the player is sprinting.

IsSwimming

public bool IsSwimming { get; }

Whether the player is swimming.

Latency

public int Latency { get; }

The round trip time to the client in milliseconds (-1 for a stale handle).

Locale

public string Locale { get; }

The client’s language, e.g. “en_us”.

Location

public Location Location { get; }

Position and rotation in the player’s world.

MaxHealth

public double MaxHealth { get; }

The maximum health (the attribute value, 20 by default). Read only: change it with attribute modifiers.

Name

public string Name { get; }

The player’s name, empty for a stale handle.

PermissionLevel

public int PermissionLevel { get; }

The vanilla operator level of the player (0-4, from ops.json); 0 for an offline handle.

Position

public Vec3d Position { get; }

The player’s position (feet), default for a stale handle.

Saturation

public double Saturation { get; set; }

The saturation, 0..Player.FoodLevel: the buffer that is used up before the food level drops.

TotalExperience

public int TotalExperience { get; }

The total experience points ever collected (drives the score on the death screen). Read only; use Player.GiveExperience.

Uuid

public Uuid Uuid { get; }

The player’s profile id, default for a stale handle.

WalkSpeed

public float WalkSpeed { get; set; }

The walking speed, 0..1 (default 0.1).

World

public World World { get; }

The dimension the player is in (the overworld for a stale handle).

None

public static Player None { get; }

The “no player” handle.

Methods

Member	Description
bool AddEffect(PotionEffect effect)	Adds a status effect (a stronger or longer effect of the same kind replaces the current one like in vanilla).
bool ClearEffects()	Removes every status effect.
bool ClearFakeBlock(BlockPos position)	Shows the world’s real block at a position again.
void ClearFakeBlocks()	Ends every fake block of this player.
void ClearTitle(bool resetTimes = false)	Hides the current title and subtitle.
bool Equals(Player other)
override bool Equals(object? obj)
ref T Get<T>() where T : unmanaged	Reference to a plugin component on the player’s entity; throws if the player lacks it.
PotionEffect? GetEffect(string effect)	The active effect of a kind, null when the player does not have it.
override int GetHashCode()
void GiveExperience(int points)	Gives experience points (negative takes them away), levelling up as needed, like /xp add.
void GiveExperienceLevels(int levels)	Gives whole experience levels (negative takes them away).
bool Has<T>() where T : unmanaged	Whether the player has a plugin component.
bool HasPermission(string node)	Whether the player has a permission node (groups, per-player entries, wildcards and node defaults are resolved by the permission backend).
void Kick(Component reason)	Disconnects the player.
bool ListensOn(string channel)	Whether the player’s client registered the channel (minecraft:register), that is, whether it listens on it.
PlaySound	Plays a sound to this player only, at his position.
PlaySound	Plays a sound to this player only, coming from a position.
Player Remove<T>() where T : unmanaged	Removes a plugin component from the player.
void RemoveAllResourcePacks()	Removes every resource pack the server pushed.
bool RemoveEffect(string effect)	Removes a status effect.
void RemoveResourcePack(Uuid id)	Removes a resource pack from the client.
void SendActionBar(Component message)	Shows a message in the action bar above the hotbar.
void SendMessage(Component message)	Sends a chat (system) message to the player.
bool SendPluginMessage(string channel, ReadOnlySpan<byte> data)	Sends a plugin message to the player on a channel (a custom payload of the play state).
void SendResourcePack(ResourcePack pack)	Asks the client to download and apply a resource pack.
Player Set<T>(in T value) where T : unmanaged	Adds or overwrites a plugin component on the player.
bool SetGlowingFor(Player viewer, bool glowing)	Makes this player glow for one viewer: the viewer sees the outline (for him only, the others do not change).
void SetListName(Component? name)	Changes the name everybody sees for this player in the tab list (colours, prefixes).
void SetTabList(Component? header, Component? footer)	Sets the text above and below the player list (Tab).
bool ShowBlock(BlockPos position, BlockState state)	Shows a block state at a position to this player only.
void ShowSubtitle(Component subtitle)	Shows only a subtitle (it appears together with the next title; vanilla shows nothing for a subtitle without a title).
void ShowTitle(Component title, Component? subtitle = null, TitleTimes? times = null)	Shows a title (and optionally a subtitle) in the middle of the screen.
SpawnParticle	Shows a particle effect to this player only.
void StopSound(string? sound = null, SoundCategory? category = null)	Stops sounds this player is hearing.
bool Teleport(Location location)	Teleports the player to a location, also into another dimension.
bool Teleport(Vec3d position)	Teleports the player within his dimension, keeping his rotation.
override string ToString()
void Transfer(string host, int port = 25565)	Sends the client to another server (it must accept transfers: accepts-transfers=true there).
bool TryGet<T>(out T value) where T : unmanaged	Copies a plugin component of the player if present.

AddEffect

public bool AddEffect(PotionEffect effect)

Adds a status effect (a stronger or longer effect of the same kind replaces the current one like in vanilla).

Parameters

Name	Type	Description
effect	PotionEffect	The effect.

Returns bool: Whether it was applied (false for an unknown effect key).

ClearEffects

public bool ClearEffects()

Removes every status effect.

Returns bool: Whether there was any.

ClearFakeBlock

public bool ClearFakeBlock(BlockPos position)

Shows the world’s real block at a position again.

Parameters

Name	Type	Description
position	BlockPos	The block position.

Returns bool: True when there was a fake block there.

ClearFakeBlocks

public void ClearFakeBlocks()

Ends every fake block of this player.

ClearTitle

public void ClearTitle(bool resetTimes = false)

Hides the current title and subtitle.

Parameters

Name	Type	Description
resetTimes	bool = false	Whether the timings also return to the defaults.

Equals

public bool Equals(Player other)

Parameters

Name	Type	Description
other	Player

Returns bool

Equals

public override bool Equals(object? obj)

Parameters

Name	Type	Description
obj	object?

Returns bool

Get<T>

public ref T Get<T>() where T : unmanaged

Reference to a plugin component on the player’s entity; throws if the player lacks it. The reference points into ECS storage and dies with the next structural change: re-fetch instead of keeping it.

Type parameters

• T: A component type registered with Ecs.RegisterComponent.

Returns ref T: A reference to the component.

GetEffect

public PotionEffect? GetEffect(string effect)

The active effect of a kind, null when the player does not have it.

Parameters

Name	Type	Description
effect	string	The effect key.

Returns PotionEffect?

GetHashCode

public override int GetHashCode()

Returns int

GiveExperience

public void GiveExperience(int points)

Gives experience points (negative takes them away), levelling up as needed, like /xp add.

Parameters

Name	Type	Description
points	int	The points.

GiveExperienceLevels

public void GiveExperienceLevels(int levels)

Gives whole experience levels (negative takes them away).

Parameters

Name	Type	Description
levels	int	The levels.

Has<T>

public bool Has<T>() where T : unmanaged

Whether the player has a plugin component.

Type parameters

• T: The component type.

Returns bool: True if present.

HasPermission

public bool HasPermission(string node)

Whether the player has a permission node (groups, per-player entries, wildcards and node defaults are resolved by the permission backend).

Parameters

Name	Type	Description
node	string	The dotted node, e.g. “homes.use”.

Returns bool: True when granted; false for an offline handle.

Kick

public void Kick(Component reason)

Disconnects the player. Fires PlayerKickEvent first (a handler may cancel it).

Parameters

Name	Type	Description
reason	Component	Shown on the disconnect screen.

ListensOn

public bool ListensOn(string channel)

Whether the player’s client registered the channel (minecraft:register), that is, whether it listens on it. False for a stale handle.

Parameters

Name	Type	Description
channel	string	A channel id, namespace:path.

Returns bool

PlaySound

public void PlaySound(string sound, SoundCategory category = SoundCategory.Master, float volume = 1f, float pitch = 1f)

Plays a sound to this player only, at his position.

Parameters

Name	Type	Description
sound	string	The sound event id, e.g. minecraft:entity.experience_orb.pickup.
category	SoundCategory = SoundCategory.Master	The volume slider it belongs to.
volume	float = 1f	1 is normal; above 1 the sound carries further.
pitch	float = 1f	0.5 to 2; 1 is normal.

PlaySound

public void PlaySound(string sound, Vec3d position, SoundCategory category = SoundCategory.Master, float volume = 1f, float pitch = 1f)

Plays a sound to this player only, coming from a position.

Parameters

Name	Type	Description
sound	string	The sound event id.
position	Vec3d	Where it comes from.
category	SoundCategory = SoundCategory.Master	The volume slider it belongs to.
volume	float = 1f	1 is normal; above 1 the sound carries further.
pitch	float = 1f	0.5 to 2; 1 is normal.

Remove<T>

public Player Remove<T>() where T : unmanaged

Removes a plugin component from the player.

Type parameters

• T: The component type.

Returns Player: This player.

RemoveAllResourcePacks

public void RemoveAllResourcePacks()

Removes every resource pack the server pushed.

RemoveEffect

public bool RemoveEffect(string effect)

Removes a status effect.

Parameters

Name	Type	Description
effect	string	The effect key.

Returns bool: Whether the player had it.

RemoveResourcePack

public void RemoveResourcePack(Uuid id)

Removes a resource pack from the client.

Parameters

Name	Type	Description
id	Uuid	The id of the pack that was sent.

SendActionBar

public void SendActionBar(Component message)

Shows a message in the action bar above the hotbar. No-op for a stale handle.

Parameters

Name	Type	Description
message	Component	The message.

SendMessage

public void SendMessage(Component message)

Sends a chat (system) message to the player. No-op for a stale handle.

Parameters

Name	Type	Description
message	Component	The message (a string converts to a literal component).

SendPluginMessage

public bool SendPluginMessage(string channel, ReadOnlySpan<byte> data)

Sends a plugin message to the player on a channel (a custom payload of the play state). Vanilla clients ignore channels they did not register; clients with a mod or a proxy that listens on it receive the bytes.

Parameters

Name	Type	Description
channel	string	A channel id, namespace:path. The minecraft:, velocity: and bungeecord:* channels are refused.
data	ReadOnlySpan<byte>	The payload, at most 1 MiB.

Returns bool: True when the message was queued for the player; false when it was not sent: the player is not online, the channel is invalid or reserved, the payload is too large, or the tick’s send budget is spent (scripting.channels.send_bytes_per_tick).

SendResourcePack

public void SendResourcePack(ResourcePack pack)

Asks the client to download and apply a resource pack. The answer arrives as PlayerResourcePackStatusEvent events.

Parameters

Name	Type	Description
pack	ResourcePack	The pack.

Set<T>

public Player Set<T>(in T value) where T : unmanaged

Adds or overwrites a plugin component on the player. The component disappears when the player leaves.

Type parameters

• T: The component type.

Parameters

Name	Type	Description
value	in T	The value.

Returns Player: This player.

SetGlowingFor

public bool SetGlowingFor(Player viewer, bool glowing)

Makes this player glow for one viewer: the viewer sees the outline (for him only, the others do not change). See Entity.SetGlowingFor.

Parameters

Name	Type	Description
viewer	Player	The player who sees it.
glowing	bool	Whether it glows for the viewer.

Returns bool: False when the engine refused it.

SetListName

public void SetListName(Component? name)

Changes the name everybody sees for this player in the tab list (colours, prefixes). Null restores the profile name. The name is kept until the player leaves.

Parameters

Name	Type	Description
name	Component?	The list name.

SetTabList

public void SetTabList(Component? header, Component? footer)

Sets the text above and below the player list (Tab). Null clears a part.

Parameters

Name	Type	Description
header	Component?	The header.
footer	Component?	The footer.

ShowBlock

public bool ShowBlock(BlockPos position, BlockState state)

Shows a block state at a position to this player only. The world keeps its real block; the server still collides with the real one, and the client predicts collisions against what it sees. The fake block is re-sent with its chunk and after real changes of its position, and dropped when the player changes world or leaves.

Parameters

Name	Type	Description
position	BlockPos	The block position (in the player’s world).
state	BlockState	The block state to show.

Returns bool: False when the engine refused it (the player is not in play, the state is invalid, or the per-player limit is reached).

ShowSubtitle

public void ShowSubtitle(Component subtitle)

Shows only a subtitle (it appears together with the next title; vanilla shows nothing for a subtitle without a title).

Parameters

Name	Type	Description
subtitle	Component	The subtitle.

ShowTitle

public void ShowTitle(Component title, Component? subtitle = null, TitleTimes? times = null)

Shows a title (and optionally a subtitle) in the middle of the screen. No-op for a stale handle.

Parameters

Name	Type	Description
title	Component	The big text.
subtitle	Component? = null	The smaller text below it, null for none.
times	TitleTimes? = null	Fade in / stay / fade out in ticks; null keeps the client’s current timings (vanilla defaults 10 / 70 / 20).

SpawnParticle

public bool SpawnParticle(string particle, Vec3d position, int count = 1, Vec3d offset = default, float speed = 0f, bool force = false)

Shows a particle effect to this player only.

Parameters

Name	Type	Description
particle	string	The particle (see Particle): minecraft:flame, minecraft:dust 1 0 0 1, minecraft:block minecraft:stone.
position	Vec3d	Where.
count	int = 1	How many particles (0 makes offset the direction and speed the velocity, like vanilla).
offset	Vec3d = default	The spread of the particles around position.
speed	float = 0f	The particle speed.
force	bool = false	Whether to show it beyond the usual distance and ignore the client’s particle setting.

Returns bool: False when the particle is unknown or needs options this server does not encode.

StopSound

public void StopSound(string? sound = null, SoundCategory? category = null)

Stops sounds this player is hearing.

Parameters

Name	Type	Description
sound	string? = null	The sound id to stop, null for any.
category	SoundCategory? = null	Only that category, null for all.

Teleport

public bool Teleport(Location location)

Teleports the player to a location, also into another dimension. Fires PlayerTeleportEvent (cause TeleportCause.Plugin); a handler may change the destination or cancel it.

Parameters

Name	Type	Description
location	Location	The destination.

Returns bool: True when the player was teleported; false when a handler cancelled it, the world does not exist or the handle is stale.

Teleport

public bool Teleport(Vec3d position)

Teleports the player within his dimension, keeping his rotation.

Parameters

Name	Type	Description
position	Vec3d	The destination.

Returns bool: True when the player was teleported.

ToString

public override string ToString()

Returns string

Transfer

public void Transfer(string host, int port = 25565)

Sends the client to another server (it must accept transfers: accepts-transfers=true there).

Parameters

Name	Type	Description
host	string	The host name.
port	int = 25565	The port.

TryGet<T>

public bool TryGet<T>(out T value) where T : unmanaged

Copies a plugin component of the player if present.

Type parameters

• T: The component type.

Parameters

Name	Type	Description
value	out T	The value when found.

Returns bool: Whether the player has the component.

Operators

Member	Description
static bool operator !=(Player a, Player b)	Inequality.
static bool operator ==(Player a, Player b)	Equality (same entity id).
static implicit operator Entity(Player p)	A player is the entity it wraps.

operator !=

public static bool operator !=(Player a, Player b)

Inequality.

Parameters

Name	Type	Description
a	Player
b	Player

Returns bool

operator ==

public static bool operator ==(Player a, Player b)

Equality (same entity id).

Parameters

Name	Type	Description
a	Player
b	Player

Returns bool

operator implicit

public static implicit operator Entity(Player p)

A player is the entity it wraps.

Parameters

Name	Type	Description
p	Player

Returns Entity

See also

BlockPos · BlockState · Component · Entity · GameMode · ItemStack · Location · PlayerInventory · PotionEffect · ResourcePack · SoundCategory · TitleTimes · Uuid · Vec3d · World