Player API

This reference covers the core classes for working with players in Hytale server mods.

PlayerRef vs Player

Class	Purpose	Thread Safety
`PlayerRef`	Handle for connected player, works anywhere	Safe from any thread
`Player`	ECS component with game state	Requires world thread

PlayerRef is the primary handle - use it for messaging, transfers, and getting the entity reference.

Player is the ECS component - use it for game state like inventory, game mode, and managers.

PlayerRef

The primary handle for interacting with a connected player. Accessible from anywhere, even off the world thread.

Package: com.hypixel.hytale.server.core.universe.PlayerRef

Key Properties

Method	Return Type	Description
`getUuid()`	`UUID`	Player’s unique identifier
`getUsername()`	`String`	Player’s display name
`getLanguage()`	`String`	Player’s language preference
`getPacketHandler()`	`PacketHandler`	Network connection for sending packets
`getChunkTracker()`	`ChunkTracker`	Manages loaded chunks for this player
`getHiddenPlayersManager()`	`HiddenPlayersManager`	Controls player visibility
`getTransform()`	`Transform`	Last known position/rotation
`getWorldUuid()`	`UUID`	UUID of the world the player is in (nullable)

Key Methods

Method	Description
`sendMessage(Message)`	Send a chat message to the player
`referToServer(host, port)`	Transfer player to another server
`referToServer(host, port, data)`	Transfer with custom data

See Messaging and Server Transfer for details.

Entity Access

Method	Return Type	Description
`getReference()`	`Ref<EntityStore>`	Entity reference when in a world (nullable)
`getHolder()`	`Holder<EntityStore>`	Entity holder when not in a world (nullable)
`isValid()`	`boolean`	True if player has either a reference or holder

Getting the Component Type

ComponentType<EntityStore, PlayerRef> type = PlayerRef.getComponentType();

Getting Player from Commands

public class MyCommand extends AbstractPlayerCommand {
    @Override
    protected void execute(CommandContext context, Store<EntityStore> store,
                          Ref<EntityStore> ref, PlayerRef playerRef, World world) {
        // playerRef is the command sender
        UUID uuid = playerRef.getUuid();
        String name = playerRef.getUsername();

        // get Player component
        Player player = store.getComponent(ref, Player.getComponentType());
    }
}

Getting Player from Events

events.registerGlobal(PlayerConnectEvent.class, event -> {
    PlayerRef playerRef = event.getPlayerRef();
    Holder<EntityStore> holder = event.getHolder();

    // access components from holder
    Player player = holder.getComponent(Player.getComponentType());
});

events.registerGlobal(PlayerReadyEvent.class, event -> {
    Ref<EntityStore> ref = event.getPlayerRef();
    Player player = event.getPlayer();

    // player is now fully loaded in world
});

Checking Online Status

PlayerRef player = Universe.get().getPlayer(uuid);
if (player != null && player.isValid()) {
    // player is online and connected
}

Code Reference

Class	Package
`PlayerRef`	`com.hypixel.hytale.server.core.universe.PlayerRef`
`Player`	`com.hypixel.hytale.server.core.entity.entities.Player`
`Universe`	`com.hypixel.hytale.server.core.universe.Universe`
`World`	`com.hypixel.hytale.server.core.universe.world.World`
`PlayerUtil`	`com.hypixel.hytale.server.core.universe.world.PlayerUtil`
`GameMode`	`com.hypixel.hytale.protocol.GameMode`