Public Access
137 lines
7.0 KiB
Markdown
137 lines
7.0 KiB
Markdown
# 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.
|