Chunk Lattice

A world has a single instance of a ChunkLattice. The Chunk Lattice is used to retrieve, set, modify and remove chunks that make up the entirety of your game's world.

Accessing A ChunkLattice

The ChunkLattice is used as a singleton and automatically created for a given world instance.

You can access the chunk lattice for a world like this:

world.chunkLattice

Using A ChunkLattice

The ChunkLattice exposes a number of ways to get chunks, or block types for a world at given types of coordinates. Here's some examples. For a complete list, please see the ChunkLattice API Reference.

// Returns an array of all loaded chunks in the world
world.chunkLattice.getAllChunks();

// Returns the block type id set at the provided global coordinate in the world
world.chunkLattice.getBlock({ x: 0, y: 0, z: 0 });

// Returns the chunk at the provided chunk origin coordinate in the world.
// Origin coordinates must be in increments of +/- 16
// You can convert a global coordinate to an origin coordinate
// with the static method Chunk.globalCoordinateToOriginCoordinate();
world.chunkLattice.getChunk({ x: 16, y: 32, z: -16 });

// Returns true or false if a block is set at the provided
// global coordinate
world.chunkLattice.hasBlock({ x: 5, y: 0, z: -4 );

// Returns true or false if a chunk exists at the provided
// origin coordinate
world.chunkLattice.hasChunk({ x: -16, y: 16, z: -48 });

// Sets a block by block type id at the provided
// global coordinate
// Assume 5 is the id of a block type we previously registered
world.chunkLattice.setBlock({ x: 1, y: 2, z: 3 }, 5);  

An Example Of Iterating Chunks

Sometimes, you might want to iterate through every chunk in your world. We can do that with the ChunkLattice. The ChunkLattice represents the spatial representation of all the known chunks in our world, and allows us to iterate and manipulate the entire chunk and even block state of the world through it.

In this example, let's iterate through all our chunks and replace all of the set blocks in our world of block type id 4 (Let's say id 4 is a water block) with block type id 5 (Let's say id 5 is a lava block).

world.chunkLattice.getAllChunks().forEach(chunk => {
  // A array of 4096 elements, each as a number 0 to 255
  // representing a blockTypeId, or no block (if 0).
  const chunkBlocks = chunk.blocks; 
  
  chunkBlocks.forEach(blockTypeId, blockIndex => {
    if (blockTypeId === 4) {
      // Using Chunk static method blockIndexToLocalCoordiante to convert
      // the index from the flat blocks array to the equivalent x,y,z 
      // coordinate. We have to do this because chunks
      // store blocks as a flat array Uint8Array[4096] for efficiency.
      const localCoordinate = Chunk.blockIndexToLocalCoordinate(blockIndex); 
    
      chunk.setBlock(localCoordinate, 5); // replace with block type 5
    }
  });
});

Dynamic Chunk Load/Unload

Currently HYTOPIA does not automatically handle the dynamic loading and unloading of chunks in the ChunkLattice relative to player location in a game. If you want to take on the challenge or require exceptionally large maps in your world, at this time you'll need to implement your own version of dynamic chunk load/unload.

This can be used by a combination of checking player positions each tick, tracking all possible chunks manually, and loading/unloading chunk instances with chunk.spawn() and chunk.despawn() as needed.

We intend to build out and support this feature in the future.

Diving Deeper

The ChunkLattice class is constantly evolving. You can find the latest ChunkLattice API Reference here.

If there are features that we don't currently support for the ChunkLattice that you'd like to see added to the HYTOPIA SDK, you can submit a feature request here.