Files
rivencraft/docs/NATIVE_BIOME_FAMILIES.md
T
2026-11-17 18:12:07 -05:00

140 lines
7.4 KiB
Markdown

# Native biome families — issue #111
Release builds: **1.21.1.0.6** and **26.3.0.10**. Player in-game validation passed on both versions (2026-11-17).
## Pages and terrain
| Controller Page | Biome selection |
| --- | --- |
| Native | Existing terrain default. On new Cave Ages, non-Nether cave biomes only. |
| Native Caves | All recognized non-Nether caves, using seeded regional placement. |
| Native Nether | All recognized Nether biomes, using seeded regional placement. |
| Native End | All recognized End biomes, using seeded regional placement. |
The three explicit family controllers work with Standard, Amplified, Island,
Cave, Flat and Void terrain. The **Terrain Page still controls geometry**.
Void stays empty; its biomes can affect weather and seasons. These controllers
do not select a sky style, dimension type or season.
The player chose **seeded regional layout including modded biomes** for Native
Nether/End, rather than vanilla climate or End-island placement. The family
controllers use the established Native Cave/Tiny regional scale (16-block
base cells), across the whole frozen family pool. A single available biome
uses a FixedBiomeSource.
Native controllers select their own pool. Individual biome Pages before one
retain the existing conflict/recovery rule: the manual biome entries are
discarded and instability applies. To choose/weight individual Nether biomes
on Cave terrain, use Single/Tiled/region controllers as before.
## Classification
- Caves: `rivencraft:cave_biomes`, including optional `c:is_cave`, plus
recognized vanilla cave keys. 26.3 retains its new **Sulfur Caves** biome.
- Nether: `minecraft:is_nether` **or** membership in a TerraBlender Nether
region. No mod-specific name list or namespace heuristic is used.
- End: `minecraft:is_end` and known vanilla End members. TerraBlender exposes
Overworld and Nether regions, not an End region in either supported API.
- Nether classification wins over Cave tagging for Native Caves, including
a biome that belongs to a Nether region but lacks `is_nether`.
- TerraBlender's internal deferred placeholder is never a native-family biome.
Family pools are sorted and deduplicated. Vanilla family members provide safe
fallbacks when broad tags are empty; Cave fallbacks are still checked against
Nether classification. A one-biome pool remains valid. If no cave family member
can be used at all, a registered non-Nether biome is the last-resort safety
fallback; an entirely unusable registry reports a binding error.
The broader Cave-compatible authoring pool is preserved. Explicit Nether
biome Pages on Cave terrain remain legal and retain existing materials.
Other terrain eligibility and non-Native distributions are not filtered by
this new default-pool rule.
## Random Ages and persistence
Ordinary random-Age controller ranks remain unchanged. When random or
seed-completed writing resolves to Cave terrain + Native, its new pool excludes
Nether biomes. The new family Pages are explicit authoring choices; they are
not added as extra rank tickets to the random controller deck.
The selected family is saved separately from the existing NATIVE distribution
enum, so seeded distribution ordinals/ranks do not change.
- Authored 1.21.1 plans save optional `NativeKind` with their frozen biome IDs.
- New random Native Cave Ages in 1.21.1 generation version **18** also save
`RandomBiomes` in the Age definition. Spawn updates and reseeding retain it.
- 26.3's existing frozen biome plan saves optional `native_kind`. Random Native
Cave Ages now explicitly freeze the CAVES family.
- Missing family fields on old saves mean TERRAIN and **do not re-filter the
old list**. Existing frozen Cave pools containing Nether biomes are preserved.
- Unplanned generation-16/17 Native Cave Ages retain their prior broad pool
algorithm; older Ages retain their existing legacy generator. They are not
silently migrated to the new family default.
- Regions use the Age seed; reseeding can change spatial placement in future
chunks while retaining the selected IDs. Existing chunks are not rewritten.
On 26.3, authored noise-terrain generation can now construct a vanilla noise
baseline when the primary Overworld is Flat/custom rather than a Noise generator.
This allows the independent Native-family/terrain pairing in that setup instead
of failing with “Overworld generator cannot accept authored noise settings.”
The existing path for an ordinary noise Overworld is unchanged. Issue #115's
separate material-abundance baseline work is not completed by this fix.
## Creative, JEI and loot policy
All three new JSON-backed controllers enter the existing **biome generation**
Creative category and optional JEI page feed. Glyphs use the existing component
renderer and poems; no new generated texture or recipe is needed.
Native/Cave tooltips explain the default-pool rule.
Page allow/block lists categorize the new IDs as biome controllers, separately
from individual biome IDs. Manual authoring is still unaffected by those lists.
Normal library eligibility can expose the new Pages; Age-only loot uses the
Age's own written/result Pages.
## Verification
Run one target at a time:
```sh
python3 scripts/regression_native111.py mc1211
python3 scripts/regression_native111.py mc263
python3 scripts/regression_native111.py mc1211 --biome-mods
python3 scripts/regression_native111.py mc263 --biome-mods
```
The optional-mod checks use the installed Dev instance's BOP/TerraBlender/
GlitchCore JARs. Every run uses the host-wide server lock, a new temporary
world, isolated fixture output and a 60-second stall handoff. Worlds and fixture
outputs are deleted on pass or fail; logs remain in
`build/verification/native111/`. The fixture code is not shipped in the mod
or added to the default GameTest deck.
Results: **91 checks per version without biome mods; 94 per version with
BOP/TerraBlender**. Coverage includes:
- All three explicit family controllers on all six terrains.
- Explicit Native, seed-completed Native and random Native Cave selection.
- Overlapping Cave/Nether tags, region-only Nether membership, empty-tag
fallback, a valid single-cave saved pool and optional-mod absence.
- Explicit Crimson Forest + Cave + Single authoring.
- Frozen plan/codec and root random-Age registry save/load behavior.
- Preservation of an older mixed Cave/Nether snapshot without a family field.
- Controller-policy categories, last-controller recovery, and new Creative/JEI index entries.
- 26.3 runtime source overrides on Standard, Void and Cave, including a Flat
primary world. Actual world appearance remains player validation.
### Player checks — both versions
1. Create **Cave + Native** Ages and explore: no Nether biomes should be selected.
Revisit after restart; the chosen cave pool should remain stable.
2. Try Native Caves, Native Nether and Native End with Standard or Flat terrain.
Confirm their biome IDs and normal travel, including optional BOP biome IDs.
3. Try those family Pages on Void terrain: no terrain should be added solely
by the controller. Biome-based weather/season behavior can still apply.
4. Create **Cave + Crimson Forest + Single** to confirm explicit Nether authoring
still works. Native End on Cave should also bind through the explicit family.
5. Verify all three Pages appear under biome generation in Creative and JEI.
6. Reopen an older Native Cave Age if available. Its saved mixed pool is kept;
create a new Age to test the new default rather than expecting migration.