Player Events

Package: com.hypixel.hytale.server.core.event.events.player

Events related to player connections, interactions, and state changes.

PlayerConnectEvent

Fired when a player connects, after authentication.

Class: com.hypixel.hytale.server.core.event.events.player.PlayerConnectEvent

Property	Value
Implements	`IEvent<Void>`
Cancellable	No

Methods

Method	Return Type	Description
`getHolder()`	`Holder<EntityStore>`	Returns the player entity holder
`getPlayerRef()`	`PlayerRef`	Returns the player reference
`getPlayer()`	`Player`	Returns the player component. Deprecated
`getWorld()`	`World`	Returns the initial spawn world (nullable)
`setWorld(World world)`	`void`	Sets the initial spawn world

Example (from InstancesPlugin)

events.register(PlayerConnectEvent.class, event -> {
    // set player's spawn world based on saved data
    World targetWorld = getPlayerLastWorld(event.getPlayerRef());
    if (targetWorld != null) {
        event.setWorld(targetWorld);
    }
});

PlayerDisconnectEvent

Fired when a player disconnects.

Class: com.hypixel.hytale.server.core.event.events.player.PlayerDisconnectEvent

Property	Value
Extends	`PlayerRefEvent<Void>`
Cancellable	No

Methods

Method	Return Type	Description
`getPlayerRef()`	`PlayerRef`	Returns the disconnecting player (inherited from `PlayerRefEvent`)
`getDisconnectReason()`	`DisconnectReason`	Returns the reason for disconnection

DisconnectReason

getServerDisconnectReason() - String message if server-initiated
getClientDisconnectType() - DisconnectType.Disconnect or DisconnectType.Crash

PlayerSetupConnectEvent

Fired early in connection, before entity creation. This event is cancellable - cancel to reject connection.

Class: com.hypixel.hytale.server.core.event.events.player.PlayerSetupConnectEvent

Property	Value
Implements	`IEvent<Void>`, `ICancellable`
Cancellable	Yes

Constants

Constant	Type	Value
`DEFAULT_REASON`	`String`	`"You have been disconnected from the server!"`

Methods

Method	Return Type	Description
`getPacketHandler()`	`PacketHandler`	Returns the network packet handler
`getUuid()`	`UUID`	Returns the player’s UUID
`getUsername()`	`String`	Returns the player’s username
`getAuth()`	`PlayerAuthentication`	Returns authentication details
`getReferralData()`	`byte[]`	Returns referral data (nullable)
`isReferralConnection()`	`boolean`	Returns `true` if player was referred from another server
`getReferralSource()`	`HostAddress`	Returns the source server for referrals (nullable)
`getClientReferral()`	`ClientReferral`	Returns the client referral set via `referToServer()` (nullable)
`referToServer(String host, int port)`	`void`	Redirect player to another server
`referToServer(String host, int port, byte[] data)`	`void`	Redirect with custom referral data (max 4096 bytes)
`getReason()`	`String`	Returns the disconnect reason
`setReason(String reason)`	`void`	Sets the disconnect reason

Example

events.register(PlayerSetupConnectEvent.class, event -> {
    if (isBanned(event.getUuid())) {
        event.setCancelled(true);
        event.setReason("You are banned from this server.");
    }
});

Example (Server Referral)

events.register(PlayerSetupConnectEvent.class, event -> {
    // redirect player to a different server
    event.referToServer("play.example.com", 25565);
});

PlayerSetupDisconnectEvent

Fired if player disconnects during setup phase (before fully connected).

Class: com.hypixel.hytale.server.core.event.events.player.PlayerSetupDisconnectEvent

Property	Value
Implements	`IEvent<Void>`
Cancellable	No

Methods

Method	Return Type	Description
`getUsername()`	`String`	Returns the player’s username
`getUuid()`	`UUID`	Returns the player’s UUID
`getAuth()`	`PlayerAuthentication`	Returns authentication details
`getDisconnectReason()`	`DisconnectReason`	Returns the reason for disconnection

PlayerReadyEvent

Fired when player is fully loaded in a world. Keyed by world name.

Class: com.hypixel.hytale.server.core.event.events.player.PlayerReadyEvent

Property	Value
Extends	`PlayerEvent<String>`
KeyType	`String` (world name)

Methods

Method	Return Type	Description
`getPlayerRef()`	`Ref<EntityStore>`	Returns the entity reference (inherited from `PlayerEvent`)
`getPlayer()`	`Player`	Returns the player component (inherited from `PlayerEvent`)
`getReadyId()`	`int`	Returns the ready ID, which increments each time player is ready

Example (from InstancesPlugin)

// show instance discovery notification when player loads
events.registerGlobal(PlayerReadyEvent.class, event -> {
    Player player = event.getPlayer();
    showInstanceNotification(player);
});

PlayerChatEvent

Fired when player sends a chat message. This event is async and cancellable.

Class: com.hypixel.hytale.server.core.event.events.player.PlayerChatEvent

Property	Value
Implements	`IAsyncEvent<String>`, `ICancellable`
Async	Yes
Cancellable	Yes

Methods

Method	Return Type	Description
`getSender()`	`PlayerRef`	Returns the player who sent the message
`setSender(PlayerRef sender)`	`void`	Sets the sender of the message
`getTargets()`	`List<PlayerRef>`	Returns the list of players who will receive the message
`setTargets(List<PlayerRef> targets)`	`void`	Sets the list of players who will receive the message
`getContent()`	`String`	Returns the message content
`setContent(String content)`	`void`	Sets the message content
`getFormatter()`	`Formatter`	Returns the message formatter
`setFormatter(Formatter formatter)`	`void`	Sets the message formatter

Default Formatter

// default formats as: "<username>: <message>"
DEFAULT_FORMATTER = (playerRef, msg) ->
    Message.translation("server.chat.playerMessage")
        .param("username", playerRef.getUsername())
        .param("message", msg);

How Chat is Dispatched

// from GamePacketHandler - shows how targets are filtered
List<PlayerRef> targets = new ObjectArrayList<>(Universe.get().getPlayers());
targets.removeIf(target -> target.getHiddenPlayersManager().isPlayerHidden(senderUUID));

HytaleServer.get().getEventBus()
    .dispatchForAsync(PlayerChatEvent.class)
    .dispatch(new PlayerChatEvent(sender, targets, message))
    .whenComplete((event, throwable) -> {
        if (throwable != null) {
            // log error
        } else if (!event.isCancelled()) {
            Message formatted = event.getFormatter().format(sender, event.getContent());
            for (PlayerRef target : event.getTargets()) {
                target.sendMessage(formatted);
            }
        }
    });

Interaction Events

Player interactions use two separate pipelines:

Mouse input events — PlayerMouseButtonEvent and PlayerMouseMotionEvent fire on raw mouse input, before any gameplay logic. Use these to observe or block clicks early.
Interaction chain events — BreakBlockEvent, DamageBlockEvent, PlaceBlockEvent, UseBlockEvent fire as ECS events when specific interaction operations execute. Use these to intercept specific gameplay actions.

PlayerMouseButtonEvent

Fired on every mouse button press and release. This is the primary event for reacting to player clicks — it fires before the interaction chain system processes the action.

Class: com.hypixel.hytale.server.core.event.events.player.PlayerMouseButtonEvent

Property	Value
Extends	`PlayerEvent<Void>`
KeyType	`Void` (global)
Cancellable	Yes

Methods

Method	Return Type	Description
`getPlayerRefComponent()`	`PlayerRef`	The player reference
`getClientUseTime()`	`long`	Client-side timestamp
`getItemInHand()`	`Item`	Item asset config held during click (nullable)
`getTargetBlock()`	`Vector3i`	Block the cursor is pointing at (nullable)
`getTargetEntity()`	`Entity`	Entity the cursor is pointing at (nullable)
`getScreenPoint()`	`Vector2f`	Screen coordinates of the click
`getMouseButton()`	`MouseButtonEvent`	Mouse button details (see below)

MouseButtonEvent

Field	Type	Values
`mouseButtonType`	`MouseButtonType`	`Left(0)`, `Middle(1)`, `Right(2)`, `X1(3)`, `X2(4)`
`state`	`MouseButtonState`	`Pressed(0)`, `Released(1)`
`clicks`	`byte`	Click count (1 = single, 2 = double)

Example

eventRegistry.registerGlobal(PlayerMouseButtonEvent.class, event -> {
    MouseButtonEvent mouse = event.getMouseButton();

    // only react to right-click press
    if (mouse.mouseButtonType != MouseButtonType.Right) return;
    if (mouse.state != MouseButtonState.Pressed) return;

    Entity target = event.getTargetEntity();
    if (target != null) {
        // player right-clicked an entity
        handleEntityClick(event.getPlayer(), target);
    }
});

PlayerMouseMotionEvent

Fired on mouse movement. Includes the current cursor target and motion delta.

Class: com.hypixel.hytale.server.core.event.events.player.PlayerMouseMotionEvent

Property	Value
Extends	`PlayerEvent<Void>`
KeyType	`Void` (global)
Cancellable	Yes

Methods

Method	Return Type	Description
`getClientUseTime()`	`long`	Client-side timestamp
`getItemInHand()`	`Item`	Item asset config held during motion (nullable)
`getTargetBlock()`	`Vector3i`	Block the cursor is pointing at (nullable)
`getTargetEntity()`	`Entity`	Entity the cursor is pointing at (nullable)
`getScreenPoint()`	`Vector2f`	Screen coordinates
`getMouseMotion()`	`MouseMotionEvent`	Motion details (see below)

MouseMotionEvent

Field	Type	Description
`mouseButtonType`	`MouseButtonType[]`	Buttons held during motion (nullable)
`relativeMotion`	`Vector2i`	Mouse movement delta (nullable)

PlayerInteractEvent

Class: com.hypixel.hytale.server.core.event.events.player.PlayerInteractEvent

Property	Value
Extends	`PlayerEvent<String>`
Cancellable	Yes
Deprecated	Yes — never fired

PlayerCraftEvent

Class: com.hypixel.hytale.server.core.event.events.player.PlayerCraftEvent

Property	Value
Extends	`PlayerEvent<String>`
Cancellable	No
Deprecated	Yes (for removal)

AddPlayerToWorldEvent

Fired when player is added to a world. Keyed by world name.

Class: com.hypixel.hytale.server.core.event.events.player.AddPlayerToWorldEvent

Property	Value
Implements	`IEvent<String>`
KeyType	`String` (world name)

Methods

Method	Return Type	Description
`getHolder()`	`Holder<EntityStore>`	Returns the player entity holder
`getWorld()`	`World`	Returns the world being joined
`shouldBroadcastJoinMessage()`	`boolean`	Returns whether to broadcast a join message
`setBroadcastJoinMessage(boolean broadcast)`	`void`	Sets whether to broadcast a join message

Example (from CreativeHubPlugin)

events.registerGlobal(AddPlayerToWorldEvent.class, event -> {
    // send hint about returning to hub
    PlayerRef player = event.getHolder().get().getComponent(PlayerRef.getComponentType());
    player.sendMessage(Message.translation("hub.returnHint"));
});

DrainPlayerFromWorldEvent

Fired when player is removed from a world (teleporting, disconnecting).

Class: com.hypixel.hytale.server.core.event.events.player.DrainPlayerFromWorldEvent

Property	Value
Implements	`IEvent<String>`
KeyType	`String` (world name)
Cancellable	No

Methods

Method	Return Type	Description
`getHolder()`	`Holder<EntityStore>`	Returns the player entity holder
`getWorld()`	`World`	Returns the world being left
`setWorld(World world)`	`void`	Sets the world being left
`getTransform()`	`Transform`	Returns the player’s transform at time of drain
`setTransform(Transform transform)`	`void`	Sets the player’s transform

WindowCloseEvent

Fired when a player window (UI) is closed.

Class: com.hypixel.hytale.server.core.entity.entities.player.windows.Window.WindowCloseEvent

Property	Value
Implements	`IEvent<Void>`
Cancellable	No