Teleport presentation
Aether gathering, the same-dimension blink and the dimensional passage that accompany every player teleport.
Every player teleport the mod performs can announce itself to the client, which answers with up to three screen shaders: a gather while a ritual or gateway charges, a blink of about 0.7 seconds for travel within one dimension, and the dimensional passage for travel between dimensions. All three are presentation only. They never hold input, choose a destination or decide whether a teleport may happen. Player rules are in Teleport Stones.
What it does
Gather. The rim of the view sinks into a hue aura threaded with bright wisps, runes surface in that mist and drift inward, and focus lines converge on the centre. The edge twists slightly toward the centre while the middle of the view stays readable. From 75% charge the aura beats and sends rings of light inward.
Blink. The departure frame rushes outward past the camera while a vortex tears open at the centre. The live destination then unfolds from that vortex behind a refractive rim and shed glitter.
Passage. The departure frame cracks from the centre like struck crystal and shatters into shards that fly past the camera. Behind it runs an aether corridor of nebula walls, energy filaments, aurora ribbons, light streams and passing rune gates around a distant star. Arrival rushes into the star, whites out, then dissolves from the centre along a glittering edge.
All three light themselves from one crossing colour. CrossingPalette lifts the brightest channel to 1, raises chroma by ×1.35 so pastel portal colours still glow, and turns an accent 0.6 radians around the grey axis: toward violet for greens, cyans and blues, toward the warm side for yellows, reds and magentas. Dark tones come from a fixed violet night, not from the hue, so gold stays gold.
Runtime model
The server sends two packets. Both are a single current format with no legacy decoder.
| Packet | Payload, in order | Sent |
|---|---|---|
isekaiexpansion:teleport_gather | ticks (varint), colour (int) | When a ritual or charge that ends in a crossing begins. |
isekaiexpansion:teleport_crossing | passage (boolean), colour (int), arrival (block position) | After the destination is validated and immediately before the player moves. |
TeleportScreenCues.cross sets passage when the destination world differs from the player’s current world. Current producers:
| Producer | Gather | Crossing colour |
|---|---|---|
TeleportUtil.tryTeleport ritual path, used by teleport stones | 22 ticks (1.1 seconds), the ritual’s transfer delay | 0xFF85CFFF |
TeleportUtil.tryTeleport instant path | None | 0xFF85CFFF |
PortalEntity: Portal spell pairs, and Global Portal links to a World Gate | None | The portal’s colour. |
| World Gate journey | None | The gate’s configured colour. |
| Dungeon entry and return | Client gateway probe on entry | Difficulty entrance colour, or 0xFFFFD66B return gold. |
| Any other dimension change | None | 0xFF18DFFF, started by the client’s dimension-change hooks. |
Gather
GatherController ticks with the game and samples between ticks with the frame’s partial tick, so it freezes while paused. Each gather starts its animation loop from zero, and the loop wraps every 480 ticks (24 seconds) without a seam, so a gather held at full charge repeats cleanly. Focus lines speed up from 0.6× to 1.4× real time as the charge builds; their travel is integrated per tick, so a changing charge never makes them jump. Reduced motion runs both clocks at 0.3×. The larger of two drivers sets the charge:
| Driver | Rise | Release |
|---|---|---|
| Timed cue | Linear over the announced ticks, clamped to 1–100 (0.05–5 seconds). | Without a crossing, holds full for 10 ticks (0.5 seconds), then falls by 1/5 per tick. |
| Dungeon gateway probe | Over 38 ticks (1.9 seconds) while the player overlaps a gateway. | Over 4 ticks (0.2 seconds) after leaving, or after a full charge that no crossing answers within 20 ticks (1 second). |
The probe takes its colour from a dungeon portal within 1.5 blocks of the gateway, else 0xFF18DFFF. Spectators never charge it. Arriving on a gateway restarts the server’s portal cooldown while the player stands there, so after a world change the probe stays dark until the player has been clear of gateways for 10 ticks (0.5 seconds). A refused entry starts the same cooldown instead of retrying every tick, so the player steps off for 10 ticks (0.5 seconds) before the gateway charges again; the probe collapses after its unanswered full charge and re-arms on the same rule. Any crossing clears the gather at once; its departure frame already carries the gathered look.
Blink
On a blink crossing, BlinkController copies the frame the game last presented into a FrameSnapshot, HUD included. Its PresentedClock starts at the next presented frame, adds no time while paused and skips whatever part of a frame gap exceeds 50 milliseconds.
| Phase | Time | Rule |
|---|---|---|
| Tear | 0.32 seconds | The departure rushes outward around the opening vortex. |
| Hold | Until arrival, at most 1.4 seconds | Unfolding waits for the player to stand within 4 blocks of the arrival with that chunk section drawn. |
| Unfold | 0.5 seconds | Starts no earlier than 0.2 seconds; the destination opens from the centre. |
A blink therefore lasts 0.7 seconds when the destination is ready and at most 1.9 seconds. The snapshot texture is freed when the blink ends.
Passage
TravelPresentation captures its own departure frame and composes after the game frame, including over loading screens. TravelTimeline counts presented seconds the same way as the blink.
| Phase | Time | Rule |
|---|---|---|
| Entry | 1.6 seconds | Crack and shatter; the departure texture is freed when it completes. |
| Corridor | From 2.1 seconds until ready | Arrival waits for the chunk at the player’s position to be drawn, or for the wait budget. |
| Arrival | 1.8 seconds | Aperture, white-out, then the light dissolves from the centre. |
Gather and blink are Satin post effects drawn before the HUD. Each renders into its own swap target and copies only colour back, so scene depth survives. Both skip Iris shadow passes. Disconnecting releases their effects and the snapshot on the client thread.
Contracts
net.kzeroko.isekaiexpansion.api.fx.TeleportScreenAPI is the server facade. Colours are packed RGB; alpha is ignored.
| Member | What it does |
|---|---|
gather(ServerPlayerEntity player, int ticks, int color) | Announces a crossing ticks ahead. Clamped to 1–MAX_GATHER_TICKS. |
cross(ServerPlayerEntity player, ServerWorld destination, Vec3d arrival, int color) | Announces the crossing itself; chooses blink or passage from the destination world. |
STONE_COLOR | 0xFF85CFFF, the teleport stone ritual’s colour. |
MAX_GATHER_TICKS | 100, the longest announced gather. |
Call cross once per player move, after every check that can cancel it. The client reads the frame it last presented as the departure view, so a cross sent long before the move shows a stale location.
net.kzeroko.isekaiexpansion.api.client.FrontendAPI.beginTravel(int durationMs, int color) opens the passage from client code. It dispatches to the client thread and clamps its wait budget to 2000–30000 milliseconds. A passage already under way keeps its colour and timeline; the crossing packet uses 30000.
FrontendAPI.reducedMotion() reads the shared client preference. With Reduced motion on, the passage does not start and loading uses the normal loading screen. Gather and blink keep their colour and light but drop every displacement, so the blink becomes a soft radial cross-fade.
The first blink frame reproduces the departure frame, and its last returns the live frame unchanged. Zero gather charge returns the scene unchanged, and a finished passage is fully transparent.
Extending it
A new server teleport calls the facade around its own move:
TeleportScreenAPI.gather(player, chargeTicks, color);
// ...later, once the destination has been validated:
TeleportScreenAPI.cross(player, destinationWorld, arrival, color);
FabricDimensions.teleport(player, destinationWorld, new TeleportTarget(arrival, Vec3d.ZERO, player.getYaw(), player.getPitch()));
Skip gather for a teleport that happens on contact. Shaders live in assets/isekaiexpansion/shaders: core/dimension_passage for the passage, and program/teleport_warp and program/teleport_gather with matching post definitions. Keep their endpoints neutral and take every highlight from the Hue and Accent uniforms that CrossingPalette.applyTo writes. Drive post-effect animation through a Clock uniform, never Time: vanilla’s PostEffectPass overwrites Time on every pass with its own sawtooth that wraps every 20 ticks (1 second). A looping effect takes its Clock from a LoopClock and its Loop length beside it, and every timed motion in the shader must complete whole cycles per loop.
Verifying
Run ./gradlew.bat compileJava. In game, check the first and last blink frames, zero gather charge and the completed passage in landscape, portrait and ultrawide windows. Confirm that each effect uses the crossing colour and that its boundary frames leave the scene unchanged.
In game, test a stone within a dimension and across dimensions, far stone and World Gate trips whose chunks load late, portal spell portals of different colours, dungeon entry and return, standing on a gateway after returning, pause during each phase, Reduced motion, disconnect and resource reload. Check with and without Iris, and confirm the HUD stays sharp over the blink and scene depth survives.
Related
Teleport Stones · Dungeons · Entity FX · Shaders and materials