Troubleshooting

​

Known Issues

​

Bedrock Layer Spawning

1. Manual teleportation: Use the following command to teleport players to a safe underground location:
   /tp @p ~ 100 ~
   
2. Spawn adjustment: Configure your server’s spawn settings to force players to spawn at a specific Y-level (recommended: Y: 50-150).
3. Plugin solution: Use a spawn control plugin (for Bukkit/Spigot/Paper) to override the default spawn behavior.

​

Player Suffocation on Spawn

1. Pre-generate spawn chunks: Use a world pre-generation plugin or tool to generate spawn chunks before players join:
   /worldborder center ~ ~
   /worldborder set 1000
   /chunky worldborder
   /chunky start
   
2. Safe spawn plugin: Install a plugin that ensures players spawn in a safe location with air blocks.
3. Manual intervention: Temporarily give players creative mode or resistance effects during first spawn.

​

Coral Coves Border Issues

​

Installation Issues

​

Terra Not Loading Config

1. Verify installation path: Ensure Substratum is installed in the correct directory:
   • Bukkit/Spigot/Paper: plugins/Terra/packs/Substratum/
   • Fabric: config/Terra/packs/Substratum/
2. Check pack.yml: Verify that pack.yml exists in the Substratum root directory and is properly formatted.
3. Server logs: Check your server console for Terra errors during startup. Look for lines containing [Terra].
4. Reload Terra: Try reloading Terra after installation:
   /terra reload
   

​

Wrong Generator Applied

1. Verify bukkit.yml: For Bukkit-based servers, ensure your bukkit.yml is correctly configured:
   worlds:
     world:
       generator: Terra:SUBSTRATUM
   
2. World must be new: Terra generators can only be applied to newly generated worlds. You cannot convert existing worlds.
3. Delete and regenerate: If you’ve already generated a world with the wrong generator:
   • Stop the server
   • Delete the world folder(s)
   • Update bukkit.yml
   • Start the server to generate a new world
4. Fabric level.dat: On Fabric, you must manually edit the level.dat file to apply custom generation. See the Terra documentation for details.

​

End Dimension Not Generating

worlds:
  world:
    generator: Terra:SUBSTRATUM
  world_the_end:
    generator: Terra:SUBSTRATUM

​

Drop-In Merge Issues

​

Duplicate Files During Merge

• pack.yml (keep the existing pack’s version)
• Any Terra core files that already exist
• Shared utility configurations

​

Cave Biomes Not Appearing

1. Add the extrusion: Edit your pack’s preset file (e.g., biome-providers/presets/default.yml) and add:
   extrusions:
     - << biome-providers/extrusions/add_substratum_cave_biomes.yml:extrusions
   
2. Configure Y-levels: Edit substratum_meta.yml to adjust the Y-level ranges for cave biome generation to match your pack’s requirements:
   cave-biome-max: 48  # Adjust based on your pack
   cave-biome-min: -16  # Adjust based on your pack
   
3. Check biome scale: If caves are too rare or too common, adjust the cave-biome-scale parameter in substratum_meta.yml.

​

Biome Blending Issues

1. Adjust biome scale: Increase cave-biome-scale in substratum_meta.yml for larger, more gradual biome transitions:
   cave-biome-scale: 300  # Larger = smoother transitions
   
2. Disable problematic biomes: Comment out specific biomes in biome-providers/extrusions/add_substratum_cave_biomes.yml if they clash with your pack’s aesthetic.
3. Review pack compatibility: Some packs may have incompatible cave generation systems. Check the host pack’s documentation for known conflicts.

​

Performance Issues

​

Low FPS in Caves

1. Complex decorations: Substratum caves feature detailed decorations (stalactites, icicles, giant structures). Consider:
   • Reducing render distance
   • Using optimization mods like Sodium (Fabric) or Optifine (Forge)
   • Disabling some decoration features
2. Lighting updates: Underground caves require extensive lighting calculations:
   • Use Phosphor or Starlight mods for faster lighting
   • Pre-generate chunks to reduce runtime lighting updates

​

Server Lag During Generation

1. Pre-generate terrain: Use a chunk pre-generation plugin to generate the world before players explore:
   • Chunky (recommended): /chunky radius 5000 then /chunky start
   • WorldBorder: Set a world border and pre-generate to the edge
2. Reduce biome complexity: Disable feature-heavy biomes in add_substratum_cave_biomes.yml by commenting them out with #.
3. Allocate more RAM: Ensure your server has adequate memory allocated (recommended: 4GB minimum for small servers, 8GB+ for larger servers).

​

Configuration Issues

​

Biomes Too Large or Too Small

biome-distribution:
  global-scale: 1        # Affects everything
  cave-biome-scale: 200  # Affects cave biome size specifically

• Increase the scale for larger biomes
• Decrease the scale for smaller, more varied biomes

​

Strata Layers at Wrong Y-Levels

strata:
  deepslate:
    top: 7     # Y level where deepslate begins to replace stone
    bottom: -7  # Y level where all stone is replaced by deepslate
  bedrock:
    top: -60   # Y level where bedrock begins to replace deepslate
    bottom: -64 # Y level where all deepslate is replaced by bedrock

​

Getting Help