Skip to content
Signs of Life

Detailed world building

A custom world type points at a terrain file (WorldGenerator/WGD_*.json) that tells the Osiris generator what to build. This page covers the settings you usually change. Pair it with Custom worlds for the menu entry, sky, gravity, and save rules.

Two recipes that work

Approach When to use Starting point
Rich world Ores, biomes, prefabs, and an Osiris-like surface Copy the game's Osiris terrain file and retune it (Example Mod Flatlands)
Bare sandbox A simple test surface Keep only the passes you need (Example Mod Moon: surface height plus marble fill)

Do not invent a third generator. Mod worlds still run through the same generator as Osiris. You change the inputs, not the engine.

Terrain fields that matter

Field Role
SurfaceTileHeight Vertical seating for the surface. The sky often tracks this ground line.
DefaultBlockID Fill block when nothing else paints a tile (for example dirt or marble).
WorldGenPassUUIDs Ordered terrain passes by built-in id (Stone, SurfaceHeight, Tunnels, …). A mod can also ship extra WGP_*.json files under WorldGenerator/.
OreGenPassUUIDs Ore passes (CopperOre, Coal, …). An empty list means no ore. Extra ore passes can ship as OGP_*.json.
BackgroundWGBDPath Optional background layers. Prefer a file next to the terrain file (for example WGBD_Moon.json).
FlatnessRegions Softer or flatter bands of surface along the map.
PrefabGroups / Prefabs Placed structures and how densely they sit.
StructureGroups / ItemGroups / Creatures Ambient structures, loose items, and creature rolls.
FaceDecorGroups Extra art on exposed block faces (for example cave overlays). Missing or null does nothing.
SimpleOverlayDistributions Light overlays such as scatter and cover.

Built-in pass ids stay available. You do not need every Osiris pass — Moon shows that a one-pass world is valid.

Face decoration

FaceDecorGroups paint extra face art (and optional background tiles) onto solids that terrain passes already placed. They do not carve caves, and they do not spawn creatures.

You can omit the list, change the depth range or block ids, or point the background tile at another tile your mod registered.

Flatness and prefabs

  • Raise flatness toward 1.0 for plains-style ground (Flatlands).
  • Start and end values are fractions of map width.
  • On SMALL maps, dense prefab groups crowd easily — lower the density when you shrink the recommended size.

Sky and horizon

Prefer ParallaxDefinitionPath on the world type (a parallax_*.json in your mod) over a built-in ParallaxStyle alone. That keeps the sky with your mod and lets the horizon follow the world's ground.

Copy a built-in sky that matches the mood you want, then retune layers in your own file.

Spawns

SpawnDetailsName on the world type must match the Name inside your Spawning/SPWN_*.json. An empty or missing spawn file means no ambient creatures from that path.

Checklist before you publish

  1. The world type JSON points at real files inside the mod.
  2. Mod Prep Validate passes on the mod folder.
  3. Create a SMALL Sandbox world of your type and walk the surface, caves, and sky once.
  4. Confirm a save of that world still requires your mod enabled to load.

See also