rivencraft/docs/PREVIEW_COMPATIBILITY.md

Destination preview compatibility

Rivencraft has three destination preview backends. The selected backend is a client presentation detail; the server validates travel and Age generation is independent of every preview integration.

Selection matrix

Set book_preview.mode in rivencraft-client.toml.

Configured mode	Immersive Portals installed	Create/Ponder installed	Selected backend
AUTO	yes	either	Immersive Portals
AUTO	no	yes	Ponder snapshot
AUTO	no	no	built-in legacy animation
IMMERSIVE_PORTALS	yes	either	Immersive Portals
IMMERSIVE_PORTALS	no	either	built-in legacy animation
PONDER	either	yes	Ponder snapshot
PONDER	either	no	built-in legacy animation
LEGACY	either	either	built-in legacy animation

Explicit optional modes fall back directly to LEGACY. They do not silently select the other optional integration. GameTests exercise every row and every dependency-presence permutation.

Book behavior

Held Linking and Descriptive Books render the selected backend in the preview panel. Immersive Portals additionally exposes Explore: the player remains at the opening position, mouse look controls the remote camera, and right-click returns to the standard book view.

Books on a Book Stand use the same preview panel, but Explore is disabled so the player cannot move away and leave a remote preview session owned by the stand screen. Closing either screen releases its server chunk loader. Linking, disconnecting, unloading the destination Age, and stopping the server also release affected loaders.

The Immersive Portals backend force-loads the initial 3 by 3 destination area before registering its wider preview chunk loader. The Ponder backend clears the previous snapshot before applying replacement block data. The live backend clears its framebuffer on each render and restores the Minecraft viewport afterward. These rules prevent stale snapshot frames and book UI elements from being captured in the preview.

Supported combinations and upstream limits

The compatibility baseline is Minecraft 1.21.1, NeoForge 21.1.251, Create 6.0.10, and Immersive Portals 6.0.7. Core Age generation and the LEGACY backend run without Create or Immersive Portals; the headless GameTest server uses that dependency-free path.

Immersive Portals 6.0.7 is incompatible with Sodium 0.8.13 for Minecraft 1.21.1: its Sodium compatibility mixin references the removed OcclusionCuller.Visitor class and crashes while entering a world. Sodium 0.6.13 avoids that specific mixin failure. This compatibility boundary belongs to Immersive Portals and Sodium, before Rivencraft's preview code runs.

Immersive Portals reports that some Create contraptions can be invisible when the two mods are installed together. Rivencraft does not replace either mod's world or contraption renderer, so this remains an upstream rendering limit. The PONDER or LEGACY mode is the supported fallback when live rendering is unstable in a particular graphics or mod configuration.

Release verification

For preview-related releases:

1. Run ./gradlew runGameTestServer to verify the complete selection matrix, core Age creation, persistence, and travel without optional renderers.
2. Open held Linking and Descriptive Books once with each available backend.
3. Open both book types from a Book Stand and confirm Explore is disabled.
4. With Immersive Portals, enter and leave Explore, travel between dimensions, close the screen, and disconnect; confirm destination chunks render and no preview loader remains active.
5. With Ponder, reopen different destinations and confirm the previous snapshot does not bleed into the next one.