Skip to content
Hytale Modding Docs

Player

Player

Section titled “Player”

Package: com.hypixel.hytale.server.core.entity.entities

public class Player extends LivingEntity implements CommandSender, PermissionHolder, MetricProvider

The core player entity class. Represents a connected human player in the game world. Extends LivingEntity with player-specific functionality: UI managers, game mode control, spawn protection, permissions, and command sending.

Player implements three interfaces:

  • CommandSender — can execute commands and receive messages
  • PermissionHolder — has a permission set that can be queried
  • MetricProvider — exposes performance metrics for monitoring

Constants

Section titled “Constants”
public static final int DEFAULT_VIEW_RADIUS_CHUNKS = 6

Default client view radius in chunks. Controls how far the server sends chunk data to the client.

public static final long RESPAWN_INVULNERABILITY_TIME_NANOS = TimeUnit.MILLISECONDS.toNanos(3000L)

Duration of spawn protection after respawning, in nanoseconds. During this window, hasSpawnProtection() returns true and the player is immune to damage.

public static final long MAX_TELEPORT_INVULNERABILITY_MILLIS = 10_000L  // 10000ms

Maximum duration of invulnerability after a teleport, in milliseconds. Prevents damage during the brief period where the client is loading the new location.

Serialization

Section titled “Serialization”

Player has a BuilderCodec CODEC that extends LivingEntity.CODEC with player-specific fields (game mode, view radius, spawn state, configuration data).

Methods

Section titled “Methods”

Component Type

Section titled “Component Type”
@Nonnull
public static ComponentType<EntityStore, Player> getComponentType()

Returns the ECS ComponentType for Player. Used to access the Player component on an entity ref via Store.getComponent().

Initialization

Section titled “Initialization”
public void init(@Nonnull UUID uuid, @Nonnull PlayerRef playerRef)

Initializes the player with the given UUID and player reference. Called when a player connection is established and the player entity is created. Sets up the player’s identity and binds the network connection.

Configuration

Section titled “Configuration”
@Nonnull
public PlayerConfigData getPlayerConfigData()

Returns the player’s persistent configuration data. PlayerConfigData stores per-player settings that persist across sessions.

UI Managers

Section titled “UI Managers”

Player owns several manager objects that control different aspects of the player’s client-side UI.

@Nonnull
public WorldMapTracker getWorldMapTracker()

Returns the world map tracker. Manages the player’s world map state and exploration data.

@Nonnull
public WindowManager getWindowManager()

Returns the window manager. Controls server-driven UI windows (inventories, crafting tables, NPC dialogs).

@Nonnull
public PageManager getPageManager()

Returns the page manager. Manages multi-page UI content.

@Nonnull
public HudManager getHudManager()

Returns the HUD manager. Controls the player’s heads-up display elements.

@Nonnull
public HotbarManager getHotbarManager()

Returns the hotbar manager. Manages hotbar slot selection and content.

public void resetManagers(@Nonnull Holder<EntityStore> holder)

Resets all UI managers to their default state. Called during respawn or world transfer to ensure a clean UI state.

Spawn State

Section titled “Spawn State”
public boolean isFirstSpawn()

Returns true if this is the player’s first time spawning in this world (i.e., they have never joined before).

public void setFirstSpawn(boolean firstSpawn)

Sets the first-spawn flag. Cleared after the player’s initial spawn sequence completes.

public boolean hasSpawnProtection()

Returns true if the player is currently within the spawn protection window (RESPAWN_INVULNERABILITY_TIME_NANOS after their last respawn). During this window, the player is immune to damage.

Respawn

Section titled “Respawn”
@Nonnull
public static CompletableFuture<Transform> getRespawnPosition(@Nonnull Ref<EntityStore> ref, @Nonnull String worldName, @Nonnull ComponentAccessor<EntityStore> componentAccessor)

Resolves the player’s respawn position in the named world. Returns a CompletableFuture because respawn position resolution may require asynchronous operations (loading spawn chunks, checking for valid spawn locations, collision checking). The returned Transform includes position and orientation.

Game Mode

Section titled “Game Mode”
public GameMode getGameMode()

Returns the player’s current game mode.

public static void setGameMode(@Nonnull Ref<EntityStore> playerRef, @Nonnull GameMode gameMode, @Nonnull ComponentAccessor<EntityStore> componentAccessor)

Sets the player’s game mode. Dispatches a ChangeGameModeEvent so that systems and plugins can react to the mode change. Static because it operates on the ref and component accessor directly.

public static void initGameMode(@Nonnull Ref<EntityStore> playerRef, @Nonnull ComponentAccessor<EntityStore> componentAccessor)

Initializes the player’s game mode during entity setup. Applies the default game mode without dispatching a change event.

View Radius

Section titled “View Radius”
public int getClientViewRadius()

Returns the client-side view radius in chunks. This is the radius the client has requested or been configured with.

public int getViewRadius()

Returns the effective server-side view radius in chunks. May differ from the client view radius due to server-side caps or per-player overrides.

Block Placement

Section titled “Block Placement”
public boolean isOverrideBlockPlacementRestrictions()

Returns whether block placement restrictions are overridden for this player. When true, the player can place blocks in locations that would normally be restricted (e.g., overlapping entities, protected regions).

public void setOverrideBlockPlacementRestrictions(@Nonnull Ref<EntityStore> ref, boolean overrideBlockPlacementRestrictions, @Nonnull ComponentAccessor<EntityStore> componentAccessor)

Sets whether block placement restrictions are overridden for this player.

Item Pickup

Section titled “Item Pickup”
public void notifyPickupItem(@Nonnull Ref<EntityStore> ref, @Nonnull ItemStack itemStack, @Nullable Vector3d position, @Nonnull ComponentAccessor<EntityStore> componentAccessor)

Notifies the player that they have picked up an item. Sends the appropriate client notification (pickup animation, inventory update). The position parameter specifies where the item was in the world, or null if the pickup has no spatial origin (e.g., given via command).

CommandSender Implementation

Section titled “CommandSender Implementation”
@Override
public void sendMessage(@Nonnull Message message)

Sends a formatted message to the player’s chat. Implementation of CommandSender.sendMessage().

@Override
public String getDisplayName()

Returns the player’s display name (their username). Implementation of CommandSender.getDisplayName().

PermissionHolder Implementation

Section titled “PermissionHolder Implementation”
@Override
public boolean hasPermission(@Nonnull String id)

Returns whether the player has the named permission. Returns false if the permission is not set.

@Override
public boolean hasPermission(@Nonnull String id, boolean def)

Returns whether the player has the named permission, returning def if the permission is not explicitly set.

Persistence

Section titled “Persistence”
@Nonnull
public CompletableFuture<Void> saveConfig(@Nonnull World world, @Nonnull Holder<EntityStore> holder)

Saves the player’s configuration data to persistent storage. Returns a CompletableFuture that completes when the save is finished. Called during world save, player disconnect, and periodic auto-save.

Section titled “Related Types”
  • LivingEntity — parent class providing inventory, stat modifiers, and fall damage
  • Entity — root entity class providing identity, lifecycle, and world membership
  • CommandSender — interface for command execution and message receiving
  • Store — the EntityStore containing player component data
  • Ref — entity reference used in most player operations
  • ComponentType — type key returned by getComponentType()
  • PermissionHolder — interface for permission checks
  • MetricProvider — interface for performance metric exposure
  • GameMode — enum of available game modes
  • ChangeGameModeEvent — event dispatched when game mode changes via setGameMode()
  • HotbarManager — manages hotbar slot state
  • WindowManager — manages server-driven UI windows
  • PageManager — manages multi-page UI content
  • HudManager — manages HUD elements
  • WorldMapTracker — manages world map exploration state
  • CameraManager — manages camera behavior (not exposed via public getter)
  • MovementManager — manages movement state (not exposed via public getter)
  • PlayerConfigData — persistent per-player configuration
  • PlayerRef — network-level player reference
  • Transform — position and orientation, returned by getRespawnPosition()
  • World — the world the player inhabits
  • ItemStack — item data for pickup notifications