# Optional Seamless Portals integration — issue #117 Local candidate **26.3.0.9**, Minecraft 26.3 / NeoForge 26.3.0.99 / Java 25. Pending real-client validation; not committed or published. Minecraft 1.21.1 is unchanged by this issue. ## Supported engines and API boundary Install **one** portal fork per instance: - Seamless Portals **1.0.0**, installed file `seamlessportals-neoforge-1.0.0.jar`. - Immersive Portals Reborn **7.0.12**, retaining its previously implemented path. - Neither: Rivencraft's animated panels/surfaces and ordinary travel remain. The actual installed Seamless JAR was inspected and compiled against, not assumed compatible from its name. Used public GUI rendering, WorldRenderInfo builder, chunk-loader and PortalAPI signatures match Reborn. ClientWorldLoader and Portal have additional fork-specific members; Rivencraft does not use those differences for live views. The native dimension adapter still uses each fork's own `DimIdSyncPacket.createFromServer` factory and wire format. The existing Reborn implementation has been renamed into shared `ImmersiveBookPreviews`, `ImmersivePreviewChunks`, `ImmersiveLiveBookPanel`, `ImmersiveCrystalPortals` and `ImmersiveCrystalView` classes. No second copy of the rendering, destination, chunk-stream or mesh algorithms was introduced. Optional API references remain behind availability guards; neither fork is bundled or required. The Reborn acknowledgement workaround is still **Reborn-only**. This change does not resolve or establish a root cause for the Reborn crashes in [#118](https://git.paddedcell.org/dnorberg/rivencraft/issues/118). ## Configuration In `config/rivencraft-local.toml`: ```toml [book_previews] seamless_live_views = true seamless_crystal_live_views = true reborn_live_views = true reborn_crystal_live_views = true ``` The active fork uses its own switches. The existing Reborn preferences keep their meanings; Seamless defaults to enabled. Book views are a local client choice. Crystal views are server-controlled. Disable the relevant switch for animated fallback; portal/book travel remains Rivencraft's responsibility. ## Books Both Linking and Descriptive Books request a rotating live destination panel. Stand books get the panel without exploration. The handheld eye enters look-only exploration inside the book window; movement is disabled, and right-click returns to ordinary book controls. The camera starts at the linked arrival eye position. Missing/unready destination chunks retain the animation. Each player has one validated preview stream, tied to source world, held or stand book and session UUID. Requests are rate limited. A 30-second lease is renewed by the open book and released on close, logout, dimension changes, invalid source book, expiry and shutdown. Late responses cannot overwrite a newer book session. Only one GUI render target task is queued at once. The target stays alive across deferred GUI frames rather than being destroyed while still referenced. The shared engine hook clears the remote target before rendering and restores the player's local camera afterward. Remote book-world sounds are filtered; source rain/audio and camera restoration remain explicit player checks. ## Crystal portals Native portals are render-only: Rivencraft portal cells retain travel, cooldowns, link properties and destination safety rules. Connected cells are grouped into one coplanar masked mesh per side of an opening, not repeated per-block views. The linked standing eye position maps through the native transform onto the actual destination eye position; the frame sits in front of the live view. A complete native surface disables the fallback texture. Missing/disabled native views retain it. Receptacle maintenance restores views after reload; book removal/frame shutdown removes native entities. Existing ownership tags are preserved so maintenance can find saved views rather than duplicate them. ## Automated and player validation The isolated `scripts/regression_portal117.py` probe accepts `none`, `seamless --jar /path/to/seamless.jar`, or `reborn`. Run each separately; the host-wide server lock prevents overlap. Every run uses a new temporary world, removes it and fixture outputs regardless of result, and retains a log under `build/verification/portal117/`. A 60-second stall is stopped and handed to the player without retry. The fixture explicitly warms a forced test chunk before querying native entities. An unticked startup chunk does not expose its entities through the normal spatial query. Portal widths/heights use the engine's W/H axes, which can swap relative to world X/Y; assertions check world-space spans and the actual eye transform. Final sequential server results: **24 checks passed with Seamless, 24 with Reborn, and 8 with neither**. Earlier fixture assertions were corrected for entity-section visibility and native axis ordering; no stalled run was retried. Server checks cover dynamic Age registration/catalog synchronization, six-cell frame formation, one mesh per side, correct physical spans, exact eye mapping, non-teleporting/non-interactive native surfaces, refresh reuse, config fallback, reactivation and cleanup. They do **not** verify GPU output, connected preview leases, multiplayer packet delivery, or real-client restart behavior. ### Required player matrix Use Seamless alone with Rivencraft 26.3.0.9 on both ends: 1. Bind a new Descriptive Book, open/close it repeatedly and link through it. Compare the live view with the real destination. 2. Test a Linking Book and a stand book. Confirm the panel stays inside the book and stands have no eye exploration. 3. Enter handheld exploration, look around, right-click out, re-enter, close and reopen. Confirm no movement or full-screen view, and local rain/audio remain correct. 4. Form a multi-block crystal opening. Check one continuous view, frame occlusion, no fallback overlay, matching arrival position/facing, and travel. 5. Remove/reinsert the book and break/rebuild the frame; no orphan views. 6. Reconnect and fully restart. Check saved books, previews and portal reactivation, including initially unloaded destination chunks. 7. Explore across chunk boundaries for a sustained period. Do not assume Seamless is free of the Reborn renderer problem without testing. 8. On a dedicated server, check two players using different books/portals, closing/logging out independently, and creating a new Age after joining. 9. Disable each Seamless switch and verify its animated fallback and normal travel. No portal mod and Reborn are separate regression configurations. Inspected Seamless artifact SHA-256: `5d2bfc2a811a6526e3f6722c521d97e5de2869a6ead1c681323c3c472e4367a0`. ## Release validation (2026-11-17) Player in-game checks passed. Included in releases 1.21.1.0.6 and 26.3.0.10 (Seamless integration applies to 26.3 only). Earlier candidate notes above describe development history. Known Reborn/Seamless acknowledgement and rendering failures remain tracked in [#118](https://git.paddedcell.org/dnorberg/rivencraft/issues/118); this release does not resolve them.