Scan and Spatial Memory

Why spatial memory exists

A typical Overworld is only roughly half safely teleportable - oceans, rivers, ravines, and steep terrain eat the rest; the Nether is mostly lava and stone, and the End is nearly all void. A plugin with no memory pays the full chunk-load cost to rediscover this one candidate at a time, forever.

RTP instead remembers which sectors of a region failed safety checks. As it evaluates candidates it records the bad ground per region (a "bad-location map") and the spiral selector steps over those sectors instead of rerolling into them. The result is the opposite of the usual RTP behavior: the longer a region runs, the faster and more reliable its teleports get, because known-bad ground is never loaded again.

This learned state is persistent - it is written to your database backend (config.yml database) on shutdown and reloaded on startup, so a restart does not throw the learning away.

/rtp scan - building memory without players

You do not have to wait for player traffic to populate spatial memory. /rtp scan walks a region's spiral in the background, off the main thread, running the same safety verification a real teleport would and recording the verdicts. It never blocks the main thread.

/rtp scan                          # resume, or start, a scan
/rtp scan start [region=<name>]    # start scanning a region
/rtp scan pause                    # pause the running scan
/rtp scan resume                   # resume a paused scan
/rtp scan cancel                   # stop the running scan
/rtp scan reset  [region=<name>]   # discard learned data and start over

A bare /rtp scan resumes (or starts) a scan. The permission node is rtp.scan. (This replaces the older /rtp fill.)

Warning Learned data becomes invalid if the region's geometry changes. Run scans after a region's shape, radius, and center are finalized. Changing a region's shape clears its memory by design (mismatched datasets are worse than none); use /rtp scan reset if you want to rebuild deliberately.

Do I need Chunky or another pre-generator?

No. /rtp scan is a built-in, off-tick generator, but its philosophy is different from whole-world pre-generation:

• Chunky / pre-generators load every chunk up front so the world exists on disk.
• /rtp scan pre-verifies candidates and remembers which sectors are unsafe, so it learns to avoid loading bad ground at all.

You can still run Chunky alongside RTP if you want a fully pre-generated map - the two are complementary. But you do not need it just to make /rtp fast.

Relationship to the location queues

Spatial memory is not the same thing as the pre-warmed location cache:

• Spatial memory is the persisted bad-location map per region - it tells the selector which coordinates to skip.
• The location cache (cacheCap in the region file) is the pool of ready-to-serve, already-verified coordinates that make /rtp instant.

Scanning improves both: by skipping known-bad ground, candidate generation succeeds more often, which keeps the cache full with less work.

See also: Performance, Regions, Why.