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
Procedural generator: com.hypixel.hytale.builtin.hytalegenerator
WorldGen modifiers: com.hypixel.hytale.builtin.worldgen.modifier

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);
}

Staged Chunk Generator (Engine)

The StagedChunkGenerator at com.hypixel.hytale.builtin.hytalegenerator.engine.chunkgenerator manages chunk generation through a pipeline of Stage implementations:

Stage	Description
`BiomeStage`	Determines biome at each position
`BiomeDistanceStage`	Calculates distance to biome edges
`TerrainStage`	Generates terrain density and block placement
`PropStage`	Places props and decorations
`EnvironmentStage`	Applies environment settings
`TintStage`	Applies block tinting

Each stage implements Stage with run(Context), getInputTypesAndBounds_bufferGrid(), getOutputTypes(), and getName().

Generation Pipeline

Zone Generation: Determine zone at position
Biome Generation: Determine biome within zone
Heightmap: Generate terrain height
Block Placement: Place blocks based on layers
Cave Carving: Carve caves and caverns
Prefab Placement: Place structures
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

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

Props are decorative elements placed during world generation.

Prop API (v4)

public abstract class Prop {
    public abstract boolean generate(Prop.Context context);
    public abstract Bounds3i getReadBounds_voxelGrid();
    public abstract Bounds3i getWriteBounds_voxelGrid();

    public static class Context {
        public Vector3i position;
        public VoxelSpace<Material> materialReadSpace;
        public VoxelSpace<Material> materialWriteSpace;
        public EntityFunnel entityWriteBuffer;
        public double distanceToBiomeEdge;
    }
}

New Prop Types

Prop	Description
`CuboidProp`	Cuboid generation
`DensityProp`	Density-based block placement (rewritten in v4)
`DensitySelectorProp`	Density-based prop selection
`EmptyProp`	No-op singleton (`EmptyProp.INSTANCE`)
`LocatorProp`	Locator-based placement
`ManualProp`	Manual block placement
`MaskProp`	Masking support
`OffsetProp`	Position offset applied to child prop
`OrienterProp`	Orientation handling
`PrefabProp`	Prefab structure placement
`PondFillerProp`	Pond filling
`QueueProp`	Queued prop execution
`StaticRotatorProp`	Static rotation
`UnionProp`	Union of multiple props
`WeightedProp`	Weight-based random selection

WeightedProp

Selects a child prop randomly based on weight probability:

public class WeightedProp extends Prop {
    private final WeightedMap<Prop> props;
}

Configuration:

{
  "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 extends Prop {
    private final Vector3i offset;
    private final Prop childProp;
}

Configuration:

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

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

Use Cases:

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

SimpleHorizontalPositionProvider

Provides horizontal positions for prop placement:

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

Configuration:

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

Scanners

Scanners find valid positions for prop placement within a region.

public abstract class Scanner {
    @Deprecated
    public abstract void scan(Scanner.Context context);

    public abstract void scan(Vector3i position, Pipe.One<Vector3i> pipe);

    public abstract Bounds3i getBounds_voxelGrid();

    public Bounds3i getBoundsWithPattern_voxelGrid(Pattern pattern);
}

Scanner	Description
`DirectScanner`	Direct position scanning (replaces `OriginScanner`)
`EmptyScanner`	No-op singleton
`LinearScanner`	Linear scanning pattern
`QueueScanner`	Queue-based scanning
`RadialScanner`	Radial scanning pattern
`RandomScanner`	Random position scanning

Position Providers

Position providers generate candidate positions for prop distribution.

public abstract class PositionProvider {
    public abstract void generate(PositionProvider.Context context);

    public static class Context {
        public Bounds3d bounds;
        public Pipe.One<Vector3d> pipe;
        public Vector3d anchor;
    }
}

Pipe System

public class Pipe {
    @FunctionalInterface
    public interface One<Input> {
        void accept(Input input, Control control);
    }

    @FunctionalInterface
    public interface Two<InputA, InputB> {
        void accept(InputA a, InputB b, Control control);
    }
}

public class Control {
    public boolean stop = false;
    public void reset();
}

Setting control.stop = true within a pipe callback signals the caller to stop iterating, allowing early termination of position or prop generation.

Prop Distribution System

Prop distributions manage how props are selected and positioned within biomes.

Distribution	Description
`AssignedPropDistribution`	Distribution with prop assignments
`ConstantPropDistribution`	Constant prop distribution
`NoPropDistribution`	No-op distribution
`PositionsPropDistribution`	Position-based distribution
`UnionPropDistribution`	Union of multiple distributions

VoxelSpace

public interface VoxelSpace<T> {
    void set(T value, int x, int y, int z);
    void set(T value, Vector3i pos);
    void setAll(T value);
    T get(int x, int y, int z);
    T get(Vector3i pos);
    Bounds3i getBounds();
}

Implementation	Description
`ArrayVoxelSpace`	Array-backed storage
`MaskVoxelSpace`	Boolean mask (replaces `BooleanVoxelSpace`)
`NullSpace`	Null-pattern implementation
`RotationVoxelSpace`	Rotation-aware access
`WindowVoxelSpace`	Windowed view into another space

RNG System

The RNG system at com.hypixel.hytale.builtin.hytalegenerator.rng provides deterministic random number generation for world generation.

Class	Description
`Rng`	Static utility with `getRandomInt(seed, key)`, `mix(seed, a, b)`, `splitMixLong(n)`
`RngField`	Position-seeded RNG field with `get(x, y, z)` and `get(x, y)`
`SeedBox`	Seed container (relocated from `seed/`)

Patterns

WorldGen Modifier System

Modifiers target specific world-gen configurations and apply operations (add/remove) to biome and cave content lists. This allows plugins to inject or remove biome covers, layers, prefabs, tints, cave types, and more.

WorldGenModifier Asset

public class WorldGenModifier {
    protected String id;
    protected EventPriority priority;
    protected Target target;
    protected Map<EventType, Op[]> content;
}

Field	Type	Description
`Priority`	`EventPriority`	Order relative to other modifiers
`Target`	`Target`	Which world-gen configuration to modify
`Content`	`Map<EventType, Op[]>`	Operations to apply per event type

Target

public class Target {
    private String root = "Default";
    private String[] rules;
}

Root: the world-gen root configuration folder name to target
Rules: glob patterns to match asset file paths within the root

Event Types

Event Type	Description
`Biome_Covers`	Surface cover blocks
`Biome_Environments`	Environment settings
`Biome_Fluids`	Fluid configurations
`Biome_Dynamic_Layers`	Dynamic block layers
`Biome_Static_Layers`	Static block layers
`Biome_Prefabs`	Structure placement
`Biome_Tints`	Block tinting
`Cave_Types`	Cave type definitions
`Cave_Covers`	Cave surface covers
`Cave_Prefabs`	Cave structure placement

Operations

Two built-in operations are available:

Add: adds content to the target list via a Content reference (file path or inline JSON)
Remove: removes entries matching glob Rules. Supports "*" to clear all entries. Glob matching is implemented for prefab paths and cave type names.

Example Configuration

{
  "Priority": "NORMAL",
  "Target": {
    "Root": "Default",
    "Rules": ["Biomes/Plains/*"]
  },
  "Content": {
    "Biome_Prefabs": [
      {
        "Operation": "Add",
        "Content": {
          "Type": "File",
          "Path": "MyPlugin.Prefabs.CustomTree"
        }
      }
    ]
  }
}

Event Handling

The EventHandler is scoped per thread and acquired for a root configuration path. It collects all matching modifiers, sorts them by priority and asset pack order, and dispatches operations against ModifyEvent instances during asset loading.

Entity Funnel

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

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

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

World Generation Overview

World Generation Overview

Package Location

Architecture

World Gen Providers

IWorldGenProvider Interface

HytaleWorldGenProvider

World Config Usage

Built-in Providers

ChunkGenerator

Staged Chunk Generator (Engine)

Generation Pipeline

Zones

Zone Record

Zone Configuration

Zone Pattern Provider

Biomes

Biome Class

Biome Containers

Layer Container

Cave Generation

CaveGenerator

Cave Configuration

Prefabs

PrefabContainer

Prefab Configuration

Unique Prefabs

Props

Prop API (v4)

New Prop Types

WeightedProp

OffsetProp

SimpleHorizontalPositionProvider

Scanners

Position Providers

Pipe System

Prop Distribution System

VoxelSpace

RNG System

Patterns

WorldGen Modifier System

WorldGenModifier Asset

Target

Event Types

Operations

Example Configuration

Event Handling

Entity Funnel

Populators

Built-in Populators

Populator Interface

Generated Chunk

Noise Functions

NoiseProperty

Height Threshold Interpreter

Procedural Library

Conditions

Property Suppliers

World Bounds

Caching

Configuration Files

World.json

Zone Configuration

Custom World Generation

Implementing IWorldGenProvider

Registering Provider

Timings and Metrics

Best Practices

Related