RustNotMC/docs/portal-scan-benchmark.md

Nether-portal section-scan benchmark

Run with the pinned prepared client resources:

CARGO_BUILD_JOBS=6 cargo run --profile fast -p horizon-client --example portal_scan_bench -- \
  .local/horizon-client/26.3

The example keeps the original Game::may_hold_portal alongside the resident cache (portal_sections). Both run in the same optimized binary, alternating measurement order. Each workload has one discarded warmup pair and seven pairs of 300 ticks. It reports resource loading and fixture construction separately. This measures the section scan only, not the whole entity_portals span, the sweep that follows a positive answer, or the rest of the tick.

The fixture is a 17x17 chunk world (289 chunks), each with 24 sections, and 500 entity reaches spread over it (an item or mob box 0.25 wide and the small move that produces the swept box). A reach touches 1-4 sections. Four palettes: sparse (one non-portal state), dense (128 distinct), global (300 distinct, a global palette whose maybe_has walks the whole state range) and dense_portal (the dense palette with a portal in every fifth section). These are controlled fixtures, not a claim about typical generated terrain.

Steady includes the initial cache fill amortized over 300 ticks. Cold recreates the cache each tick, including allocation and destruction; reload clears it each tick while retaining capacity. Edit workloads alternate a block value in three or all 289 chunks before every scan. Timing includes the Arc::make_mut move of the 176-byte chunk wrapper caused by weak cache handles; the baseline holds no such handles. Both paths keep the original outer reach list.

The scan is parity-checked in the same run: the cached and per-tick answers must agree for every reach over every sample, or the example panics.

Measured on an AMD Ryzen 5 5600X (12 logical CPUs), Linux x86-64, rustc 1.99.0 (b940084d7), using fast (release optimization, LTO off, 16 codegen units). Resource loading took 705 ms; fixture construction took 66 ms sparse, 360 ms dense, 392 ms global and 385 ms dense_portal, shared by both implementations.

Median microseconds per tick (seven paired samples):

Palette	Workload	Original	Cached	Speedup
sparse	steady	40.058	16.836	2.38x
sparse	cold	40.203	48.619	0.83x
sparse	reload	40.828	44.552	0.92x
sparse	edit_1pct	41.282	52.200	0.79x
sparse	edit_all	50.119	4192.396	0.01x
dense	steady	244.610	21.869	11.19x
dense	cold	292.533	1505.691	0.19x
dense	reload	250.397	1301.608	0.19x
dense	edit_1pct	256.522	69.132	3.71x
dense	edit_all	263.829	5904.581	0.04x
global	steady	6179.070	360.082	17.16x
global	edit_1pct	6251.530	1565.249	3.99x
dense_portal	steady	256.854	21.078	12.19x
dense_portal	cold	240.498	1526.251	0.16x
dense_portal	reload	347.879	2037.123	0.17x
dense_portal	edit_1pct	368.684	118.108	3.12x
dense_portal	edit_all	282.876	7194.112	0.04x

The global palette's maybe_has walks the whole ID range, so rescanning every chunk each tick (cold, reload, edit_all) is intractable; those rows are not measured for it.

Keep: the steady scan improves for every palette (2.4x to 17x), which is the case that repeats each tick in real play. Under constant edits the cache also improves the dense and global palettes (edit_1pct 3-4x) because the original rescans through the per-tick map. Rescanning every chunk every tick (cold, reload, edit_all) is slower than the original because a miss scans all 24 sections of a chunk, where the original only touched the sections a reach overlaps. No whole-game speedup is inferred from this microbenchmark; real terrain's palette sizes and block-write frequency determine the gain. Lighting and other chunk changes conservatively invalidate a chunk's mask.

The cache adds a weak handle and mask per visited resident chunk, retains no unloaded block data, and is pruned when a chunk unloads (sync_tick_chunks) and cleared on resource reload, like random_tick_sections. Editing a cached chunk can move its 176-byte wrapper (plus Arc bookkeeping) on the first edit after it is cached; it does not force a deep copy of the block data. The original outer reach-list allocation remains.