Skip to content

WORLD_STRUCTURE.md

Latest commit

 

History

History
188 lines (149 loc) · 5.86 KB

WORLD_STRUCTURE.md

File metadata and controls

188 lines (149 loc) · 5.86 KB

World Structure

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

The WorldStructureAsset is the root definition of a V2 world generation configuration. It defines which biomes exist, how they are selected based on noise, and how transitions between them work. There is currently one registered type: NoiseRange.

Type: NoiseRange

Class: BasicWorldStructureAsset Type String: "NoiseRange"

The NoiseRange world structure maps a density function's output to biome ranges, creating a noise-driven biome distribution system.

CODEC Fields

Field Type Required Default Description
Biomes BiomeRangeAsset[] Yes [] Array of biome-to-noise-range mappings
Density DensityAsset Yes Constant(0) Density function used for biome selection noise
DefaultBiome string Yes "" Asset ID of the fallback biome when no range matches
DefaultTransitionDistance int Yes 32 Distance (in blocks) for biome edge transitions. Must be > 0
MaxBiomeEdgeDistance int Yes 0 Maximum distance to track from biome edges. Must be >= 0
Framework FrameworkAsset[] No [] Shared constants/positions available to all child assets
SpawnPositions PositionProviderAsset No List() Position provider for world spawn point candidates

BiomeRangeAsset

Each entry in the Biomes array maps a biome to a noise value range:

Field Type Required Default Description
Biome string Yes "" Reference to a BiomeAsset by ID
Min double Yes -1.0 Minimum noise value (inclusive)
Max double Yes 1.0 Maximum noise value (inclusive)

JSON Example

{
  "Biomes": {
    "plains_range": {
      "Biome": "plains",
      "Min": -0.3,
      "Max": 0.3
    },
    "mountains_range": {
      "Biome": "mountains",
      "Min": 0.3,
      "Max": 1.0
    },
    "desert_range": {
      "Biome": "desert",
      "Min": -1.0,
      "Max": -0.3
    }
  }
}

Biome Selection: SimpleNoiseCarta

The NoiseRange structure uses SimpleNoiseCarta to map density values to biome IDs at runtime.

How It Works

  1. The Density function is evaluated at position (x, 0, z) — note Y is always 0 for biome selection
  2. The resulting noise value is looked up in a DoubleRangeMap
  3. If a matching range is found, the corresponding biome is returned
  4. If no range matches, the DefaultBiome is returned
// From SimpleNoiseCarta.apply()
Density.Context context = new Density.Context();
context.position = new Vector3d(x, 0.0, z);
double noiseValue = this.density.process(context);
T value = this.rangeMap.get(noiseValue);
return value == null ? this.defaultValue : value;

The biome selection is purely 2D (XZ plane), meaning biomes don't vary vertically — only terrain shape within a biome changes with Y.

Biome Transition Blending

The DefaultTransitionDistance controls how biome edges are smoothed:

  • A larger value creates smoother, more gradual transitions between biomes
  • A value of 1 creates hard biome boundaries (minimum allowed)
  • The default of 32 blocks provides moderate blending

The MaxBiomeEdgeDistance works with the DistanceToBiomeEdge density function type, allowing terrain features to react to proximity to biome boundaries.

Build Pipeline

graph TD
    A[BasicWorldStructureAsset.build] --> B[Build Framework references]
    B --> C[Resolve DefaultBiome asset]
    C --> D[Build default Biome]
    D --> E[Build Density function]
    E --> F[Create Registry + SimpleNoiseCarta]
    F --> G[For each BiomeRangeAsset]
    G --> H[Build Biome if not cached]
    H --> I[Register biome + add range to carta]
    I --> J[Create WorldStructure]
Loading

The build process:

  1. Framework assets are built first — these provide shared constants and position references (ReferenceBundle)
  2. The default biome is resolved and built (cached for reuse)
  3. The density function is built from its asset graph
  4. A biome registry is created, mapping integer IDs to Biome instances
  5. Each biome range is processed — biomes are built once and cached via a HashMap<BiomeAsset, Biome>
  6. The SimpleNoiseCarta is populated with DoubleRange → biomeId mappings
  7. A WorldStructure is returned containing the carta, registry, transition distance, and spawn positions

Complete JSON Example

{
  "Type": "NoiseRange",
  "DefaultBiome": "plains",
  "DefaultTransitionDistance": 48,
  "MaxBiomeEdgeDistance": 16,
  "Density": {
    "Type": "SimplexNoise2D",
    "Seed": "biome_selection",
    "Frequency": 0.002,
    "Amplitude": 1.0
  },
  "Biomes": {
    "forest_range": {
      "Biome": "forest",
      "Min": 0.2,
      "Max": 0.6
    },
    "mountains_range": {
      "Biome": "mountains",
      "Min": 0.6,
      "Max": 1.0
    },
    "swamp_range": {
      "Biome": "swamp",
      "Min": -0.6,
      "Max": -0.2
    },
    "tundra_range": {
      "Biome": "tundra",
      "Min": -1.0,
      "Max": -0.6
    }
  },
  "Framework": [],
  "SpawnPositions": {
    "Type": "List",
    "Positions": []
  }
}

Runtime Class: WorldStructure

The built WorldStructure holds:

Field Type Description
biomeMap BiCarta<Integer> Maps (x, z) → biome registry ID
biomeRegistry Registry<Biome> Maps integer IDs → Biome instances
biomeTransitionDistance int Edge blending distance
maxBiomeEdgeDistance int Max tracked edge distance
spawnPositions PositionProvider World spawn candidates

Source files: BasicWorldStructureAsset.java, WorldStructure.java, BiomeRangeAsset.java, SimpleNoiseCarta.java, DoubleRangeMap.java