Skip to content

Rework map holder tracking and unload unused map data - #540

Merged
jpenilla merged 5 commits into
ver/26.3.xfrom
map-holder-tracking
Nov 19, 2026
Merged

jpenilla merged 5 commits into
ver/26.3.xfrom
map-holder-tracking

Conversation

@jpenilla

@jpenilla jpenilla commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Includes PaperMC/Paper#14499 (rework map holder tracking) and
PaperMC/Paper#14500 (unload unused map data) as feature patches, with the
Folia changes on top:

  • Minecraft patches 0001: the Paper PRs' file patch changes, 0002 and
    0003: their feature patches, unmodified
  • Paper patches 0001: the Paper PRs' source changes
  • Region Threading Base: the region threading parts only

Once the Paper PRs are merged, those first patches can be dropped and
Region Threading Base rebased as is.

Vanilla updates every holder of a map from each holder's tick, reading other
players' inventories, positions and equipment, which in Folia may be owned by
other regions (reported in #538). Holders also remove each other, so frame
viewers are constantly dropped and re-added and receive the full map again on
every frame update.

Design

A player is a holder of a map while the map is in their inventory or
equipment, or while a frame showing it is tracking them. Each player only
ever modifies their own holder entry, on their own thread.

  • Inventory: a map ticked from the player's inventory/equipment marks
    them as carrying it and updates only their own marker. At the end of the
    player's aiStep, maps that were not ticked are dropped. This covers every
    way a map can leave (drop, chest, death, /clear, plugins, cursor) within
    one tick, and replaces Paper's drop hook. Spectators whose tick is skipped
    while touching unloaded chunks still update the maps they carry.
  • Frames: players are subscribed when they start tracking the frame
    (ServerEntity.addPairing) and sent the map immediately; unsubscribed when
    tracking stops or the frame's map changes. Frame markers are ticked once
    per frame instead of once per viewer.
  • Map invisibility equipment hides the wearer's marker per viewer, using
    the existing per-viewer filters (addSeenPlayers, CraftMapRenderer); the
    wearer still sees themselves.
  • World leave only visits the player's own maps instead of every loaded
    map.

For a map with N carriers and V frame viewers, approximately:

Before After
Carrier ticks O(N²) inventory scans O(N)
Frame updates O(V · (N + V)) O(V)
World leave every loaded map player's maps
Full resends to frame viewers per viewer per frame update while carried only on first subscription

Each map lock is now held for constant work per holder instead of a loop over
all holders.

The second commit stops copying player markers to locked maps: they are live
state, and copies were either replaced immediately or left stale forever
(escaping map invisibility and, once offline, vanish filtering).

Unloading unused map data

Map data was kept in memory from first use until shutdown. Paper's
MapDataCache unloads maps that were not used since the previous save and
that no player holds (relying on the holder tracking above), no plugin
renderer is attached to, and whose file is up to date. Unloaded maps stay
weakly referenced, so MapViews held by plugins keep working. See
PaperMC/Paper#14500 for details.

Folia changes on top:

  • Unused maps are also unloaded before Folia's periodic map save
    (RegionizedServer#autoSaveMaps), on the global region thread like the
    other map saves
  • SavedDataStorage#read is removed, map data is loaded through
    MapDataCache, which handles MapInitializeEvent thread-safely

Behaviour changes

  • A cancelled PlayerTrackEntityEvent for an item frame now also withholds
    that frame's map contents.
  • With item-frame-cursor-update-interval <= 0, viewers get the map once
    when they start tracking the frame, and no updates after.
  • Moving a map with the inventory cursor causes one full resend (the cursor
    is not ticked).
  • NMS: tickCarriedBy lost its frame parameter (frames use tickFrame),
    getHoldingPlayer throws, and carriedBy/carriedByPlayers include
    frame-only viewers.

Testing

Tested in-game with two players: carrying across separate regions, clearing
(single/stacked/multiple stacks), Q drop, offhand F-swap into a chest, cursor
move, death, nether teleport and boat through a portal, frame
subscribe/unsubscribe with a same-region carrier (no repeated resends),
logout/login near a frame, map invisibility, cartography locking and banners.

Map data unloading: unused maps unload after two idle saves on the global
region thread; using an unloaded map again returns the same object; once
collected, it is read from disk again on the using region's thread; a framed
map stays loaded while a player tracks the frame and unloads after they leave.

No region thread check failures.

Vanilla updates every holder of a map from each holder's tick, reading
other players' inventories, positions and equipment, which in Folia may
be owned by other regions. Holders also remove each other, so frame
viewers are constantly dropped and re-added and receive the full map
again on every frame update.

A player is now a holder of a map while the map is in their inventory or
equipment, or while a frame showing it is tracking them, and only ever
updates their own holder entry:
- Carrying is detected from the map being ticked from the player's
  inventory/equipment; maps that were not ticked are removed at the end
  of the player's tick, which also replaces Paper's drop hook
- Frame viewers are subscribed when they start tracking the frame and
  are sent the map immediately; they stay subscribed until tracking
  stops or the frame's map changes, so they no longer get full resends
- Map invisibility equipment hides the player's marker per viewer, the
  wearer still sees themselves
- Players keep a set of their maps, so leaving the world no longer
  scans every loaded map

For a map with N carriers and V frame viewers, approximately:
- Carrier ticks: O(N^2) inventory scans per tick -> O(N)
- Frame updates: O(V * (N + V)) -> O(V), frame markers are updated once
  per frame instead of once per viewer
- World leave: O(loaded maps) lock acquisitions -> O(player's maps)
- Full map resends to frame viewers while the map is carried: up to one
  per viewer per frame update -> only on first subscription

Each map lock is now held for constant work per holder instead of a
loop over all holders, which greatly reduces contention between regions
sharing a map, and no player ever waits on a map lock to update another
player.

Reported in #538
Player markers are live state maintained by each holder's tick, not
part of the map's content. Copying them when locking is inconsistent:
the copy is replaced as soon as that player holds the locked map, but
stays at their lock-time position if they never do, where it also
escapes map invisibility equipment and, once they are offline, vanish
(canSee) filtering.

Treat them as live state only, like on any other map. Frame and banner
markers are still copied with the rest of the map's content.
Match the code from PaperMC/Paper#14499, so that once it is merged only
the region threading parts remain in Folia:
- Use the Paper PR's layout, comments and marker names (as Folia markers
  until it is merged)
- Keep holders of spectators whose tick is skipped up to date
- getHoldingPlayer throws instead of creating a holder
Apply PaperMC/Paper#14499 (rework map holder tracking) and
PaperMC/Paper#14500 (unload unused map data) as feature patches before
Region Threading Base:
- 0001: their file patch changes
- 0002, 0003: their feature patches, unmodified

Region Threading Base only adds the region threading changes on top, so
once the Paper PRs are merged the first three patches can be dropped.

Folia changes for unloading map data:
- Unload unused maps before Folia's periodic map save
- Remove SavedDataStorage#read, map data is now loaded through
  MapDataCache
@jpenilla jpenilla changed the title Rework map holder tracking to avoid cross-region access Rework map holder tracking and unload unused map data Nov 18, 2026
Sync PaperMC/Paper#14500 review fixes:
- Call MapInitializeEvent for new maps after registering them, and
  register them atomically, so listeners and other threads see the
  new map instead of looking it up on disk
- Keep maps loaded again when a plugin removes a renderer
- Make the saved data cache concurrent on Paper too; Region Threading
  Base keeps a diff on that line
@jpenilla
jpenilla merged commit 466e9cb into ver/26.3.x Nov 19, 2026
2 checks passed
R00tB33rMan added a commit to CraftCanvasMC/Canvas that referenced this pull request Nov 19, 2026
Map holders were updated from every holder's tick, which read other players' inventories, positions and equipment from regions that don't own them. A player now only updates their own holder entry, from their inventory tick or from tracking a frame showing the map, and maps nobody used since the last map save are unloaded before it. Canvas unloads them before its global map autosave, which replaced Folia's.

Port of PaperMC/Folia#540 and PaperMC/Folia@dc3d3f2, carrying PaperMC/Paper#14499 and PaperMC/Paper#14500 until they are merged
@jpenilla
jpenilla deleted the map-holder-tracking branch November 19, 2026 04:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant