Performance

performance.yml tunes RTP for faster or slower servers. Edit case by case - misuse (e.g. high maxAttempts plus synchronous loading) can effectively DDoS your own server.

Task timing and limits

Key	Default	Purpose
maxAttempts	32	Max location search attempts before giving up. High impact - higher values cost more CPU per request.
period	20	Ticks between background cache cycles (20 ticks = 1 second). Lower refills faster but uses more CPU.
syncAllottedTime	50	Max milliseconds per tick spent on synchronous RTP tasks.
asyncAllottedTime	50	Max milliseconds per tick spent on asynchronous RTP tasks.

World loading

Key	Default	Purpose
viewDistanceSelect	0	Chunk radius pre-loaded around candidate locations during selection. High impact.
viewDistanceTeleport	0	Chunk radius pre-loaded around the destination before teleport. High impact.
syncLoading	false	Synchronous chunk loading for selection. Not recommended - can hang the server.

Throttling and queueing

Key	Default	Purpose
minTPS	19.0	Minimum server TPS (0.0-20.0) required to queue new locations.
postTeleportQueueing	false	Immediately try to refill the cache after a teleport.

Parsing and recall

Key	Default	Purpose
onEventParsing	false	Parse permissions on every event. Incompatible with *.* permissions.
effectParsing	true	Parse effect permissions on startup.
biomeRecall	true	Reuse previously found biome locations.
biomeRecallForced	false	Only use biomes already discovered and cached.
checkOnChunkLoads	false	Passively scan for safe locations in all loaded chunks in range. High impact on busy servers.

Observational mode

Key	Default	Purpose
visitorEnabled	true	Background "region data visitor" that gathers bad-location and biome data even when the cache is full, without triggering worldgen. Low impact.

Tuning playbook (symptom -> knob)

Change one knob at a time, then watch /rtp info for a tick or two before changing anything else. The dashboard counter named in each row is the one to watch.

Symptom (from /rtp info)	Likely cause	First knob to try	Then
cached sits near zero, locationQueue non-zero	Generation is not keeping up with demand	Run /rtp scan start region=<name> to build spatial memory	Lower period (refill more often), enable postTeleportQueueing
cached low even when idle	Cache refills too slowly	Lower period	Raise the region's cacheCap (in the region file)
TPS drops / MSPT spikes during /rtp bursts	Too much work per tick	Lower maxAttempts; keep syncLoading: false	Lower syncAllottedTime / asyncAllottedTime; raise minTPS so refills back off under load
Rising pipelineMsP95/P99	Chunk-load / verification cost per attempt	Confirm spatial memory is populated (scan); keep viewDistanceSelect/viewDistanceTeleport at 0 unless you need a buffer	Verify the Anvil pre-filter is active
High memBadPct, one dominant memTopCause	A filter is rejecting most candidates	Loosen that cause in safety.yml or biome controls	Re-scan after changing geometry/filters
Memory pressure with a huge region	cacheCap too high, or scanning an unbounded region	Lower cacheCap; do not scan effectively unbounded regions	Let traffic-driven learning fill spatial memory instead
Server hangs while selecting	Synchronous chunk loading	Set syncLoading: false (the default)	Never combine high maxAttempts with syncLoading: true

!!! warning "The one combination to never ship" High maxAttempts plus syncLoading: true can effectively DDoS your own server: every failed attempt loads chunks synchronously on the tick thread. Keep syncLoading: false and let the async pipeline and spatial memory do the work.

!!! tip "Sizing rule of thumb" Bigger regions need either a scan or patience (traffic-driven learning), not a bigger cacheCap. The cache holds ready coordinates; spatial memory is what makes finding new ones cheap. Front-load learning with /rtp scan on reasonably-sized regions, and reserve large/unbounded regions for traffic-driven learning.

version is an internal config version - do not change it.