VolumeIndex

Spatial index for Unturned's VolumeManager lookups. Replaces the engine's linear scans with region-bucketed lookups, eliminating per-tick volume scan cost on large maps.

Status: synthetic benchmarks and correctness verification pass cleanly, but the plugin has not yet been stress-tested on a live server with real player load. UPS impact under load is theoretical based on the per-query speedups below.

Why

Vanilla VolumeManager.GetFirstOverlappingVolume iterates every volume of a given type on every call. PlayerMovement.updateRegionAndBound, CharacterControllerExtension.CheckedMove, and PlayerLife.simulate call into this per player per tick, so server CPU scales with players × volumes × tick_rate. On California 2 (321 AmbianceVolumes, 212 UndergroundWhitelistVolumes) this dominates the server frame at high player counts.

This plugin Harmony-patches the affected VolumeManager methods to query a 64×64 region grid instead. Same results, dictionary-lookup speed.

Credits

• RBMKBlaze for diagnosing the volume-scan hot path and posting the original Harmony band-aid fix that pointed straight at the problem. See Unturned-3.x-Community#5464.

Features

• Region-bucketed spatial index for 6 hot-path volume types: Ambiance, Deadzone, HordePurchase, UndergroundWhitelist, Safezone, Oxygen.
• Drop-in replacement, zero gameplay changes (shelter zones, fishing intervals, breathability all preserved).
• Built-in verification command compares index lookups against the engine's linear scan.
• Built-in benchmark command shows per-type speedup.
• Auto-primes on plugin load if level already loaded; otherwise primes on Level.onLevelLoaded.

Benchmarks

Real numbers from California 2 (/volumeindex bench 100000):

Volume type	Volumes	Linear	Indexed	Speedup
Ambiance	321	4821 ms	19 ms	252×
UndergroundWhitelist	212	2844 ms	4 ms	601×
Safezone	38	678 ms	3 ms	204×
Deadzone	26	527 ms	3 ms	134×
Oxygen	23	504 ms	8 ms	60×

/volumeindex verify 30000 reports 0 mismatches across all 6 types.

Commands

• /volumeindex stats (alias /vidx stats) – Print bucket stats per type: volume count, cells used, max bucket size, average bucket size.
• /volumeindex verify [n] – Compare engine linear scan vs index lookup over n random points (default 1000) per type. Expects 0 mismatches.
• /volumeindex bench [n] – Time engine linear vs index lookup for n random points (default 10000) per type. Reports speedup.

Permissions

<Permission Cooldown="0">volumeindex</Permission>

How it works

On plugin load:

1. Harmony patches VolumeManager<T,M>.AddVolume, RemoveVolume, and GetFirstOverlappingVolume for each covered volume type.
2. Patches OxygenVolumeManager.IsPositionInsideBreathableVolume / IsPositionInsideNonBreathableVolume (custom alpha-aware methods).
3. Patches DeadzoneVolumeManager.GetMostDangerousOverlappingVolume.
4. Primes the indexes from each manager's existing volume list (handles plugin reload after level boot).

On every AddVolume, the volume's world-space AABB is computed (8 corners for boxes, position ± radius for spheres) and the volume is registered in every region cell its AABB touches.

On every GetFirstOverlappingVolume(position) query, the plugin looks up the single region cell containing position and runs IsPositionInsideVolume only on the candidates in that cell — typically 0–5 volumes instead of all 200+.

Configuration

None. Plugin works out of the box.

Compatibility

• RocketMod-based Unturned servers (LDM / Legally-Distinct-Missile).
• Tested on Unturned 3.26.x.
• Compatible with CaliforniaLagFix (RBMKBlaze) but redundant — this plugin solves the same perf problem without removing AmbianceVolume gameplay (snow shelter, per-area weather, fishing intervals all preserved).