LogoLogo
  • Get Started
  • Getting Started
    • Initial Setup
    • Create Your First Game
    • API Reference
    • Build Your First World Map
    • Multiplayer Testing
    • Use Templates & Examples
    • Styling & Assets
      • Modeling Guidelines
      • Texturing Guidelines
      • Default Assets
  • Build Faster With AI Tools
  • SDK Guides
    • Assets
    • Audio & SFX
      • Audio Manager
    • Blocks & Chunks
      • Block Types
      • Block Type Registry
      • Chunks
      • Chunk Lattice
    • Camera
    • Chat & Commands
    • Debugging
    • Entities
      • Animations
      • Block Entities
      • Colliders & Hitbox
      • Child Entities
      • Entity Controllers
        • Base Entity Controller
        • Pathfinding Entity Controller
        • DefaultPlayer Entity Controller
        • Simple Entity Controller
      • Entity Manager
      • Model Entities
      • Movement & Pathfinding
      • Player Controlled Entities
    • Events
    • Input & Controls
    • Lighting
      • Ambient Light
      • Light Manager
      • Point Lights
      • Spot Lights
      • Sun Light (Directional)
    • Mobile
    • Persisted Data
    • Players
      • Player Manager
      • Persisted Player Data
    • Plugins
    • Physics
      • Colliders
      • Collision Groups
      • Debugging
      • Gravity
      • Raycasts
      • Rigid Bodies
    • User Interface
      • Overlay UI
      • Scene UIs
      • Scene UI Manager
    • Worlds
      • Map Data Format
  • Helpful Resources
    • HYTOPIA Architecture & Platform Overview
    • Useful Third-Party Tools
Powered by GitBook
On this page
  • Accessing A ChunkLattice
  • Using A ChunkLattice
  • An Example Of Iterating Chunks
  • Dynamic Chunk Load/Unload
  • Diving Deeper
Export as PDF
  1. SDK Guides
  2. Blocks & Chunks

Chunk Lattice

PreviousChunksNextCamera

Last updated 6 months ago

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 .

// 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 .

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 .

ChunkLattice API Reference
ChunkLattice API Reference here
submit a feature request here