Skip to main content

​
Overview

The TellusIntegration class provides integration with the Tellus mod (Terra 1-to-1 Earth) to generate real-world terrain data and ingest it into Voxy’s LOD system. It manages asynchronous terrain generation using a dedicated thread pool and builds detailed voxel data including terrain, water bodies, vegetation, and biome-specific surface blocks. Package: com.ethan.voxyworldgenv2.integration.tellus

​
Architecture

The integration consists of several components:
  • TellusIntegration (main API): Manages initialization, worker threads, and generation queue
  • TellusSampler: Samples real-world terrain data (heights, cover classes, slopes, water)
  • VoxyIngester: Directly interfaces with Voxy’s internal engine for low-level voxel insertion
  • TellusWorldFeatures: Places procedural trees and vegetation

​
Methods

​
isTellusWorld

Checks if a given level is a Tellus (Terra 1-to-1) world. 
public static boolean isTellusWorld(ServerLevel level)
​
level
ServerLevel
required
The server level to check
​
return
boolean
true if the level uses Tellus’s EarthChunkGenerator, false otherwise
Behavior:
  • Initializes the integration on first call
  • Checks if Tellus is present via TellusSampler
  • Inspects the chunk generator class name for “EarthChunkGenerator”
  • Returns false if Tellus is not installed
Example: 
import com.ethan.voxyworldgenv2.integration.tellus.TellusIntegration;
import net.minecraft.server.level.ServerLevel;

@Override
public void onWorldLoad(ServerLevel level) {
    if (TellusIntegration.isTellusWorld(level)) {
        LOGGER.info("Tellus world detected: {}", level.dimension().location());
        // Enable real-world terrain LOD generation
    }
}

​
enqueueGenerate

Enqueues asynchronous LOD generation for a specific chunk position in a Tellus world. 
public static void enqueueGenerate(
    ServerLevel level,
    ChunkPos pos,
    Runnable onComplete
)
​
level
ServerLevel
required
The Tellus world to generate LOD data for
​
pos
ChunkPos
required
The chunk position to generate
​
onComplete
Runnable
Callback invoked after generation completes (on worker thread). Pass null if no callback is needed
Behavior:
  • Submits generation to a dedicated worker thread pool
  • Prevents duplicate generation requests for the same chunk
  • Invokes callback immediately if chunk is already being processed
  • Thread pool uses caller-runs policy when queue is full (max 10,000 tasks)
  • Worker threads run at NORM_PRIORITY - 1 to avoid blocking game logic
Generation Process:
  1. Prefetch: Calls TellusSampler.prefetch() to warm up data caches
  2. Sample: Retrieves terrain heights, cover classes, slopes, water data
  3. Build: Constructs voxel sections with terrain, water, and vegetation
  4. Ingest: Directly inserts sections into Voxy’s world engine
  5. Cleanup: Removes chunk from tracking set and invokes callback
Example: 
import net.minecraft.world.level.ChunkPos;

// Generate LOD for chunks around a player
for (int dx = -32; dx <= 32; dx++) {
    for (int dz = -32; dz <= 32; dz++) {
        ChunkPos pos = new ChunkPos(playerChunkX + dx, playerChunkZ + dz);
        
        TellusIntegration.enqueueGenerate(level, pos, () -> {
            // Optional: log completion or update progress
            LOGGER.debug("LOD generated for chunk {}", pos);
        });
    }
}
Thread Pool Configuration:
  • Thread count: max(1, availableProcessors / 2)
  • Queue capacity: 10,000 tasks
  • Rejection policy: Caller-runs (tasks execute on calling thread when queue is full)
  • Thread naming: tellus-voxy-worker-N

​
shutdown

Shuts down the integration, stopping all worker threads and clearing state. 
public static void shutdown()
Behavior:
  • Forcibly terminates the worker thread pool (shutdownNow())
  • Waits up to 2 seconds for threads to terminate
  • Clears the set of in-progress chunks
  • Resets initialization state
  • Logs shutdown completion
Example: 
// Server shutdown hook
@Override
public void onServerStopping() {
    TellusIntegration.shutdown();
}
Shutdown is abrupt and does not wait for in-progress tasks to complete gracefully. Ensure no critical work is pending before calling.

​
Generation Details

​
Terrain Surface Rules

The integration applies biome-specific surface blocks based on ESA cover classes and slopes:
​
Grass/Dirt
Palette
Default for most land biomes (grass block top, dirt filler)
​
Sand/Sandstone
Palette
Deserts, beaches (sand top, sandstone filler)
​
Stone
Palette
High slopes (≥3) above sea level (stone top and filler)
​
Snow/Ice
Palette
ESA class 70 regions (snow block top, deepslate filler)
​
Water Variants
Palette
Oceans use gravel (10%), clay (5%), or sand (85%) based on random variation
​
Mud
Palette
Mangrove swamps (mud top and filler)

​
Water Handling

Water bodies are processed with shoreline detection:
  1. Expanded Grid: Samples a 24×24 grid (includes 4-block border) to detect shorelines beyond chunk boundaries
  2. Distance to Shore: Calculates distance to nearest land within 5 blocks
  3. Shallow Slopes: Lowers underwater terrain near shores (targetHeight = waterLevel - distanceToShore)
  4. Ocean Depth: Ensures ocean floors are at least 8 blocks below sea level
  5. Water Surface: Uses sampled water head heights from Tellus data

​
Vegetation Placement

The integration places three types of vegetation:
​
Procedural Trees
TellusWorldFeatures.placeProceduralTrees
Large trees placed based on Tellus forest cover data, using various oak/birch/spruce log and leaf blocks
​
Surface Vegetation
TellusWorldFeatures.placeVegetation
Grass, flowers, mushrooms placed on grass blocks in non-badlands/desert biomes
​
Underwater Vegetation
TellusWorldFeatures.placeUnderwaterVegetation
Kelp, seagrass placed in water columns
Vegetation is stored in a Map<BlockPos, Long> and placed during voxel section building.

​
Lighting and Biomes

All voxel data includes:
  • Block ID: From Voxy’s BlockStateMapper
  • Biome ID: Sampled from Minecraft’s biome source at each quart-position
  • Sky Light: Full brightness (level 15) for all blocks

​
Performance Characteristics

​
Sampling
Fast
Tellus data is pre-cached via prefetch() before sampling
​
Building
CPU-intensive
Processes up to ~384 sections per chunk (24 vertical sections × 16×16 columns)
​
Ingestion
Direct
Bypasses normal chunk pipelines, directly inserting into Voxy’s world engine
​
Concurrency
Multi-threaded
Worker pool processes multiple chunks in parallel (default: CPU cores / 2)

​
Implementation Details

​
Initialization

On first API call:
  1. Initializes TellusSampler (detects Tellus classes via reflection)
  2. Initializes VoxyIngester (resolves Voxy internal API)
  3. Creates thread pool with daemon threads
  4. Logs initialization status

​
Duplicate Prevention

The buildingChunks concurrent set prevents duplicate work:
  • add(pos) returns false if chunk is already being processed
  • Chunk is removed from set in finally block after completion
  • Thread-safe across multiple worker threads

​
Error Handling

  • Tellus Detection Failures: Return false from isTellusWorld, log info
  • Generation Failures: Log error with chunk position, continue processing other chunks
  • Voxy Unavailable: Return early from generation, no ingestion occurs

​
Utility Methods

​
seedFromCoords

Generates a pseudo-random seed from world coordinates (used internally for biome-based randomization). 
public static long seedFromCoords(int x, int y, int z)
​
x
int
required
World X coordinate
​
y
int
required
World Y coordinate
​
z
int
required
World Z coordinate
​
return
long
Deterministic pseudo-random seed based on coordinates
Example: 
long seed = TellusIntegration.seedFromCoords(blockX, blockY, blockZ);
Random random = new Random(seed);

​
Source Reference

See TellusIntegration.java:20-329 for the complete implementation.

Build docs developers (and LLMs) love

Get started for freeTalk to us