Getting Started

Getting started

This is the shortest path from adding VoxLib to returning a custom shape from a block. By the end, you will have one fixed table shape and the four horizontal variants derived from it.

The examples use Mojang mappings and VoxLib 1.8.0 for Minecraft 1.21.1.

1. Add VoxLib

Follow Installation for your loader. Your development environment needs VoxLib on the compile and runtime classpaths. Fabric projects also need Fabric API and Fabric Language Kotlin.

2. Build a shape once

Minecraft measures block-model coordinates from 0 to 16. The following shape is a tabletop with four legs:

import com.github.mystery2099.voxlib.combination.VoxelAssembly.createCuboidShape
import com.github.mystery2099.voxlib.combination.VoxelAssembly.plus
import net.minecraft.world.phys.shapes.VoxelShape

private val TABLE_SHAPE: VoxelShape =
    createCuboidShape(0, 14, 0, 16, 16, 16) +
    createCuboidShape(1, 0, 1, 3, 14, 3) +
    createCuboidShape(13, 0, 1, 15, 14, 3) +
    createCuboidShape(1, 0, 13, 3, 14, 15) +
    createCuboidShape(13, 0, 13, 15, 14, 15)

Keep fixed shapes in a top-level property, companion object, or static field. Minecraft can ask for a block's shape many times, and rebuilding the same geometry inside getShape only creates work you could have done once.

VoxLib also provides the same general shape as CommonShapes.createTable() if its dimensions suit your block.

3. Return it from the block

import net.minecraft.core.BlockPos
import net.minecraft.world.level.BlockGetter
import net.minecraft.world.level.block.Block
import net.minecraft.world.level.block.state.BlockState
import net.minecraft.world.phys.shapes.CollisionContext
import net.minecraft.world.phys.shapes.VoxelShape

class TableBlock(properties: Properties) : Block(properties) {
    override fun getShape(
        state: BlockState,
        level: BlockGetter,
        pos: BlockPos,
        context: CollisionContext
    ): VoxelShape = TABLE_SHAPE
}

getShape controls the selection and outline shape. Vanilla also uses it for collision unless you override getCollisionShape separately. Most blocks should return the same shape for both. Split them only when the gameplay collision really should differ from the visible outline.

4. Add horizontal facings when needed

Do not hand-build the same block four times. Build one north-facing shape, derive the other three once, and select the right one from the blockstate:

import com.github.mystery2099.voxlib.rotation.VoxelRotation.flipHorizontal
import com.github.mystery2099.voxlib.rotation.VoxelRotation.rotateLeft
import com.github.mystery2099.voxlib.rotation.VoxelRotation.rotateRight
import net.minecraft.core.Direction

private val SHAPES_BY_FACING = mapOf(
    Direction.NORTH to NORTH_SHAPE,
    Direction.EAST to NORTH_SHAPE.rotateRight(),
    Direction.SOUTH to NORTH_SHAPE.flipHorizontal(),
    Direction.WEST to NORTH_SHAPE.rotateLeft()
)

In getShape, read your horizontal-facing property and return the matching entry. See Rotating and flipping shapes for the direction convention.

Where to go next

• Creating shapes explains coordinates and cuboids.
• Combining shapes covers unions and conditional geometry.
• Common shapes lists the built-in factories.
• Debug tools shows the live outline and collision overlays.
• Using VoxLib from Java covers the JVM API, including Kotlin object access.