🧱 Voxel Engine

Configure world generation parameters. Call before generating chunks.

configureVoxelWorld({
  seed: 42,
  renderDistance: 6,
  seaLevel: 62,
  lodLevels: [4, 8],
  generateTerrain: (chunk, ctx) => {
    // Custom flat world
    for (let x = 0; x < ctx.CHUNK_SIZE; x++)
      for (let z = 0; z < ctx.CHUNK_SIZE; z++)
        for (let y = 0; y < 60; y++)
          chunk.setBlock(x, y, z, ctx.BLOCK_TYPES.STONE);
  },
});

Load/unload chunks around the player. Call periodically in update().

if (frameCount % 10 === 0) updateVoxelWorld(player.x, player.z);

Synchronously load all chunks in render distance. Useful for initial world setup in init().

Clear all chunks, entities, and meshes. Resets world to empty state.

Returns the current world configuration object.

Get the block type at world coordinates.

Place or remove a block. Automatically updates chunk meshes and propagates lighting.

setVoxelBlock(10, 65, 10, BLOCK_TYPES.STONE);    // Place stone
setVoxelBlock(10, 65, 10, BLOCK_TYPES.AIR);      // Remove block
setVoxelBlock(5, 60, 5, BLOCK_TYPES.STONE_SLAB); // Place slab

Returns the Y of the highest non-air, non-water block at (x, z). Useful for spawning.

Returns the biome name at world position. One of: "Frozen Tundra", "Taiga", "Desert", "Jungle", "Savanna", "Forest", "Snowy Hills", "Plains".

Register a custom block type for your cart.

registerVoxelBlock(100, {
  name: 'crystal',
  color: 0xff00ff,
  solid: true,
  transparent: true,
  lightEmit: 10,
  shape: 'slab_bottom',
});

Returns the shape string for a block type.

Returns the collision bounding box [minX, minY, minZ, maxX, maxY, maxZ] relative to block origin (0–1 range).

Returns true if the block shape is 'cube'. Non-cube blocks don't occlude neighbor faces.

DDA voxel traversal — pixel-perfect block targeting. Returns hit info with block position, face normal, and adjacent block for placing.

const result = raycastVoxelBlock([px, py+1.6, pz], lookDir, 10);
if (result.hit) {
  // Break block
  setVoxelBlock(...result.position, BLOCK_TYPES.AIR);
  // Place block on adjacent face
  setVoxelBlock(...result.adjacent, BLOCK_TYPES.STONE);
}

AABB collision check against solid blocks (excluding fluids). Uses shape-aware bounding boxes for non-cube blocks.

Check if position is inside a fluid block (water/lava).

Swept AABB physics with per-axis resolution, auto-step (0.6 blocks), water drag, and ground detection.

const result = moveVoxelEntity(
  player.pos,
  player.vel,
  [0.6, 1.8, 0.6],  // width, height, depth
  dt
);
player.pos = result.position;
player.vel = result.velocity;
player.grounded = result.grounded;

Returns the light level (0–15) at a position. Max of sky light and block light.

Set time of day (0.0–1.0). Sky light brightness scales with time for day/night cycle.

let time = 0;
export function update(dt) {
  time = (time + dt * 0.01) % 1;
  setVoxelDayTime(time); // Smooth day/night
}

Place a fluid source block. Flow propagation begins automatically.

setVoxelFluidSource(10, 70, 10, BLOCK_TYPES.WATER); // Water source
setVoxelFluidSource(20, 70, 20, BLOCK_TYPES.LAVA);  // Lava source

Remove a fluid source. Flowing blocks retract via BFS.

Returns the fluid level at a position (0 = full, 7 = thinnest, -1 = no fluid).

Spawn a new entity in the voxel world.

Remove entity and its mesh from the world.

Retrieve an entity by ID.

Modify entity health. Entity removed when health reaches 0.

Tick all entity AI callbacks and physics. Call in update().

Find all entities within radius using spatial hash (O(1) bucket lookup).

Query entities by type or get total count.

Attach or update a component on an entity.

setVoxelEntityComponent(id, 'inventory', { slots: 10, items: [] });
setVoxelEntityComponent(id, 'hostile', { aggroRange: 16 });

Get component data. Returns undefined if not present.

Check if entity has a specific component.

Remove a component from an entity.

Find all entities that have all required components, with optional filter function.

// All entities with 'hostile' and 'ai' components
const enemies = queryVoxelEntities(['hostile', 'ai']);

// With filter
const nearbyEnemies = queryVoxelEntities(['hostile'], e =>
  dist(e.position, player.pos) < 32
);

Define a reusable entity template with default components.

Spawn an entity from a registered archetype. Built-in archetypes: mob, item, projectile, npc, vehicle.

const zombie = spawnVoxelEntityFromArchetype('mob', [10, 65, 10], {
  health: 20,
});
setVoxelEntityComponent(zombie.id, 'hostile', { damage: 3 });

A* pathfinding on the voxel grid. Returns an array of [x, y, z] positions, or null if no path found.

Export a rectangular region as an RLE-compressed ArrayBuffer. Header: [version, sizeX, sizeY, sizeZ] + RLE body.

Import a schematic at the given position.

Export the entire world (all loaded chunks) as a JSON object with seed, config, and chunk data.

Import a world from a previously exported JSON object. Replaces current world state.

Save all modified chunks to IndexedDB under the given name.

Load a previously saved world from IndexedDB.

List all saved world names in IndexedDB.

Delete a saved world from IndexedDB.

Toggle the procedural texture atlas (27 pixel-art tiles). Enabled: textured blocks. Disabled: vertex-color blocks.

Load a custom texture atlas image. Mapping defines which tile index goes to which block face.

Multi-octave 2D fractal simplex noise. Returns 0–1.

Multi-octave 3D fractal simplex noise. Returns 0–1. Use for caves, ore veins, 3D effects.

Generate a tree (wood trunk + leaf canopy) at the specified base position. Biome-appropriate variety: oak, birch, spruce, jungle, acacia.