Files
horizon-airdef/docs/server-levels.md
T
Ludovic Marie 86fdc72069 Server players go through End gateways
handle_server_portal ignored End gateways, so on a server (dedicated, or
single player's server thread) no player could use one: the in-frame game's
gateway code moved only its own player.

A gateway that is not cooling down now takes a server player at once
(EndGatewayBlock.entityInside, triggerCooldown, setAsInsidePortal), within
the End, keeping its motion and look (Relative.DELTA and ROTATION). An exact
exit is reached straight away; otherwise the player waits at the destination
while it loads, and the exit is found or built there (the in-frame
resolve_gateway, shared through gateway_job).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 15:32:24 +02:00

5.7 KiB

A server's levels: one per dimension

Vanilla's MinecraftServer holds a ServerLevel per dimension, and each player is in one of them. Horizon's server does the same. That covers the dedicated server and single player's server thread (Game::serving, the default since #1114). So a LAN world's host and each guest can be in different dimensions at the same time.

How the single-level Game maps onto vanilla's levels

The game's tick code reads one level: the one held in Game's own fields (the world, its streaming and save, block ticks, entities, block entities and their per-level queues). game/levels.rs keeps the other dimensions' levels as Parked values and swaps one into place (enter_level). The swap is mem::swap of each per-level field, so the tick code runs unchanged, one level at a time.

Vanilla Horizon
MinecraftServer.levels the level in place plus Levels::parked
MinecraftServer.tickChildren, every level tick_server: each level with a player in it, in Overworld, Nether, End order. The first pass reads the network and runs the shared parts (clock, weather, functions, autosave).
ServerLevel.players Hub::here: the guests whose dimension is the level in place
ServerPlayer.teleport into another level server_travel.rs: a Respawn packet, then the teleport once the destination has loaded (portals and execute in … tp). An End gateway teleports within the End.
PlayerList.respawn guest_respawn: back into the Overworld's level
ServerLevel.noPlayersEmptyTime, chunk unloading close_idle_levels: a level other than the Overworld with nobody in it for 300 ticks is saved and closed
CommandSourceStack.getLevel with_source puts the source's level in place for a command (execute in, execute at a player in another level)
the levels' shared LevelData not swapped: game time, day time, weather, game rules, scoreboard, maps, entity ids (next_entity, unique across levels)

The packets of a guest are read in its own level's pass (Hub::tick_level), so its actions and commands run with its level in place.

The window's own game (--no-server-thread, HORIZON_SERVER_THREAD=0, and the command harness) keeps one level, which follows its player (enter_dimension). LAN guests of a world run that way stay in the host's dimension. That mode is the escape hatch now, so it gets no multi-level work.

One code path for both

The dedicated server and the server thread are the same code. The server thread runs a Game with options.dedicated set and a hub without a host player. The window joins it through memory as one more player. Everything above serves both, and server_dimension_players (vanilla clients on Horizon's dedicated server) and lan_e2e --server-thread (Horizon clients on the server thread) check it from the two sides.

Cost of an extra level

Measured on the Mac mini (M4 Pro) at render distance 12, on 2026-10-22. The host and a guest each played a fresh world on the server thread. RSS is the host's whole process, window included. Tick time is /tick query's average over 100 ticks.

Where the players are Average tick P95 Host RSS
both in the Overworld 1.0 ms 1.3 ms 1194 MB
guest in the Nether (two levels tick) 2.2 ms 2.9 ms 1238 MB
guest in the End (the Nether still parked) 0.9 ms 1.1 ms 1324 MB
both back, the Nether and End closed after 300 idle ticks 0.8 ms 0.9 ms 1335 MB
  • A level costs only while a player is in it: its chunks around that player, their entities, and the tick. With nobody outside the Overworld, tick_server runs one pass, as before.
  • A closed level's memory goes back to the allocator, not always to the system.
  • Entering a level the first time opens its region files and streaming (open_level). That cost comes once, before the player's chunks load.

Saving

save_game saves the level in place, then every parked level (save_parked_levels). Each level has its own region folder, as in vanilla (DIM-1, DIM1). A level closed for being idle is saved first. Each player's saved data holds its dimension (Dimension). A guest who leaves in the Nether, or whose host saves and quits, joins again in the Nether where it was.

What's checked

python3 tools/lan_e2e.py --server-thread --check portals --check levels:

  • portals: the guest goes to the Nether through a portal while the host stays. The host then goes to the End while the guest is in the Nether, so three levels run at once, and both come back.
  • levels, with the host and the guest each in a level of its own:
    • execute in the_nether run tp moves the guest alone. From the Nether, execute in overworld and execute at the host change and test blocks in the host's level.
    • Mobs and armour stands fall in two levels at once, and every entity id is unique across the levels.
    • The guest leaves in the Nether and joins again there.
    • The guest dies in the Nether and respawns in the Overworld.
    • The host takes a Nether portal alone.
    • The guest takes an End portal, an End gateway and then the exit portal alone.
    • The host saves, quits and opens the world again with the guest in the Nether, and the guest joins again there.

Not done yet

  • End credits for server players. The first exit from the End should show a player the credits (EndPortalBlock.entityInside, seenCredits). The client's WinScreen is #338.
  • Entities through portals between levels. Mobs, items and minecarts that enter a portal on a server, and portal tickets (TeleportTransition.PLACE_PORTAL_TICKET), are not handled.
  • Unlimited selectors. @e without a distance or volume reads only the source's level. Vanilla's reads every level.