Documentation/content/world/chunks.en.md

title, type, weight

title	type	weight
Chunks	docs	2

Chunks are the fundamental unit of world storage and loading in Hytale.

Chunk Basics

A chunk represents a fixed-size section of the world containing blocks:

import com.hypixel.hytale.server.core.universe.Universe;
import com.hypixel.hytale.server.core.universe.world.World;
import com.hypixel.hytale.server.core.asset.type.blocktype.config.BlockType;

World world = Universe.get().getWorld("default");

// Chunks are loaded automatically when needed
// Access blocks within a chunk through the World API
BlockType blockType = world.getBlockType(x, y, z);

Chunk Coordinates

Chunks use a separate coordinate system from block coordinates:

// Convert block coordinates to chunk coordinates
int chunkX = blockX >> 4;  // Divide by 16
int chunkZ = blockZ >> 4;

// Convert chunk coordinates to block coordinates (corner)
int blockX = chunkX << 4;  // Multiply by 16
int blockZ = chunkZ << 4;

ChunkStore

The ChunkStore manages chunk persistence:

// ChunkStore handles saving and loading chunks
// This is typically managed internally by the server

Chunk Loading

Chunks are loaded dynamically based on player positions:

import com.hypixel.hytale.server.core.event.events.player.PlayerConnectEvent;
import com.hypixel.hytale.server.core.universe.PlayerRef;
import com.hypixel.hytale.math.vector.Vector3d;
import com.hypixel.hytale.math.vector.Transform;
import java.util.logging.Level;

getEventRegistry().register(PlayerConnectEvent.class, event -> {
    PlayerRef playerRef = event.getPlayerRef();

    // Get position from PlayerRef.getTransform()
    // Note: Player.getPosition() does NOT exist!
    Transform transform = playerRef.getTransform();
    if (transform != null) {
        Vector3d pos = transform.getPosition();
        // Vector3d uses getX(), getZ() - NOT x(), z()
        int chunkX = (int) pos.getX() >> 4;
        int chunkZ = (int) pos.getZ() >> 4;

        getLogger().at(Level.INFO).log("Player at chunk: " + chunkX + ", " + chunkZ);
    }
});

Working with Chunks

Iterating Blocks in a Chunk

// Iterate through all blocks in a chunk area
int chunkX = 0;
int chunkZ = 0;
int startX = chunkX << 4;
int startZ = chunkZ << 4;

for (int x = startX; x < startX + 16; x++) {
    for (int z = startZ; z < startZ + 16; z++) {
        for (int y = 0; y < 256; y++) {
            BlockType blockType = world.getBlockType(x, y, z);
            // Process block...
        }
    }
}

Chunk-based Operations

// Perform operations on a chunk basis for efficiency
public void processChunk(World world, int chunkX, int chunkZ) {
    int baseX = chunkX << 4;
    int baseZ = chunkZ << 4;

    for (int x = 0; x < 16; x++) {
        for (int z = 0; z < 16; z++) {
            // Process relative to chunk origin
            int worldX = baseX + x;
            int worldZ = baseZ + z;
            // ...
        }
    }
}

Performance Considerations

{{< callout type="warning" >}} Avoid loading or processing many chunks simultaneously as this can impact server performance. Use async operations for heavy chunk processing. {{< /callout >}}

import com.hypixel.hytale.server.core.Message;
import com.hypixel.hytale.math.vector.Vector3i;
import java.util.Map;
import java.util.HashMap;
import java.util.concurrent.CompletableFuture;

// Process chunks asynchronously
World world = player.getWorld();
PlayerRef playerRef = player.getPlayerRef();

CompletableFuture.runAsync(() -> {
    // Heavy chunk processing here
    Map<Vector3i, String> results = new HashMap<>();
    // ... process

    // Return to world thread to apply results
    world.execute(() -> {
        for (var entry : results.entrySet()) {
            Vector3i pos = entry.getKey();
            // Vector3i uses getX(), getY(), getZ() - NOT x(), y(), z()
            world.setBlock(pos.getX(), pos.getY(), pos.getZ(), entry.getValue());
        }
        playerRef.sendMessage(Message.raw("Chunk processing complete!"));
    });
});

Chunk Management

{{< callout type="info" >}} Note: Hytale handles chunk loading and unloading internally. There are no direct chunk load/unload events exposed to plugins. Chunks are automatically managed based on player positions and view distance. {{< /callout >}}

import com.hypixel.hytale.math.vector.Vector2i;

// Calculate chunk coordinates from a player position
public Vector2i getChunkCoords(PlayerRef playerRef) {
    Transform transform = playerRef.getTransform();
    if (transform == null) {
        return new Vector2i(0, 0);
    }

    Vector3d pos = transform.getPosition();
    // Vector3d uses getX(), getZ() - NOT x(), z()
    int chunkX = (int) pos.getX() >> 4;
    int chunkZ = (int) pos.getZ() >> 4;
    return new Vector2i(chunkX, chunkZ);
}