Skip to content

WORLD_JSON.md

Latest commit

 

History

History
106 lines (82 loc) · 2.78 KB

WORLD_JSON.md

File metadata and controls

106 lines (82 loc) · 2.78 KB
Raw

World.json (V1 Configuration)

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

World.json is the root configuration file for V1 (legacy) world generation. It defines the world dimensions, zone mask, and data overrides. Located at the root of a world generation data folder, it is loaded by ChunkGeneratorJsonLoader.

Fields

Field Type Required Default Description
Width int Yes — World width in chunks
Height int Yes — World height in chunks
OffsetX int Yes — World X offset position
OffsetY int Yes — World Y offset position
Masks string | string[] | object No "Mask.png" Zone mask image(s)
Randomizer object No — Random seed configuration
PrefabStore string No "DEFAULT" Which prefab store to use
OverrideDataFolder string No — Path to override data folder

Masks

The Masks field supports three formats:

Single string:

{ "Masks": "Mask.png" }

Array of strings (randomly selected):

{ "Masks": ["Mask1.png", "Mask2.png", "Mask3.png"] }

Weighted object (weighted random selection):

{
  "Masks": {
    "Mask.png": 1.0,
    "AlternateMask.png": 0.5
  }
}

Masks are PNG images where pixel colors map to zones via Zones.json color mappings. If the field is empty or missing, it defaults to "Mask.png".

OverrideDataFolder

When specified, the generator loads assets from this override folder in addition to the base data. The path must exist within the parent directory of the world data folder. This enables per-world customization without modifying the base generator files.

Loading Pipeline

graph TD
    A[World.json] --> B[loadWorldSize]
    A --> C[loadWorldOffset]
    A --> D[loadMaskProvider]
    A --> E[loadOverrideDataFolder]
    A --> F[loadPrefabStore]
    B --> G[Open FileIOSystem]
    E --> G
    G --> H[loadZonePatternGenerator]
    H --> I[ZonesJsonLoader]
    I --> J[Load each Zone.json]
    J --> K[Create ChunkGenerator]
Loading
  1. Read World.json
  2. Load override folder if specified
  3. Open FileIOSystem for asset resolution
  4. Load world size and offset
  5. Load and select mask provider (random selection from weighted options)
  6. Load zone pattern generator from Zones.json
  7. Load zones via ZonesJsonLoader
  8. Initialize zone pattern system
  9. Create ChunkGenerator

Example

{
  "Width": 64,
  "Height": 64,
  "OffsetX": 0,
  "OffsetY": 0,
  "Masks": {
    "Overworld.png": 1.0,
    "Overworld_Alt.png": 0.3
  },
  "PrefabStore": "DEFAULT",
  "OverrideDataFolder": "CustomData"
}

Source files: ChunkGeneratorJsonLoader.java