namespaceVoxels2 functionsUI apps only

datumhue.voxel

Editable voxel volumes: palette materials, transform properties, scene-space raycasting, and bulk fills driven by the noise, grid, and image APIs.

Returns handles: Voxel, VoxelWorld

The examples on this page start from:

lua

local vec3 = datumhue.math.vec3
local scene = datumhue.scene.new({ width = 320, height = 240 })
scene:mount({ width = 320, height = 240 })
scene:directional_light({ direction = vec3(-1, -2, -1) })

Functions 2

datumhue.voxel.new

functionUI apps only

datumhue.voxel.new(scene: Scene, opts: voxel.NewOptions) -> Voxel

Create a voxel volume inside scene. Cells hold 0-based palette indices, 0 = air.

Example

-- 16 x 4 x 16 cells of half a unit; pos is the minimum corner.
local terrain = datumhue.voxel.new(scene, {
    width = 16,
    height = 4,
    depth = 16,
    cell_size = 0.5,
    pos = vec3(-4, 0, -4),
})
terrain:palette(1, { color = datumhue.color("#a7c080") })
terrain:fill(0, 0, 0, 15, 0, 15, 1)
-- Width in scene units: cells times cell size.
print(terrain.width * terrain.cell_size) --> 8.0

opts voxel.NewOptions options 12 keys

Key	Type	Default	Description
width required	integer	no default	Cells along x.
height required	integer	no default	Cells along y.
depth required	integer	no default	Cells along z.
pos	Vec3	datumhue.math.vec3(0, 0, 0)	World-space position of the volume's minimum corner.
rotation	Quat	datumhue.math.quat.identity()	Rotation quaternion.
cell_size	number	1	World units per cell, 0.001 to 1000000.
material	Material \| Shader	vertex colors lit through a plain white surface	Material for the volume's solid surfaces: a standard Material, or a Shader, whose color the surfaces show unlit.
sunlight	boolean	false	Sky light fills open-air columns from above and spreads into overhangs. With it off, baked lighting still activates when any palette entry emits light.
ambient	number	0.15	Baked-light floor 0..1: how bright a fully dark face renders. Only meaningful when lighting is active.
physics	boolean	false	Attach a static physics body whose collider matches the volume's cells, following every edit.
layers	integer[]	the body belongs to every layer	Collision membership: layer bit indices 0..=31 the body belongs to. Requires `physics`.
collides_with	integer[]	the body collides with every layer	Collision filter: only collide with bodies in these layer bit indices 0..=31. Requires `physics`.

datumhue.voxel.world

functionUI apps only

datumhue.voxel.world(scene: Scene, opts: voxel.WorldOptions) -> VoxelWorld

Create a chunk-streamed voxel world inside scene. Chunks load nearest-first around center under the per-frame budget and unload least-recently-needed beyond unload_radius. Each chunk is a full voxel volume sharing the world's palette, lighting, and physics configuration.

Example

-- Chunks of 16 cells load around center; fill each as it arrives.
local world = datumhue.voxel.world(scene, {
    chunk_size = 16,
    load_radius = 1,
    on_chunk_load = function(chunk)
        if chunk.coords.y == 0 then
            chunk.voxel:fill(0, 0, 0, 15, 0, 15, 1)
        end
    end,
})
world:palette(1, { color = datumhue.color("#83c092") })

opts voxel.WorldOptions options 12 keys

Key	Type	Default	Description
chunk_size required	integer	no default	Cells per chunk axis, 1..128 (chunks are cubes).
cell_size	number	1	World units per cell, 0.001 to 1000000.
load_radius	integer	2	Chunks within this radius (in chunks) of the center load.
unload_radius	integer	one chunk beyond `load_radius`	Chunks beyond this radius unload; must be >= load_radius. The gap is hysteresis.
budget	integer	4	Maximum chunk loads (and unloads) per frame.
pos	Vec3	datumhue.math.vec3(0, 0, 0)	World-space position of the world's origin chunk corner.
center	Vec3	datumhue.math.vec3(0, 0, 0)	Initial streaming focus, relative to the world origin.
physics	boolean	false	Every chunk carries a static collider matching its cells.
sunlight	boolean	false	Sky light fills open-air columns in every chunk.
ambient	number	0.15	Baked-light floor 0..1 for every chunk.
on_chunk_load	fun(chunk: VoxelChunk)	no default	Invoked after a chunk loads; fill `chunk.voxel` with content or restore a snapshot via `chunk:write`.
on_chunk_unload	fun(coords: Vec3, data: Bytes)	no default	Invoked after a chunk unloads, with its grid coordinates and cell snapshot — the chunk is already gone. Persist `data` and hand it back to `chunk:write` on the next load.

Types 4

voxel.PaletteOptions

options

options 7 keys

Key	Type	Default	Description
color	Color	datumhue.color(1, 1, 1)	Base color; tints the tile when textured.
emissive	Color	the entry renders lit	Emissive color: entries with one render unlit at this color (channel values above 1 feed bloom).
transparent	boolean	false	Transparent entries render alpha-blended and don't occlude neighboring faces.
light	integer	0	Block-light emission level 0..15: cells of this entry glow and light their surroundings, falling off one level per cell.
texture	integer \| voxel.TextureFaces	the faces show `frames`, or the color alone	Atlas tile for every face, or a tile per face. Needs an atlas bound via `voxel:atlas`. At most one of `texture` / `frames`.
frames	integer[]	the faces show `texture`, or the color alone	Animated tile sequence shown on every face, advancing at `fps`.
fps	number	the tiles advance 4 times per second	Animation frames per second for `frames`.

Used by: Voxel:palette, VoxelWorld:palette

voxel.Region

options

options 2 keys

Key	Type	Default	Description
min required	Vec3	no default	Minimum cell corner (inclusive).
max required	Vec3	no default	Maximum cell corner (inclusive, clamped to the volume).

Nested in: voxel.FillNoiseOptions, voxel.HeightmapOptions

voxel.StampPlane

enum

Value	Description
`"xz"`
`"xy"`
`"zy"`

Nested in: voxel.StampGridOptions, voxel.StampImageOptions

voxel.TextureFaces

options

options 3 keys

Key	Type	Default	Description
top required	integer	no default	Atlas tile index for the top face.
bottom required	integer	no default	Atlas tile index for the bottom face.
side required	integer	no default	Atlas tile index for the four side faces.

Nested in: voxel.PaletteOptions

`/` or `Ctrl` `K`	Search
`↑` `↓` `Enter`	Pick a result
`Tab`	Next result filter
`j` `k`	Next or previous entry
`[` `]`	Previous or next page
`y`	Copy a link to the current entry
`?`	These shortcuts
`Esc`	Close

datumhue.voxel

Functions 2

datumhue.voxel.new

datumhue.voxel.world

Types 4

voxel.PaletteOptions

voxel.Region

voxel.StampPlane

voxel.TextureFaces

Try

Recently viewed

Settings

Keyboard shortcuts

On this page