godot_voxel/doc/source/blocky_terrain.md

Blocky terrains

This page focuses more in detail on blocky terrains, Minecraft-like, or made of cubes.

VoxelMesherBlocky

This mesher combines small meshes corresponding to voxel IDs into chunks. It culls faces occluding each other, but doesn't do greedy meshing. This is a similar technique used in Minecraft.

Voxel data used by this mesher may be stored in the following channel: VoxelBuffer.CHANNEL_TYPE

Creating voxel types

The mesher has a library property of type VoxelLibrary. This is a resource containing a list of all the models you want to use in order to build a voxel mesh: grass, dirt, wood, leaves, water, shrubs, stairs, door parts etc. You can create a new library in place, or make one saved to a file if you want to re-use it in several places. You can also create it from code.

First, set how many voxel types you need by setting the voxel_count property. If you need more later, you can increase it. A list of voxel types is shown below:

Each slot can contain a Voxel resource. The index shown on their left will be the ID they use in voxel data. Voxel 0 is a special case: by convention, it may be used as the default "air" voxel. You may assign a new Voxel resource to each slot, and fill in their properties.

With default 16-bit voxel data, you can create up to 65,536 voxel types. But in the future, some bits of the TYPE channel might be used to store orientation, so a more realistic limit could be around 4,096.

Cubes

A simple start is to set the geometry_type to Cube, so the voxel will be a cube.

Currently, texturing on this mesher is meant to use atlases. You may create a texture containing all the tiles your voxels can use. For example, here is one from the blocky game demo:

This atlas is a square texture and can contain up to 16x16 tiles. This number is important and needs to be set on the VoxelLibrary atlas_size property, so texture coordinates can be generated properly:

Voxel types using the Cube geometry can have different tiles on each of their faces. You can decide which one to use by assigning properties of Voxel, under the Cube tiles category. Coordinates here are in tiles, not pixels.

For example, if you want to use the "planks" tile, you may use x=3 and y=1:

So far we defined a cubic voxel with specific texture coordinates on its faces, but we still have to actually assign the texture and material used to render it. This is configured on the VoxelTerrain node directly. VoxelTerrain has a list of materials in its properties:

You may assign a new SpatialMaterial in the first slot, and assign its albedo_texture to your texture. You may also check the Vertex Color/Use as albedo property, because this will allow the mesher to bake ambient occlusion on the edge of cubes.

You can use more atlases or more materials by adding them to the VoxelTerrain node. Voxel types can only use one of them at a time. In order to choose which material a voxel will use, you may assign its material ID property. This property corresponds to the ID of the material assigned on the VoxelTerrain.

!!! note The reason texture atlas is preferred with a minimal amount of materials is because it allows to reduce the number of draw calls tremendously. The more materials you use, the more draw calls voxels will require, and the slower rendering will be.

Meshes

Creating voxel types with the Cube geometry is a shortcut that can be used for simple voxels, but the most versatile workflow is to use actual meshes. If you change geometry_type to CustomMesh, you may be allowed to assign a mesh resource. In this mode, the Cube tiles properties are not available, because you will have to assign texture coordinates of the mesh within a 3D modeler like Blender.

Meshes can have any shape you want, however there are a few constraints to respect:

• The origin of the mesh should be its lower corner.
• Blender's coordinate system is Z-up, but Godot is Y-up. Make sure the meshes you export don't go into negative coordinates once imported in Godot.
• Vertices should preferably be located within the 0..1 range, in all directions
• Keep it low-poly. The mesher can deal with large models, but performance can decrease very quickly if a numerous voxel type has a complex mesh.
• Faces lying on the sides of the 1x1x1 unit cube will be the only faces that can be culled by the mesher. Make sure they are perfectly lining up. If they don't, it can cause dramatic slowdowns due to the amount of generated geometry not getting culled.

The best format to use to export your meshes is OBJ. Godot imports this format by default as a mesh resource. Other formats are not suitable because Godot imports them as scenes, and Voxel resources require meshes, not scenes. Materials are not necessary to export, they are still setup in Godot on the terrain node. If you export/import your meshes with a material on them, it will be ignored.

Usage of voxel type IDs

Voxel IDs defined in a VoxelLibrary are like tiles in a tilemap: for simple games, they can directly correspond to a type of block. However, you may want to avoid treating them directly this way over time. Instead, you may define your own list of block types, and each type can correspond to one, or multiple Voxel IDs.

Examples from Minecraft:

• Stairs can be placed at different orientations, and sometimes have different appearance. These are actually multiple voxel IDs.
• Crops can have several growth stages. Each stage is a different voxel ID, for the same type of block.
• One door is actually made of 2 voxels. Its top, and bottom. There could be even more if we consider opened and closed doors.
• One rail can correspond to many different voxels: straight rails, slopes, and turns. They are all rails, but in different sub-configurations.

Managing the correspondance between your "game's block" IDs and voxel IDs is up to you.

!!! note At the moment, rotating or flipping voxels is not supported, so you have to create each rotated version you may need for a type of voxel.

Transparency

You may want some of your voxel types to be transparent. There is in fact two main ways to achieve this:

• Using alpha clip: transparent pixels are discarded, allowing rendering through the opaque pass, which avoids some typical issues with transparent surfaces.
• Alpha blend: actual transparency, which has a few limitations when multiple transparent surfaces are rendered behind each other

Both require to use a different material from the default one you may have used. You will need to add more materials on the VoxelTerrain node. Thanks to using a texture atlas, a typical setup only needs 3 materials using the same atlas: opaque, alpha clip and transparent Remember to assign the material ID of your voxel types so they use the right material.

Voxel resources also have a transparency_index property. This property allows to tune how two voxels occlude their faces. For example, let's say you have two transparent voxels, glass and leaves. By default, if you put them next to each other, the face they share will be culled, allowing you to see through the leaves from the glass block:

If two faces touch each other, if they have the same transparency index, they can get culled. But if their transparency index is different, they may not. This allows to see the leaves directly behind glass, instead of seeing the insides.

Here, glass has transparency_index=2, and leaves have transparency_index=1:

Random tick

Voxel has a property named random_tickable. This is for use with a very specific function of VoxelToolTerrain: run_blocky_random_tick

VoxelMesherCubes

TODO

Fast collisions alternative

Move and slide

Mesh-based collisions are quite accurate and feature-rich in Godot, however it has some drawbacks:

• Trimesh collision shapes have to be built each time the terrain is modified, which is very slow.
• The physics engine has to process arbitrary triangles near the player, which can't take advantage of particular situations, such as everything being cubes
• Sometimes you may also want a simpler, more game-oriented collision system

The VoxelBoxMover class provides a Minecraft-like collision system, which can be used in a similar way to move_and_slide(). It is more limited, but is extremely fast and is not affected by tunnelling.

The code below shows how to use it, but see the blocky demo for the full code.

var box_mover = VoxelBoxMover.new()
var character_box  = AABB(Vector3(-0.4, -0.9, -0.4), Vector3(0.8, 1.8, 0.8))
var terrain = get_node("VoxelTerrain")

func _physics_process(delta):
	# ... Input commands that set velocity go here ...

    # Apply terrain collision
	var motion : Vector3 = velocity * delta
	motion = box_mover.get_motion(get_translation(), motion, character_box, terrain)
	global_translate(motion)
	velocity = motion / delta

This technique mainly works if you use VoxelMesherBlocky, because it gets information about which block is collidable from the VoxelLibrary used with it. It might have some limited support in other meshers though.

If you use VoxelMesherBlocky, it will use the list of AABBs specified in Voxel resources. If the list is empty, the voxel won't have collisions. You can also filter out some collisions by assigning the collision mask property of VoxelBoxMover. This will be matched against the collision mask property found on Voxel resources.

Raycast

An alternative raycast function exists as well, which returns voxel-specific results. It may be useful if you turned off classic collisions as well. This is accessible with the VoxelTool class. An instance of it bound to the terrain can be obtained with get_voxel_tool().

var terrain : VoxelTerrain = get_node("VoxelTerrain")
var vt : VoxelTool = terrain.get_voxel_tool()
var hit = vt.raycast(origin, direction, 10)

if hit != null:
    # The returned position is in voxel coordinates,
    # and can be used to access the value of the voxel with other functions of `VoxelTool`
    print("Hit voxel ", hit.position)

If you use VoxelMesherBlocky, it is possible to filter out some voxel types by specifying the collision mask argument. This will be matched against the collision mask property found on Voxel resources.