Home

Voxelate Documentation

This module adds the voxels entity. You spawn it like any other entity:

local myVoxels = ents.Create("voxels")

This should be done on the server side. You should not try creating, configuring or interacting with voxels on the client side via lua. They are networked to the client automatically.

Voxels are configured by setting their config variable. Like this:

myVoxels.config = {key1 = value1,key2 = value2}

Once you configure the voxels, spawn them. You can also change the position of the voxels entity. Changing the rotation is not reccomended.

myVoxels:SetPos(Vector(-12800,-12800,0))
myVoxels:Spawn()

You cannot change the config settings once the voxels are spawned.

Config Options

There are a number of config options. None are required, but you're going to have to set some of them to get anything to appear.

dimensions

• Type: Vector
• Default: Vector(1,1,1)

This option specifies the dimensions of the system of voxels, in chunks. Chunk sizes are currently hardcoded 16x16x16 blocks, but this may change. You should use integers here, floating point numbers will be truncated. The lower corner of the first chunk will be on the entity's origin. Chunks will grow out in the positive x/y/z directions.

scale

• Type: Number
• Default: 1

This controls the size of the voxels themselves. The number corrisponds the the width of a single voxel. Leaving this at the default setting is not reccomended. Very small values will probably cause you to crash if you have physical meshes enabled.

drawExterior

• Type: Bool
• Default: false

This controls whether meshe faces will generate on the outer bounds of the system of voxels. You should only ever use it if your voxel system does not fill the whole map. Otherwise leave it off.

atlasMaterial

• Type: String
• Default: "models/debug/debugwhite"

This is the material that the voxel system will pull textures from. It should be a grid of textures for voxels. It should exist clientside. It must be a VMT, not a PNG. See the section on atlas setup for more info.

atlasWidth/atlasHeight

• Type: Number
• Default: 1

These two settings control the dimensions of the grid in the texture atlas. They should match how you design your texture atlas.

atlasIsPadded

• Type: Bool
• Default: false

Adjusts UV mapping for a padded atlas generated with my voxtex utility.

useMeshCollisions

• Type: Bool
• Default: false

Enables mesh collisions. This will cause the server to generate collision meshes as the client generates visual meshes. This will cause the server to use more memory and spend more time updating chunks. It will allow physical objects to collide with the system of voxels. Players, bullets, and other traces will always be able to collide with the voxels.

voxelTypes

• Type: Table
• Default: {}

A table of voxel types. The keys are block IDs, which can range from 0-255. The values are tables of settings for that specific block type. See the following section on Voxel Type Options.

Voxel Type Options

atlasIndex

• Type: Number
• Default: 0

The index in the atlas used for the block's texture. Cells in the atlas are numbered in rows from left to right, top to bottom.

atlasIndex_[xyz](Pos|Neg)

• Type: Number
• Default: atlasIndex

The index in the atlas to use for each side. Will override whatever you used for atlasIndex.

Methods

These functions can be used on the voxels entity. They all only exist on the server. They should only be used after the voxels entity has been spawned.

Voxels:generate(f)

Generates the map using the function f. Returns nothing. This will hang the server and re-stream the map to all connected clients. The function f takes the arguments (x,y,z) -- the integer coordinates of the block to generate. It should return the ID of the block in that position.

Voxels:save(filename)

Saves the voxels to a file. Filename should be a valid filename in the DATA path. Returns true if successful.

Voxels:load(filename)

Loads the voxels from a file. This will hang the server and re-stream the map to all connected clients. Filename should be a valid filename in the DATA path. The dimensions of the voxel system must match the dimensions of the saved system. Returns true if successful.

Voxels:getBlock(x,y,z)

Returns the ID of the block at the integer voxel coordinates (x,y,z).

Voxels:setBlock(x,y,z,d)

Sets the ID of the block at the integer voxel coordinates (x,y,z) to d.

Voxels:getAt(pos)

Returns the ID of the block at the world position pos.

Voxels:setAt(pos,d)

Sets the ID of the block at the world position pos to d.

Voxels:setRegion(x,y,z,sx,sy,sz,d)

Sets IDs of voxels in the region from the integer voxel coordinates (x,y,z) to (x+sx,y+sy,z+sz) to d. You should always use this when you can because the networking is optimized. Note that setting sx,sy,and sz to 0 will only place 1 block.

Voxels:setRegionAt(v1,v2,d)

Sets the IDs of voxels in the region from the world position v1 to v2. The vectors v1 and v2 do not need to be ordered. You should always use this when you can because the networking is optimized.

Voxels:setSphere(x,y,z,r,d)

Sets the IDs of voxels in the sphere centered at the integer voxel coordinates (x,y,z) with a radius of r voxels to d. You should always use this when you can because the networking is optimized.

Voxels:setSphereAt(pos,r,d)

Sets the IDs of voxels in the sphere centered at the world position pos with a radius of r source units to d. You should always use this when you can because the networking is optimized.

Atlas Setup

The atlas must be a VMT/VTF pair, not a PNG.

Here is a sample material:

"VertexLitGeneric"
{
	$basetexture TEXTURENAME
}

You can use my texture packing utility to easily create atlas textures.

If you want to implement separate "texture packs", I recommend you do so by hot-swapping the texture in the VMT.