Custom worlds

A mod can add extra Sandbox world types next to the built-in ones (Osiris, Asteroid, and others). Generation still uses the same terrain system as Osiris. Your mod supplies different terrain settings, spawns, and optionally its own sky.

Files

File	Role
worldprofile_*.json	Menu entry, icon, terrain file, spawn list, recommended size, options
WorldGenerator/WGD_*.json	Terrain details (passes, flatness, prefabs, …)
WorldGenerator/WGBD_*.json	Optional background tile layers (named from the WGD file)
Spawning/SPWN_*.json	Ambient spawn groups; Name must match SpawnDetailsName exactly, including case
Spawning/spawnrule_*.json	Optional additive wildlife groups, targeted by full profile id
Parallax/parallax_*.json	Optional sky (layers, sun/moon, clouds, lighting)
A PNG	Picture in the Sandbox type picker (IconPath)

Built-in terrain passes stay available by their usual ids. You can also ship extra pass files in your mod's WorldGenerator/ folder (WGP_*.json for terrain, OGP_*.json for ore).

worldprofile_*.json shape

{
  "WorldProfile": {
    "UniqueIdentifier": "moon",
    "DisplayName": "Moon",
    "Description": "…",
    "IconPath": "WorldGenerator/icon_moon.png",
    "WorldGenDetailsPath": "WorldGenerator/WGD_Moon.json",
    "SpawnDetailsName": "Moon",
    "RecommendedMapSize": "SMALL",
    "ParallaxStyle": "MOON",
    "ParallaxDefinitionPath": "Parallax/parallax_moon.json",
    "GravityScale": 0.1654,
    "SkipEarthSurfaceDecor": true
  }
}

The id stored on the save is UniqueModName.UniqueIdentifier (for Example Mod's Moon type, ExampleMod.moon). That string tells the game which mod's world type to load.

Field	Notes
RecommendedMapSize	Defaults the size picker only (SMALL, MEDIUM, or LARGE). Players can still change size.
ParallaxDefinitionPath	Sky JSON inside your mod (preferred). The horizon follows the world's ground.
ParallaxStyle	Optional shortcut if you are not shipping a sky file: NEW_EARTH, ASTEROID, HEPHAESTUS, PREFAB_BUILD, or MOON.
GravityScale	Surface gravity as a fraction of Earth (1.0 is Earth). The Moon sample uses about 0.1654.
SkipEarthSurfaceDecor	Skip tall grass, ground scatter, and similar Osiris surface extras.

Example Mod samples

With Example Mod copied into Mods and enabled:

World type	Idea
Flatlands	Osiris-like terrain, flatter ground, recommended SMALL
Moon	Simple marble surface, a space sky, low gravity, no Osiris surface extras

Validate the mod with Mod Prep before publishing.

Authoring the terrain

See Detailed world building for terrain fields, Flatlands vs Moon recipes, flatness and prefabs, sky tips, and a publish checklist.

Saves and multiplayer

• Built-in worlds do not store a mod world-type id.
• Worlds created from a mod remember that type.
• Loading such a world without that mod enabled is refused (the game will not silently switch to Osiris).
• Multiplayer still requires the same game version; everyone needs the same mod for that world type.

Authoring tips

• Prefer a sky file in your mod over borrowing another world's sky math.
• Map size is chosen in the Sandbox menu — do not put the size in the type name.
• For pass lists, flatness, prefabs, and horizon options, use Detailed world building.