Custom Structures - simibubi/Worldshape GitHub Wiki

Worldshape can generate your new ruins, dungeons, villages or other points of interest in any worlds you create.

In order to register a structure, create a <structure name>.json file in your datapacks' structure_spawners/ folder.
The content of this file is as follows:

{
    "template": { ... },        // required
    "placement": { ... },       // required

    "averageSpacing": integer,  // required
    "minimumSpacing": integer,  // optional, defaults to (averageSpacing / 2)
    "seed": integer,            // optional, defaults to random number
    "avoidOthers": bool,        // optional, defaults to (true if placement is set to avoid villages)
    
    "biomes": [ ... ],          // optional, defaults to empty array
    "dimensions": [ ... ]       // optional, defaults to empty array
}

averageSpacing denotes the average horizontal distance (in chunks) between every attempts of generating this structure.
minimumSpacing marks the lower boundary of the possible distance (in chunks) between two structures of this type.
seed is cryptographic salt for the placement algorithm. Structure types with equal spacing and equal seeds will always target the same set of chunks to generate in.
avoidOthers unlocks additional checks in the placement algorithm where before spawning, a structure checks all other structure types with avoidOthers set to true and only generates when none of the prior ones did.
Note that if the placement type is cave, the structure only checks for other cave structure types.
biomes will create a biome filter. Add biome ids or categories prefixed with a #. Your structure now only spawns in these biomes.
[ "minecraft:desert", "#forest", "#beach" ] matches the desert biome and any biomes categorised as either forest or beach.
dimesions will create a dimension filter. Your structure now only spawns in these dimensions.
[ "minecraft:overworld", "minecraft:the_end" ] matches the overworld and end dimension.

The template section:

    "template": {
        "type": string,           // required, allows "single" and "pool"
        "id": string,             // required
        "maxDepth": integer,      // optional, defaults to 10
        
                                  // relevant if type is single
        "followTerrain": bool     // optional, defaults to false
    }

id tells the location of the structure in loaded datapacks. Format is namespace:path
type chooses a way to load the actual structure when a suitable place is found.
- single will look for a template .nbt file at worldshape/data/<namespace>/structures/<path>.nbt, or for structures with matching resource location in any other datapacks currently loaded. You can use Structure Blocks or the Create mod to make .nbt files from things you built in-world.
  id: "my_pack:houses/wooden" would refer to the file worldshape/data/my_pack/structures/houses/wooden.nbt
- pool will spawn from a template pool .json file at worldshape/data/<namespace>/worldgen/template_pool/<path>.nbt, or from pools with matching resource location in any other datapacks currently loaded. These pools are the same as the ones Jigsaw Blocks use to spawn structure clusters.
  id: "my_pack:random_house" would refer to the file worldshape/data/my_pack/worldgen/template_pool/random_house.json
maxDepth becomes relevant if the spawned structure contains jigsaw blocks. The resulting graph depth is limited by this value. Increase with caution
followTerrain causes a template to 'collapse' onto the terrain, like for instance a path would. Only relevant for single templates, as a template pool gives you this option within its own .json structure.

The placement section:

    "placement": {
        "type": string,            // required, allows "surface", "nether", "cave" and "underground"
        "minY": integer,           // optional, defaults to 0
        "maxY": integer,           // optional, defaults to 256
        "offset": integer,         // optional, defaults to 0
        "fluidSurface": bool,      // optional, defaults to false

                                   // relevant if type is surface or nether or underground
        "terraform": integer,      // optional, disabled if missing

                                   // relevant if type is cave or nether
        "ceiling": bool,           // optional, defaults to false
        "pickHighest": bool,       // optional, defaults to false
        "minSpace": integer,       // optional, defaults to 1

                                   // relevant if type is underground
        "surfaceMargin": integer,  // optional, defaults to 0
    }

type chooses a way to determine the vertical location.
- surface will place structures on the highest point of generated blocks in the chunk.
- nether will spawn structures in below-surface spaces formed by the noise generator. (mountain overhangs, the nether)
- underground will spawn structures at a randomly selected y value between the surface and minY.
- cave will spawn structures in caves formed by carvers. (caves, ravines, etc.)
  Note that on the technical level, using the cave type makes the structure a "feature", which means large jigsaw clusters may generate inconsistently and the /locate command cannot be used to find these structures.
minY & maxY will narrow the placement scope between two y values. If the placement type cannot provide a suitable height for a location, the structure will not spawn there.
offset nudges the template above or below the y value found by the placement type. Helps to align your structure with the respective surfaces you are generating them on.
fluidSurface set to true allows structure placement on water or lava only. Otherwise structures will avoid fluid surfaces. This setting also affects cave and nether placement.
terraform set to a value will inform the terrain noise generator to form a base around your structure, and to elegantly carve out any intersecting landmass. The value denotes the height relative to the structure, which the landmass should target. Set to "0" merges only the lowest layer of your schematic into the ground. "-1" neatly places the schematic on top of the surface. Positive values submerge it further.
Note that terraform generally only works well on structures spawned above a dimensions' "sea level".

The following settings are relevant only for cave or nether type placement:

ceiling will cause it to find the y value of the first empty space beneath a ceiling, instead of the first above a surface.
pickHighest will cause it to search for suitable spaces from top-to-bottom, instead of the reverse
minSpace denotes the minimum height of a cave to qualify as "enough room" to spawn the structure

The following setting is relevant only for underground type placement:

surfaceMargin changes boundary of randomly chosen y values depending on the surface.
If the surface at a sampled spawn is at y=70, the resulting y value is chosen between minY and min( maxY, 70 - surfaceMargin )
Note that surface margin can be negative, to spawn structures a at random distance above the surface.

Appendix

All Vanilla Dimension ids:

    "dimensions": [
        "minecraft:overworld", 
        "minecraft:the_nether", 
        "minecraft:the_end"
    ]

All available Biome Categories:

    "biomes": [
        "#none",
        "#taiga",
        "#extreme_hills",
        "#jungle",
        "#mesa",
        "#plains",
        "#savanna",
        "#icy",
        "#beach",
        "#forest",
        "#ocean",
        "#desert",
        "#river",
        "#swamp",
        "#mushroom",
        "#nether",
        "#the_end"
    ]

Custom Structures - simibubi/Worldshape GitHub Wiki

Appendix

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️