Chunks

A Chunk represents a 16x16x16 subsection of world block space in a world. To make the entirety of a world

Global, Local and Origin Coordinate Types

HYTOPIA uses 3 distinct coordinate types within the block and chunk systems. You'll encounter these different types through the argument signatures of various SDK functions and methods. All coordinates are a Vector3 object, comprised of an x, y and z property.

• Global Coordinates - These are the simplest type of coordinates, they are coordinates within the context of the world and can be anything.

• Local Coordinates - These are coordinates local to a chunk. These coordinates may only have x, y and z values in the range of 0..15. For example, { x: 0, y: 10, z: 4 } is a valid local coordinate, but { x: -1, y: 0, z: 16 } is not.

• Origin Coordinates - These are the origin coordinates of a chunk relative to the world. These coordinates are global to the world, but are constrained to only allowing x, y and z values that are increments of +/- 16, denoting the starting origin point of the chunk in the global world space. For example, { x: 0, y: 32, z: -16 } is a valid origin coordinate, but { x: 0, y: 14, z: -3 }, is not.

Data Structure

Chunks internally are represented as an array of 4,096 8-bit numbers. We are able to translate from this flat array to the local coordinate representation of each block coordinate using the following:

public static blockIndexToLocalCoordinate(index: number): Vector3 {
  return {
    x: index % CHUNK_SIZE,
    y: (index / CHUNK_SIZE | 0) % CHUNK_SIZE,
    z: index / (CHUNK_SIZE * CHUNK_SIZE) | 0,
  };
}

At this time, because chunks use an 8-bit number to represent the block type id of each block within the chunk, the unique number of block types is limited to 255 possible block types. Block type ID 0 is reserved as a magic number meaning "no block" or "air".

Creating, Spawning And Despawning Chunks

Created Chunks will not be added to the world until they are spawned. They also will not be removed from the world until they are despawned. When using something like world.chunkLattice.setBlock() to modify blocks in the world space, you don't need to worry about chunk spawning and despawning because it is internally managed, whereas if you manipulate and create/remove chunks directly, you'll need to explicitly use .spawn() and .despawn() .

const myChunk = new Chunk();

// Set all x and z plane blocks
for (let x = 0; x < 16; x++) {
  for (let z = 0; z < 16; z++) {
    // assume block id 5 is dirt, or some type we made previously for this example
    myChunk.setBlock({ x, y: 0, z }, 5); // local coordinate space
  }
}

myChunk.spawn(world);

.isSimulated vs .isSpawned

Chunks have multiple lifecycle states, these are despawned, spawned and simulated.

Chunks have 2 readonly properties .isSimulated and .isSpawned to reflect the lifecycle state of the chunk.

We can use the following readonly properties of a chunk to determine the lifecycle state.

• .isSimulated - The chunk has been completely loaded into the physics simulation and has internally represented colliders. If .isSimulated is true, the chunk is also guaranteed to have .isSpawned as true as well.

• .isSpawned - The chunk has been loaded and registered in the world's ChunkLattice, but may not be simulated in the physics engine yet. This is because chunk simulation is deferred and batched to the next tick for internal reasons. A chunk that has .isSimulated equal to true, is not guaranteed to also have .isSimulated equal to true.

In most cases, you will not need to think about lifecycle states because they are internally managed and handled, you simply need to use chunk .spawn() and .despawn() to control if a chunk is in the world or not.

Diving Deeper

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

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