Spawn Methods

Spawn Methods

A method receives a SpawnContext and returns a ResolveResult with a feet position, dimension, angle, status and warnings. Methods only compute a position; the caller decides whether to persist it.

Common concepts

• Feet position is the block the player's feet occupy. Level.getHeight(...) already returns this value; do not add one.
• Chunk budget: most methods accept max_chunk_loads and will force-load chunks up to that budget. The global default comes from search.maxChunkLoads.
• Safe standing requires a sturdy non-fluid block below, and passable, non-fluid feet and head positions.
• A method returning UNSAFE/EMPTY/TIMEOUT triggers the template's fallback.

default

Overworld-style ring search for the nearest safe land.

Parameter	Default	Meaning
center_x, center_z	0, 0	Search center.
max_radius	256	Maximum ring radius.
ring_step	64	Distance between rings.
max_surface_depth	16	How far below the heightmap top a surface point may be.
min_surface_y	seaLevel - 16	Reject points below this Y.
vanilla_fallback	true	Try the vanilla climate sampler before giving up.
max_chunk_loads	config	Chunk-generation budget.

Sampling density grows with radius (16–64 points per ring). The vanilla fallback uses findSpawnPosition and PlayerRespawnLogic over a bounded area.

top

Nether-style downward scan from a ceiling.

Parameter	Default	Meaning
center_x, center_z	0, 0	Search center.
min_y	minBuildHeight + 1	Lowest Y to scan.
max_y	maxBuildHeight - 2	Start below this Y; set 127 for the Nether.
search_radius	128	Horizontal search radius.
ring_step	32	Ring distance.
avoid_lava	true	Skip lava.
max_chunk_loads	config	Chunk budget.

fixed

Returns exactly x, y, z.

Parameter	Default	Meaning
x, y, z	0, 64, 0	Feet position.
angle	random	Spawn yaw.
safe_check	true	If unsafe, return UNSAFE and trigger fallback.

portal_type

Finds a site that can fit a portal interior. It does not place portal blocks.

Parameter	Default	Meaning
center_x, center_z	0, 0	Search center.
min_y, max_y	minBuildHeight+32, 127	Vertical scan range.
search_radius	128	Horizontal radius.
ring_step	32	Ring distance.
portal_width, portal_height	2, 3	Interior size.
avoid_lava	true	Skip lava.
build_platform	true	Build a platform when no natural site is found.
platform_x/y/z	center, 64, center	Platform ground layer.
platform_size	5	Platform edge length.
platform_material	minecraft:netherrack	Platform block.
max_chunk_loads	config	Chunk budget.

A natural site requires a safe standing column, a solid floor, and enough non-fluid air for the interior. The first column must have solid ground; the other interior columns only need clear air. The platform fallback clears portal_height + 1 blocks above it.

cave

Finds a cavity with a solid floor and a low roof. It does not use the sky or surface heightmap, so it works in no-sky dimensions and underground.

Parameter	Default	Meaning
center_x, center_z	0, 0	Search center.
min_y, max_y	minBuildHeight+1, maxBuildHeight-2	Vertical scan range.
search_radius	128	Horizontal radius.
ring_step	32	Ring distance.
min_air_height	2	Required non-fluid air above the feet.
roof_scan	8	Maximum distance to a roof.
avoid_lava	true	Skip lava.
max_chunk_loads	config	Chunk budget.

If no solid block is found within roof_scan above the feet, the column is treated as open surface and skipped. For the Nether, setting max_y to about 120 avoids scanning the open space above the bedrock ceiling.

floating_island

Wider ring search that can skip the center.

Parameter	Default	Meaning
center_x, center_z	0, 0	Search center.
min_radius	64	First ring radius.
max_radius	2048	Maximum radius.
ring_step	64	Ring distance.
max_surface_depth	32	Depth below the heightmap top.
max_chunk_loads	config	Chunk budget.

water_world

Treats fluids as air and prefers dry land; can return a submerged solid-ground candidate when no dry land is found.

Parameter	Default	Meaning
center_x, center_z	0, 0	Search center.
max_radius	2048	Maximum radius.
ring_step	64	Ring distance.
allow_submerged	true	Allow returning a submerged candidate.
max_chunk_loads	config	Chunk budget.

platform

Builds a platform as the final fallback.

Parameter	Default	Meaning
x, y, z	0, 64, 0	Platform ground layer.
size	3	Edge length; even values are rounded up.
material	minecraft:stone	Platform block.

In simulate mode it returns the position without modifying the world.