Skip to content

ZONES_V1.md

Latest commit

 

History

History
148 lines (105 loc) · 4.59 KB

ZONES_V1.md

File metadata and controls

148 lines (105 loc) · 4.59 KB
Raw

Zones (V1 Legacy System)

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

Zones are the V1 (legacy) biome-grouping system. Each zone represents a distinct region of the world (e.g., "Lush Lands", "Desert") and contains its own tile biomes, custom biomes, cave generators, and discovery configuration. Zones are placed on the world map via color-coded mask images.

Zone Structure

Each zone is defined in Zones/<ZoneName>/Zone.json and loaded by ZoneJsonLoader.

Zone Record

Field Type Description
id int Auto-incrementing zone ID
name String Zone name (directory name)
discoveryConfig ZoneDiscoveryConfig UI/audio discovery settings
caveGenerator CaveGenerator Cave generation (nullable)
biomePatternGenerator BiomePatternGenerator Biome placement strategy
uniquePrefabContainer UniquePrefabContainer Unique structure placement

Zone.json Structure

{
  "Discovery": {
    "Display": true,
    "ZoneName": "Emerald Grove",
    "Major": true
  },
  "BiomeGenerator": { },
  "UniquePrefabs": { }
}

Discovery Config

Controls the zone discovery UI when a player enters a new zone.

Field Type Required Default Description
Display boolean No false Show zone discovery UI
ZoneName string No "Void" Display name for the zone
SoundEventId string No — Sound effect ID for discovery
Icon string No — Icon asset path
Major boolean No true Whether zone is a major region
Duration float No 4.0 Discovery animation duration (seconds)
FadeInDuration float No 1.5 Fade-in time (seconds)
FadeOutDuration float No 1.5 Fade-out time (seconds)

Tile Biomes

Each zone contains tile biomes loaded from Zones/<ZoneName>/Tile.<BiomeName>.json. Tile biomes are collected into a WeightedMap<TileBiome> — the zone must have at least one tile biome.

Cave Generator

Caves are optional per-zone. If Zones/<ZoneName>/Cave/Caves.json exists, it is loaded.

Caves.json

Field Type Description
Types CaveType[] Array of cave type definitions

Each cave type defines a distinct cave generation style within the zone.

Zone Pattern System

Zone placement on the world map is controlled by Zones.json at the world data root.

Zones.json Fields

Field Type Required Description
GridGenerator object Yes Point generator for zone center placement
MaskMapping object Yes RGB color to zone name mapping
UniqueZones object No Unique zone placement rules

Color Mapping

Each pixel color in the mask image maps to a zone. The loader validates that every color present in the mask has a corresponding zone mapping — unmapped colors cause an error.

Unique Zones

Special zones that need specific placement logic. Each unique zone entry contains:

Field Type Description
zone Zone Reference to the zone
color int RGB color from mask
parent int[] Parent colors this zone can attach to
radius int Placement radius
padding int Padding around placement

Zone File Context

Zones maintain registries for their biomes:

Registry Type Description
tileBiomes Registry<BiomeFileContext> Standard tile biomes
customBiomes Registry<BiomeFileContext> Custom biome overrides

File path format: Zones.<ZoneName>.<BiomeName> — e.g., Zones.LushLands.Forest

Directory Structure

WorldData/
├── World.json
├── Zones.json
├── Mask.png
└── Zones/
    ├── LushLands/
    │   ├── Zone.json
    │   ├── Tile.Forest.json
    │   ├── Tile.Plains.json
    │   └── Cave/
    │       └── Caves.json
    ├── Desert/
    │   ├── Zone.json
    │   ├── Tile.Dunes.json
    │   └── Cave/
    │       └── Caves.json
    └── Ocean/
        ├── Zone.json
        └── Tile.DeepOcean.json

Source files: Zone.java, ZoneDiscoveryConfig.java, ZoneJsonLoader.java, ZonesJsonLoader.java, ZonePatternProvider.java, ZonePatternProviderJsonLoader.java, ZoneFileContext.java, ZoneBiomesJsonLoader.java, CaveGeneratorJsonLoader.java