rivencraft/docs/AGES.md

Age creation and administration

Creation

A page-free Descriptive Book creates an Age when the player assigns a name and presses Create. Rivencraft immediately assigns a UUID, derives a unique Minecraft-safe dimension identifier from the requested name, rolls a seed and traits, and persists that definition before asking Dynamic Dimensions to create the runtime world. Names that normalize to the same identifier receive stable suffixes such as _2 and _3.

The selected terrain profile, biome distribution, lighting, weather, celestial period, celestial angle, and phase are deterministic and become part of the saved definition. A five-by-five cobblestone platform with clear headroom is prepared at a safe arrival point. The completed book and every copy carrying the same UUID resolve to that definition.

Creating an Age can take several ticks. The book cannot be reopened while its creation request is active. If creation is interrupted after the definition is saved, using the book again resumes from the same immutable definition instead of rolling a replacement.

Persistence

Rivencraft owns each Age definition for the lifetime of a world. A definition contains the Age UUID, canonical name, seed, generation version, runtime dimension identifier, spawn, and deterministic traits. Definitions are stored in the Overworld saved data and are never rerolled during ordinary loading. Runtime terrain and entity data remain in the normal world dimension storage managed by Minecraft and Dynamic Dimensions. Back up the complete world folder while the server is stopped; copying only a dimension folder does not preserve the authoritative Age registry.

Lifecycle

An Age definition is created before its runtime dimension. If dimension creation is interrupted, the saved definition remains authoritative and the same Age is reconstructed the next time its Descriptive Book is used.

Registered Ages load when the server starts. A book also loads its destination on demand when an administrator previously unloaded it. Unloading retains the definition and world folder, so existing books continue to reference the same Age and later reload the same terrain.

Rivencraft does not automatically delete Ages. Safe permanent deletion needs a complete reference index for books in inventories, containers, Book Stands, and unloaded chunks. Until that exists, retaining the definition prevents an administrator action from silently orphaning books.

Destination-preview chunk loaders are temporary. Rivencraft releases them when the book closes, the player travels, the player disconnects, the destination Age is unloaded, or the server stops.

Commands

The commands require permission level 2.

• /rivencraft age list lists every registered Age and whether its runtime dimension is currently loaded.
• /rivencraft age unload <dimension> safely unloads one Age. Players in that Age are handled by Dynamic Dimensions, and its definition and world data are retained. Use the command suggestions to select a registered dimension.

Opening a Descriptive Book for an unloaded Age loads it again from its saved definition.

Configuration

Rivencraft writes gameplay settings to the world/server configuration managed by NeoForge. descriptive_books.return_link_mode accepts:

• DISABLED (default): never create Return Links automatically.
• ON_CREATION: create one Return Link the first time a player enters each Age.
• ALWAYS: create a Return Link after every successful Descriptive Book trip.

Each client has a separate rivencraft-client.toml. Its book_preview.mode setting accepts AUTO, IMMERSIVE_PORTALS, PONDER, or LEGACY. This changes only presentation and cannot change server-side Age generation or travel validation. See PREVIEW_COMPATIBILITY.md for the selection matrix and integration limits.

Runtime generation profiles are server data-pack resources. Their schema, override rules, reload behavior, and deterministic fallback are documented in AGE_PROFILES.md.

Administrator recovery

Use this sequence when a book cannot load an existing Age:

1. Stop the server and make a copy of the complete world folder.
2. Start the server and run /rivencraft age list. Confirm that the expected canonical name and dimension identifier remain registered.
3. If the Age is listed as unloaded, open its Descriptive Book to reload it. This keeps the UUID, seed, profile, traits, and existing world folder.
4. If a data-pack profile is missing or invalid, restore or repair that pack, run /reload, then unload and reopen the Age. A removed custom profile uses the deterministic rivencraft:standard fallback and logs the substitution.
5. If the definition is missing, restore the complete world backup. Moving a dimension folder into another world cannot reconstruct its UUID or books.
6. If the definition exists but its dimension data is damaged, restore the matching dimension data and authoritative world saved data from the same backup generation. Do not combine them from different backups.

There is intentionally no delete command in Milestone 3. Do not manually delete an Age definition or rename its dimension folder: books may exist in inventories, containers, Book Stands, or unloaded chunks, and would be orphaned. /rivencraft age unload is the supported reversible maintenance operation.