Updated Docs, and Cortections

2026-08-30 05:50:48 +00:00 · 2026-08-08 00:29:48 -06:00
parent c40e1cf152
commit 506787f51a
70 changed files with 9485 additions and 3050 deletions
@@ -0,0 +1,227 @@
+# 15 - Caves & Carving
+
+Iris carves caves itself during mantle generation via `MantleCarvingComponent` and `IrisCaveCarver3D`. Density fields from `IrisCaveProfile` decide solid vs air/water/lava. Cave biomes paint floors, ceilings, decorators, and objects inside carved space. Vanilla and mod noise carvers never run over Iris terrain.
+
+Related: `11 - Dimensions.md`, `12 - Regions.md`, `13 - Biomes.md`, `14 - Generators & Noise.md`, `16 - Surfaces, Decorators & Deposits.md`, `17 - Trees, Fungi, Coral, Crystals, Formations, Ruins.md`, `20 - Object Placement.md`, `22 - Native Structures & Datapacks.md`.
+
+## Architecture (author-relevant)
+
+1. Dimension `carvingEnabled` must be true (default).
+2. Per column, Iris resolves a cave profile from biome → region → dimension (`enabled` profiles only).
+3. Profiles blend across neighbors; `IrisCaveCarver3D` samples 3D density and writes carve flags into the mantle.
+4. Cave biomes (region `caveBiomes`, dimension `carving` Y-band overrides, surface biome `carvingBiome`) supply materials and content for carved voxels.
+5. Fluid placement inside caves follows profile water/lava rules and surface-clearance guards.
+
+Empty pack folders such as `caves/` or `ravines/` are not separate registrant types. Carving is profile-driven JSON on dimensions/biomes/regions, not standalone cave files.
+
+## Vanilla carvers never run
+
+Iris does not implement Minecraft `NoiseGeneratorSettings` carver sampling. Generated biome JSON keeps empty `carvers` arrays. `applyCarvers` on the Iris chunk generator is a no-op for Iris-owned terrain. Pack authors must use `caveProfile` (and related cave biomes), not vanilla carver JSON or datapack carver features. See also platform notes in `30 - Platform Differences.md` / API matrix.
+
+## Dimension gates
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `carvingEnabled` | boolean | `true` | Master switch for all profile carving |
+| `caveProfile` | `IrisCaveProfile` | disabled defaults | Global/default profile |
+| `carving` | `IrisDimensionCarvingEntry[]` | `[]` | Absolute world-Y cave biome bands |
+| `caveBiomeStyle` | `IrisGeneratorStyle` | cellular | Picks among region cave biomes |
+| `requireObjectSurfaceSupport` | boolean | `true` | Refuse surface objects over carve openings |
+| `objectSurfaceSupportBuffer` | int 0..16 | `2` | Minimum solid buffer for surface objects |
+| `upperDimensionCarving` | boolean | `false` | Carve through ceiling/upper terrain when set |
+| `useMantle` | boolean | `true` | Mantle required for carving/objects |
+
+## Cave profile (`IrisCaveProfile`)
+
+Snippet key: `cave-profile`. Appears on **dimension**, **region**, and **biome**. Resolution prefers the most specific enabled profile in the mantle path (biome/region/dimension blend).
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `enabled` | boolean | `false` | Must be true to carve |
+| `verticalRange` | `IrisRange` | `0..384` | Global carve Y band for the profile |
+| `verticalEdgeFade` | int 0..128 | `20` | Soft edge near min/max |
+| `verticalEdgeFadeStrength` | double 0..1 | `0.18` | Fade strength |
+| `baseDensityStyle` | `IrisGeneratorStyle` | cellular iris double | Primary density field |
+| `detailDensityStyle` | `IrisGeneratorStyle` | simplex | Detail field |
+| `warpStyle` | `IrisGeneratorStyle` | flat | Coordinate warp |
+| `baseWeight` | double ≥ 0 | `1` | Base field multiplier |
+| `detailWeight` | double ≥ 0 | `0.35` | Detail multiplier |
+| `warpStrength` | double ≥ 0 | `0` | Warp amount |
+| `densityThreshold` | `IrisStyledRange` | ±0.2 cellular | Carve cutoff band |
+| `thresholdBias` | double 0..1 | `0.16` | Extra bias subtracted before tests |
+| `sampleStep` | int 1..8 | `1` | Vertical density step |
+| `adaptiveSampling` | boolean | `true` | Coarse predictor then refine |
+| `adaptiveSampleStep` | int 2..4 | `2` | Horizontal predictor grid |
+| `adaptiveThresholdMargin` | double 0..1 | `0.04` | Ambiguity margin |
+| `surfaceClearance` | int 0..64 | `4` | Min solid below terrain before carve |
+| `allowSurfaceBreak` | boolean | `true` | Permit selected surface openings |
+| `surfaceBreakStyle` | style | simplex zoomed | Where openings may occur |
+| `surfaceBreakNoiseThreshold` | double -1..1 | `0.62` | Min noise for break columns |
+| `surfaceBreakDepth` | int 0..64 | `18` | Depth window for break logic |
+| `surfaceBreakThresholdBoost` | double 0..1 | `0.2` | Easier carve near surface break |
+| `objectMinDepthBelowSurface` | int 0..64 | `6` | Cave-object depth gate |
+| `modules` | `IrisCaveFieldModule[]` | `[]` | Extra density layers |
+| `defaultObjectAnchor` | `IrisCaveAnchorMode` | `FLOOR` | Cave object anchor default |
+| `defaultObjectPlaceMode` | `ObjectPlaceMode` | null | Prefer stilt modes for cave props |
+| `anchorScanStep` | int 1..8 | `1` | Vertical anchor search step |
+| `anchorSearchAttempts` | int 1..64 | `6` | Random column retries per chunk |
+| `allowWater` | boolean | `true` | Cave water below fluid height |
+| `waterMinDepthBelowSurface` | int 0..64 | `12` | Depth before cave water |
+| `waterRequiresFloor` | boolean | `true` | Solid floor under water |
+| `allowLava` | boolean | `true` | Cave lava by lava height rules |
+
+### Density module (`IrisCaveFieldModule`)
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `style` | `IrisGeneratorStyle` | cellular | Module density |
+| `weight` | double ≥ 0 | `1` | Contribution |
+| `threshold` | double -1..1 | `0` | Pre-blend offset |
+| `verticalRange` | `IrisRange` | `0..384` | Module Y window |
+| `invert` | boolean | `false` | Invert before weighting |
+
+### Anchor modes (`IrisCaveAnchorMode`)
+
+| Value | Meaning |
+|-------|---------|
+| `PROFILE_DEFAULT` | Use profile default |
+| `FLOOR` | Solid support below carved cell |
+| `CEILING` | Solid support above |
+| `CENTER` | No immediate floor/ceiling support |
+| `ANY` | Any carved anchor |
+
+## Dimension carving entries (`IrisDimensionCarvingEntry`)
+
+Absolute world-Y cave biome overrides independent of surface biome.
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `id` | string | `""` | Stable id (child references) |
+| `enabled` | boolean | `true` | Toggle |
+| `biome` | biome key | `""` | Cave biome applied in band |
+| `worldYRange` | `IrisRange` | `-64..320` | Absolute world Y |
+| `children` | string[] | `[]` | Child entry ids (cycles allowed, depth-limited) |
+| `childShrinkFactor` | double | `1.5` | Child patch scale |
+| `childStyle` | style | cellular | Child patch shape |
+| `childRecursionDepth` | int | `3` | Max child resolve depth |
+
+## Cave biomes (content)
+
+Cave biomes are normal biome JSON used only underground:
+
+| Mechanism | Location | Role |
+|-----------|----------|------|
+| Region `caveBiomes` | region JSON | Pool selected by `caveBiomeStyle` |
+| Biome `carvingBiome` | surface biome | Optional fixed carve biome under that surface |
+| Biome `caveMinDepthBelowSurface` | surface biome | Min depth before that carve biome applies |
+| Dimension `carving[]` | dimension | Y-band force biomes |
+| Biome `caveProfile` | any biome | Local carve density override when enabled |
+| `layers` / `caveCeilingLayers` / `wall` | cave biome | Floor / ceiling / wall materials |
+| `decorators` with `partOf: CEILING` | cave biome | Hang from ceilings |
+| `objects` / `proceduralObjects` | cave biome | Cave props (`carvingSupport: CARVING_ONLY`) |
+
+Surface biomes still provide height generators; cave biomes typically omit height generators or use fillers—the carve step removes solid first.
+
+## Overworld examples
+
+Dimension switch and deepdark band (`dimensions/overworld.json`):
+
+```json
+{
+"carvingEnabled": true,
+"caveProfile": {
+  "enabled": true,
+  "verticalRange": { "min": 6, "max": 700 },
+  "baseDensityStyle": { "style": "PERLIN_IRIS", "zoom": 0.72 },
+  "detailDensityStyle": { "style": "SIMPLEX", "zoom": 0.54 },
+  "warpStyle": { "style": "FRACTAL_WATER", "zoom": 0.5 },
+  "baseWeight": 0.9,
+  "detailWeight": 0.11,
+  "warpStrength": 0.24,
+  "densityThreshold": {
+    "min": -0.14,
+    "max": -0.06,
+    "style": { "style": "SIMPLEX", "zoom": 0.74 }
+  },
+  "thresholdBias": 0.14,
+  "sampleStep": 3,
+  "surfaceClearance": 5,
+  "allowSurfaceBreak": true,
+  "surfaceBreakStyle": { "style": "SIMPLEX", "zoom": 0.88 },
+  "surfaceBreakNoiseThreshold": 0.6,
+  "surfaceBreakDepth": 16,
+  "surfaceBreakThresholdBoost": 0.1,
+  "objectMinDepthBelowSurface": 14,
+  "defaultObjectAnchor": "FLOOR",
+  "defaultObjectPlaceMode": "ORGANIC_STILT",
+  "anchorSearchAttempts": 12,
+  "allowWater": true,
+  "waterMinDepthBelowSurface": 20,
+  "waterRequiresFloor": true,
+  "allowLava": true,
+  "modules": [
+    {
+      "style": { "style": "SIMPLEX_VASCULAR", "zoom": 1.08 },
+      "weight": 0.08,
+      "threshold": 0.03,
+      "verticalRange": { "min": 24, "max": 660 },
+      "invert": false
+    }
+  ],
+  "verticalEdgeFade": 24,
+  "verticalEdgeFadeStrength": 0.18
+},
+"carving": [
+  {
+    "id": "global-deepdark-band",
+    "enabled": true,
+    "biome": "carving/standard-deepdark",
+    "worldYRange": { "min": -250, "max": -175 }
+  }
+]
+}
+```
+
+Region cave pool (`regions/temperate.json`):
+
+```json
+{
+"caveBiomes": [
+  "carving/rocky-cavebiome",
+  "carving/deep",
+  "carving/drip",
+  "carving/chalk-gardens",
+  "carving/moss-pillars"
+]
+}
+```
+
+Cave biome content (`biomes/carving/amethyst.json` excerpt): floor/wall amethyst, floor buds, ceiling-facing clusters via `"partOf": "CEILING"`, `caveCeilingLayers` for roof materials.
+
+## Authoring workflow
+
+1. Enable dimension `caveProfile` with a vertical range covering playable Y.
+2. Add `modules` for tunnels/rooms instead of raising `detailWeight` alone.
+3. List themed biomes under each region's `caveBiomes` (and optional dimension `carving` bands).
+4. Paint cave biomes with `layers`, `caveCeilingLayers`, `wall`, ceiling/floor decorators, and cave-only objects.
+5. For surface sinkholes, keep `allowSurfaceBreak` true and tune `surfaceBreak*` noise; for sealed caves raise `surfaceClearance` and disable surface break.
+6. Place cave objects with `carvingSupport: CARVING_ONLY` and stilt place modes (`FAST_MIN_STILT` / `ORGANIC_STILT`) to avoid floating props.
+7. Verify: studio regen, check openings, waterfalls (`waterRequiresFloor`), and lava depth.
+
+## Tuning knobs (quick)
+
+| Goal | Adjust |
+|------|--------|
+| Larger caverns | Lower `densityThreshold` band / raise bias toward carve |
+| Thinner tunnels | Raise threshold, lower `detailWeight`, add inverted modules |
+| Fewer surface holes | Raise `surfaceBreakNoiseThreshold`, lower `surfaceBreakDepth`, or `allowSurfaceBreak: false` |
+| Safer cave props | Raise `objectMinDepthBelowSurface`, set place mode + anchor |
+| Dry caves | `allowWater: false` |
+| Performance | Higher `sampleStep`, keep adaptive sampling on, simpler styles |
+
+## Practical notes
+
+- Profile `enabled: false` (the Java default) produces no profile carving even if cave biomes are listed.
+- Cave biome layers still need solid carve first; they do not create voids alone.
+- Upper-dimension carving is optional and off in overworld.
+- Pack JSON may contain unknown keys; only fields on `IrisCaveProfile` apply.