How Matching Works

This page explains what happens between a supporter pressing search and a set of candidates appearing. It is written for staff tuning a world, and it is the page to read when a search comes back empty.

The pipeline

For each attempt, up to 200 attempts or until enough candidates are accepted:

1. Draw a point

A random angle and a random distance between the world's minimum and maximum search distance, measured from the world origin.

2. Snap to the nearest real match

A random dart almost never lands inside a specific biome patch, especially a patchy one like a swamp. So each draw is snapped to the nearest actual occurrence of the requested landscape within 3,000 blocks. That turns the question from "did the dart land in the patch" into "is there a patch anywhere near the dart", which is what makes rare biomes findable at all. If there is no occurrence in range, the attempt is discarded.

Draws are bucketed into 200-block cells and their snap result is reused, so repeated nearby draws do not re-run the same expensive terrain scan.

3. Cheap geometry checks

The candidate plot is rejected if it:

• falls outside the search distance band,
• crosses the world border, allowing for the safety margin,
• touches the spawn keep-out plus its buffer,
• touches any enabled exclusion zone plus its buffer,
• comes within the minimum gap of an existing claim that has exclusion enabled, or
• comes within the minimum candidate separation of another candidate already accepted for this supporter.

These run before any terrain sampling, because they are almost free.

4. Coverage sampling

Only survivors get sampled. The plot is measured for:

• combined coverage, the share of the plot that is any requested landscape,
• connected coverage, the share that forms one contiguous piece rather than scattered fragments, and
• adjacency gap, with a secondary selector, the distance between the two landscapes.

The candidate is rejected if combined coverage or connected coverage is below the world's threshold, if a secondary was requested but does not appear inside the plot at all, or if the adjacency gap exceeds the maximum.

5. Score

Accepted candidates are scored out of 100:

Component	Weight
Combined coverage	40%
Connected coverage	35%
Adjacency	25%

With a single selector, adjacency scores full marks. With a secondary, it falls off with the gap between the two landscapes and reaches zero at 64 blocks.

The score is what a supporter compares candidates on, and it is stored on the claim.

Why a search found nothing

A search that returns no candidates has exhausted all 200 attempts without anything clearing every filter. The usual causes, roughly in order:

1. The biome is not in range. The requested landscape does not occur within the search band on this seed. Widen maximumSearchDistance or reduce minimumSearchDistance.
2. Thresholds are too tight. A 70% combined coverage floor is demanding for a patchy biome at a 100-block radius. Lower the floor, or accept that some landscapes only work at smaller radii.
3. A two-selector request is too specific. Two landscapes both present and within 32 blocks of each other is a much rarer thing than either alone. Widen maximumAdjacencyGapBlocks, or search for one.
4. The world is full. Enough claims and exclusion zones now cover the search area that little is left. Check the world map, and consider disabling exclusion on claims that no longer need to block.
5. The search area is too sparse. If maximumSearchDistance was set to match a huge border, 200 draws across that area will rarely land anywhere useful. See the warning in Configuration.

Coverage is not a survey

Coverage is measured from the world seed's biome generation, not from the live server. Player builds, terraforming, structures, and anything that has happened since generation are invisible to it. A plot that scores 100 can still contain someone's abandoned base. Exclusion zones are the tool for that, and spot-checking a candidate in game before a campaign opens is worth the few minutes.