Voxels

A fixed size grid of blocks, divided into chunks

Create a world by adding it to an entity with entity:add(voxel.world, sizeInChunks[, chunkSize]). The world is made of sizeInChunks chunks, each chunkSize blocks in size (vec3(16, 128, 16) by default). It starts out empty, with the standard blocks available in voxel.world.blocks

Moving, rotating or scaling the entity moves, rotates or scales the world

The size of the world in blocks

The size of each chunk in blocks

The block types that can be used in this world

Gets the block at a coordinate

Sets the block at a coordinate. Coordinates outside of the world are ignored

Fills every block between two corners, including the corners themselves

Fills every block within radius blocks of center

Fills a line of blocks from start to end, including both ends

How far (in blocks) from the voxel.world.focus chunks are generated and drawn when the world has a generator. Chunks a little further away than this are unloaded. Defaults to 128

The point (in scene space) that chunks are generated around, such as the position of a player. When nil (the default) the scene’s camera is used

true while chunks within the view distance are still being generated or built, useful for showing a loading screen

The material blocks are drawn with, the voxel material unless it’s changed. Cutout and translucent blocks are drawn with copies of it, which follow any changes made to it. Set it to nil to go back to a new voxel material

Fills the world using a generator function as chunks come within voxel.world.viewDistance of the voxel.world.focus. Chunks that move out of range are unloaded, unless they have been changed since they were generated. Calling generate again replaces the generator and starts generating from scratch

The function is called with a voxel.chunk to fill, on background threads so the game keeps running smoothly while the world is generated. Each thread runs the code from tab in its own Lua environment, so the function can use the code in that tab, the standard math, string and table libraries, noise, hash, color and print, but not globals or functions from your other tabs. Anything else it needs is passed in through params, which is copied and available to the generator as the global params

math.random is seeded for each chunk from its position (and params.seed when it is set), so a world generates the same way every time

hash(x[, y[, z]]) gives a number from 0 up to 1 for a position, which is always the same for that position (and params.seed), whichever chunk asks for it. Neighbouring chunks can use it to agree on things that cross the edges between them, where math.random would give each chunk different numbers. Coordinates are rounded down to whole numbers, and neighbouring positions give unrelated numbers (use noise for numbers that change smoothly). Give it an extra coordinate for more than one number at a position

Blocks can only be changed in chunks that have been generated, changes elsewhere are ignored

Removes every block from the world, and stops generating

Copies a voxel.model into the world as blocks of one type, each tinted with its voxel’s color. The model’s voxel (0, 0, 0) goes at origin, and its empty voxels leave the world as it is. Placing with a nil block removes the blocks the model covers instead

Saves the world’s blocks to a .cvox file

A generated world only saves the chunks that have been changed since they were generated, as its generator can make the rest again. This keeps saves small, even for very large worlds

Replaces the world’s blocks with those in a file saved by voxel.world.save()

Blocks are matched to the world’s block types by name. A block type the world doesn’t have yet is added without a texture, and can be given one afterwards with voxel.blocks.add(). The world must have the same chunk size as the one that was saved. Chunks beyond the world’s size are left out

To load a generated world, call voxel.world.generate() first and then load. Chunks in the file replace the generated ones, and the generator goes on making the rest

Finds the first block along a ray. The ray is in scene space (the same space as camera.screenToRay()), so it works however the world’s entity is moved, rotated or scaled

The result of voxel.world.raycast()

The coordinate of the block that was hit

The direction of the face that was hit, such as vec3(0, 1, 0) for the top of a block. coord + normal is the empty space in front of that face. vec3(0, 0, 0) when the ray starts inside a block

The type of block that was hit

The tint of the block that was hit

The point where the ray hit the block, in scene space

The distance from the ray’s origin to point

A chunk of the world being filled by a generator function (see voxel.world.generate()). Coordinates are world block coordinates, the same as voxel.world.set(), and anything outside of the chunk is ignored. Blocks are given by name or id, or nil for empty, and can be followed by a tint color like the world’s own functions. Coordinates are given as numbers, as vec3 isn’t available to generators

The x coordinate of the first block in the chunk

The y coordinate of the first block in the chunk

The z coordinate of the first block in the chunk

The size of the chunk along the x axis

The size of the chunk along the y axis

The size of the chunk along the z axis

Gets the name and tint of a block in the chunk

Sets a block in the chunk

Fills every block between two corners, including the corners themselves

Fills every block within radius blocks of a center block

Fills a line of blocks between two blocks, including the ends

The block types available to a world. Every world starts with the standard blocks below, which use textures from the builtin Blocks asset pack

Grass, Dirt, Sand, Stone, Gravel, Snow, Ice, Bedrock, Water, Glass, Glass Frame, Red Brick, Brick, Coal Ore, Gold Ore, Diamond Ore, Redstone Ore, Planks, Wood, Leaves, Crafting Table and Solid (plain white, use it with a tint)

Block types can be looked up by name, world.blocks.Stone or world.blocks["Glass Frame"]

Adds a new block type, or changes the existing type with the same name. The definition table can contain:

• texture - an image asset used for every face, or a table of assets by face
• color - a tint for every face, or a table of colors by face
• translucent - true for blended blocks like water and glass. Faces between translucent blocks of the same type are hidden
• cutout - true for blocks with see-through holes like leaves, where pixels with less than half alpha are not drawn
• roughness and metallic - from 0 to 1, used in place of the world material’s
• emissive - how brightly the block glows in its own color, from 0 to 8, used in place of the world material’s

Faces are named all, sides, top, bottom, north, south, east and west (most specific wins). Blocks without a texture are plain white, tinted by their color

Any other values in the definition become custom properties of the block type

Gets a block type by name or id

Gets every block type, in the order they were added

Removes every block type, including the standard blocks. Blocks already in the world using a removed type are no longer drawn

A type of block, such as Grass or Water

Custom values can be stored on a block type, either in its definition or by setting them directly

The name of this block type

A number identifying this block type within its world

Whether this block type is blended, like water and glass

Whether this block type has see-through holes, like leaves

The roughness of this block type, from 0 to 1, or nil to use the world material’s

How metallic this block type is, from 0 to 1, or nil to use the world material’s

How brightly this block type glows in its own color, from 0 to 8, or nil to use the world material’s

A small grid of colored voxels drawn as a single mesh, for things like characters, vehicles and props

Load a model from a .cvox or MagicaVoxel .vox file with voxel.model(asset.Name), or make an empty one with voxel.model(size). Voxels are addressed by integer coordinates from vec3(0, 0, 0) up to (but not including) voxel.model.size, and each one is either empty or filled with a color

MagicaVoxel scenes with several objects are combined into one model, using their positions and rotations. Hidden objects and layers are left out, and MagicaVoxel’s z-up axes are turned to match Codea’s y-up

The size of the model in voxels

A mesh that draws the model, with one unit per voxel and its origin at the corner of voxel (0, 0, 0). Faces between neighbouring voxels are left out and corners are shaded by ambient occlusion, like a voxel.world. It’s drawn with a new voxel material, or any other material given to its entity

The same mesh is returned until the model changes, so it can be shared by many entities. Changing a voxel makes a new mesh the next time this is read, entities already using the old mesh keep showing it

Gets the color of a voxel

Sets the color of a voxel, or empties it. Coordinates outside of the model are ignored

Makes a copy of the model. Changing either one leaves the other as it is, which makes copies useful for undo in an editor. The copy shares the model’s voxel.model.mesh until one of them changes, so a copy made after the mesh is read can be shown again without being meshed

Replaces the model’s size and voxels with another model’s, leaving the other model as it is. Entities keep showing the old mesh until they’re given voxel.model.mesh again

Saves the model to a file. The file’s extension picks the format: .cvox for the Voxel Editor, or .vox for MagicaVoxel. MagicaVoxel files can hold at most 255 different colors and 256 voxels in each dimension, larger or more colorful models can be saved as .cvox