World System

The World class is the central access point for world data. Each world runs on its own thread and manages chunks, entities, time, and player tracking.

World dimensions:

• Chunks are 32×32 blocks horizontally
• World height is 320 blocks (Y=0 to Y=319)
• Chunks are divided into 10 vertical sections (each 32×32×32 blocks)

See also: Creating Worlds for creating, loading, and removing worlds | World Events for lifecycle events | Threading for world thread details

Getting a World Reference

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

// get all worlds
Map<String, World> worlds = Universe.get().getWorlds();

// get default world
World defaultWorld = Universe.get().getDefaultWorld();

// get specific world by name
World lobby = Universe.get().getWorld("lobby");

Key Properties

Method	Return Type	Description
getName()	String	World’s unique identifier
isAlive()	boolean	Whether the world is still running
getTick()	long	Current tick number
getPlayerCount()	int	Number of players in the world
getPlayerRefs()	Collection<PlayerRef>	All players in the world
getSavePath()	Path	Filesystem path for world data

World State

// pause/resume world ticking
world.setPaused(true);
boolean isPaused = world.isPaused();

// control chunk ticking (entities still tick)
world.setTicking(false);
boolean isTicking = world.isTicking();

// set tick rate (default 30)
world.setTps(20);

// time dilation (0.01 to 4.0)
World.setTimeDilation(2.0f, componentAccessor);

The componentAccessor parameter is a ComponentAccessor - either a Store (in commands/events) or CommandBuffer (in ECS systems).

Thread Safety

World operations must run on the world thread. Use execute() for cross-thread calls:

// schedule on world thread
world.execute(() -> {
    // safe to modify world state here
    WorldChunk chunk = world.getChunk(ChunkUtil.indexChunkFromBlock(x, z));
    chunk.setBlock(x, y, z, "hytale:stone", 0);
});

// check if already on world thread
if (world.isInThread()) {
    // direct access is safe
}

Stores

// access chunk store (blocks, sections, chunk data)
ChunkStore chunkStore = world.getChunkStore();

// access entity store (entities, players)
EntityStore entityStore = world.getEntityStore();

Both store objects exist immediately, but their internal ECS stores are null until the world starts. Wait for StartWorldEvent before accessing store contents, the chunk loader, or entities. See World initialization order.

---

Entities

For full entity documentation, see Entity API.

Spawning Entities

// create entity holder
Holder<EntityStore> holder = EntityStore.REGISTRY.newHolder();
// ... add components ...

// add to world
world.getEntityStore().getStore().addEntity(holder, AddReason.SPAWN);

Finding Entities

// get entity by UUID
Ref<EntityStore> ref = world.getEntityRef(uuid);

// iterate all entities with a component type
// ComponentType implements Query, so pass it directly
Store<EntityStore> store = world.getEntityStore().getStore();
store.forEachChunk(Player.getComponentType(), (archetypeChunk, commandBuffer) -> {
    for (int i = 0; i < archetypeChunk.size(); i++) {
        Player player = archetypeChunk.getComponent(i, Player.getComponentType());
        // process player
    }
});

// for complex queries, use Query combinators
Query<EntityStore> query = Query.and(Player.getComponentType(), Health.getComponentType());
store.forEachChunk(query, (archetypeChunk, commandBuffer) -> { ... });

Players

// get all player references
Collection<PlayerRef> players = world.getPlayerRefs();

// add player to world
CompletableFuture<PlayerRef> future = world.addPlayer(playerRef);

// add with specific transform
world.addPlayer(playerRef, transform, clearWorld, fadeInOut);

// drain all players to another world
world.drainPlayersTo(targetWorld);

---

Utilities

Messaging

// broadcast to all players in world
world.sendMessage(Message.raw("Hello world!"));
world.sendMessage(Message.translation("mymod.messages.welcome"));

World Configuration

WorldConfig config = world.getWorldConfig();

See World Configuration for all settings — gameplay toggles (PvP, fall damage, NPC spawning), ticking, time, saving, client effects, and the two-layer config system with GameplayConfig.

Lighting

ChunkLightingManager lighting = world.getChunkLighting();

// invalidate light at block
lighting.invalidateLightAtBlock(chunk, x, y, z, blockType, oldHeight, newHeight);

World Map

WorldMapManager mapManager = world.getWorldMapManager();

// add marker provider
mapManager.addMarkerProvider("mymarkers", myProvider);