Init

content/world/chunks.en.md

@@ -0,0 +1,172 @@
+---
+title: Chunks
+type: docs
+weight: 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:
+
+```java
+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:
+
+```java
+// 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:
+
+```java
+// ChunkStore handles saving and loading chunks
+// This is typically managed internally by the server
+```
+
+## Chunk Loading
+
+Chunks are loaded dynamically based on player positions:
+
+```java
+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
+
+```java
+// 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
+
+```java
+// 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 >}}
+
+```java
+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 >}}
+
+```java
+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);
+}
+```