Structure Files

Structure Files

Structure files define what your structure is, where it can spawn, and how it behaves. This page covers all available options for structure JSON files.

Structure Types

Moogs Structure Lib provides two main structure types:

1. Generic Jigsaw Structure

Type: moogs_structures:moogs_structures_generic_jigsaw_structure

Used for overworld structures. Supports all standard features plus advanced terrain checks, burying types, and height restrictions.

2. Generic Nether Jigsaw Structure

Type: moogs_structures:moogs_structures_generic_nether_jigsaw_structure

Designed specifically for Nether structures. Includes special land search algorithms optimized for Nether terrain.

Required Fields

Every structure JSON must include these fields:

type

Type: String
Example: "moogs_structures:moogs_structures_generic_jigsaw_structure"

The structure type identifier. Determines which structure system to use.

start_pool

Type: Resource Location (String)
Example: "mvs:carts/cart/start_pool"

Reference to the template pool that defines which structure pieces to use. Must match a pool defined in worldgen/template_pool/.

size

Type: Integer (0-128)
Example: 1

The jigsaw generation size. Controls how many times the structure can expand

Note: For simple structures without jigsaw connections, use 1.

start_height

Type: Height Provider Object
Example: { "absolute": 0 }

Defines the starting height for structure placement. Common options:

{ "absolute": 0 }           // Absolute Y coordinate
{ "uniform": { "min_inclusive": 60, "max_inclusive": 80 } }  // Random range

The actual placement will be adjusted by project_start_to_heightmap if specified.

biomes

Type: Biome Tag or Array
Example: "#mvs:has_structure/overworld_biomes" or ["minecraft:plains", "minecraft:forest"]

Which biomes the structure can spawn in. Can be:

• A biome tag: "#namespace:tag_name"
• An array of biome IDs: ["minecraft:plains", "minecraft:forest"]

For more info and examples of biome tags, read this.

step

Type: String
Example: "surface_structures"

The generation step when structures spawn. Possible values:

• "raw_generation"
• "lakes"
• "local_modifications"
• "underground_structures"
• "surface_structures" - (most common)
• "strongholds"
• "underground_ores"
• "underground_decoration"
• "vegetal_decoration"
• "top_layer_modification"

spawn_overrides

Type: Object
Example: {} or see below

Defines custom entity spawning for the structure. Empty object {} means no custom spawning.

Example with custom spawning:

{
  "monster": {
    "bounding_box": "full",
    "spawns": [
      {
        "type": "minecraft:skeleton",
        "weight": 1,
        "minCount": 1,
        "maxCount": 2
      }
    ]
  }
}

Optional Fields

project_start_to_heightmap

Type: String
Example: "WORLD_SURFACE_WG"

Projects the structure start position to a heightmap. Common values:

• "WORLD_SURFACE_WG" - World surface (most common)
• "OCEAN_FLOOR_WG" - Ocean floor (for underwater structures)
• "WORLD_SURFACE" - World surface (non-worldgen)
• "OCEAN_FLOOR" - Ocean floor (non-worldgen)
• "MOTION_BLOCKING" - Motion blocking blocks
• "MOTION_BLOCKING_NO_LEAVES" - Motion blocking excluding leaves

If not specified, uses the start_height value directly.

cannot_spawn_in_liquid

Type: Boolean
Default: false
Example: true

Prevents the structure from spawning if there is liquid at the sampled point. It checks a single column at the middle of the start chunk, not the whole chunk.

terrain_height_radius_check

Type: Integer (1-100)
Example: 1

Checks terrain height in a radius around the structure. Used with allowed_terrain_height_range or y_allowance.

• 1: Checks a 3x3 chunk area (one chunk out in each direction)
• Higher values: Checks further out

allowed_terrain_height_range

Type: Integer (1-1000)
Example: 3

Maximum allowed height difference in the checked area. If terrain varies more than this, structure won't spawn.

Example: With terrain_height_radius_check: 1 and allowed_terrain_height_range: 3, the structure will only spawn if the terrain height in the checked area varies by 3 blocks or less.

valid_biome_radius_check

Type: Integer (1-100)
Example: 5

Checks that all biomes in a radius match the required biome. Ensures structures don't spawn on biome borders.

y_allowance

Type: Object
Example: { "min_y_allowed": 50, "max_y_allowed": 100 }

Restricts structure placement to a specific Y range. Useful for structures that must spawn at certain heights.

{
  "min_y_allowed": 50,    // Minimum Y coordinate
  "max_y_allowed": 100    // Maximum Y coordinate
}

Both fields are optional. You can specify just min_y_allowed or just max_y_allowed.

Note: max_y_allowed cannot be less than min_y_allowed.

max_distance_from_center

Type: Integer (1-128)
Example: 35

Maximum distance (in blocks) that jigsaw pieces can extend from the center. Prevents structures from growing too large.

Useful for large jigsaw structures like mineshafts or cathedrals.

pools_that_ignore_boundaries

Type: Array of Resource Locations
Example: ["mvs:cathedral/special_pool"]

Lets pieces drawn from a pool’s fallback ignore the structure boundary and overlap other pieces. The ids listed are matched against a pool’s fallback field, not against the pool a jigsaw points at, so listing a target pool does nothing.

burying_type

Type: String
Example: "LOWEST_CORNER"

How the structure should be buried/positioned relative to terrain. Options:

• "LOWEST_CORNER" - Places structure so lowest corner aligns with terrain
• "AVERAGE_LAND" - Places structure at average terrain height
• "LOWEST_SIDE" - Places structure so lowest side aligns with terrain

Useful for structures that should be partially buried or adapt to terrain.

liquid_settings

Type: String
Example: "ignore_waterlogging"

How to handle liquids in the structure. Options:

• "apply_waterlogging" - Waterlogs blocks placed in water. This is the default when the field is omitted
• "ignore_waterlogging" - Leaves blocks dry

terrain_adaptation

Type: String
Example: "beard_thin"

How the structure adapts to terrain. Common values:

• "none" - No adaptation
• "beard_thin" - Thin beard adaptation (most common)
• "beard_box" - Box beard adaptation
• "encapsulate" - Encapsulation adaptation
• "bury" - Bury adaptation

Nether-Specific Fields

These fields are only available for moogs_structures:moogs_structures_generic_nether_jigsaw_structure:

Note that the reverse is also true: project_start_to_heightmap, terrain_height_radius_check, allowed_terrain_height_range and burying_type are not read by the nether type. Writing them there produces no error and no effect. See Nether jigsaw structures.

land_search_direction

Type: String
**Required for Nether structures
Example: "HIGHEST_LAND"

Which direction to search for valid placement:

• "HIGHEST_LAND" - Places on highest solid block
• "LOWEST_LAND" - Places on lowest solid block
• "FIXED_HEIGHT" - Skips the search and places at start_height

Optimized for Nether terrain. Values are uppercase and case sensitive.

ledge_offset_y

Type: Integer (0-100)
Example: 5

Y offset when placing on ledges. Adjusts structure position relative to found land.

Complete Examples

Simple Structure (Cart)

{
  "type": "moogs_structures:moogs_structures_generic_jigsaw_structure",
  "start_pool": "mvs:carts/cart/start_pool",
  "size": 1,
  "biomes": "#mvs:has_structure/overworld_biomes",
  "project_start_to_heightmap": "WORLD_SURFACE_WG",
  "cannot_spawn_in_liquid": true,
  "step": "surface_structures",
  "terrain_adaptation": "beard_thin",
  "start_height": {
    "absolute": 0
  },
  "spawn_overrides": {}
}

Medium Complexity (Barn)

{
  "type": "moogs_structures:moogs_structures_generic_jigsaw_structure",
  "start_pool": "mvs:houses/barn/start_pool",
  "size": 1,
  "biomes": "#mvs:has_structure/overworld_biomes",
  "project_start_to_heightmap": "WORLD_SURFACE_WG",
  "cannot_spawn_in_liquid": true,
  "terrain_height_radius_check": 1,
  "allowed_terrain_height_range": 3,
  "step": "surface_structures",
  "terrain_adaptation": "beard_thin",
  "start_height": {
    "absolute": 0
  },
  "spawn_overrides": {}
}

Complex Structure (Cathedral)

{
  "type": "moogs_structures:moogs_structures_generic_jigsaw_structure",
  "start_pool": "mvs:cathedral/temp",
  "size": 17,
  "max_distance_from_center": 35,
  "project_start_to_heightmap": "WORLD_SURFACE_WG",
  "cannot_spawn_in_liquid": true,
  "terrain_height_radius_check": 1,
  "allowed_terrain_height_range": 5,
  "liquid_settings": "ignore_waterlogging",
  "biomes": "#mvs:has_structure/overworld_biomes",
  "step": "surface_structures",
  "terrain_adaptation": "beard_thin",
  "start_height": {
    "absolute": 0
  },
  "spawn_overrides": {
    "monster": {
      "bounding_box": "full",
      "spawns": [
        {
          "type": "minecraft:skeleton",
          "weight": 1,
          "minCount": 1,
          "maxCount": 2
        },
        {
          "type": "minecraft:zombie",
          "weight": 2,
          "minCount": 2,
          "maxCount": 5
        }
      ]
    }
  }
}

Nether Structure (Nether Devil)

{
  "type": "moogs_structures:moogs_structures_generic_nether_jigsaw_structure",
  "start_pool": "mvs:other_decoration/nether_devil/start_pool",
  "size": 1,
  "biomes": "#mvs:has_structure/nether_biomes",
  "land_search_direction": "HIGHEST_LAND",
  "cannot_spawn_in_liquid": true,
  "step": "surface_structures",
  "terrain_adaptation": "beard_thin",
  "start_height": {
    "absolute": 0
  },
  "spawn_overrides": {}
}

Ocean Structure (Ocean Tower)

{
  "type": "moogs_structures:moogs_structures_generic_jigsaw_structure",
  "start_pool": "mvs:ocean_tower_start_pool",
  "size": 1,
  "project_start_to_heightmap": "OCEAN_FLOOR_WG",
  "biomes": "#mvs:has_structure/deep_ocean_biomes",
  "step": "surface_structures",
  "terrain_adaptation": "beard_thin",
  "y_allowance": {
    "max_y_allowed": 25
  },
  "start_height": {
    "absolute": 0
  },
  "spawn_overrides": {}
}

Underground Structure (Mineshaft)

{
  "type": "moogs_structures:moogs_structures_generic_jigsaw_structure",
  "start_pool": "mvs:mineshaft/mineshaft",
  "size": 10,
  "max_distance_from_center": 90,
  "project_start_to_heightmap": "WORLD_SURFACE_WG",
  "cannot_spawn_in_liquid": true,
  "terrain_height_radius_check": 1,
  "allowed_terrain_height_range": 2,
  "liquid_settings": "ignore_waterlogging",
  "biomes": "#mvs:has_structure/taiga_biomes",
  "step": "underground_structures",
  "terrain_adaptation": "none",
  "start_height": {
    "absolute": 0
  },
  "spawn_overrides": {}
}

Common Patterns

Surface Structures

Most common pattern for overworld structures:

• step: "surface_structures"
• project_start_to_heightmap: "WORLD_SURFACE_WG"
• cannot_spawn_in_liquid: true
• terrain_adaptation: "beard_thin"

Underwater Structures

For ocean structures:

• project_start_to_heightmap: "OCEAN_FLOOR_WG"
• y_allowance to restrict depth
• Appropriate biome tags for ocean biomes

Large Jigsaw Structures

For expanding structures:

• size: 10 or higher
• max_distance_from_center to limit growth
• Multiple template pools for different pieces

Nether Structures

Always use:

• type: "moogs_structures:moogs_structures_generic_nether_jigsaw_structure"
• land_search_direction: "HIGHEST_LAND" or "LOWEST_LAND"
• Nether biome tags

Troubleshooting

Structure not spawning?

• Check biome tags exist and are correct
• Verify spacing > separation in structure set
• Check terrain height restrictions aren't too strict
• Ensure cannot_spawn_in_liquid isn't blocking valid locations

Structure spawning in wrong places?

• Adjust terrain_height_radius_check and allowed_terrain_height_range
• Use valid_biome_radius_check to avoid biome borders
• Check y_allowance restrictions

Structure too large/small?

• Adjust size for jigsaw expansion
• Use max_distance_from_center to limit growth
• Check template pool connections

---

Next: Learn about Template Pools to understand how structure pieces connect!