Rens Roosloot

Voxel Generation Spec

Volledige gerenderde weergave van GENERATION_SPEC.md.

Laatst gesynchroniseerd: 13 april 2026

Generation Spec - Voxel Cutaway World Generator

Version: 0.2.0
Date: 2026-03-08
Author: Rens Roosloot / Codex collaboration

1. Purpose

This document defines the recommended world-generation rules for the first MVP.

The goal is not maximum simulation complexity. The goal is to consistently generate small, attractive, readable cutaway chunks.

2. Generation Philosophy

The generator should prioritize:

  • coherence over chaos
  • readability over density
  • consistent visual quality over extreme variation

The chunk should usually look believable on the first try.

3. Chunk Model

Recommended MVP model:

  • fixed width
  • fixed depth
  • fixed height
  • finite 3D voxel grid

Suggested design intent:

  • wide enough to show terrain shape
  • tall enough to expose underground structure
  • small enough for good mobile performance

4. Generation Pass Order

Recommended ordered passes:

  1. initialize empty voxel grid
  2. generate terrain height map
  3. assign top surface and subsurface layers
  4. fill water below waterline
  5. apply snow by elevation
  6. place trees
  7. carve caves
  8. place ores
  9. place lava
  10. validate and clean obvious broken states

5. Terrain Rules

5.1 Height map

  • use deterministic seeded noise
  • limit vertical variation to moderate hills
  • avoid extreme spikes and needle peaks

5.2 Surface shaping

  • topmost solid block becomes the surface type
  • default surface is grass or topsoil
  • local smoothing may be applied if needed to reduce ugly stair-step noise

6. Water Rules

  • define one fixed water level for the MVP
  • fill empty low areas up to the water level
  • water should appear as ponds, edges, or lowland fills
  • avoid isolated one-voxel water artifacts where practical

7. Snow Rules

  • define a snow threshold height
  • apply snow only above that threshold
  • snow should remain patchy or elevation-driven, not fully random
  • underwater and underground snow placement is not allowed

8. Tree Rules

  • trees spawn only on valid surface blocks
  • trees do not spawn underwater
  • trees do not spawn on snow unless intentionally allowed by tuning
  • trees require enough local clearance for trunk and canopy
  • tree density should stay modest

Recommended tree structure:

  • simple trunk
  • compact leaf canopy

9. Underground Layer Rules

9.1 Dirt

  • immediately below surface
  • thickness may vary slightly

9.2 Stone

  • dominant deeper material

9.3 Ores

  • ores appear inside stone regions only
  • ores should appear in small clusters
  • rarity should increase as depth decreases

10. Cave Rules

  • caves should be carved below the upper dirt-heavy region
  • cave density should remain moderate
  • caves should create visible side cutaway interest
  • caves should not remove most of the world volume
  • caves should not routinely disconnect the surface into thin islands

11. Lava Rules

  • lava appears only at deeper levels
  • lava is rare
  • lava may fill cave pockets or small underground pools
  • lava must not routinely dominate the cutaway view

12. Cleanup Rules

Recommended post-generation cleanup:

  • remove unsupported floating tree parts
  • remove isolated single-block artifacts where visually distracting
  • prevent water from appearing above terrain without support
  • prevent lava from appearing near the surface unless explicitly intended

13. Tuning Parameters

Internal tuning parameters may include:

  • chunk width/depth/height
  • terrain roughness
  • terrain amplitude
  • water level
  • snow threshold
  • tree density
  • cave density
  • ore frequency
  • lava depth threshold

Recommendation:

  • keep these internal until the base generator is visually stable

14. Generator Quality Rules

A generated chunk is acceptable when:

  • the top silhouette is readable
  • the side cutaway is interesting
  • the world contains at least some underground variation
  • water, snow, trees, caves, and lava do not visibly contradict each other
  • the chunk feels like a world sample, not random decorated noise

15. Seed Rules

  • generation shall be deterministic by seed
  • the same seed and parameter set shall always reproduce the same chunk
  • a newly generated seed should usually produce a visibly different result from the previous one

16. Deferred Rules

Deferred until later versions:

  • multiple biome families
  • beaches and sand transitions
  • custom presets in UI
  • erosion simulation
  • overhang-heavy terrain
  • animated water
  • underground structures beyond caves and ore pockets
Terug naar home