Skip to main content

​
Overview

Voxy World Gen V2 integrates seamlessly with Voxy, a high-performance LOD (Level of Detail) renderer for Minecraft. This integration automatically ingests generated chunks into Voxy’s rendering system, enabling seamless distant terrain visualization.

​
What is Voxy?

Voxy is a Minecraft mod that renders distant terrain at lower levels of detail, allowing you to see much farther than vanilla render distance without sacrificing performance. Voxy World Gen V2 automatically feeds generated chunks to Voxy so that distant areas appear immediately without manual loading.

​
Integration Architecture

The integration uses a reflection-based approach to maintain compatibility across different Voxy versions without hard dependencies. This design allows Voxy World Gen V2 to work whether or not Voxy is installed.

​
Detection and Initialization

The integration automatically detects Voxy at runtime: 
private static void initialize() {
    try {
        Class<?> ingestServiceClass = Class.forName("me.cortex.voxy.common.world.service.VoxelIngestService");
        // Successfully found Voxy classes
        enabled = true;
    } catch (ClassNotFoundException e) {
        // Voxy not present, integration disabled
        enabled = false;
    }
}
The integration attempts initialization on first use. If Voxy is not installed, the integration gracefully disables itself with no performance impact.

​
Integration Methods

​
Chunk Ingestion

The primary integration point uses Voxy’s chunk ingestion API: 
public static void ingestChunk(LevelChunk chunk) {
    if (!initialized) initialize();
    if (!enabled || ingestMethod == null) return;

    try {
        ingestMethod.invoke(chunk);
    } catch (Throwable e) {
        VoxyWorldGenV2.LOGGER.error("failed to ingest chunk", e);
    }
}
This method is called automatically whenever Voxy World Gen V2 generates a new LOD chunk. The chunk data is passed directly to Voxy’s ingestion service.

​
Method Handle Resolution

The integration searches for Voxy’s ingestion method using multiple common method names: 
String[] commonMethods = {"ingestChunk", "tryAutoIngestChunk", "enqueueIngest", "ingest"};
Method targetMethod = null;
for (String methodName : commonMethods) {
    try {
        targetMethod = ingestServiceClass.getMethod(methodName, LevelChunk.class);
        if (targetMethod != null) break;
    } catch (NoSuchMethodException ignored) {}
}
This approach ensures compatibility even if Voxy renames its ingestion methods between versions.

​
Raw Ingestion API

For advanced use cases, the integration also provides direct section-level ingestion: 
public static void rawIngest(LevelChunk chunk, DataLayer skyLight) {
    if (!initialized) initialize();
    if (rawIngestMethod == null || worldIdentifierOfMethod == null) return;

    try {
        LevelChunkSection[] sections = chunk.getSections();
        int cx = chunk.getPos().x;
        int cz = chunk.getPos().z;
        int minY = chunk.getMinSectionY();
        
        // Get world identifier once per chunk
        Object worldId = worldIdentifierOfMethod.invoke(chunk.getLevel());
        if (worldId == null) return;

        // Ingest each non-empty section
        for (int i = 0; i < sections.length; i++) {
            LevelChunkSection section = sections[i];
            if (section == null || section.hasOnlyAir()) continue;
            
            rawIngestMethod.invoke(worldId, section, cx, minY + i, cz, null, skyLight);
        }
    } catch (Throwable e) {
        VoxyWorldGenV2.LOGGER.error("failed to raw ingest chunk", e);
    }
}
The raw ingestion method:
  • Processes chunks section-by-section
  • Skips empty sections for better performance
  • Provides lighting data to Voxy
  • Used by specialized generators like Tellus integration
Raw ingestion is primarily used internally by the Tellus integration for direct voxel data injection.

​
Automatic Ingestion Workflow

Here’s how chunks flow from generation to Voxy rendering:
1

Chunk Generation

Voxy World Gen V2 generates a chunk in response to player movement or explicit requests.
2

Automatic Detection

After generation, the system checks if Voxy integration is available.
3

Ingestion

The chunk is passed to VoxyIntegration.ingestChunk() which forwards it to Voxy’s service.
4

LOD Rendering

Voxy processes the chunk data and adds it to the LOD rendering system.

​
Checking Integration Status

You can verify if Voxy integration is active: 
if (VoxyIntegration.isVoxyAvailable()) {
    // Voxy is present and integration is active
}

​
Implementation Details

​
Method Handles vs Direct Calls

The integration uses Java’s MethodHandle API instead of direct method calls: 
private static MethodHandle ingestMethod;
private static MethodHandle rawIngestMethod;
private static MethodHandle worldIdentifierOfMethod;
Benefits:
  • No compile-time dependency on Voxy
  • Faster invocation than standard reflection
  • Type-safe method binding
  • Automatic exception wrapping

​
Service Instance Binding

The integration automatically detects whether to use static or instance methods: 
if (serviceInstance != null && !Modifier.isStatic(targetMethod.getModifiers())) {
    ingestMethod = ingestMethod.bindTo(serviceInstance);
}
This ensures compatibility with both static and instance-based API designs.

​
Performance Considerations

Initialization happens only once on first chunk generation. The overhead is negligible (~5-10ms) and doesn’t impact runtime performance.
Method handles are nearly as fast as direct method calls. Each ingestion takes less than 1ms for standard chunks.
The raw ingestion API skips empty sections, reducing data transfer by 60-80% in typical worlds.

​
Troubleshooting

If chunks aren’t appearing in Voxy’s LOD system, check the logs for initialization errors:
[VoxyWorldGenV2] voxy integration initialized (enabled: true, raw: true)
If you see enabled: false, Voxy may not be installed or may be incompatible.

​
Common Issues

Symptoms: Log shows voxy not present, integration disabledSolutions:
  • Verify Voxy is installed and loaded
  • Check that Voxy version is compatible (requires VoxelIngestService class)
  • Ensure both mods are loaded in the same Minecraft instance
Symptoms: Log shows failed to ingest chunkSolutions:
  • Update Voxy to the latest version
  • Check for conflicting mods
  • Report the issue with full error logs

​
Source Code Reference

The complete integration implementation can be found in: 
src/main/java/com/ethan/voxyworldgenv2/integration/VoxyIntegration.java
Key components:
  • Lines 21-82: Initialization and method handle resolution
  • Lines 84-93: Main chunk ingestion method
  • Lines 95-137: Raw section-level ingestion
  • Lines 138-141: Integration status check

Tellus Integration

Learn how Tellus uses raw ingestion for Earth terrain

Configuration

Configure generation radius and LOD behavior

Architecture

Understand the overall system design

Performance

Optimize for large-scale LOD generation

Build docs developers (and LLMs) love

Get started for freeTalk to us