Worldshape Mod — Guide

Getting Started

Worldshape operates at the modpack level. Upon the first launch, the mod automatically generates a worldshape directory within your Minecraft instance folder (alongside mods, config, and saves). This folder acts as a local data repository for your custom generation rules.

Directory Structure

To add structures, you must follow a specific namespaced folder hierarchy:

Folder Path	Description
`worldshape/data/<namespace>/structures/`	Contains the `.nbt` schematic files for your structures.
`worldshape/data/<namespace>/structure_spawners/`	Contains the `.json` configuration files that define how and where structures spawn.
`worldshape/data/<namespace>/worldgen/template_pool/`	Contains `.json` files for Jigsaw block pools (optional).

Note: Changes made to files in the structure_spawners folder require a game restart to take effect.

Placement Mechanics

The placement object determines the vertical logic and environment checks for the structure. Worldshape supports four primary placement types:

Placement Types

surface: Snaps the structure to the highest solid block. * Optional: fluidSurface (Boolean) allows spawning on water or lava.
underground: Spawns the structure within solid terrain between minY and maxY.
cave: Specifically targets air pockets within caves. * Note: Structures using cave type are treated as "features" and cannot be found using the /locate command.
nether: Optimized for the Nether's ceiling and floor logic.

Advanced Placement Settings

Setting	Type	Relevant Types	Description
`minY` / `maxY`	Integer	All	Restricts spawning to a specific height range.
`offset`	Integer	All	Nudges the structure up or down from its found position.
`ceiling`	Boolean	Cave, Nether	If true, searches for a ceiling to hang the structure from.
`pickHighest`	Boolean	Cave, Nether	Searches for suitable spaces from top-to-bottom instead of bottom-to-top.
`minSpace`	Integer	Cave	The minimum vertical height required for the cave to be valid.

Jigsaw System Support

Worldshape fully leverages Minecraft's Jigsaw system, allowing for procedural generation of large-scale POIs. By using the pool key in the template section, you can point to a template_pool JSON file.

Template Pools

Template pools define a list of structure pieces and their relative weights. This is the same system used by vanilla villages and Bastion Remnants.

Location: worldshape/data/<namespace>/worldgen/template_pool/
Usage: Allows for randomized variations of a structure (e.g., a house that sometimes has a balcony or a different roof style).