Add cave layers (#2826)

IntegratedQuantum · web-flow · commit 3a7b55815cf4 · 2026-04-06T20:02:32.000+02:00
This moves (most) height restrictions of biomes to layers instead. Biomes are now assigned to layers using tags. This allows having multiple distinct layers of caves broken up by other biomes (→#2464 #1463). Furthermore this will make cave layers more addon friendly. e.g. an addon could add their own layer between e.g. the caves and the root. The engine would then automatically shift down the layers below by the size of the new layer. Note: The depth hint only decides the order of the layers and is not representative of the actual depth. The actual depth is computed using the layer heights of all layers above it (or below for sky layers). Root and sky layers are currently set to 10000 to allow addons to place other things above/below it. However as long as no such layers exist, the root/sky will continue until the integer limit. To @ikabod-kee and @careeoki I'll put this in requires artistic review for you to look at the new way to specify cave biome height and the new layers.
diff --git a/assets/cubyz/biomes/cave/basalt.zig.zon b/assets/cubyz/biomes/cave/basalt.zig.zon
@@ -1,7 +1,7 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.maxHeight = -1000,
-	.minHeight = -48250,
 	.chance = 0.2,
 	.fogDensity = 8,
 
diff --git a/assets/cubyz/biomes/cave/cave.zig.zon b/assets/cubyz/biomes/cave/cave.zig.zon
@@ -1,7 +1,6 @@
 .{
 	.isCave = true,
-	.maxHeight = 0,
-	.minHeight = -48250,
+	.tags = .{.cave_layer},
 
 	.fogDensity = 2,
 	.caveNoiseStrength = 10,
diff --git a/assets/cubyz/biomes/cave/crystal.zig.zon b/assets/cubyz/biomes/cave/crystal.zig.zon
@@ -1,7 +1,7 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.maxHeight = -512,
-	.minHeight = -48250,
 
 	.chance = 0.2,
 	.crystals = 32,
diff --git a/assets/cubyz/biomes/cave/crystal_forest.zig.zon b/assets/cubyz/biomes/cave/crystal_forest.zig.zon
@@ -1,7 +1,7 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.maxHeight = -512,
-	.minHeight = -48250,
 	.chance = 0.01,
 
 	.crystals = 32,
diff --git a/assets/cubyz/biomes/cave/curl_forest.zig.zon b/assets/cubyz/biomes/cave/curl_forest.zig.zon
@@ -1,7 +1,7 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.maxHeight = -512,
-	.minHeight = -48250,
 
 	.fogDensity = 2,
 
diff --git a/assets/cubyz/biomes/cave/dropoff.zig.zon b/assets/cubyz/biomes/cave/dropoff.zig.zon
@@ -1,9 +1,8 @@
 .{
 	.isCave = true,
+	.tags = .{.dropoff_layer},
 	.caveNoiseStrength = 12,
 
-	.maxHeight = -48125,
-	.minHeight = -48500,
 	.stoneBlock = "cubyz:slate/base",
 	.fogDensity = 10,
 	.fogColor = 0x272334,
diff --git a/assets/cubyz/biomes/cave/ice_cave.zig.zon b/assets/cubyz/biomes/cave/ice_cave.zig.zon
@@ -1,8 +1,8 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.caveNoiseStrength = 10,
 	.maxHeight = -256,
-	.minHeight = -48250,
 	.chance = 0.2,
 	.fogDensity = 20,
 	.fogColor = 0xbabfbf,
diff --git a/assets/cubyz/biomes/cave/lava_cave.zig.zon b/assets/cubyz/biomes/cave/lava_cave.zig.zon
@@ -1,7 +1,7 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.maxHeight = -1500,
-	.minHeight = -48250,
 	.fogDensity = 20,
 	.chance = 0.1,
 	.fogColor = 0x51240c,
diff --git a/assets/cubyz/biomes/cave/marble_cave.zig.zon b/assets/cubyz/biomes/cave/marble_cave.zig.zon
@@ -1,7 +1,7 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.caveNoiseStrength = 5,
-	.maxHeight = -64,
 	.minHeight = -512,
 	.chance = 0.2,
 
diff --git a/assets/cubyz/biomes/cave/mushroom/_defaults.zig.zon b/assets/cubyz/biomes/cave/mushroom/_defaults.zig.zon
@@ -1,5 +1,6 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.fogDensity = 2,
 	.music = "cubyz:heart-of-the-beast",
 	.structures = .{
diff --git a/assets/cubyz/biomes/cave/mushroom/big/_defaults.zig.zon b/assets/cubyz/biomes/cave/mushroom/big/_defaults.zig.zon
@@ -1,7 +1,7 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.maxHeight = -512,
-	.minHeight = -48250,
 	.music = "cubyz:la_kubisa_caverna",
 	.ground_structure = .{
 		"2 to 3 cubyz:soil",
diff --git a/assets/cubyz/biomes/cave/mushroom/glimmergill.zig.zon b/assets/cubyz/biomes/cave/mushroom/glimmergill.zig.zon
@@ -1,6 +1,5 @@
 .{
 	.maxHeight = -200,
-	.minHeight = -48250,
 	.chance = 0.05,
 	.structures = .{
 		.{
diff --git a/assets/cubyz/biomes/cave/mushroom/toadstool_bolete.zig.zon b/assets/cubyz/biomes/cave/mushroom/toadstool_bolete.zig.zon
@@ -1,5 +1,4 @@
 .{
-	.maxHeight = -64,
 	.minHeight = -1000,
 	.chance = 0.3,
 	.structures = .{
diff --git a/assets/cubyz/biomes/cave/rare/crying_cave.zig.zon b/assets/cubyz/biomes/cave/rare/crying_cave.zig.zon
@@ -1,5 +1,6 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.fogDensity = 8,
 	.fogColor = 0x3b5c8c,
 	.chance = 0.01,
diff --git a/assets/cubyz/biomes/cave/rare/phantasmal.zig.zon b/assets/cubyz/biomes/cave/rare/phantasmal.zig.zon
@@ -1,10 +1,10 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.fogDensity = 35,
 	.fogColor = 0x000C14,
 	.chance = 0.01,
 	.maxHeight = -5000,
-	.minHeight = -48250,
 	.music = "cubyz:cubyz",
 	.stoneBlock = "cubyz:chalk/black",
 
diff --git a/assets/cubyz/biomes/cave/sky.zig.zon b/assets/cubyz/biomes/cave/sky.zig.zon
@@ -1,7 +1,6 @@
 .{
 	.isCave = true,
-	.minHeight = 0,
-	.maxHeight = 7000,
+	.tags = .{.sky_layer},
 	.caveNoiseStrength = 10,
 	.music = "cubyz:GymnopedieNo1",
 
diff --git a/assets/cubyz/biomes/cave/sky_islands/_defaults.zig.zon b/assets/cubyz/biomes/cave/sky_islands/_defaults.zig.zon
@@ -1,6 +1,6 @@
 .{
 	.isCave = true,
-	.minHeight = 10000,
+	.tags = .{.sky_island_layer},
 	.fogColor = 0xbbebff,
 	.fogDensity = 5.0,
 	.fogLower = 1e10,
diff --git a/assets/cubyz/biomes/cave/sky_islands/gap.zig.zon b/assets/cubyz/biomes/cave/sky_islands/gap.zig.zon
@@ -1,4 +1,4 @@
 .{
+	.tags = .{.sky_island_fog_layer},
 	.chance = 10,
-	.minHeight = 7000,
 }
diff --git a/assets/cubyz/biomes/cave/stalagmite_cave.zig.zon b/assets/cubyz/biomes/cave/stalagmite_cave.zig.zon
@@ -1,8 +1,8 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.caveNoiseStrength = 10,
 	.maxHeight = -256,
-	.minHeight = -48250,
 	.chance = 0.2,
 
 	.fogDensity = 10,
diff --git a/assets/cubyz/biomes/cave/starlit.zig.zon b/assets/cubyz/biomes/cave/starlit.zig.zon
@@ -1,7 +1,7 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 	.maxHeight = -10000,
-	.minHeight = -15000,
 	.music = "cubyz:heart-of-the-beast",
 	.chance = 0.1,
 	.structures = .{
diff --git a/assets/cubyz/biomes/cave/stone_forest.zig.zon b/assets/cubyz/biomes/cave/stone_forest.zig.zon
@@ -1,9 +1,8 @@
 .{
 	.isCave = true,
+	.tags = .{.cave_layer},
 
 	.chance = 0.01,
-	.maxHeight = -50,
-	.minHeight = -48250,
 
 	.music = "cubyz:heart-of-the-beast",
 
diff --git a/assets/cubyz/biomes/cave/void/rare/phantasmal/_defaults.zig.zon b/assets/cubyz/biomes/cave/void/rare/phantasmal/_defaults.zig.zon
@@ -1,8 +1,8 @@
 .{
 	.isCave = true,
+	.tags = .{.root_layer},
 	.fogDensity = 10,
 	.fogColor = 0x272334,
-	.maxHeight = -50000,
 	.music = "cubyz:cubyz",
 	.stoneBlock = "cubyz:chalk/black",
 	.chance = 0.01,
diff --git a/assets/cubyz/biomes/cave/void/void.zig.zon b/assets/cubyz/biomes/cave/void/void.zig.zon
@@ -1,7 +1,6 @@
 .{
 	.isCave = true,
-	.maxHeight = -48500,
-	.minHeight = -50000,
+	.tags = .{.void_layer},
 	.fogDensity = 10,
 	.fogColor = 0x272334,
 	.chance = 1,
diff --git a/assets/cubyz/biomes/cave/void/void_cavern.zig.zon b/assets/cubyz/biomes/cave/void/void_cavern.zig.zon
@@ -1,6 +1,6 @@
 .{
 	.isCave = true,
-	.maxHeight = -50000,
+	.tags = .{.root_layer},
 	.chance = 0.1,
 	.fogDensity = 10,
 	.fogColor = 0x272334,
diff --git a/assets/cubyz/biomes/cave/void/void_crystal.zig.zon b/assets/cubyz/biomes/cave/void/void_crystal.zig.zon
@@ -1,6 +1,6 @@
 .{
 	.isCave = true,
-	.maxHeight = -50000,
+	.tags = .{.root_layer},
 	.fogDensity = 10,
 	.fogColor = 0x272334,
 	.chance = 0.01,
diff --git a/assets/cubyz/biomes/cave/void/void_roots.zig.zon b/assets/cubyz/biomes/cave/void/void_roots.zig.zon
@@ -1,6 +1,6 @@
 .{
 	.isCave = true,
-	.maxHeight = -50000,
+	.tags = .{.root_layer},
 	.fogDensity = 10,
 	.fogColor = 0x272334,
 	.chance = 1,
diff --git a/assets/cubyz/cave_layers/caves.zig.zon b/assets/cubyz/cave_layers/caves.zig.zon
@@ -0,0 +1,5 @@
+.{
+	.tags = .{.cave_layer},
+	.layerHeight = 48250,
+	.depthHint = -1,
+}
diff --git a/assets/cubyz/cave_layers/dropoff.zig.zon b/assets/cubyz/cave_layers/dropoff.zig.zon
@@ -0,0 +1,5 @@
+.{
+	.tags = .{.dropoff_layer},
+	.layerHeight = 250,
+	.depthHint = -48250,
+}
diff --git a/assets/cubyz/cave_layers/sky.zig.zon b/assets/cubyz/cave_layers/sky.zig.zon
@@ -0,0 +1,5 @@
+.{
+	.tags = .{.sky_layer},
+	.layerHeight = 7000,
+	.depthHint = 0,
+}
diff --git a/assets/cubyz/cave_layers/sky_island_fog.zig.zon b/assets/cubyz/cave_layers/sky_island_fog.zig.zon
@@ -0,0 +1,5 @@
+.{
+	.tags = .{.sky_island_fog_layer},
+	.layerHeight = 3000,
+	.depthHint = 7000,
+}
diff --git a/assets/cubyz/cave_layers/sky_islands.zig.zon b/assets/cubyz/cave_layers/sky_islands.zig.zon
@@ -0,0 +1,5 @@
+.{
+	.tags = .{.sky_island_layer},
+	.layerHeight = 10000,
+	.depthHint = 10000,
+}
diff --git a/assets/cubyz/cave_layers/void.zig.zon b/assets/cubyz/cave_layers/void.zig.zon
@@ -0,0 +1,5 @@
+.{
+	.tags = .{.void_layer},
+	.layerHeight = 1500,
+	.depthHint = -48500,
+}
diff --git a/assets/cubyz/cave_layers/void_roots.zig.zon b/assets/cubyz/cave_layers/void_roots.zig.zon
@@ -0,0 +1,5 @@
+.{
+	.tags = .{.root_layer},
+	.layerHeight = 10000,
+	.depthHint = -50000,
+}
diff --git a/src/assets.zig b/src/assets.zig
@@ -29,6 +29,7 @@ pub const Assets = struct {
 	tools: ZonHashMap,
 	biomes: ZonHashMap,
 	biomeMigrations: AddonNameToZonMap,
+	caveLayers: ZonHashMap,
 	entityComponents: ZonHashMap,
 	entityComponentMigrations: AddonNameToZonMap,
 	structureTables: ZonHashMap,
@@ -50,6 +51,7 @@ pub const Assets = struct {
 			.tools = .{},
 			.biomes = .{},
 			.biomeMigrations = .{},
+			.caveLayers = .{},
 			.entityComponents = .{},
 			.entityComponentMigrations = .{},
 			.structureTables = .{},
@@ -71,6 +73,7 @@ pub const Assets = struct {
 		self.tools.deinit(allocator.allocator);
 		self.biomes.deinit(allocator.allocator);
 		self.biomeMigrations.deinit(allocator.allocator);
+		self.caveLayers.deinit(allocator.allocator);
 		self.entityComponents.deinit(allocator.allocator);
 		self.entityComponentMigrations.deinit(allocator.allocator);
 		self.structureTables.deinit(allocator.allocator);
@@ -92,6 +95,7 @@ pub const Assets = struct {
 			.tools = self.tools.clone(allocator.allocator) catch unreachable,
 			.biomes = self.biomes.clone(allocator.allocator) catch unreachable,
 			.biomeMigrations = self.biomeMigrations.clone(allocator.allocator) catch unreachable,
+			.caveLayers = self.caveLayers.clone(allocator.allocator) catch unreachable,
 			.entityComponents = self.entityComponents.clone(allocator.allocator) catch unreachable,
 			.entityComponentMigrations = self.entityComponentMigrations.clone(allocator.allocator) catch unreachable,
 			.structureTables = self.structureTables.clone(allocator.allocator) catch unreachable,
@@ -116,6 +120,7 @@ pub const Assets = struct {
 			addon.readAllZon(allocator, "tools", true, &self.tools, null);
 			addon.readAllZon(allocator, "structure_tables", false, &self.structureTables, null);
 			addon.readAllZon(allocator, "biomes", true, &self.biomes, &self.biomeMigrations);
+			addon.readAllZon(allocator, "cave_layers", true, &self.caveLayers, null);
 			addon.readAllZon(allocator, "recipes", false, &self.recipes, null);
 			addon.readAllZon(allocator, "sbb", true, &self.structureBuildingBlocks, null);
 			addon.readAllBlueprints(allocator, "sbb", &self.blueprints);
@@ -128,8 +133,8 @@ pub const Assets = struct {
 	}
 	fn log(self: *Assets, typ: enum { common, world }) void {
 		std.log.info(
-			"Finished {s} assets reading with {} blocks, {} items, {} tools, {} biomes, {} structure tables, {} recipes, {} structure building blocks, {} blueprints, {} particles, and {} world presets",
-			.{@tagName(typ), self.blocks.count(), self.items.count(), self.tools.count(), self.biomes.count(), self.structureTables.count(), self.recipes.count(), self.structureBuildingBlocks.count(), self.blueprints.count(), self.particles.count(), self.worldPresets.count()},
+			"Finished {s} assets reading with {} blocks, {} items, {} tools, {} biomes, {} cave layers, {} structure tables, {} recipes, {} structure building blocks, {} blueprints, {} particles, and {} world presets",
+			.{@tagName(typ), self.blocks.count(), self.items.count(), self.tools.count(), self.biomes.count(), self.caveLayers.count(), self.structureTables.count(), self.recipes.count(), self.structureBuildingBlocks.count(), self.blueprints.count(), self.particles.count(), self.worldPresets.count()},
 		);
 	}
 
@@ -697,6 +702,9 @@ pub fn loadWorldAssets(assetFolder: []const u8, blockPalette: *Palette, itemPale
 	}
 	biomes_zig.finishLoading();
 
+	// Cave layers:
+	try main.server.terrain.cave_layers.registerCaveLayers(&worldAssets.caveLayers);
+
 	// EntityComponents
 	{
 		var map: std.StringHashMap(u32) = .init(main.stackAllocator.allocator);
@@ -757,6 +765,7 @@ pub fn unloadAssets() void { // MARK: unloadAssets()
 	items_zig.reset();
 	migrations_zig.reset();
 	biomes_zig.reset();
+	main.server.terrain.cave_layers.reset();
 	migrations_zig.reset();
 	main.server.terrain.structures.reset();
 	main.models.reset();
diff --git a/src/server/terrain/biomes.zig b/src/server/terrain/biomes.zig
@@ -298,6 +298,13 @@ pub const Biome = struct { // MARK: Biome
 			.maxSubBiomeCount = zon.get(f32, "maxSubBiomeCount", std.math.floatMax(f32)),
 			.tags = Tag.loadTagsFromZon(main.worldArena, zon.getChild("tags")),
 		};
+		if (self.isCave) {
+			for (self.tags) |tag| {
+				if (std.mem.endsWith(u8, tag.getName(), "_layer")) break;
+			} else {
+				std.log.err("Cave biome {s} is missing a '_layer' tag to assign it to a cave layer.", .{id});
+			}
+		}
 		if (minRadius > maxRadius) {
 			std.log.err("Biome {s} has invalid radius range ({d}, {d})", .{self.id, minRadius, maxRadius});
 		}
@@ -382,7 +389,7 @@ pub const Biome = struct { // MARK: Biome
 		return hashGeneric(self.*);
 	}
 
-	fn hasTag(self: Biome, tag: Tag) bool {
+	pub fn hasTag(self: Biome, tag: Tag) bool {
 		return std.mem.containsAtLeastScalar(Tag, self.tags, 1, tag);
 	}
 };
diff --git a/src/server/terrain/cave_layers.zig b/src/server/terrain/cave_layers.zig
diff --git a/src/server/terrain/cavebiomegen/RandomBiomeDistribution.zig b/src/server/terrain/cavebiomegen/RandomBiomeDistribution.zig
diff --git a/src/server/terrain/terrain.zig b/src/server/terrain/terrain.zig
diff --git a/src/utils.zig b/src/utils.zig
