Debug Tools

Debug tools

Shape bugs are much easier to fix when you can see the shape Minecraft is actually using. VoxLib includes an in-game overlay for quick checks and a few code-level helpers for custom development tools.

In-game targeted overlay

The quickest option needs no code:

1. Install VoxLib (plus Mod Menu on Fabric).
2. Open the VoxLib settings screen. On Fabric, use Mod Menu and enable Show libraries to see VoxLib. On NeoForge, use the Mods screen.
3. Enable Debug mode.
4. Toggle Show targeted outline, Show targeted collision, or both.
5. Look at any block. The configured shape draws over it in the configured color and transparency.

Settings persist to config/voxlib-client.json in the client game directory:

{
  "debugModeEnabled": true,
  "showTargetedOutline": true,
  "showTargetedCollision": false,
  "debugShapeColor": -65536,
  "debugShapeAlpha": 0.4
}

debugShapeColor is ARGB. Partial files keep their defaults for missing fields, and alpha values outside 0.0 to 1.0 are clamped when loaded.

The settings screen is client-only. The rendering debug tools live in shared client sources compiled into each loader's client entrypoint, so they never load on a dedicated server.

Rendering a shape yourself (client)

For your own dev tools, render any shape at a position:

import com.github.mystery2099.voxlib.debug.VoxelShapeDebug
import net.minecraft.core.BlockPos
import java.awt.Color

VoxelShapeDebug.renderShape(
    matrices,
    vertexConsumers,
    shape,
    BlockPos(x, y, z),
    color = Color.GREEN,
    alpha = 0.5f
)

The method draws every box of the shape with RenderType.lines(). The lineWidth parameter is retained for compatibility but unused; RenderType controls line width.

To render using the configured debug settings (respecting debug mode, color, and alpha):

VoxelShapeDebug.renderShapeWithConfig(matrices, vertexConsumers, shape, pos)

Call these from a client render context such as a world-render callback. VoxelShapeDebug imports Minecraft client classes. Referencing it from common initialization or dedicated-server code can crash class loading, so keep it on the client side.

Logging shape info

These functions print to standard output. They are methods on the client-only VoxelShapeDebug class, so use them only from client code:

import com.github.mystery2099.voxlib.debug.VoxelShapeDebug

VoxelShapeDebug.logShapeInfo(shape, "MyShape")

Output lists the box count and each box's coordinates:

MyShape contains 3 boxes:
  AABB: (0.0, 0.0, 0.0) to (1.0, 0.5, 1.0)
  ...

Coordinates print in the 0 to 1 shape-space scale used by VoxelShape.forAllBoxes, not the 0 to 16 block-unit scale used by createCuboidShape.

Comparing two shapes

When a transformation or refactor looks suspicious, compare the shapes before and after:

VoxelShapeDebug.compareShapes(original, rotated, "Original", "Rotated")

This prints both shapes' boxes or reports that the shapes are identical.

Typical workflow

1. Log the base shape with logShapeInfo to see its boxes.
2. Apply the rotation or union you intend.
3. Use compareShapes to confirm the boxes moved the way you expect.
4. In game, enable the targeted overlay to see real blockstate-driven shapes in context.

Java usage

import com.github.mystery2099.voxlib.debug.VoxelShapeDebug;
import java.awt.Color;

VoxelShapeDebug debug = VoxelShapeDebug.INSTANCE;
debug.renderShape(matrices, vertexConsumers, shape, pos, Color.GREEN, 0.5f, 2.0f);
debug.renderShapeWithConfig(matrices, vertexConsumers, shape, pos);
debug.logShapeInfo(shape, "MyShape");
debug.compareShapes(a, b, "Original", "Rotated");