05-player-entity.md

Player & Entity System

Key Classes

PlayerRef (Component<EntityStore>) — persistent player identity
  └── Holder<EntityStore> — entity data container (when not in world)
  └── Ref<EntityStore> — live reference (when in world/Store)

Player (Component<EntityStore>) — player gameplay component
  └── GameMode, HotbarManager, MovementManager, CameraManager, etc.

World — game world containing entities
Universe — manages worlds and player refs

PlayerRef

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

The primary identifier for a connected player. Implements Component<EntityStore> and IMessageReceiver.

Key Methods

// Identity
@Nonnull public UUID getUuid();
@Nonnull public String getUsername();
@Nonnull public String getLanguage();

// Entity access
@Nullable public Holder<EntityStore> getHolder();          // When not in Store
@Nullable public Ref<EntityStore> getReference();          // When in Store (live)
public boolean isValid();                                   // Entity or holder exists

// Component access (deprecated, use Store directly)
@Nullable @Deprecated
public <T extends Component<EntityStore>> T getComponent(@Nonnull ComponentType<EntityStore, T> componentType);

// World management
@Nullable public Ref<EntityStore> addToStore(@Nonnull Store<EntityStore> store);
@Nonnull public Holder<EntityStore> removeFromStore();

// Messaging (implements IMessageReceiver)
public void sendMessage(@Nonnull Message message);
public void sendMessage(@Nonnull Message message, @Nonnull ChatType chatType);

// Network
@Nonnull public PacketHandler getPacketHandler();
@Nonnull public ChunkTracker getChunkTracker();
@Nonnull public HiddenPlayersManager getHiddenPlayersManager();

// ComponentType accessor
@Nonnull public static ComponentType<EntityStore, PlayerRef> getComponentType();

Getting PlayerRef from Events

// From PlayerConnectEvent/PlayerDisconnectEvent:
PlayerRef playerRef = event.getPlayerRef();

// From AddPlayerToWorldEvent (keyed ECS event):
Holder<EntityStore> holder = event.getHolder();
PlayerRef playerRef = holder.getComponent(PlayerRef.getComponentType());

Player

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

The gameplay component attached to a player entity. Provides game state access.

Key Methods

// Game mode
public GameMode getGameMode();
public void setGameMode(GameMode gameMode);

// ComponentType accessor
@Nonnull public static ComponentType<EntityStore, Player> getComponentType();

Accessing Player from PlayerRef

// Via Holder (when player not in world Store):
Holder<EntityStore> holder = playerRef.getHolder();
Player player = holder.getComponent(Player.getComponentType());

// Via Ref (when player is in world Store):
Ref<EntityStore> ref = playerRef.getReference();
Store<EntityStore> store = ref.getStore();
Player player = store.getComponent(ref, Player.getComponentType());

World

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

public class World {
    @Nonnull public String getName();
    // ... world management methods
}

Getting World from Events

// From PlayerConnectEvent:
World world = event.getWorld(); // May be null

// From AddPlayerToWorldEvent:
World world = event.getWorld();

Universe

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

Singleton access: Universe.get()

public class Universe {
    public static Universe get();
    public ComponentType<EntityStore, PlayerRef> getPlayerRefComponentType();
    // World management, player tracking
}

Player Sub-components

Located in server.core.entity.entities.player:

Component	Purpose
CameraManager	Camera control (fly cam, effects)
HiddenPlayersManager	Player visibility
HotbarManager	Hotbar slot management
MovementManager	Player movement state
MovementConfig	Movement parameters
PageManager	UI page management
HudManager	HUD elements

Player Data Components

Located in server.core.entity.entities.player.data:

Component	Purpose
PlayerConfigData	Player configuration
PlayerDeathPositionData	Last death position
PlayerRespawnPointData	Respawn point
PlayerWorldData	Per-world player data
UniqueItemUsagesComponent	Item usage tracking

HyperPerms Usage Patterns

// Track player on connect
private void onPlayerConnect(PlayerConnectEvent event) {
    PlayerRef playerRef = event.getPlayerRef();
    UUID uuid = playerRef.getUuid();
    String username = playerRef.getUsername();
    String worldName = event.getWorld() != null ? event.getWorld().getName() : null;
}

// Get Player entity for game mode
private Player getPlayerEntity(PlayerRef playerRef) {
    var holder = playerRef.getHolder();
    if (holder != null) {
        return holder.getComponent(Player.getComponentType());
    }
    return null;
}

// Access game mode
Player player = getPlayerEntity(playerRef);
if (player != null) {
    GameMode gameMode = player.getGameMode();
    // "adventure" or "creative"
    String modeName = gameMode.name().toLowerCase();
}

IMessageReceiver Interface

Package: com.hypixel.hytale.server.core.receiver

public interface IMessageReceiver {
    void sendMessage(Message message);
}

Both PlayerRef and CommandSender implement this interface.