Skip to content

WORLDGEN_OVERVIEW.md

Latest commit

 

History

History
258 lines (199 loc) · 10.4 KB

WORLDGEN_OVERVIEW.md

File metadata and controls

258 lines (199 loc) · 10.4 KB
Raw

World Generation Overview

Source: Decompiled from HytaleServer.jar (pre-release 2026.02.05-9ce2783f7)

Hytale's world generation system is a massive, modular framework with 170+ registered asset types across 380+ source files. It supports two parallel generation pipelines: a V1 legacy zone-based system and a V2 asset-driven system built around density functions, material providers, and props.

Two-System Architecture

Hytale runs two world generation systems simultaneously:

System Entry Point Configuration Status
V1 (Legacy) ChunkGeneratorJsonLoader World.json + Zones.json + zone folders Active — handles zones, masks, caves, prefabs
V2 (Asset-Based) AssetManager HytaleGenerator/ subdirectories Active — handles biomes, density, materials, props

Both systems coexist: V1 provides the zone/mask infrastructure and cave generation, while V2 provides the modern biome and terrain generation via JSON-configured asset graphs.

V2 Asset Pipeline

The V2 system loads assets from structured subdirectories under HytaleGenerator/:

HytaleGenerator/
├── Biomes/              → BiomeAsset[]
├── WorldStructures/     → WorldStructureAsset[]
├── Density/             → DensityAsset[]
├── MaterialMasks/       → BlockMaskAsset[]
├── Assignments/         → AssignmentsAsset[]
└── Settings/            → SettingsAsset[]

Each asset store is registered in AssetManager.java with:

  • A path for file discovery
  • A key function for ID lookup
  • A CODEC for JSON deserialization

Polymorphic Type System

All V2 assets use a polymorphic type dispatch pattern. Each JSON asset file contains a "Type" field that selects the concrete implementation:

{
  "Type": "SimplexNoise2D",
  "Seed": "terrain_noise",
  "Frequency": 0.01,
  "Amplitude": 1.0
}

The AssetManager static initializer registers all type strings to their Java classes:

DensityAsset.CODEC.register("SimplexNoise2D", SimplexNoise2dDensityAsset.class, ...);
DensityAsset.CODEC.register("Constant", ConstantDensityAsset.class, ...);
// ... 68 density types total

This pattern is used across all asset categories (density, materials, props, curves, patterns, etc.).

V1 Pipeline: Zone Loading

graph TD
    A[WorldGenPlugin] --> B[HytaleWorldGenProvider]
    B --> C[ChunkGeneratorJsonLoader]
    C --> D[Load World.json]
    D --> E[Load Masks]
    D --> F[Load PrefabStore]
    D --> G[Load Zones.json]
    G --> H[ZonePatternProviderJsonLoader]
    H --> I[ZonesJsonLoader]
    I --> J["Zone[] array"]
    J --> K[ChunkGenerator]
Loading

WorldGenPlugin bootstraps the system:

  1. Validates version-specific world generation packs
  2. Registers HytaleWorldGenProvider as the default provider

HytaleWorldGenProvider provides codec-based configuration:

  • Name — generator identifier
  • Version — semantic version string
  • Path — data folder path

ChunkGeneratorJsonLoader loads V1 configuration:

  1. Reads World.json (size, offset, masks, prefab store)
  2. Opens a FileIOSystem with AssetFileSystem for layered resolution
  3. Loads Zones.json → zone pattern generator
  4. Loads individual zones with biome/cave generators
  5. Constructs the final ChunkGenerator

V2 Pipeline: Chunk Generation

graph TD
    CG[ChunkGenerator] -->|"async, thread pool"| CGE[ChunkGeneratorExecution]
    CGE --> BP[BlockPopulator]
    CGE --> CP[CavePopulator]
    CGE --> PP[PrefabPopulator]
    CGE --> WP[WaterPopulator]

    BP --> HTI[HeightThresholdInterpolator]
    HTI --> ZBR[ZoneBiomeResult]
    ZBR --> B[Biome]
    B --> TD[TerrainDensity]
    B --> MP[MaterialProvider]
    B --> PF[PropFields]
    B --> EP[EnvironmentProvider]
    B --> TP[TintProvider]
Loading

ChunkGenerator is the runtime orchestrator:

  • Dispatches chunk generation to a thread pool (75% of available CPU cores)
  • Maintains caches for zone/biome results, cave data, and unique prefabs
  • Generates chunks asynchronously via CompletableFuture

ChunkGeneratorExecution runs the per-chunk pipeline in order:

  1. Tint mapping — averages tint colors in a radius-4 neighborhood
  2. Environment mapping — assigns environment IDs per column
  3. BlockPopulator.populate() — places terrain blocks using density + materials
  4. CavePopulator.populate() — carves caves
  5. PrefabPopulator.populate() — places structure prefabs
  6. WaterPopulator.populate() — fills water/fluid

World Height

The world height is 0–319 (320 blocks), as seen in the block placement bounds checks.

Threading & Caching

Thread Pool

int poolSize = Math.max(1, (int)(Runtime.getRuntime().availableProcessors() * 0.75));

The chunk generator uses 75% of available CPU cores for parallel chunk generation. Each thread gets its own ChunkGeneratorResource via ThreadLocal.

Caching Strategy

Cache Purpose Implementation
Generator Cache Zone/biome results, height noise CoreDataCacheEntry with interpolated biome counts
Cave Generator Cache Cave generation results Per-chunk cave data
Unique Prefab Cache One-off structure positions Seed-based prefab entries
Prefab Loading Cache Loaded prefab templates ConcurrentHashMap-based

Asset Type Registry (Complete)

All types registered in AssetManager.java (lines 354–597):

Top-Level Asset Stores

Asset Store Class Path Count
Biomes BiomeAsset HytaleGenerator/Biomes —
World Structures WorldStructureAsset HytaleGenerator/WorldStructures 1 type
Density Functions DensityAsset HytaleGenerator/Density 68 types
Block Masks BlockMaskAsset HytaleGenerator/MaterialMasks —
Assignments AssignmentsAsset HytaleGenerator/Assignments 5 types
Settings SettingsAsset HytaleGenerator/Settings —

Polymorphic Type Registrations

Category Types Doc
Density Functions 68 Computational graph nodes
Curves 19 Value mapping functions
Patterns 15 Block placement conditions
Material Providers 14 Block material selection
Position Providers 14 Coordinate generation
Props 11 Object/structure placement
Return Types 10 Cell noise return modes
SpaceAndDepth Conditions 7 Layer condition logic
Scanners 5 Position scanning strategies
Assignments 5 Prop distribution configs
Vector Providers 5 3D vector generation
SpaceAndDepth Layers 4 Thickness definitions
Directionality 4 Prop rotation modes
Environment Providers 2 Biome environment selection
Tint Providers 2 Biome color tinting
Terrain 1 Terrain density wrapper
Framework 2 Shared constants/positions
World Structure 1 Root biome layout
Noise 2 Noise algorithm configs
Distance Functions 2 Distance metric selection
Point Generators 1 Grid point generation

Total: 170+ registered types

Key Java Packages

Package Purpose
com.hypixel.hytale.builtin.worldgen Plugin bootstrap (WorldGenPlugin)
com.hypixel.hytale.server.worldgen Provider, config, caching
com.hypixel.hytale.server.worldgen.chunk ChunkGenerator, ChunkGeneratorExecution, populators
com.hypixel.hytale.server.worldgen.loader V1 JSON loading pipeline
com.hypixel.hytale.server.worldgen.zone Zone system
com.hypixel.hytale.builtin.hytalegenerator V2 asset system root
com.hypixel.hytale.builtin.hytalegenerator.assets All asset definitions
com.hypixel.hytale.builtin.hytalegenerator.assets.density 68 density function assets
com.hypixel.hytale.builtin.hytalegenerator.density Runtime density nodes
com.hypixel.hytale.builtin.hytalegenerator.biome Biome interface, SimpleBiome
com.hypixel.hytale.builtin.hytalegenerator.materialproviders Material provider runtime
com.hypixel.hytale.builtin.hytalegenerator.cartas SimpleNoiseCarta biome mapping
com.hypixel.hytale.builtin.hytalegenerator.worldstructure WorldStructure runtime
com.hypixel.hytale.procedurallib.file FileIO, FileIOSystem

Documentation Index

Core Systems

Supporting Systems

Configuration

V1 Legacy

Infrastructure

Source files: WorldGenPlugin.java, HytaleWorldGenProvider.java, ChunkGenerator.java, ChunkGeneratorExecution.java, AssetManager.java, ChunkGeneratorJsonLoader.java