Universe

Universe

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

public class Universe extends JavaPlugin implements IMessageReceiver, MetricProvider

The top-level container for all worlds and connected players on a Hytale server. Universe is a singleton — accessed via Universe.get() — and is itself a plugin (JavaPlugin), meaning it participates in the standard plugin lifecycle.

Universe manages the complete player connection flow: when a player connects, it creates the player entity, dispatches PlayerConnectEvent, and adds the player to a World. When a player disconnects, it dispatches PlayerDisconnectEvent and cleans up the player’s state.

Singleton Access

public static Universe get()

Returns the singleton Universe instance. This is the primary entry point for accessing the world and player management APIs.

World Management

Worlds are stored in a ConcurrentHashMap<String, World> keyed by world name.

Creating Worlds

@Nonnull
@CheckReturnValue
public CompletableFuture<World> addWorld(@Nonnull String name)

Creates and adds a new World with the given name using default configuration and save path. Returns a future that completes when the world is initialized and ready.

@Nonnull
@CheckReturnValue
public CompletableFuture<World> makeWorld(@Nonnull String name, @Nonnull Path savePath, @Nonnull WorldConfig worldConfig)

Creates and adds a new World with explicit save path and configuration. This is the lower-level factory method that addWorld delegates to. Returns a future that completes when the world is initialized.

@Nonnull
@CheckReturnValue
public CompletableFuture<World> loadWorld(@Nonnull String name)

Loads an existing World from disk by name. The world’s save directory and configuration are read from the server’s world storage. Returns a future that completes when the world is loaded and ready.

Querying Worlds

@Nullable
public World getWorld(@Nullable String worldName)

Returns the World with the given name, or null if no such world exists. Returns null if worldName is null.

@Nullable
public World getWorld(@Nonnull UUID uuid)

Returns the World with the given UUID, or null if no such world exists.

@Nullable
public World getDefaultWorld()

Returns the default world (the world named "default"), or null if no default world has been created.

@Nonnull
public Map<String, World> getWorlds()

Returns an unmodifiable view of all worlds, keyed by name.

Removing Worlds

public boolean removeWorld(@Nonnull String name)

Removes a world by name. Players in the world should be drained first via World.drainPlayersTo(). Returns true if the world was found and removed.

Player Management

Connected players are stored in a ConcurrentHashMap<UUID, PlayerRef>.

Player Lookup

@Nonnull
public List<PlayerRef> getPlayers()

Returns a list of all currently connected PlayerRef instances.

@Nullable
public PlayerRef getPlayer(@Nonnull UUID uuid)

Returns the PlayerRef for the player with the given UUID, or null if the player is not connected.

@Nullable
public PlayerRef getPlayer(@Nonnull String value, @Nonnull NameMatching matching)

Returns the PlayerRef matching the given string value using the specified NameMatching strategy (exact match, case-insensitive, prefix, etc.). Returns null if no match is found.

public int getPlayerCount()

Returns the number of currently connected players.

Player Lifecycle

public void removePlayer(@Nonnull PlayerRef playerRef)

Disconnects a player from the server. Dispatches PlayerDisconnectEvent, removes the player from their current world, and cleans up the player’s state.

@Nonnull
public CompletableFuture<PlayerRef> resetPlayer(@Nonnull PlayerRef oldPlayer)

Resets a player’s state by creating a new PlayerRef with fresh ECS data while preserving the player’s network connection. The old player reference is invalidated and the new one takes its place. Returns a future that completes with the new PlayerRef.

Player Component Type

@Nonnull
public ComponentType<EntityStore, PlayerRef> getPlayerRefComponentType()

Returns the ComponentType used to store PlayerRef as a component on player entities in the entity store. This is the key for accessing a player’s PlayerRef through the ECS.

Messaging and Broadcasting

@Override
public void sendMessage(@Nonnull Message message)

Broadcasts a message to all connected players across all worlds. Implements IMessageReceiver. For world-scoped messaging, use World.sendMessage() instead.

public void broadcastPacket(@Nonnull Packet packet)

Sends a raw network packet to all connected players. Lower-level than sendMessage — used for protocol-level broadcasts.

Storage

public PlayerStorage getPlayerStorage()

Returns the PlayerStorage instance responsible for persisting and loading player data.

public WorldConfigProvider getWorldConfigProvider()

Returns the WorldConfigProvider that supplies world configuration data for world creation and loading.

Connection Flow

The complete player connection and disconnection sequence managed by Universe:

Connection

Client connects
    --> Universe creates player entity (Holder<EntityStore>)
    --> PlayerSetupConnectEvent dispatched
    --> PlayerConnectEvent dispatched (world field is mutable)
    --> World.addPlayer(playerRef) called
    --> AddPlayerToWorldEvent dispatched
    --> PlayerReadyEvent dispatched

Disconnection

Client disconnects (or server kicks)
    --> PlayerSetupDisconnectEvent dispatched
    --> PlayerDisconnectEvent dispatched
    --> Player removed from World
    --> DrainPlayerFromWorldEvent dispatched (if world transfer)
    --> Player state finalized and cleaned up

Related Types

• World — game world instances managed by Universe
• PlayerRef — persistent player reference managed per-connection
• PluginBase — base plugin class; Universe extends JavaPlugin which extends PluginBase
• Store — ECS store; each World has an EntityStore and ChunkStore
• ComponentType — type key for PlayerRef component access
• EventRegistry — event registration; Universe dispatches lifecycle events
• PlayerConnectEvent — dispatched by Universe when a player connects
• PlayerDisconnectEvent — dispatched by Universe when a player disconnects
• PlayerSetupConnectEvent — dispatched early in connection before player entity exists
• PlayerSetupDisconnectEvent — dispatched early in disconnection
• PrepareUniverseEvent — dispatched during Universe initialization
• AddPlayerToWorldEvent — dispatched when a player enters a world
• DrainPlayerFromWorldEvent — dispatched when a player leaves a world
• WorldConfig — configuration for world creation
• WorldConfigProvider — supplies world configurations
• PlayerStorage — player data persistence
• NameMatching — player lookup strategy enum
• Packet — network packet base type
• JavaPlugin — concrete plugin base class that Universe extends