hytale-world-gen

name: hytale-world-gen description: Documents Hytale's procedural world generation systems for plugin development. Covers the Java API (Zones, Biomes, Caves) and the data-driven node/JSON system (Density, Curves, Patterns, Material Providers, Props, Scanners, Positions, Assignments, Directionality, Vector Providers, Block Masks). Use when creating custom zones, biomes, caves, terrain, world generation features, density fields, asset packs, or working with the Hytale Node Editor. Triggers - world gen, world generation, zone, biome, cave, ZonePatternGenerator, BiomePatternGenerator, CaveGenerator, CaveType, Zone, CustomBiome, TileBiome, ZoneDiscoveryConfig, ZoneGeneratorResult, CaveBiomeMaskFlags, terrain, procedural generation, border transition, biome mask, density, noise, simplex, curves, patterns, material provider, props, prefab, scanner, positions, assignments, directionality, vector provider, block mask, asset pack, HytaleGenerator, node editor.

Hytale World Generation System

Comprehensive reference for Hytale's procedural world generation systems used to create environments, biomes, and structures dynamically as players explore the world.

Related skills: For ECS fundamentals, see hytale-ecs. For persistent data/Codec patterns, see hytale-persistent-data. For entity effects, see hytale-entity-effects.

Quick Reference

Overview

Hytale's world generation is organized into three interconnected systems:

World Generation
├── Zones       — Large-scale regions defining overall world structure
├── Biomes      — Terrain characteristics and environment within zones
└── Caves       — Underground structures and networks within zones

These systems are hierarchical: Zones contain Biomes, and both Zones and Biomes influence Cave generation. They work together to produce smooth transitions and coherent regional themes.

Zones

Zones are the largest-scale division in world generation. Each zone defines its own biome patterns, cave configurations, and unique structures (prefabs).

Zone Lookup and Generation

// Get zone at a world position
ZonePatternGenerator zoneGen = /* from world generator */;
ZoneGeneratorResult zoneResult = zoneGen.generate(seed, x, z);
Zone zone = zoneResult.getZone();

ZoneGeneratorResult

The result object provides:

Zone Class

A Zone encapsulates all generation data for a region:

Creating a Custom Zone

// 1. Configure zone discovery (player notification on entry)
ZoneDiscoveryConfig discovery = new ZoneDiscoveryConfig(
    true,                           // Show notification
    "Custom Zone",                  // Display name
    "zone.forest.discover",         // Sound event
    "icons/forest.png",             // Icon
    true,                           // Major zone
    5.0f, 2.0f, 1.5f               // Duration, fade in, fade out
);

// 2. Create biome pattern
IPointGenerator biomePoints;
IWeightedMap<TileBiome> tileBiomes;
CustomBiome[] customBiomes;

BiomePatternGenerator biomeGen = new BiomePatternGenerator(
    biomePoints,
    tileBiomes,
    customBiomes
);

// 3. Create cave configuration
CaveType[] caveTypes; // cave definitions
CaveGenerator caveGen = new CaveGenerator(caveTypes);

// 4. Assemble the zone
Zone customZone = new Zone(
    100,                    // Unique ID
    "new_custom_zone",      // Internal name
    discovery,              // Discovery config
    caveGen,                // Cave generator
    biomeGen,               // Biome pattern
    uniquePrefabs           // Unique structures
);

ZoneDiscoveryConfig

Controls what the player sees when entering a zone:

Biomes

Biomes define terrain characteristics, vegetation, and environmental properties within a zone. Each zone has its own BiomePatternGenerator that determines biome layout.

Biome Lookup

// Get the biome at a specific position within a zone
Zone zone = zoneResult.getZone();
BiomePatternGenerator biomeGen = zone.biomePatternGenerator();
Biome biome = biomeGen.generateBiomeAt(zoneResult, seed, x, z);

BiomePatternGenerator

Constructs the biome layout from three inputs:

Biome Properties

Each Biome has at minimum:

CustomBiome Fading

Custom biomes support smooth transitions near zone borders via a fade container:

CustomBiome customBiome = /* ... */;
FadeContainer fade = customBiome.getFadeContainer();
double maskFadeSum = fade.getMaskFadeSum();
double factor = fade.getMaskFactor(zoneResult);

Caves

Caves are underground structures generated within zones. Each zone optionally has a CaveGenerator with one or more CaveType definitions.

Cave Lookup

Zone zone = /* ... */;
CaveGenerator caveGen = zone.caveGenerator();
if (caveGen != null) {
    // This zone has caves
    CaveType[] types = caveGen.getCaveTypes();
}

CaveType and Biome Masks

Cave types use biome masks to control where caves can generate:

// Cave type with biome restrictions
Int2FlagsCondition biomeMask = caveType.getBiomeMask();
int biomeId = biome.getId();
int flags = biomeMask.eval(biomeId);

// Check if cave can generate in this biome
if (CaveBiomeMaskFlags.canGenerate(flags)) {
    // Generate cave
}

System Integration

Zone → Biome Integration

Each zone defines its own biome pattern. The biome generator requires the zone result (for border distance and zone context):

Zone zone = zoneGen.generate(seed, x, z).getZone();
BiomePatternGenerator biomeGen = zone.biomePatternGenerator();
Biome biome = biomeGen.generateBiomeAt(zoneResult, seed, x, z);

Zone → Cave Integration

Each zone defines its own cave patterns. Not all zones have caves:

Zone zone = /* ... */;
CaveGenerator caveGen = zone.caveGenerator();
if (caveGen != null) {
    CaveType[] types = caveGen.getCaveTypes();
}

Biome → Cave Integration

Caves use biome masks to restrict generation to specific biomes:

Int2FlagsCondition biomeMask = caveType.getBiomeMask();
int biomeId = biome.getId();
int flags = biomeMask.eval(biomeId);

if (CaveBiomeMaskFlags.canGenerate(flags)) {
    // Cave can generate in this biome
}

Border Transitions

All systems respect zone boundaries. Custom biomes fade near borders for smooth transitions:

ZoneGeneratorResult result = zoneGen.generate(seed, x, z);
double borderDistance = result.getBorderDistance();

// Fade custom biomes near borders
if (borderDistance < customBiome.getFadeContainer().getMaskFadeSum()) {
    double factor = customBiome.getFadeContainer().getMaskFactor(result);
    // Apply fading based on factor (0.0 = fully faded, 1.0 = full strength)
}

Key Classes Summary

Common Patterns

Full World Position → Zone + Biome + Cave Pipeline

// Complete lookup pipeline
ZonePatternGenerator zoneGen = /* from world generator */;
long seed = /* world seed */;
int x = /* world x */;
int z = /* world z */;

// 1. Determine zone
ZoneGeneratorResult zoneResult = zoneGen.generate(seed, x, z);
Zone zone = zoneResult.getZone();

// 2. Determine biome within zone
BiomePatternGenerator biomeGen = zone.biomePatternGenerator();
Biome biome = biomeGen.generateBiomeAt(zoneResult, seed, x, z);

// 3. Check for caves
CaveGenerator caveGen = zone.caveGenerator();
if (caveGen != null) {
    for (CaveType caveType : caveGen.getCaveTypes()) {
        Int2FlagsCondition biomeMask = caveType.getBiomeMask();
        int flags = biomeMask.eval(biome.getId());
        if (CaveBiomeMaskFlags.canGenerate(flags)) {
            // This cave type can generate here
        }
    }
}

// 4. Handle border transitions
double borderDistance = zoneResult.getBorderDistance();
// Use borderDistance for custom blending/fading logic

Zone Entry Notification Setup

// Minimal zone discovery config
ZoneDiscoveryConfig discovery = new ZoneDiscoveryConfig(
    true,                    // Show notification
    "Enchanted Forest",      // Display name
    "zone.forest.discover",  // Sound event
    "icons/forest.png",      // Icon
    true,                    // Major zone
    5.0f, 2.0f, 1.5f        // Duration, fade in, fade out
);

Data-Driven World Generation (Node/JSON System)

Beyond the Java plugin API, Hytale's world generation is primarily data-driven through JSON asset files and an in-game Node Editor. Biomes, terrain shapes, materials, and content placement are all defined declaratively.

Detailed references for every node type are in the references/ subdirectory of this skill. Source: hytalemodding.dev — World Generation System Source: HytaleModding/site — Official World Generation Documentation

Asset Directory Structure

World generation assets are located in the Server/HytaleGenerator/ directory within your asset pack.

Server/HytaleGenerator/
├── WorldStructure/    # Generator files defining which biomes spawn together
├── Biomes/            # Biome assets with content configurations
├── Density/           # Reusable density assets referenced by other generation assets
└── Assignments/       # Reusable prop assignment assets referenced by biomes

World Instance Configuration

To test your world generation, you need to create an Instance that uses your generator. Instances are separate worlds players can join via /instances. The instance configuration is a .bson file in Server/Instances/.

{
  "WorldGen": {
    "Type": "HytaleGenerator",
    "WorldStructure": "Basic", // Change to your WorldStructure asset name
    "playerSpawn": {
      "X": 123, "Y": 480, "Z": 10000,
      "Pitch": 0, "Yaw": 0, "Roll": 0
    }
  }
}

Instance configs are stored at Server/Instances/. Create custom instances by duplicating the basic config and changing WorldStructure to your asset name.

Previewing World Generation

Biome Asset Structure

Every biome has 5 root components:

Each biome is self-contained — it controls everything within its boundaries except Base Heights.

Node System Overview

World generation uses a node-based system of composable JSON assets. Each node type has parameters and inputs:

Core Concept: Density Fields

Terrain generation is built on density fields — maps of decimal values (typically -1 to 1) defining terrain shape:

• Positive values → solid terrain
• Negative values → empty space (air)
• Density is calculated from the sum of all nodes: f(x) = z + y

Common terrain formula: Simplex 2D noise + Y-Curve (height gradient) = basic terrain shape.

Function nodes manipulate density fields: Absolute (ridged shapes), Normalization (rescaling range), Scale (stretch/contract), Rotator (orientation), Warp (distortion), and many more.

Core Concept: Props Pipeline

Props place procedural content (trees, prefabs, grass) using three connected systems:

Positions → Scanner → Pattern → Prop Placement

1. Positions provide candidate locations (e.g., Mesh2D grid, BaseHeight offsets)
2. Scanner searches around each position (e.g., ColumnLinear scans Y range)
3. Pattern validates positions (e.g., Floor pattern checks for solid ground below)
4. Prop places content at validated positions (e.g., Prefab with Directionality)

Asset Packs

Asset Packs override or add assets to the base game. Required for world gen customization:

{
  "Group": "My Group",
  "Name": "Pack Example",
  "Version": "1.0.0",
  "Description": "An Example Asset Pack",
  "Authors": [{"Name": "Me", "Email": "", "Url": ""}],
  "Dependencies": {},
  "DisabledByDefault": false,
  "IncludesAssetPack": false,
  "SubPlugins": []
}

• Stored in C:\Users\<user>\AppData\Roaming\Hytale\UserData\Mods
• Per-world packs stored in UserData\Saves\<world>\mods
• Asset Packs exist entirely on the server — only the host needs them
• Assets inside packs override base game assets

Import/Export System

Most node types support Imported and Exported nodes for reusability:

• Exported: Makes a node tree available by name, with optional SingleInstance for shared caching
• Imported: References an exported asset by name
• This enables modular, reusable density fields, curves, patterns, etc.

Notes

• The worldgen module is a built-in Hytale module. Plugins interact with it through the public API classes listed above.
• Zone IDs must be unique across the world generation configuration.
• CaveGenerator is nullable — not all zones have caves.
• Biome masks use a flags-based system (Int2FlagsCondition) for efficient cave-biome filtering.
• Border transitions use FadeContainer with getMaskFadeSum() and getMaskFactor() for smooth blending between zones.
• The --validate-world-gen server launch flag can be used to validate world generation assets.
• World gen examples can be found in HytaleGenerator/Biomes/Examples/.
• The Hytale Node Editor is accessible in-game from the Content Creation menu (Tab key).
• Performance tip: In Multiplier nodes, order inputs with cheapest mask first — the node skips remaining inputs after a 0 value.
• Performance tip: Use Cache/Cache2D nodes on expensive density lookups that are queried multiple times.

Source: hytalemodding.dev — World Generation System Source: HytaleModding/site — Official World Generation Documentation