Skip to content

Home

Jump to bottom
Mystery2099 edited this page Sep 18, 2026 · 4 revisions

VoxLib

A Fabric and NeoForge library for working with Minecraft's VoxelShape system.

VoxLib started as a collection of helpers inside Wooden Accents, where I kept writing the same shape code for directional blocks. I eventually pulled those helpers into their own library so I could reuse them without copying them between projects.

The goal is pretty simple: make shape code easier to write and read without replacing Minecraft's normal VoxelShape system. VoxLib can create, combine, rotate, flip, simplify, cache, and debug shapes, but vanilla still does the geometry underneath.

If another mod lists VoxLib as a dependency, install the release that matches your Minecraft version and loader. You only need the rest of this wiki if you are using VoxLib in your own mod.

Quick example

import com.github.mystery2099.voxlib.combination.VoxelAssembly.createCuboidShape
import com.github.mystery2099.voxlib.combination.VoxelAssembly.plus
import com.github.mystery2099.voxlib.rotation.VoxelRotation.rotateLeft

val table = createCuboidShape(0, 15, 0, 16, 16, 16) +
    createCuboidShape(1, 0, 1, 3, 15, 3) +
    createCuboidShape(13, 0, 1, 15, 15, 3) +
    createCuboidShape(1, 0, 13, 3, 15, 15) +
    createCuboidShape(13, 0, 13, 15, 15, 15)

val tableFacingWest = table.rotateLeft()

Writing a mod with VoxLib? Follow Getting started to add this shape to a block. Java users should start with Using VoxLib from Java because Kotlin object APIs use INSTANCE when called from Java.

Version matrix

Pick the VoxLib release that matches your Minecraft version. A JAR built for a nearby Minecraft version is not a safe substitute. Every release line has its own notes on Version history and migration.

VoxLib Minecraft Loaders Java required Status
1.8.0+1.21.1 1.21.1 Fabric, NeoForge 21 Current release
1.7.0+1.20.6 1.20.6 Fabric, NeoForge 21 Supported
1.6.1+1.20.1 1.20.1 Fabric, Forge 17 Supported
1.2.0 to 1.6.0+1.19.4 1.19.4 Fabric 17 Legacy
1.0.0, 1.1.0 1.19.4 Fabric 17 Historic

Each release targets one Minecraft version. Mod version suffixes follow the Minecraft version, for example 1.6.1+1.20.1.

Loader notes:

  • Fabric needs Fabric Language Kotlin in addition to Fabric API. Use the version listed on the Modrinth page for your VoxLib release.
  • NeoForge releases (1.20.6 and 1.21.1) bundle Kotlin and Caffeine inside the JAR. Kotlin for NeoForge is not required.
  • The Forge 1.20.1 release also bundles Kotlin and Caffeine.

Feature overview

Area What you get Page
First block Dependency setup, a fixed shape, and getShape Getting started
Installation Maven coordinates for Modrinth, GitHub Packages, and CurseForge Installation
Creating shapes createCuboidShape and the block coordinate system Creating shapes
Combining shapes +, union, BooleanOp combinations, conditional assembly DSL Combining shapes
Rotating and flipping rotateLeft, rotateRight, flip, direction mapping Rotating and flipping shapes
Pre-built shapes Slabs, pillars, tables, chairs, fences, stairs Common shapes
Simplification Approximate outline shapes and bounding boxes Simplifying shapes
Performance How the shape cache works and when it helps Caching and performance
Debug tools In-game overlays, config screen, logging helpers Debug tools
Java How to call the Kotlin API from Java mods Using VoxLib from Java
Versions Release history, mapping changes, migration guides Version history and migration

Requirements (current release)

  • Minecraft 1.21.1
  • Fabric Loader 0.19.5 or newer, or NeoForge 21.1.250 or newer within 21.1.x
  • Java 21 or newer
  • Kotlin 2.4.20 (bundled on NeoForge, provided by Fabric Language Kotlin on Fabric)
  • Client and dedicated server
  • Mod Menu is optional on Fabric and only needed for the in-game settings screen

Links

License

VoxLib is available under the Minecraft Mod Public License 1.0.1.

VoxLib wiki

Guides

Reference

Clone this wiki locally