d

docs/91 - API - Terrain.md

@@ -2,6 +2,8 @@
 
 `art.arcane.iris.api.terrain` answers what the Iris generator says about a coordinate: whether a world is Iris-generated, which biome and region the pack places, surface height, and whether that surface is land, shore, ocean, or void. It reads the **generator**, not the world: no chunk load, no forced generation, no placed-block read, and no knowledge of player edits. Reads are non-blocking noise evaluation over a shared per-chunk cache.
 
+Reach for it when you need the pack's intent for a coordinate without paying to generate it: picking a base or settlement site, rendering a map or minimap, planning a pregen region, gating a feature on "is this an Iris world", or labelling a HUD with the pack biome. If you need the blocks a player can actually see — including objects, structures, and edits — you want Bukkit's world API instead.
+
 Build and service acquisition: `90 - API - Getting Started.md`. Service: `IrisTerrainService`, registered at `ServicePriority.Normal` for Iris's enabled lifetime.
 
 ```java
@@ -141,6 +143,8 @@ Constructor rejects with `IllegalArgumentException`:
 - `maxBlockX < minBlockX` or `maxBlockZ < minBlockZ`,
 - `strideBlocks < 1`.
 
+Null `fields` throws `NullPointerException`.
+
 `fields` is defensively copied on construction and on every `fields()` call. `fields()` allocates a fresh `EnumSet` each call — hoist it out of loops.
 
 `columnCount()` and `chunkCount()` saturate at `Long.MAX_VALUE` on overflow.
@@ -175,10 +179,12 @@ Every column produces one `accept`. Placeholders for unrequested fields are not
 |---|---|---|---|
 | `SURFACE_HEIGHT` | `surfaceHeight` | absolute world Y of topmost terrain | `-1` |
 | `SURFACE_KIND` | `kind` | `LAND`, `SHORE`, `OCEAN`, or `VOID` | `IrisSurfaceKind.UNKNOWN` |
-| `BIOME_KEY` | `biomeKey` | biome load key | `null` |
+| `BIOME_KEY` | `biomeKey` | surface biome load key | `null` |
 
 `-1` is a legal absolute Y in worlds with negative min height — **never treat `-1` as absent**. Branch on your field set. `biomeKey` may be `null` even when requested if the column has no biome.
 
+The sink's `biomeKey` is the **surface** biome — the same value `surfaceBiomeKey` returns for that column, never a cave biome. There is no 3D equivalent of `biomeKey(world, x, y, z)` in a column walk.
+
 Fewer fields cost less. `SURFACE_KIND` alone skips the biome stream for void-floor and at-or-below-fluid columns. `BIOME_KEY` pays for the biome stream every column.
 
 ### Visit order
@@ -318,6 +324,8 @@ public final class SettlementSiteFinder {
 
 `Best` needs no synchronisation: the sink runs inline on the `sampleColumns` caller thread.
 
+`Player#getScheduler()` is Paper/Folia only. On Spigot, hop back with `Bukkit.getScheduler().runTask(plugin, () -> player.sendMessage(result))`.
+
 ---
 
 ## The minimum: one coordinate