Skip to content
Hytale Modding Docs

World

World

Section titled “World”

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

public class World extends TickingThread implements Executor, ExecutorMetricsRegistry.ExecutorMetric, ChunkAccessor<WorldChunk>, IWorldChunks, IMessageReceiver

The central game world class. Each World runs its own tick loop (via TickingThread), owns an EntityStore and ChunkStore for ECS data, maintains a world-scoped EventRegistry, and manages all players currently in the world. Worlds are created and managed by Universe.

A World acts as an Executor — tasks can be submitted to it via execute() and they will run on the world’s tick thread, ensuring thread-safe access to the world’s stores and state.

Constants

Section titled “Constants”
public static final float SAVE_INTERVAL = 10.0F

The interval in seconds between automatic world saves.

public static final String DEFAULT = "default"

The name used for the default world.

Constructor

Section titled “Constructor”
public World(@Nonnull String name, @Nonnull Path savePath, @Nonnull WorldConfig worldConfig) throws IOException

Creates a new world with the given name, save directory, and configuration. The world is not yet ticking after construction — call init() to start it.

Initialization

Section titled “Initialization”
@Nonnull
public CompletableFuture<World> init()

Initializes the world asynchronously. Sets up the chunk store, entity store, lighting manager, world map, and event registry. Returns a future that completes when the world is ready to tick.

Identity and Configuration

Section titled “Identity and Configuration”
@Nonnull
public String getName()

Returns the world’s name as provided to the constructor.

public boolean isAlive()

Returns true if the world’s tick thread is still running.

@Nonnull
public WorldConfig getWorldConfig()

Returns the WorldConfig that was used to create this world. Contains world generation settings, dimension properties, and other structural configuration.

@Nonnull
public GameplayConfig getGameplayConfig()

Returns the gameplay configuration for this world, controlling game rules and mechanics.

@Nonnull
public DeathConfig getDeathConfig()

Returns the death configuration for this world, controlling respawn behavior and death penalties.

Tick State

Section titled “Tick State”
public boolean isTicking()

Returns true if the world is actively running tick cycles.

public void setTicking(boolean ticking)

Enables or disables the world’s tick loop. A world that is not ticking does not process entities, chunks, or scheduled tasks.

public boolean isPaused()

Returns true if the world is paused. A paused world still runs its tick thread but skips gameplay processing.

public void setPaused(boolean paused)

Pauses or unpauses the world.

public long getTick()

Returns the current tick number. Increments by one each tick cycle.

Time Dilation

Section titled “Time Dilation”
public static void setTimeDilation(float timeDilationModifier, @Nonnull ComponentAccessor<EntityStore> componentAccessor)

Adjusts the time dilation modifier for the given entity store. Time dilation scales the effective tick rate for gameplay systems without changing the actual tick frequency.

ECS Stores

Section titled “ECS Stores”
@Nonnull
public ChunkStore getChunkStore()

Returns the world’s chunk store. The ChunkStore manages chunk-level ECS data including terrain, block states, and lighting. Chunk store components are registered via ComponentRegistryProxy.

@Nonnull
public EntityStore getEntityStore()

Returns the world’s entity store. The EntityStore manages game entities (players, mobs, items, projectiles). Entity store components are registered via ComponentRegistryProxy.

Lighting

Section titled “Lighting”
@Nonnull
public ChunkLightingManager getChunkLighting()

Returns the chunk lighting manager for this world.

World Map

Section titled “World Map”
@Nonnull
public WorldMapManager getWorldMapManager()

Returns the world map manager, which handles map-level data and rendering.

Events

Section titled “Events”
@Nonnull
public EventRegistry getEventRegistry()

Returns the world-scoped EventRegistry. Events registered here are scoped to this world instance and are cleaned up when the world is destroyed. This is distinct from the global EventBus — world-scoped events only fire for activity within this world.

Player Management

Section titled “Player Management”

Players in a world are tracked as PlayerRef instances in a ConcurrentHashMap<UUID, PlayerRef>.

@Nullable
public CompletableFuture<PlayerRef> addPlayer(@Nonnull PlayerRef playerRef)

Adds a player to this world at their current transform. Dispatches AddPlayerToWorldEvent. Returns a future that completes when the player is fully added, or null if the add fails.

@Nullable
public CompletableFuture<PlayerRef> addPlayer(@Nonnull PlayerRef playerRef, @Nullable Transform transform)

Adds a player to this world at a specific transform. If transform is null, the world’s default spawn position is used. Dispatches AddPlayerToWorldEvent.

@Nonnull
public CompletableFuture<Void> drainPlayersTo(@Nonnull World fallbackTargetWorld)

Removes all players from this world and transfers them to the specified fallback world. Dispatches DrainPlayerFromWorldEvent for each player. Used during world shutdown or reset.

public int getPlayerCount()

Returns the number of players currently in this world.

@Nonnull
public Collection<PlayerRef> getPlayerRefs()

Returns an unmodifiable view of all PlayerRef instances currently in this world.

public void trackPlayerRef(@Nonnull PlayerRef playerRef)

Begins tracking a player reference in this world’s player map. Called internally during the add-player flow.

public void untrackPlayerRef(@Nonnull PlayerRef playerRef)

Stops tracking a player reference in this world’s player map. Called internally during the remove-player flow.

Entity Management

Section titled “Entity Management”
@Deprecated
@Nullable
public <T extends Entity> T spawnEntity(T entity, @Nonnull Vector3d position, Vector3f rotation)

Deprecated. Spawns an entity at the given position and rotation. This method is a convenience wrapper that delegates to addEntity with AddReason.SPAWN. Prefer using the entity store directly for new code.

@Deprecated
@Nullable
public <T extends Entity> T addEntity(T entity, @Nonnull Vector3d position, @Nullable Vector3f rotation, @Nonnull AddReason reason)

Deprecated. Adds an entity to this world’s entity store at the given position with the specified add reason. Returns the entity if successful, or null if the add fails. Prefer using the entity store directly for new code.

@Nullable
public Ref<EntityStore> getEntityRef(@Nonnull UUID uuid)

Returns the Ref for the entity with the given UUID, or null if no such entity exists in this world’s entity store.

@Nullable
@Deprecated
public Entity getEntity(@Nonnull UUID uuid)

Deprecated. Returns the Entity component for the entity with the given UUID, or null if not found. Prefer getEntityRef() and component access via the entity store.

Messaging

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

Broadcasts a message to all players in this world. Implements IMessageReceiver. The message is forwarded to every tracked PlayerRef.

Executor

Section titled “Executor”
@Override
public void execute(@Nonnull Runnable command)

Submits a task to be executed on this world’s tick thread. Implements Executor. This is the primary mechanism for scheduling thread-safe mutations to the world’s state from external threads.

Client Features

Section titled “Client Features”
public boolean isFeatureEnabled(@Nonnull ClientFeature feature)

Returns true if the specified client feature is enabled for this world.

public void registerFeature(@Nonnull ClientFeature feature, boolean enabled)

Registers or updates a client feature’s enabled state for this world. Client features control client-side behavior such as rendering modes and UI elements.

Persistence

Section titled “Persistence”
@Nonnull
public Path getSavePath()

Returns the file-system path to this world’s save directory.

Chunk Access

Section titled “Chunk Access”

As a ChunkAccessor<WorldChunk> and IWorldChunks implementation, World provides chunk access methods. These are the primary entry points for loading and querying chunks:

  • getChunkAsync — asynchronously loads a chunk, triggering generation if needed
  • getChunkIfLoaded — returns a chunk only if it is fully loaded
  • getChunkIfInMemory — returns a chunk if it is in memory (may not be fully loaded)
  • loadChunkIfInMemory — loads a chunk from the in-memory cache without disk access
  • getNonTickingChunkAsync — loads a chunk without adding it to the tick loop

Purpose unknown for exact signatures — inferred from interface contracts and usage context.

Section titled “Related Types”
  • Universe — top-level container that manages all worlds
  • PlayerRef — persistent player reference, managed per-world
  • Store — base ECS store class; World owns an EntityStore and ChunkStore
  • Ref — entity reference handle used with the entity store
  • ComponentType — type-safe key for component access on stores
  • ComponentRegistryProxy — plugin-scoped ECS registration
  • EventRegistry — world-scoped event registration
  • PluginBase — plugin entry point that accesses worlds through Universe
  • AddPlayerToWorldEvent — fired when a player enters this world
  • DrainPlayerFromWorldEvent — fired when a player is drained from this world
  • PlayerConnectEvent — fired during player connection, contains mutable world field
  • WorldConfig — structural configuration for world creation
  • GameplayConfig — gameplay rules configuration
  • DeathConfig — death and respawn configuration
  • ChunkLightingManager — chunk lighting system
  • WorldMapManager — world map data management
  • TickingThread — base class providing the tick loop
  • ClientFeature — client-side feature flags
  • Entity — base entity component
  • Transform — position and rotation data