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.

Cave terrain and Legacy

Legacy's closest terrain generator is its Nether terrain symbol: it owns an Age-seeded octave-noise generator, accepts terrain/sea materials, and sets a sea level of 32. Legacy's separate Caves symbol instead registers a terrain alteration that carves additional caves; it is not a terrain generator. Minecraft 1.21.1 no longer has Legacy's 1.12.2 height and generation pipeline, so Rivencraft Cave terrain uses minecraft:caves noise and the modern Cave, Nether, and tagged modded Nether biome decorations. It cannot reproduce the exact Legacy noise or its older vertical layout. The Caves feature page remains a separate additive carver for other suitable terrain.

Cave Ages search for safe spawn footing from Y=64 downward rather than using the cave roof; if necessary, the usual cloud platform is placed at Y=63. Weather is clear and Serene Seasons is disabled in Cave terrain. Authored Weather, Season, and Celestial pages (including time modifiers) are retained in the book but have no effect on the Cave Age; each adds 100 base instability. The same policy applies to randomly selected Cave terrain and persists through save/reload. Cave biome selections remain limited to Cave and Nether biomes; surface-biome completion is not used for Cave terrain.

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, Floating Islands, Tendrils, Spheres, or Spikes; source fluids can become one of the lake features. Flat terrain can use Floating Islands, Tendrils, Spheres, or Spikes; Void can use Floating Islands, Tendrils, or Spheres; Cave can use Spheres or Tendrils. A page-free random Age rolls zero, one, or two distinct compatible material 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.

Structure pages are separate Feature symbols. Legacy's Dungeons, Mineshafts, Nether Fortresses, Strongholds, and Villages have writable pages, as do modern Trial Chambers, Bastion Remnants, Buried Treasure, Shipwrecks, Ocean Ruins, Pillager Outposts, Ruined Portals, Nether Fossils, Ancient Cities, and Trail Ruins. They use Minecraft's 1.21.1 structure templates and placement rules, not a recreation of 1.12.2 structure geometry. A page enables only its own structure set; absent pages do not inherit these structures from a biome. Nether Fortresses and Bastions use separate sets instead of vanilla's shared Nether-complexes set, so writing one does not enable the other. Dungeons use the vanilla monster-room feature with eight attempts per chunk; unpaged Ages do not inherit biome-default monster-room attempts. A page-free random Age may choose zero to two distinct compatible structure types, frozen on creation. An authored structure needs a compatible biome in the Age's selected pool. Fortresses, Bastions, and Nether Fossils require Cave terrain plus a Nether biome; surface-only structures reject Cave terrain. Void rejects all of these structure pages. Villages and Strongholds can also be written into Flat Ages.

For visual testing, write a Standard/Plains/Single Age with Mineshafts, Villages, and Trial Chambers, then use /locate structure in that Age to find each. An unwritten Pillager Outpost should not locate there. Test a Cave Age with Nether Wastes/Single and either the Nether Fortresses or Bastion page: only the selected type should locate. Ocean structures need their matching ocean or beach biome page; Ancient Cities need Deep Dark. Check the new pages in Rivencraft's Feature creative tab and JEI as well.

Dense Ores is an authored-only Feature page. Each copy replays one extra pass of every ore placement registered in the Age's nearby biomes, using that placement's existing height, vein-size, rarity, and biome rules. It therefore also densifies conventional mod-added ores without hard-coded mod IDs. Output blocks tagged c:ores qualify; OreConfiguration outputs with _ore in their registry name also qualify. A mod with a custom, non-OreConfiguration placed feature can opt in by tagging that feature rivencraft:dense_ores. Non-ore stone/dirt blobs are not repeated. Flat and Void reject the page, as does a biome pool without any ore placements. Page-free random Ages never roll Dense Ores. The extra pass applies only as new chunks generate; it does not retrofit existing chunks or discover ore systems that bypass biome placed features.

For an in-game check, write a Standard/Plains/Single Age with Dense Ores and verify that new underground chunks contain visibly more vanilla ore while stone/dirt blob frequency remains unchanged. With an ore-adding mod installed, write an Age using a biome where that mod registers its ore and verify the ore also appears more often. Check that Flat plus Dense Ores is rejected by the Binder and that a random, Link-Panel-only Age has no Dense Ores feature page.

Obelisks adds Legacy-shaped, rare 4×4 plinths with a 2×2 shaft rising 12 blocks, at most one attempt per 128 chunks per page. A preceding full-block Block page chooses the material; otherwise the Age seed chooses from valid block pages. Repeated Obelisks pages make independent attempts. Generation is deterministic and stays within one chunk; it requires a reasonably level, exposed solid surface, so Cave and Void terrain reject the page. Standard, Amplified, Sky Islands, and Flat terrain permit it. Page-free random surface Ages can roll Obelisks as one of their material features.

For a visual check, write a Standard or Flat Age with an Obelisks page and search newly generated terrain for the 4×4 base and 12-block shaft. Try a Block page such as Obsidian immediately before Obelisks to verify its material changes. The Binder should reject Obelisks in Cave and Void Ages. Placement is deliberately rare, so several hundred fresh chunks may be needed.

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.

Skylands is a separate subtractive feature, not the Sky Islands terrain profile or the additive Floating Islands feature. Following Legacy's primer filter, it removes base terrain below a smooth, seven-octave cutoff around world Y=76 and removes liquid above the cutoff. The selected terrain still generates first; Floating Islands and Tendrils are added afterward, so they can coexist with Skylands. Skylands has no Block-page modifier. It can be authored on every terrain, though Flat loses its low ground and Void has no base terrain to change. Page-free random noise Ages have a seeded one-in-eight chance to gain Skylands; random Flat and Void Ages do not roll this ineffective filter. The cloud-height and horizon changes from Legacy are not included yet.

For an in-game check, compare Standard terrain with and without a Skylands page. Skylands should leave upper hills suspended over open space, while a Floating Islands page instead adds isolated high islands without removing the ground below. Try Sky Islands terrain plus Skylands to confirm the page filters the terrain rather than replacing its generator. A book with both Skylands and Floating Islands should retain the added feature islands above the cutoff.

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.

Spheres and Spikes are two separate Feature pages. Spheres adds winding chains of solid sphere nodes within terrain generation; like Tendrils, it works on all terrain families, even Void and Cave. Spikes is a later, rarer surface decoration (roughly one attempt per 18 chunks) that rises from solid ground on Standard, Amplified, Sky Islands, or Flat terrain. Cave and Void reject the Spikes page because they do not provide a suitable exposed surface. Each page accepts its own immediately preceding full-collision Block page; without one, the Age seed chooses a compatible material. The pages remain distinct in the catalog, Creative menu, JEI, ordered writing, and saved Age definition. Page-free random Ages can select either where compatible.

For an in-game check, make separate Void/Spheres and Flat/Spikes books with Glowstone Block pages directly before their respective Feature pages. Spheres should form connected bright globes across chunk boundaries in Void; Spikes should appear as rare upward clusters rooted on the Flat surface. Revisit the same Ages to confirm stable locations. Check that a Void/Spikes book is rejected, and that Spheres and Spikes remain two independently selectable pages in Creative and JEI.

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 252 symbol-page positions bound an authored book. Legacy's Binder itself had no explicit page-count check; this remains a fixed-slot storage ceiling. 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.