rivencraft/docs/AGE_PROFILES.md

# Age runtime profiles

Rivencraft loads Age runtime profiles from server data packs at
`data/<namespace>/rivencraft/age_profiles/<name>.json`. The resulting profile ID
is `<namespace>:<name>`. Profiles select registered world-generation resources;
they do not contain an Age's seed, name, spawn, or rolled traits.

## Schema version 1

```json
{
  "schema_version": 1,
  "terrain": "noise",
  "noise_settings": "minecraft:overworld",
  "biome_preset": "minecraft:overworld",
  "dimension_type": "minecraft:overworld"
}
```

`terrain` is `noise`, `flat`, or `void`. Noise profiles require
`noise_settings` and `biome_preset` references. Every profile requires a
`dimension_type` reference. Omitted resource references use the Overworld
entry. Rivencraft validates all referenced entries against the loaded dynamic
registries during data-pack reload. An invalid profile is rejected.

The built-in profile IDs are `rivencraft:standard`, `amplified`, `island`,
`cave`, `flat`, and `void`. Their JSON files are ordinary built-in data-pack
resources and can be overridden by a higher-priority pack. The example under
`docs/example-age-profile-pack` can be copied into a world's `datapacks`
directory. Valid custom profiles join the stable, sorted pool used when a new
Age rolls its base terrain; the selected ID is then persisted with that Age.

Each built-in profile now has a matching `terrain/<name>` Symbol Page. Put one
of those pages after the Link Panel in a Book Binder to select that terrain
instead of the seed-selected random profile. Standard, Amplified, and Cave use
their corresponding registered noise settings; Island uses Minecraft's
floating-islands noise settings; Flat and Void use flat-source generators.
The Cave and Island pages are Rivencraft terrain choices based on existing
profiles, not claims that Legacy had identically named terrain symbols.
Every family retains a safe cobblestone arrival platform. An omitted terrain
page still uses the deterministic seed-selected profile.

The separate **Floating Islands** feature page adds rare high-altitude island
clusters above Standard, Amplified, Sky Islands, Flat, or Void terrain; it does
not replace the terrain page. The feature is seeded by the Age and saved with the written
plan, so revisiting an Age recreates the same islands. Without a preceding
Block page, the Age seed chooses one valid full-collision block from the Block
Pages pool for the island body. A full-block material page immediately before
Floating Islands overrides that choice. Ordinary surface biomes still get
dirt/grass top layers; Nether and End biomes use the chosen block throughout.
The feature is additive even on Sky Islands terrain,
which already forms its own islands. Cave terrain rejects it. A page-free random
Age may also roll Floating Islands as one of its material features.

An unpaired Block or Fluid page chooses a compatible feature from the Age seed:
full blocks can become Rocks or Floating Islands; source fluids can become one
of the lake features. Flat and Void terrain can only use Floating Islands from
this pool, while Cave terrain has no compatible material feature. A page-free
random Age rolls zero, one, or two distinct compatible features, choosing each
material from the Block or Fluid Pages pool. The choices are saved on the Age
definition, so opening the Age again does not reroll them.
Repeated Block/Fluid and Feature pages remain separate entries in authored
writing. Each unpaired material gets its own compatible feature, and repeated
decorations use separate placement rolls. Repeated unmodified feature pages
choose different compatible materials until their material pool is exhausted.

For an in-game visual check, bind Descriptive Books with a Link Panel,
one of Standard, Amplified, Sky Islands, Flat, or Void terrain, and the Floating Islands
feature page in that order. Fly through each Age at roughly Y=170–220 and
verify the elevated clusters appear above its unchanged base terrain. Reopen
the same Age to check that island positions stay fixed. Islands should be less
common than in the first test build (one source chunk in 128 instead of 64).
Sky Islands should retain its terrain islands and gain occasional additional
feature islands. Try Cave terrain too; the Binder should reject that pairing.

The **Tendrils** feature adapts Legacy's winding, branching cave-node geometry
into solid tubes. It is additive on all current terrain families, including
Flat, Void, and Cave; it does not change biome selection. A preceding full-
collision Block page chooses the tendril material. Otherwise the Age seed
chooses a valid Block Pages material, consistent with other authored material
features. Page-free random Ages can select Tendrils as a solid-material feature,
including on Cave terrain where the surface material features are unavailable.
The shape and placement use only the Age seed and source-chunk coordinates, so
revisiting an Age recreates the same geometry.

For a clear visual check, bind a Void Age with a Glowstone Block page followed
by Tendrils. Fly around world Y=0–120 across several chunks: branching solid
forms should appear in the otherwise empty dimension, continue across chunk
borders, and remain in place after leaving and returning. Repeat with a lone
Tendrils page to confirm its seed-chosen material, and with Cave terrain to
confirm the feature does not require a surface biome.

## Written biome selection (generation version 16)

Biome pages follow the terrain page and precede the distribution-control page
in the Binder. Bundled controls are Native, Single, Tiled, Grid, and Tiny through
Huge regions. Single needs one distinct biome; Tiled/Grid and Tiny–Huge need
two. An authored book receives seeded filler only when it falls below that
minimum, while extra authored pages are retained as weighted entries. A book
with no biome pages selects a seeded count from two up to the number of
eligible biomes for Tiled/Grid and Tiny–Huge. The eligible pool comes from the
terrain's biome preset, or `#rivencraft:cave_biomes` for Cave terrain, so future
biome integrations can expand it without changing the count rule. Single uses
one; Native uses its preset biome pool. This random-age maximum does not truncate
authored pages: the Binder's 27 symbol-page positions bound an authored book.
Native cannot be paired with explicit biome pages. Legacy filled Tiny–Huge to
three; Rivencraft deliberately uses two so a pair of written biome pages stays
exactly as written.
The Biome Pages creative tab offers pages for every registered vanilla biome.
Hand-authored symbol definitions take precedence; the remaining vanilla pages
are generated from the biome registry, so they do not each need a JSON file.
Custom/modded biomes still require a data-pack symbol definition.

Standard, Amplified, and Sky Island terrain fill from the vanilla Overworld
biome preset, including its underground Lush Caves, Dripstone Caves, and Deep
Dark biomes. Standard terrain therefore keeps Overworld-style cave generation,
and cave biome pages can also be written explicitly. Sky islands can use an
explicitly authored End biome page.
Cave terrain fills only from `#rivencraft:cave_biomes` (Lush Caves, Dripstone
Caves, and Deep Dark by default); explicitly authored Nether biome pages are
also accepted. Other cave/biome pairings are diagnosed and blocked for now.
Milestone 6 instability should allow such illegal combinations as unstable
Ages, without silently treating them as ordinary cave generation. Flat terrain
uses Overworld choices when a distribution is authored; its Native default
remains Plains. Void terrain defaults to The Void when no biome page is written,
but accepts authored biome pages. One authored biome uses Single distribution
when no controller is written. An explicit multi-biome distribution needs enough
authored biomes; The Void is not silently added to fill missing positions. These
biome regions exist even without blocks or a Floating Islands page, so biome-
dependent weather and optional season behavior can still vary there. To check
this in-game, bind Void terrain with a Desert Biome page and no feature page:
the Age should be empty while F3 reports Desert. A Void book without biome
pages should instead report The Void.

The resolved list of biome IDs, their order/repetitions, and distribution are
frozen into the Age plan. A removed biome ID emits a warning and uses an
eligible fallback for that load; restoring the biome recovers the original
selection. Generation-version-15 Ages keep their prior registry-wide biome
selection algorithm instead of being silently regenerated.

## Written environment

Lighting pages select Normal, Dark, or Bright lighting for the new Age. A Sky
page selects Minecraft's Overworld, Nether, or End sky effects; the chosen
effects also determine the destination preview backdrop. Overworld sky tint
continues to come from the destination biome. A written sky changes only that
Age's dimension type, not the source world or other Ages.

Normal, Fast, Slow, Off, Always, and Storm weather pages use the existing Age
weather controller. Zero, Half, Full, and Double Length pages set the day-cycle
period, and Nadir, Rising, Zenith, and Setting pages set its initial phase.
Repeated numeric modifiers combine in written order. A Zero Length Age keeps
the nonzero minimum clock rate that avoids client skybox bounce. Pages for
Cloudy, forced Rain, and Snow are not offered: vanilla precipitation rendering
cannot reproduce those Legacy distinctions yet, and Snow remains planned for
the optional season integrations. A data pack that supplies these unsupported
weather choices receives a binding error rather than a false success.

The category creative tabs and optional JEI page ingredients use the same generated
index of bundled environment symbols. Existing Age definitions and page-free
random Ages retain their saved or seeded environment unchanged.

## Persistence and reload behavior

An Age permanently stores its selected profile ID, generation version, seed,
and rolled traits. For an **authored** Age, the generation plan also stores a
copy of the resolved runtime profile: terrain shape, noise settings, biome
preset, and dimension type. `/reload` cannot reinterpret that plan; an unloaded
authored Age uses the saved profile snapshot when it loads, even if the defining
symbol or profile JSON has since changed. An older, page-free Age has no plan
and continues to resolve its saved profile ID at load time.

Registered noise, biome-preset, and dimension-type IDs are validated when
profiles load. Before loading an authored Age, the saved references are checked
again. If a data pack supplying one has been removed, the dimension stays
unloaded and the log identifies the missing resource; the Age's plan is not
silently replaced. Restore the pack to load that Age. A custom dimension type
retains its own skylight capability: normal lighting cannot make a Nether-style
type skylit.

A profile removed after a page-free Age was created resolves to `rivencraft:standard`.
The legacy `rivencraft:random_vanilla` alias also resolves to `standard`.
Rivencraft logs this fallback. Invalid built-in overrides do not replace the
required built-in definitions; a reload fails if a required built-in profile
is absent after resource resolution.

Only schema version 1 is accepted. A future schema change must add an explicit
migration path before incrementing the version. The saved Age generation
version remains independent of this data-pack schema and is never silently
rewritten.