handle18 methods, 8 fields

Voxel

An editable voxel volume returned by datumhue.voxel.new. Cells are 0-based (x, y, z) integer coordinates; each cell holds a 0-based palette index, where 0 is air (empty).

Obtained from: datumhue.physics.raycast, datumhue.physics.raycast_all, datumhue.physics.point_query, datumhue.physics.shapecast, datumhue.voxel.new, SceneNode:on_collision_start (in its callback), SceneNode:on_collision_end (in its callback), PhysicsWorld:raycast and 5 more
Accepted by: datumhue.physics.add_joint, datumhue.physics.raycast, datumhue.physics.raycast_all, datumhue.physics.point_query, datumhue.physics.shapecast, PhysicsWorld:raycast, PhysicsWorld:raycast_all, PhysicsWorld:point_query and 1 more

The examples on this page start from:

lua

local scene = datumhue.scene.new({ width = 320, height = 240 })
scene:mount({ width = 320, height = 240 })
local volume = datumhue.voxel.new(scene, {
    width = 16,
    height = 8,
    depth = 16,
    pos = datumhue.math.vec3(-8, 0, -8),
})

Fields 8

Field	Type	Access	Description
`pos`	Vec3	read/write	World-space position of the volume's minimum corner.
`rotation`	Quat	read/write	Rotation quaternion about the minimum corner.
`scale`	Vec3	read/write	Per-axis scale on top of the cell size.
`width`	integer	read-only	Cells along x.
`height`	integer	read-only	Cells along y.
`depth`	integer	read-only	Cells along z.
`cell_size`	number	read-only	World units per cell.
`physics`	boolean	read/write	Whether the volume carries a static physics body whose collider matches its cells, following every edit; collisions and physics queries name that body as this handle. Assign a boolean to toggle.

Methods 18

Voxel:set

method

Voxel:set(x: integer, y: integer, z: integer, material: integer)

Set the material index at a cell.

Example

volume:palette(1, { color = datumhue.color("#e69875") })
-- 0-based cells: x and z run 0..15 here, y 0..7.
volume:set(0, 0, 0, 1)
volume:set(15, 7, 15, 1)

Voxel:get

method

Voxel:get(x: integer, y: integer, z: integer) -> integer

Read the material index at a cell.

Example

volume:set(3, 0, 3, 1)
-- A palette index; 0 is air.
print(volume:get(3, 0, 3), volume:get(3, 1, 3)) --> 1 0

Voxel:raycast

method

Voxel:raycast(ray: Ray) -> voxel.RaycastHit?

Raycast through the volume with a scene-space ray (the volume's position, rotation, and cell size are accounted for). Returns the hit cell, or nil.

Example

volume:fill(0, 0, 0, 15, 0, 15, 1)
-- A scene-space ray down onto cell (0, 0, 0), whose top is at y = 1.
local from = datumhue.math.vec3(-7.5, 5, -7.5)
local ray = datumhue.math.ray(from, datumhue.math.vec3(0, -1, 0))
local hit = volume:raycast(ray)
print(hit.x, hit.y, hit.z, hit.material) --> 0 0 0 1
print(hit.distance, hit.normal) --> 4.0 vec3(0.0, 1.0, 0.0)

returns voxel.RaycastHit record 6 keys

Key	Type	Description
x	integer	Voxel x coordinate of the hit cell.
y	integer	Voxel y coordinate of the hit cell.
z	integer	Voxel z coordinate of the hit cell.
material	integer	Palette material index of the hit cell.
distance	number	Distance from the ray origin to the hit, in scene units.
normal	Vec3	Face normal at the hit cell, in cell axes.

Voxel:fill

method

Voxel:fill(x0: integer, y0: integer, z0: integer, x1: integer, y1: integer, z1: integer, material: integer)

Fill an axis-aligned box of cells.

Example

volume:palette(1, { color = datumhue.color("#a7c080") })
-- Both corners are included: a floor of 16 x 1 x 16 cells.
volume:fill(0, 0, 0, 15, 0, 15, 1)
print(volume:count(1)) --> 256

Voxel:palette

method

Voxel:palette(index: integer, opts: voxel.PaletteOptions)

Define a palette material: color, render class, and — with an atlas bound — static per-face or animated block textures.

Example

-- Index 0 is air; define 1..255. light is a level 0..15.
local color = datumhue.color
volume:palette(1, { color = color("#d3c6aa") })
volume:palette(2, { color = color("#dbbc7f"), light = 12 })
volume:palette(3, { color = color("#7fbbb3"), transparent = true })
volume:fill(0, 0, 0, 15, 0, 15, 1)
volume:set(8, 1, 8, 2)
volume:fill(4, 1, 4, 6, 3, 6, 3)

opts voxel.PaletteOptions 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`.

Voxel:atlas

method

Voxel:atlas(atlas: Atlas)

Bind a tile atlas to the volume; palette entries then pick tiles with texture / frames. The atlas image must carry readable pixel data. Binding replaces any previous atlas; a material set with set_material takes precedence over block textures.

Voxel:clear

method

Voxel:clear()

Reset every cell to air.

Voxel:count

method

Voxel:count(material?: integer) -> integer

Count cells holding material, or every non-air cell when omitted.

Example

volume:fill(0, 0, 0, 3, 0, 3, 1)
volume:set(0, 1, 0, 2)
-- Every solid cell, or the cells of one palette index.
print(volume:count(), volume:count(2)) --> 17 1

Voxel:set_material

method

Voxel:set_material(material: Material | Shader)

Set the material for the volume's solid surfaces: a standard Material, or a Shader, whose color the surfaces show unlit. Transparent and emissive faces keep their built-in rendering.

Example

-- A Material or a Shader for every solid face.
local stone = datumhue.material.standard({
    color = datumhue.color("#859289"),
    roughness = 0.9,
})
volume:set_material(stone)
volume:fill(0, 0, 0, 15, 1, 15, 1)

Voxel:capture

method

Voxel:capture() -> integer

Snapshot the current cells as an animation frame; returns the frame's 1-based index for play.

Voxel:play

method

Voxel:play(opts: voxel.PlayOptions)

Play captured frames as a flip-book, swapping the volume's cells on the fps clock; the first frame applies immediately. Cell edits made while playing are overwritten at the next swap.

Example

volume:set(8, 0, 8, 1)
local lit = volume:capture()
volume:set(8, 0, 8, 0)
local dark = volume:capture()
-- Frames are the 1-based indices capture returned.
volume:play({ frames = { lit, dark }, fps = 2 })
print(lit, dark) --> 1 2

opts voxel.PlayOptions options 3 keys

Key	Type	Default	Description
frames	integer[]	every captured frame, in capture order	Captured frame indices to play, in order.
fps	number	8	Frame swaps per second.
looping	boolean	true	Wrap back to the first frame after the last; with it off, playback stops on the last frame.

Voxel:stop

method

Voxel:stop()

Stop playback, leaving the currently shown frame's cells in place.

Voxel:drop_frames

method

Voxel:drop_frames()

Discard every captured frame (and stop any playback), freeing their memory; the current cells stay.

Voxel:remove

method

Voxel:remove()

Remove the volume from its scene.

Voxel:fill_noise

method

Voxel:fill_noise(opts: voxel.FillNoiseOptions)

Set material wherever 3D noise meets the threshold over the region in one call, with no per-cell calls. Cells below the threshold are untouched.

Example

-- Solid wherever the noise at a cell is 0.2 or more.
volume:fill_noise({
    sampler = datumhue.noise.simplex({ seed = 7, frequency = 0.15 }),
    material = 1,
    threshold = 0.2,
})

opts voxel.FillNoiseOptions options 6 keys

Key	Type	Default	Description
sampler required	NoiseSampler	no default	3D-sampled noise source.
material required	integer	no default	Palette index written where the sample meets the threshold.
threshold	number	0	Minimum sample value (noise output is -1..1).
region	voxel.Region	the whole volume	Cell region to fill.
scale	number	1	Cell → noise-space coordinate scale.
offset	Vec3	datumhue.math.vec3(0, 0, 0)	Noise-space offset, for scrolling or layering.

Voxel:heightmap

method

Voxel:heightmap(opts: voxel.HeightmapOptions)

Fill each (x, z) column with material up to the height the source yields — terrain from noise, a grid, or a heightmap image in one call.

Example

-- Each column rises up to 6 cells where the noise reaches 1.
volume:heightmap({
    source = datumhue.noise.perlin({ seed = 3, frequency = 0.1 }),
    material = 1,
    max_height = 6,
})

opts voxel.HeightmapOptions options 6 keys

Key	Type	Default	Description
source required	NoiseSampler \| Grid \| Image	no default	Height source: 2D-sampled noise (remapped 0..1), a grid (cell value = height in cells), or an image (luminance, stretched over the region).
material required	integer	no default	Palette index columns fill with.
max_height	integer	the region's full height	Height in cells a full-strength source value reaches, above the region floor.
region	voxel.Region	the whole volume	Cell region.
scale	number	1	Cell → noise-space scale for noise sources.
offset	Vec2	datumhue.math.vec2(0, 0)	Noise-space offset for noise sources.

Voxel:stamp_grid

method

Voxel:stamp_grid(opts: voxel.StampGridOptions)

Write a 2D grid into one slice of the volume — dungeon layouts, automata output, or path maps become geometry in one pass.

Example

local plan = datumhue.grid.new(16, 16)
plan:fill_rect(2, 2, 12, 12, 1)
plan:fill_rect(4, 4, 8, 8, 2)
-- A floor plan at height 0: grid value 1 becomes palette index 1.
volume:stamp_grid({
    grid = plan,
    plane = "xz",
    at = 0,
    materials = { [1] = 1, [2] = 2 },
})

opts voxel.StampGridOptions options 4 keys

Key	Type	Default	Description
grid required	Grid	no default	2D source; its (x, y) maps onto the plane's axes.
plane required	"xz" \| "xy" \| "zy"	no default	Slice orientation: xz is a floor plan at height `at`, xy a wall at depth `at`, zy a wall at column `at`.
at required	integer	no default	The fixed coordinate of the slice.
materials	table	positive grid values write directly as palette indices	Map of grid value → palette index; unmapped values leave cells untouched.

Voxel:stamp_image

method

Voxel:stamp_image(opts: voxel.StampImageOptions)

Write image pixels into one slice by nearest-palette-color match; pixels with alpha below 0.5 write air. The image reads upright on wall planes.

Example

volume:palette(1, { color = datumhue.color("#e67e80") })
local art = datumhue.image.new({ width = 16, height = 8 })
local red = datumhue.color("#e67e80")
art:apply(datumhue.image.picture():rectfill(2, 2, 13, 5, red))
-- A wall at z = 0; each pixel takes the nearest palette color.
volume:stamp_image({ image = art, plane = "xy", at = 0 })

opts voxel.StampImageOptions options 3 keys

Key	Type	Default	Description
image required	Image	no default	Pixel source; must carry readable pixel data.
plane required	"xz" \| "xy" \| "zy"	no default	Slice orientation (see `stamp_grid`).
at required	integer	no default	The fixed coordinate of the slice.

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

Voxel

Fields 8

Methods 18

Voxel:set

Voxel:get

Voxel:raycast

Voxel:fill

Voxel:palette

Voxel:atlas

Voxel:clear

Voxel:count

Voxel:set_material

Voxel:capture

Voxel:play

Voxel:stop

Voxel:drop_frames

Voxel:remove

Voxel:fill_noise

Voxel:heightmap

Voxel:stamp_grid

Voxel:stamp_image

Try

Recently viewed

Settings

Keyboard shortcuts

On this page