Hauteur

Hauteur is a Geyser extension for Bedrock players on Java servers whose world is taller than the Bedrock client can display.

The problem

The Bedrock client renders a fixed vertical range, chosen by the client itself. On a Java world that goes higher (for example around Y = 1950 on a BuildTheEarth-style build), Bedrock players cannot see or reach blocks above that range.

What Hauteur does

Hauteur moves the window instead of extending it. For each Bedrock player it keeps an integer offset O, always a multiple of 16. The client sees real Y minus O. When the player gets close to the edge of the visible range, Hauteur shifts O, rebuilds what the client sees from its cache, and carries on. Content outside the current window is not shown until the window moves over it.

• Every absolute-Y packet is translated at one point in Geyser's Java-side pipeline. Relative values (motion, cursor offsets, relative teleports) are never shifted.
• Original chunk packets and the block changes received since are cached, so a switch redraws the view without asking the server again.
• Client packets sent during the short freeze after a switch are held, replayed in the right frame, or dropped. An ambiguous packet is dropped, never guessed.
• Ordinary worlds are not affected. If the real world already fits the client's range, no chunk is cached and no packet is changed.
• Chat commands that take an absolute Y (tp, tppos, teleport by default) are rewritten by the same offset. Signed chat commands are left alone.

What you will notice

• A short, visible adjustment each time the window moves. The freeze lasts 400 ms by default.
• Hauteur cannot make the Bedrock client display more than its own range. It moves that range.
• Chunks larger than the cache budget are not replayed after a switch (see Known limits).

Requirements

• Java 21 or newer on the server.
• A Geyser-supported server platform: Spigot/Paper, Fabric, Velocity, BungeeCord or standalone Geyser. The build compiles against Geyser 2.11.2-SNAPSHOT.
• Geyser installed and working on your server.

Installation

1. Install Geyser on your server.
2. Download hauteur-<version>.jar from the GitHub releases and check it: sha256sum -c SHA256SUMS.txt
3. Copy the jar into the Geyser extensions folder:
   • Spigot/Paper: plugins/Geyser-Spigot/extensions/
   • Standalone: extensions/ next to the Geyser jar
4. Start the server. A config file is written to extensions/hauteur/config.properties.
5. Join from a Bedrock client and run /hauteur doctor. It shows whether the pipeline and the world-manager wrapper are attached.

Upgrading from SkyWindow 1.x: the config in extensions/skywindow/ is copied to extensions/hauteur/ on first start (the old file is kept). The old commands /skywindow, /sw and /bho still work as aliases.

Configuration (defaults)

Key	Default	Range	Meaning
switch-margin-blocks	64	32–256	Re-home the window when the player is this close to its edge
switch-cooldown-ms	2000	250–60000	Minimum time between two switches for one player
freeze-ms	400	100–5000	Length of the freeze after a switch
freeze-hold-actions	true		Hold block actions sent during a freeze
freeze-hold-movement	true		Hold movement sent during a freeze
announce-switches	false		Chat message on each switch
chunk-cache-max-chunks	2048	64–32768	Cached chunks per player
chunk-cache-max-megabytes	96	8–1024	Cache byte budget per player
max-offset-blocks	0		Cap on the offset, aligned to 16. 0 derives it from the world
rewrite-commands	tp,tppos,teleport		Commands whose absolute Y is shifted
log-switches	true		One log line per switch

Out-of-range values produce a startup warning and are clamped. Most keys reload with /geyser reload.

Commands

/hauteur (aliases /skywindow, /sw, /bho), Bedrock players only:

• info: offset, window bounds, cached chunks.
• watch on|off and recent: recent translated packets, for debugging.
• doctor: attachment and world-manager status, quarantined packet types, Geyser build.
• stats [reset]: session counters (switches, replays, held and dropped packets, cache evictions).

Known limits

• Not tested on a live server or with a real Bedrock client. Automated tests cover the Java-side translation and the decision logic. Freeze timing, how the client handles a switch, and the visual result are not verified yet.
• The client's adoption of a new window is inferred from time. Hauteur receives no acknowledgement from the client.
• A chunk larger than chunk-cache-max-megabytes is not cached, and the oldest chunks are evicted when the budget is full. Terrain for those chunks stays stale until the server sends it again.
• Light data is not re-homed. No reference was found in Geyser's core, but this has not been tested live.
• The death location is written unshifted and is not re-sent after a switch. Its effect on the compass and the death screen is untested.
• Collision and container reads depend on the world-manager wrapper. If it cannot be installed, /hauteur doctor reports it.
• Packets without an absolute Y, and signed chat commands, are not translated.
• Performance was measured only on the codec, with synthetic chunks. The cost on a live server is unknown.

Status

Experimental. The most useful bug report includes the output of /hauteur doctor and /hauteur stats.