World Generation Overview

World Generation Overview

The World Generation system creates terrain, structures, and biomes for Hytale worlds. It uses a procedural generation pipeline with zones, biomes, caves, and prefabs.

Package Location

• Providers: com.hypixel.hytale.server.core.universe.world.worldgen.provider
• Hytale generator: com.hypixel.hytale.server.worldgen
• Generated chunks: com.hypixel.hytale.server.core.universe.world.worldgen

Architecture

flowchart TB
    subgraph WorldGen["World Generation"]
        subgraph Provider["HytaleWorldGenProvider"]
            subgraph ChunkGen["ChunkGenerator"]
                ZonePattern["ZonePattern<br/>Generator"]
                BiomePattern["BiomePattern<br/>Generator"]
                CaveGen["CaveGenerator"]
                Heightmap["Heightmap<br/>Generator"]
                Prefab["Prefab<br/>Generator"]
                Populator
            end
        end
    end

World Gen Providers

IWorldGenProvider Interface

public interface IWorldGenProvider {
    IWorldGen getGenerator() throws WorldGenLoadException;
}

HytaleWorldGenProvider

The default world generation provider for Hytale:

public class HytaleWorldGenProvider implements IWorldGenProvider {
    public static final String ID = "Hytale";

    // Configuration
    String name = "Default";  // Generator name
    String path;              // Custom path (optional)
}

World Config Usage

{
  "WorldGen": {
    "Type": "Hytale",
    "Name": "MyWorldGen",
    "Path": "path/to/worldgen/config"
  }
}

Built-in Providers

Provider	Description
HytaleWorldGenProvider	Full procedural terrain (in server.worldgen package)
FlatWorldGenProvider	Flat terrain
VoidWorldGenProvider	Empty void world
DummyWorldGenProvider	No generation
HandleProvider	Custom handle-based generator (in builtin.hytalegenerator)

ChunkGenerator

The core class that generates chunks:

public class ChunkGenerator implements IBenchmarkableWorldGen, IWorldMapProvider {
    // Pool size based on CPU cores
    public static final int POOL_SIZE = Math.max(2,
        (int) Math.ceil(Runtime.getRuntime().availableProcessors() * 0.75));

    // Get zone data at coordinates
    public ZoneBiomeResult getZoneBiomeResultAt(int seed, int x, int z);

    // Get height at coordinates
    public int getHeight(int seed, int x, int z);

    // Get cave data
    public Cave getCave(CaveType caveType, int seed, int x, int z);

    // Get spawn points
    public Transform[] getSpawnPoints(int seed);
}

New in Update 3

HytaleGenerator now defines DEFAULT_SPAWN_POSITION = (0, 140, 0) and a getSpawnPositions(GeneratorProfile, maxPositionsCount) method for retrieving spawn positions from world structures. Check the Update 3 changelog for all worldgen changes.

Generation Pipeline

1. Zone Generation: Determine zone at position
2. Biome Generation: Determine biome within zone
3. Heightmap: Generate terrain height
4. Block Placement: Place blocks based on layers
5. Cave Carving: Carve caves and caverns
6. Prefab Placement: Place structures
7. Population: Add details (ores, plants, etc.)

Zones

Zones are large-scale regions of the world with distinct generation rules.

Zone Record

public record Zone(
    int id,
    String name,
    ZoneDiscoveryConfig discoveryConfig,
    CaveGenerator caveGenerator,
    BiomePatternGenerator biomePatternGenerator,
    UniquePrefabContainer uniquePrefabContainer
) {}

Zone Configuration

{
  "Id": 1,
  "Name": "Plains",
  "DiscoveryConfig": {
    "DiscoverKey": "zone_plains",
    "DiscoverRadius": 100
  },
  "CaveGenerator": "DefaultCaves",
  "BiomePattern": "plains_biomes.png"
}

Zone Pattern Provider

Generates zone layout based on patterns:

public class ZonePatternProvider {
    // Zone pattern generation
}

public class ZonePatternGenerator {
    // Generate zone at coordinates
}

Biomes

Changed in Update 3

BiomeType was renamed to Biome and SimpleBiomeType to SimpleBiome. The BiomeMap/SimpleBiomeMap classes were removed and replaced by WorldStructure, which holds a BiCarta<Integer> biome map, a Registry<Biome>, transition distances, and spawn positions. The Indexer class was replaced by a typed Registry<T> with bidirectional lookup. The Update 3 changelog documents all renames and removals.

Biomes define terrain characteristics within zones.

Biome Class

public abstract class Biome {
    int id;
    String name;
    BiomeInterpolation interpolation;
    IHeightThresholdInterpreter heightmapInterpreter;

    // Containers
    CoverContainer coverContainer;       // Surface cover (grass, etc.)
    LayerContainer layerContainer;       // Block layers
    PrefabContainer prefabContainer;     // Structures
    TintContainer tintContainer;         // Color tinting
    EnvironmentContainer environmentContainer;  // Environment settings
    WaterContainer waterContainer;       // Water features
    FadeContainer fadeContainer;         // Biome transitions

    // Noise
    NoiseProperty heightmapNoise;

    // Visual
    int mapColor;
}

Biome Containers

Container	Description
CoverContainer	Surface blocks (grass, snow)
LayerContainer	Block layer definitions
PrefabContainer	Structure placement
TintContainer	Block tinting rules
EnvironmentContainer	Environment settings
WaterContainer	Water/fluid settings
FadeContainer	Transition rules

Layer Container

Defines block layers from surface to bedrock:

{
  "Layers": [
    {
      "Block": "Grass",
      "Depth": 1
    },
    {
      "Block": "Dirt",
      "Depth": 3
    },
    {
      "Block": "Stone",
      "Depth": -1
    }
  ]
}

Cave Generation

CaveGenerator

public class CaveGenerator {
    // Generate caves for a region
}

public enum CaveType {
    // Cave type definitions
}

public class Cave {
    // Cave data
}

Cave Configuration

{
  "CaveType": "Standard",
  "Frequency": 0.5,
  "MinHeight": 10,
  "MaxHeight": 64,
  "Radius": {
    "Min": 2,
    "Max": 5
  }
}

Prefabs

Prefabs are pre-built structures placed during generation.

PrefabContainer

public class PrefabContainer {
    // Prefab placement rules
}

public class PrefabLoadingCache {
    // Cache for loaded prefabs
}

Prefab Configuration

{
  "Prefabs": [
    {
      "Id": "Village_House",
      "Chance": 0.1,
      "MinDistance": 100,
      "GroundLevel": "Surface"
    }
  ]
}

Unique Prefabs

Special one-per-world prefabs:

public class UniquePrefabContainer {
    // Unique prefab management

    public static class UniquePrefabEntry {
        boolean isSpawnLocation();
        Vector3i getPosition();
        Vector3d getSpawnOffset();
        Rotation getRotation();
    }
}

Props

New in Update 2

WeightedProp and OffsetProp were added in Update 2 for more flexible world generation.

Props are decorative elements placed during world generation. Server v2 introduces new prop types for enhanced placement control.

WeightedProp

Selects a child prop randomly based on weight probability:

public class WeightedProp implements Prop {
    // Weight-based random selection from child props
    private final List<WeightedEntry> entries;

    public record WeightedEntry(Prop prop, float weight) {}
}

Configuration:

Weighted prop example

{
  "Type": "Weighted",
  "Entries": [
    { "Prop": "Tree_Oak_Large", "Weight": 0.1 },
    { "Prop": "Tree_Oak_Medium", "Weight": 0.3 },
    { "Prop": "Tree_Oak_Small", "Weight": 0.6 }
  ]
}

Field	Type	Description
Entries	array	List of weighted prop entries
Entries[].Prop	string	Prop ID to place
Entries[].Weight	float	Relative weight (higher = more likely)

Use Cases:

• Varied tree sizes (mostly small, occasionally large)
• Rock formations with random sizes
• Flower variety in meadows

OffsetProp

Applies a position offset to a child prop:

public class OffsetProp implements Prop {
    // Offset applied to child prop position
    private final Prop childProp;
    private final Vector3d offset;
}

Configuration:

Offset prop example

{
  "Type": "Offset",
  "Prop": "Mushroom_Cluster",
  "Offset": { "X": 0, "Y": -0.5, "Z": 0 }
}

Field	Type	Description
Prop	string	Child prop ID
Offset	Vector3d	Position offset to apply

Use Cases:

• Partially buried objects
• Floating elements (vines, hanging plants)
• Stacked prop combinations

SimpleHorizontalPositionProvider

Caution

VerticalEliminatorPositionProvider was renamed to SimpleHorizontalPositionProvider in Update 2.

Changed in Update 3

SpherePositionProviderAsset / SpherePositionProvider were removed and replaced by BoundPositionProviderAsset / BoundPositionProvider, which use axis-aligned 3D bounds instead of spherical distance filtering. A new FrameworkPositionProviderAsset was also added for referencing named positions from the PositionsFrameworkAsset. See the Update 3 changelog for all position provider changes.

Provides horizontal positions for prop placement:

public class SimpleHorizontalPositionProvider implements PositionProvider {
    // Generates horizontal positions within a region
}

Configuration:

Position provider example

{
  "Type": "SimpleHorizontal",
  "Density": 0.1,
  "MinSpacing": 2.0,
  "MaxSpacing": 8.0
}

Populators

Populators add details after basic terrain is generated.

Built-in Populators

Populator	Description
BlockPopulator	Place additional blocks
CavePopulator	Carve caves
WaterPopulator	Add water features
PrefabPopulator	Place structures

Populator Interface

public interface IPopulator {
    void populate(GeneratedChunk chunk, Random random);
}

Generated Chunk

The output of chunk generation:

public class GeneratedChunk {
    // Block data
    GeneratedBlockChunk blockChunk;

    // Block states
    GeneratedBlockStateChunk blockStateChunk;

    // Entities
    GeneratedEntityChunk entityChunk;
}

Noise Functions

World generation uses noise for natural variation.

NoiseProperty

public class NoiseProperty {
    // Noise configuration
}

Height Threshold Interpreter

public interface IHeightThresholdInterpreter {
    // Interpret height thresholds for biome-specific terrain
}

Procedural Library

The procedural library provides tools for generation:

Conditions

// Height-based conditions
IHeightThresholdInterpreter

// Block-based conditions
HashSetBlockFluidCondition
FilteredBlockFluidCondition
BlockMaskCondition

Property Suppliers

ICoordinateDoubleSupplier
ConstantCoordinateDoubleSupplier
RandomCoordinateDoubleSupplier

World Bounds

public interface IWorldBounds {
    int getMinX();
    int getMaxX();
    int getMinZ();
    int getMaxZ();
}

public interface IChunkBounds {
    int getMinChunkX();
    int getMaxChunkX();
    int getMinChunkZ();
    int getMaxChunkZ();
}

Caching

World generation uses extensive caching:

public class ChunkGeneratorCache {
    // Cache zone/biome results
    // Cache heights
    // Cache interpolated values
}

public class CaveGeneratorCache {
    // Cache cave data
}

public class PrefabLoadingCache {
    // Cache loaded prefabs
}

Configuration Files

World.json

Main world generation configuration:

{
  "Zones": "zones/",
  "DefaultZone": "Plains",
  "SeaLevel": 64,
  "WorldHeight": 256,
  "Caves": {
    "Enabled": true,
    "Types": ["Standard", "Cavern"]
  }
}

Zone Configuration

Each zone has its own configuration:

• Directoryworldgen/

  • World.json
  • Directoryzones/

    • DirectoryPlains/

      • zone.json
      • Directorybiomes/

        • Grassland.json
        • Forest.json
    • DirectoryMountains/

      • zone.json
      • Directorybiomes/

        • Alpine.json
  • Directoryprefabs/

    • Directoryvillage/

      • …
    • Directorydungeons/

      • …

Custom World Generation

Implementing IWorldGenProvider

public class MyWorldGenProvider implements IWorldGenProvider {
    public static final BuilderCodec<MyWorldGenProvider> CODEC =
        BuilderCodec.builder(MyWorldGenProvider.class, MyWorldGenProvider::new)
            // Add configuration fields
            .build();

    @Override
    public IWorldGen getGenerator() throws WorldGenLoadException {
        return new MyChunkGenerator();
    }
}

Registering Provider

@Override
protected void setup() {
    IWorldGenProvider.CODEC.register(
        Priority.DEFAULT,
        "MyPlugin_WorldGen",
        MyWorldGenProvider.class,
        MyWorldGenProvider.CODEC
    );
}

Timings and Metrics

public class WorldGenTimingsCollector {
    // Collect generation timings
}

// ChunkGenerator implements MetricProvider
public interface MetricProvider {
    MetricResults getMetrics();
}

Best Practices

1. Use caching: Leverage built-in caches for performance
2. Async generation: Use thread pool for heavy operations
3. Seed consistency: Ensure deterministic generation from seed
4. Validate output: Use ValidatableWorldGen interface
5. Profile performance: Use benchmarking tools
6. Modular design: Separate zones, biomes, and populators

Related

• World System - World management
• Block System - Block types
• Asset System - Prefab assets