Skip to content

Advanced Topics

Jump to bottom
finnsetchell edited this page Dec 12, 2025 · 2 revisions

Advanced Topics

This page covers advanced features and techniques for Moogs Structure Lib, including version-aware structures, advanced placement modifiers, and complex configuration options.

Version-Aware Pool Elements

For structures that need different NBT files per Minecraft version, use version-aware pool elements. This allows a single structure definition to work across multiple Minecraft versions.

When to Use

Use version-aware elements when:

  • Block IDs or properties change between versions
  • Structure format requirements differ
  • You want to maintain compatibility across versions

How It Works

Version-aware elements automatically select the correct NBT file based on the running Minecraft version. If no version match is found, it falls back to a default file.

Syntax

Template Pool Element:

{
  "weight": 1,
  "element": {
    "element_type": "moogs_structures:version_aware_single_pool_element",
    "location": "namespace:structure/default",
    "locations": {
      "1.21.5-1.21.10": "namespace:structure/new_version",
      "1.21-1.21.4": "namespace:structure/old_version"
    },
    "processors": "minecraft:empty",
    "projection": "rigid"
  }
}

Fields

  • element_type: Must be "moogs_structures:version_aware_single_pool_element"
  • location: Default/fallback NBT file path
  • locations: Object mapping version ranges to NBT files
    • Key: Version range (e.g., "1.21.5-1.21.10")
    • Value: NBT file path for that version range
  • processors: Processor list (same as regular elements)
  • projection: Projection type (same as regular elements)

Version Range Format

Version ranges use format: "<start>-<end>"

Examples:

  • "1.21.5-1.21.10" - Versions 1.21.5 through 1.21.10
  • "1.21-1.21.4" - Versions 1.21 through 1.21.4
  • "1.21.5" - Single version

Example

{
  "name": "mvs:versioned_structure/start_pool",
  "fallback": "minecraft:empty",
  "elements": [
    {
      "weight": 1,
      "element": {
        "element_type": "moogs_structures:version_aware_single_pool_element",
        "location": "mvs:structure/default",
        "locations": {
          "1.21.5-1.21.10": "mvs:structure/v1_21_5",
          "1.21-1.21.4": "mvs:structure/v1_21"
        },
        "processors": "minecraft:empty",
        "projection": "rigid"
      }
    }
  ]
}

Behavior:

  • Minecraft 1.21.5-1.21.10: Uses mvs:structure/v1_21_5
  • Minecraft 1.21-1.21.4: Uses mvs:structure/v1_21
  • Other versions: Uses mvs:structure/default (fallback)

Advanced Structure Features

Burying Types

Burying types control how structures are positioned relative to terrain:

LOWEST_CORNER

Places structure so its lowest corner aligns with terrain height.

Use case: Structures that should sit on the ground.

{
  "burying_type": "LOWEST_CORNER"
}

AVERAGE_LAND

Places structure at average terrain height in the area.

Use case: Structures that should adapt to terrain variations.

{
  "burying_type": "AVERAGE_LAND"
}

LOWEST_SIDE

Places structure so its lowest side aligns with terrain.

Use case: Structures that should follow terrain contours.

{
  "burying_type": "LOWEST_SIDE"
}

Y Allowance

Restricts structure placement to specific Y coordinate ranges:

{
  "y_allowance": {
    "min_y_allowed": 50,
    "max_y_allowed": 100
  }
}

Use cases:

  • Ocean structures (restrict to ocean depth)
  • Sky structures (restrict to high altitudes)
  • Cave structures (restrict to underground)

Important: max_y_allowed cannot be less than min_y_allowed.

Pools That Ignore Boundaries

Allows specific pools to extend beyond normal structure boundaries:

{
  "pools_that_ignore_boundaries": [
    "mvs:cathedral/special_pool",
    "mvs:cathedral/decorative_pool"
  ]
}

Use case: Decorative elements or special features that can extend beyond main structure limits.

Max Distance From Center

Limits how far jigsaw pieces can extend from the structure center:

{
  "max_distance_from_center": 35
}

Use case: Large jigsaw structures where you want to limit total size.

Example: Cathedral structure with max_distance_from_center: 35 means no piece can be more than 35 blocks from the center.

Terrain Adaptation Modes

Controls how structures adapt to terrain:

none

No terrain adaptation. Structure places exactly as built.

{
  "terrain_adaptation": "none"
}

Use case: Underground structures, floating structures.

beard_thin

Thin beard adaptation. Structure blends slightly with terrain.

{
  "terrain_adaptation": "beard_thin"
}

Use case: Most surface structures (most common).

beard_box

Box beard adaptation. More aggressive terrain blending.

{
  "terrain_adaptation": "beard_box"
}

Use case: Structures that should blend heavily with terrain.

encapsulate

Encapsulation adaptation. Structure is encapsulated by terrain.

{
  "terrain_adaptation": "encapsulate"
}

Use case: Buried structures, underground features.

bury

Bury adaptation. Structure is buried in terrain.

{
  "terrain_adaptation": "bury"
}

Use case: Completely buried structures.

Liquid Settings

Controls how liquids are handled in structures:

{
  "liquid_settings": "ignore_waterlogging"
}

Options:

  • "ignore_waterlogging" - Ignores waterlogging (default)
  • Other options depend on Minecraft version

Use case: Underwater structures, structures near water.

Biome Radius Checks

Ensures structures don't spawn on biome borders:

{
  "valid_biome_radius_check": 5
}

Checks that all biomes within 5 chunks match the required biome.

Use case: Structures that need consistent biome context.

Placement Modifiers

Moogs Structure Lib provides placement modifiers for different use cases. Note: These are for feature placement, not structure placement. They're used in different contexts than structure generation.

Minus Eight Placement

Offsets placement position by -8 blocks in X and Z.

Type: moogs_structures:minus_eight_placement

Use case: Feature placement adjustments.

Snap To Lower Non-Air Placement

Snaps placement to the lowest non-air block below.

Type: moogs_structures:snap_to_lower_non_air_placement

Use case: Features that need to sit on solid ground.

Unlimited Count Placement

Allows unlimited count of feature placements.

Type: moogs_structures:unlimited_count

Syntax:

{
  "type": "moogs_structures:unlimited_count",
  "count": 5
}

Use case: Features that should spawn multiple times.

Note: These placement modifiers are for feature generation (ores, vegetation, etc.), not structure generation. For structures, use AdvancedRandomSpread placement in structure sets.

Processor Lists

Processor lists modify blocks during structure placement. They're referenced in template pools:

{
  "processors": "namespace:processor_list_name"
}

File location: data/<namespace>/worldgen/processor_list/<name>.json

Common processors:

  • minecraft:empty - No processing (most common)
  • Custom processors for block replacement, randomization, etc.

Example from MVS:

{
  "processors": "mvs:cathedral"
}

References data/mvs/worldgen/processor_list/cathedral.json.

Note: Processor lists are a Minecraft feature. See Minecraft documentation for details on creating custom processors.

Complex Structure Patterns

Large Jigsaw Structures

For large expanding structures like mineshafts:

{
  "type": "moogs_structures:moogs_structures_generic_jigsaw_structure",
  "start_pool": "mvs:mineshaft/mineshaft",
  "size": 10,
  "max_distance_from_center": 90,
  "pools_that_ignore_boundaries": [],
  "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",
  "dimension_padding": 10,
  "biomes": "#mvs:has_structure/taiga_biomes",
  "step": "underground_structures",
  "terrain_adaptation": "none",
  "start_height": {
    "absolute": 0
  },
  "spawn_overrides": {}
}

Key settings:

  • High size (10) for expansion
  • max_distance_from_center to limit growth
  • dimension_padding to prevent overlap
  • step: "underground_structures" for underground
  • terrain_adaptation: "none" for precise placement

Nether Structures

Nether structures use special structure type:

{
  "type": "moogs_structures:moogs_structures_generic_nether_jigsaw_structure",
  "start_pool": "mvs:nether_structure/start_pool",
  "size": 1,
  "biomes": "#mvs:has_structure/nether_biomes",
  "land_search_direction": "HIGHEST_LAND",
  "ledge_offset_y": 5,
  "project_start_to_heightmap": "WORLD_SURFACE_WG",
  "cannot_spawn_in_liquid": true,
  "terrain_height_radius_check": 2,
  "allowed_terrain_height_range": 1,
  "step": "surface_structures",
  "terrain_adaptation": "beard_thin",
  "start_height": {
    "absolute": 0
  },
  "spawn_overrides": {}
}

Key settings:

  • moogs_structures_generic_nether_jigsaw_structure type
  • land_search_direction: "HIGHEST_LAND" or "LOWEST_LAND"
  • ledge_offset_y for positioning
  • Nether biome tags

Best Practices

  1. Use Version-Aware Elements - When supporting multiple versions
  2. Test Thoroughly - Advanced features can have unexpected interactions
  3. Document Complex Structures - Note jigsaw connections and pool relationships
  4. Start Simple - Add advanced features incrementally
  5. Use Appropriate Settings - Match terrain adaptation to structure type
  6. Limit Growth - Use max_distance_from_center for large structures
  7. Test Exclusion Zones - Verify they work as expected

Troubleshooting Advanced Features

Version-aware not working?

  • Check version range format
  • Verify NBT files exist for all versions
  • Check fallback file exists

Burying type not working?

  • Verify terrain height checks are appropriate
  • Check y_allowance restrictions
  • Ensure terrain is suitable

Structures too large?

  • Reduce size value
  • Lower max_distance_from_center
  • Check jigsaw connections aren't infinite

Exclusion zones too restrictive?

  • Reduce chunk_count
  • Check structure set tags are correct
  • Verify allowed_chunk_count logic

See Also:

Clone this wiki locally