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

{
  "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.

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 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 and needs additional authored biomes for a multi-biome distribution.

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 Pages creative tab 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.