v0.16.0-beta.1 — Async POI prefetch (Tier A, load-side performance)

This build extends v0.15's async load by moving the POI region disk read off the main thread onto the background load worker. With async load on, this POI read wait was the single largest remaining main-thread cost; this build effectively eliminates it. The feature kicks in automatically with async load, Forge 1.20.1 build only. Async load itself is still off by default and opt-in

What it does

• Async load (PARTIAL mode) moves chunk deserialization to a background worker, but PoiManager.checkConsistencyWithBlocks (the POI consistency check) still replays on the main thread, and the POI region read it triggers blocks the main thread synchronously on tryRead().join() waiting for disk
• spark profiling: under fast movement / high view-distance, this POI read wait is the top remaining main-thread cost once async load is on
• This build has the load worker read that column's POI region bytes off-thread during deserialization; the main thread populates the POI cache from those prefetched bytes before replay, so the consistency check hits the cache instead of reading disk

Measured impact

• Real production server (137-mod heavyweight pack, 8 load workers, fast flight): main-thread POI getOrLoad dropped from 15.0% to 0.1%, the synchronous read wait gone, main-thread chunk-load cost down ~13.7%
• TPS at cap, zero parse fallbacks, zero POI data delta

Configuration ([load] section)

• load.asyncPoiPrefetch (default true, hot-reloadable): whether to prefetch the POI region on the load worker. Only takes effect when async load is on (load.enabled=true) and mode is PARTIAL. Set false to fall back to a main-thread synchronous POI read (vanilla behavior) if a POI-storage mod misbehaves

Safety and compatibility

• Thread safety: the worker only touches the underlying IOWorker (thread-safe), never the non-concurrent POI cache; the POI cache parse and writes all stay on the main-thread replay, in line with every other POI access
• No data loss: the prefetched bytes are that column's already-saved POI data, and the main-thread parse-and-populate is byte-for-byte equivalent to vanilla readColumn; if the column was already loaded before replay, the prefetched bytes are skipped in favor of the live data
• Failure fallback: a failed POI prefetch does not affect chunk loading — it falls back to a main-thread vanilla POI read
• The online chunk-restore path does not prefetch (it restores an already-loaded chunk whose POI is usually in memory, so a prefetch would be skipped by the guard and wasted)

Why it is still a beta

• Tier A is a load-side enhancement to async load, which itself is still in public testing and off by default; this build is marked pre-release alongside it
• Main-thread cost elimination and zero-data-loss signals are real-server verified, but sustained concurrent multiplayer steady state is still under observation

Upgrading

• Drop-in jar replacement. If you have not enabled async load (load.enabled=false, the default): this build changes nothing
• If you have enabled async load: Tier A is on automatically (asyncPoiPrefetch=true), no extra configuration needed; set asyncPoiPrefetch=false to disable it