Files
rivencraft/docs/PORTAL_TRANSITION_GUARDS.md
T
2026-11-18 22:55:03 -05:00

98 lines
5.3 KiB
Markdown

# Portal transition guards — issue #118
Released with **26.3.1.0**; NeoForge 26.3.0.99 / Java 25.
Only 26.3 client code changed for issue #118; the 1.21.1.1.0 release includes
the separately accepted Native-generation updates.
## Evidence and attribution
The installed Seamless 1.0.0 and Reborn 7.0.12 bytecode has the same unchecked
redirectHandleBlockChangedAck path: getClientWorlds asserts that the portal
engine is initialized, then iterates its worlds. Its own world-replacement
cleanup can leave initialization false until a later initialization point.
Rivencraft does not call that cleanup. Its existing workaround was Reborn-only.
Two newer Seamless reports (2026-11-18 21:51:41 and 22:05:32) still show this
same assertion. That establishes an ongoing compatibility gap, not an Age
generation exception. Local reports are retained outside the repository.
The Reborn exploration crash dereferenced a null RenderSection in its wrapped
compileAsync path. Both vanilla 26.3 and NeoForge's patched compileSections
loop retrieve the current section for an extracted job and dereference it
without a null check. ViewArea can return null for a section outside its current
storage. Reborn wraps the compile call; Seamless modifies the priority decision
instead. The observed origin of the stale job is still not conclusively
attributed to vanilla, the portal engine, or their interaction. No independent
full-client reproduction without Rivencraft is claimed.
The [Seamless project](https://www.curseforge.com/minecraft/mc-mods/immersive-portal)
links to [its upstream tracker](https://github.com/fmpapierz/SeamlessPortals/issues).
No new report has been submitted by this change. An unrelated report there does
not establish a match to these failure paths.
## Acknowledgement guard
ImmersiveBlockAckMixin runs on the client/game thread, only when either supported
fork is installed. During an uninitialized-world-map interval, it acknowledges
the packet listener's own ClientLevel directly and skips the failing multiworld
redirect. With an initialized map the fork handles the packet normally,
including remote worlds. Off-thread packets retain vanilla scheduling. With no
packet world, there is no valid local prediction state to acknowledge.
The helper and mixin were renamed from their old Reborn-only names. Optional
portal API classes remain behind the installed-engine check; no new required
dependency or configuration switch is introduced.
## Unavailable section jobs
At compileSections entry, when a supported fork is present, only jobs whose
section is absent from the current ViewArea are removed. The check uses an
invoker for the same section lookup vanilla performs later.
Every valid job retains its object identity, order, region, additional renderers
and dirty state. The whole render pass is not canceled. There is no try/catch
around rendering, permanent coordinate blacklist, terrain scan or new chunk
loading. A newly allocated section can be extracted and compiled normally.
Other exceptions propagate. This is a targeted mitigation for the observed
null receiver, not a claim to fix every renderer or world-ownership issue.
## Verification
./gradlew -p ports/mc263 build
python3 scripts/regression_client118.py
The isolated script passed **47 checks** using production guard/mixin bytecode.
It extracts and runs the acknowledgement redirect bytecode from both installed
forks, reproducing the old uninitialized-map assertion before testing guarded
delivery. Coverage includes warm/cold maps, exact-once local acknowledgement,
normal remote acknowledgement, off-thread noninterference, no-fork bypass,
missing packet world, stale/valid renderer jobs, retained job identity/payload
and dirty state, newly available sections, null view area and unrelated errors.
Minecraft lifecycle and renderer types in this script are small isolated stubs.
It starts no Minecraft client, GPU, server or test world. It does not prove
runtime Mixin application, live portal graphics or end-to-end network timing.
No stall occurred and no stalled server probe was retried. Temporary test
outputs are deleted; result retained in build/verification/issue118/guards.txt.
## Player acceptance checklist
Test each installed renderer separately; never enable both together.
1. Start with Seamless and confirm the client loads. Create/open/close a new Age
book, travel repeatedly and return. Include normal block placement/breaking
around travel to exercise prediction acknowledgements.
2. Open live book previews, enter/exit look-only exploration, close/reopen and
use a live crystal portal. Verify the view stays correct and travel works.
3. Explore across chunks, rebuild terrain (F3+A), and change render distance.
Confirm no section crash and that terrain continues rebuilding visibly.
4. Disconnect/rejoin and fully restart; repeat travel to existing/new Ages.
5. Repeat with Reborn alone, particularly sustained exploration/rebuilding.
6. Optionally check animated fallback with no portal mod. Neither renderer is
required for normal Rivencraft travel.
The user reported in-game pass and authorized publication after testing the
26.3.0.19 candidate. Issue #118 and Milestone X.1.0 are complete. This records
player acceptance; no independent exhaustive GPU/network/renderer matrix or
standalone external-fork reproduction is claimed.