Structure finders API reference

The finders API locates Minecraft structures and world features from a world seed without simulating the full game. Structure positions depend only on the lower 48 bits of the world seed and the region coordinates, so most lookups are extremely fast. Biome checks are layered on top when you need to verify that conditions are met for a structure to actually spawn.

Key structs

`StructureConfig`

Holds the positioning parameters for a structure type in a given Minecraft version.

typedef struct StructureConfig {
    int32_t salt;        // additive seed constant for this structure type
    int8_t  regionSize;  // size of the placement grid in chunks
    int8_t  chunkRange;  // range within a region for the generation attempt
    uint8_t structType;  // StructureType enum value
    int8_t  dim;         // dimension constant
    float   rarity;      // spawn probability (not used by all types)
} StructureConfig;

Field	Type	Description
`salt`	`int32_t`	Additive seed constant unique to this structure type.
`regionSize`	`int8_t`	Side length of the placement grid in chunks.
`chunkRange`	`int8_t`	Maximum chunk offset within a region for the attempt.
`structType`	`uint8_t`	`StructureType` enum value identifying the structure.
`dim`	`int8_t`	Dimension: `0` Overworld, `-1` Nether, `+1` End.
`rarity`	`float`	Generation probability (structure-specific; may be unused).

`StrongholdIter`

Iteration state for walking through stronghold positions in generation order.

typedef struct StrongholdIter {
    Pos      pos;        // accurate block position of current stronghold
    Pos      nextapprox; // approximate position (+/-112 blocks) of next
    int      index;      // stronghold index counter
    int      ringnum;    // ring number
    int      ringmax;    // max index within ring
    int      ringidx;    // index within ring
    double   angle;      // next angle within ring (radians)
    double   dist;       // next distance from origin (in chunks)
    uint64_t rnds;       // 48-bit random seed
    int      mc;         // Minecraft version
} StrongholdIter;

`StructureType` enum

Constant	Notes
`Feature`	Temple generation attempts (pre-1.13).
`Desert_Pyramid`
`Jungle_Temple`	Alias: `Jungle_Pyramid`
`Swamp_Hut`
`Igloo`
`Village`
`Ocean_Ruin`
`Shipwreck`
`Monument`
`Mansion`
`Outpost`
`Ruined_Portal`
`Ruined_Portal_N`	Nether ruined portal.
`Ancient_City`
`Treasure`	Buried treasure.
`Mineshaft`
`Desert_Well`
`Geode`
`Fortress`
`Bastion`
`End_City`
`End_Gateway`
`End_Island`
`Trail_Ruins`
`Trial_Chambers`

Finding structure positions

`getStructureConfig`

int getStructureConfig(int structureType, int mc, StructureConfig *sconf);

Populates sconf with the positioning configuration for the given structure type and MC version. Returns non-zero on success; returns zero if the version does not support the structure type.

structureType

int

required

A StructureType enum value.

int

required

Minecraft version constant.

sconf

StructureConfig *

required

Output struct to populate.

`getStructurePos`

int getStructurePos(int structureType, int mc, uint64_t seed,
    int regX, int regZ, Pos *pos);

Returns the block position of the generation attempt for the given structure type in region (regX, regZ). Only the lower 48 bits of seed are used. Returns zero if the region produces no valid attempt for this type; returns non-zero otherwise. Use isViableStructurePos to confirm biome requirements are met.

structureType

int

required

A StructureType enum value.

int

required

Minecraft version constant.

seed

uint64_t

required

World seed (only the lower 48 bits are relevant).

regX

int

required

Region X coordinate (region size depends on structure type).

regZ

int

required

Region Z coordinate.

pos

Pos *

required

Output block position.

`getFeaturePos` (inline)

Pos getFeaturePos(StructureConfig config, uint64_t seed, int regX, int regZ);

Returns the block position for a small feature (uniform distribution) given a pre-fetched StructureConfig.

`getFeatureChunkInRegion` (inline)

Pos getFeatureChunkInRegion(StructureConfig config, uint64_t seed, int regX, int regZ);

Returns the chunk-within-region offset for a small feature. Multiply the result by 16 and add the region origin to get block coordinates.

`getLargeStructurePos` (inline)

Pos getLargeStructurePos(StructureConfig config, uint64_t seed, int regX, int regZ);

Returns the block position for large structures (monuments, mansions) that use a triangular distribution.

`getMineshafts`

int getMineshafts(int mc, uint64_t seed, int chunkX, int chunkZ,
    int chunkW, int chunkH, Pos *out, int nout);

Finds mineshaft generation attempts in a rectangular chunk area starting at (chunkX, chunkZ) with size (chunkW, chunkH). Writes up to nout positions to out. Returns the total count of chunks with mineshafts in the area.

int

required

Minecraft version.

seed

uint64_t

required

World seed.

chunkX

int

required

X origin in chunk coordinates.

chunkZ

int

required

Z origin in chunk coordinates.

chunkW

int

required

Width of the search area in chunks.

chunkH

int

required

Height of the search area in chunks.

out

Pos *

Output buffer for positions. Pass NULL to count only.

nout

int

Maximum number of positions to write to out.

`isSlimeChunk` (inline)

int isSlimeChunk(uint64_t seed, int chunkX, int chunkZ);

Returns non-zero if slimes can spawn in the chunk at (chunkX, chunkZ) for the given world seed.

seed

uint64_t

required

World seed.

chunkX

int

required

Chunk X coordinate.

chunkZ

int

required

Chunk Z coordinate.

Strongholds and spawn

`initFirstStronghold`

Pos initFirstStronghold(StrongholdIter *sh, int mc, uint64_t s48);

Determines the approximate position of the first stronghold (±112 blocks) from the lower 48 bits of the world seed without biome checks. If sh is non-null it is initialized for subsequent iteration with nextStronghold. Returns the approximate block position.

StrongholdIter *

Iterator to initialize. Pass NULL to get only the first position.

int

required

Minecraft version.

s48

uint64_t

required

Lower 48 bits of the world seed.

`nextStronghold`

int nextStronghold(StrongholdIter *sh, const Generator *g);

Performs biome checks on the iterator’s current position and advances it to the next stronghold. Pass NULL for g on MC 1.19.3+ to iterate approximate positions without biome checks. Returns the number of further strongholds after this one.

StrongholdIter *

required

Iterator initialized by initFirstStronghold.

const Generator *

Overworld generator with the world seed applied. Pass NULL for approximate-only iteration on 1.19.3+.

`getSpawn`

Pos getSpawn(const Generator *g);

Returns the world spawn position. This function is slow and may be inaccurate because spawn depends on the presence of grass blocks.

const Generator *

required

Seeded Overworld generator.

`estimateSpawn`

Pos estimateSpawn(const Generator *g, uint64_t *rng);

Returns a fast approximate spawn position. The optional rng output captures the random state after the search.

const Generator *

required

Seeded Overworld generator.

rng

uint64_t *

Optional output for the RNG state. Pass NULL to ignore.

`locateBiome`

Pos locateBiome(
    const Generator *g, int x, int y, int z, int radius,
    uint64_t validB, uint64_t validM, uint64_t *rng, int *passes);

Finds a suitable pseudo-random position within a square area centered on (x, y, z). This is the algorithm used internally for spawn and stronghold placement. It is accurate but slow.

const Generator *

required

Overworld generator.

int

required

Search origin X (block coordinate).

int

required

Search origin Y (block coordinate).

int

required

Search origin Z (block coordinate).

radius

int

required

Half-side of the search square in blocks.

validB

uint64_t

required

Bitset of valid biome IDs 0–63.

validM

uint64_t

required

Bitset of valid biome IDs 192–255.

rng

uint64_t *

Output RNG state. Initialize with setSeed(rng, world_seed) before calling. Pass NULL to ignore.

passes

int *

Output count of valid positions sampled. Pass NULL to ignore.

`getShadow` (inline)

uint64_t getShadow(uint64_t seed);

Returns the shadow seed: a world seed that produces the same structure positions as seed but with inverted biome distribution.

seed

uint64_t

required

Original world seed.

Validating structure positions

`isViableStructurePos`

int isViableStructurePos(int structType, Generator *g, int blockX, int blockZ, uint32_t flags);

Performs a biome check near (blockX, blockZ) to determine whether a structure of structType can spawn there. The generator is temporarily modified during the call and restored on return. Returns non-zero if the position is viable.

structType

int

required

A StructureType enum value.

Generator *

required

Generator initialized for the correct version, dimension, and seed.

blockX

int

required

Block X coordinate (from getStructurePos).

blockZ

int

required

Block Z coordinate.

flags

uint32_t

Optional structure-specific flags (e.g. biome variant for villages). Pass 0 for defaults.

`isViableFeatureBiome`

int isViableFeatureBiome(int mc, int structureType, int biomeID);

Returns non-zero if the biome biomeID can generate the specified structure type in the given version.

int

required

Minecraft version.

structureType

int

required

A StructureType enum value.

biomeID

int

required

Biome ID to test.

`isViableStructureTerrain`

int isViableStructureTerrain(int structType, Generator *g, int blockX, int blockZ);

Rules out structure positions in 1.18 where the surface height at the bounding box corners is too low. Primarily affects Desert_Pyramid, Jungle_Temple, and Mansion. Returns non-zero if the terrain could support the structure.

structType

int

required

Structure type to check.

Generator *

required

1.18 Overworld generator with seed applied.

blockX

int

required

Block X coordinate.

blockZ

int

required

Block Z coordinate.

Structure properties

`getVariant`

int getVariant(StructureVariant *sv, int structType, int mc, uint64_t seed,
    int blockX, int blockZ, int biomeID);

Retrieves structural properties such as rotation, bounding box, and variant flags for a structure instance. Only some structure types are supported.

StructureVariant *

required

Output variant data.

structType

int

required

Structure type.

int

required

Minecraft version.

seed

uint64_t

required

World seed.

blockX

int

required

Block X coordinate of the structure.

blockZ

int

required

Block Z coordinate of the structure.

biomeID

int

required

Biome at the structure position.

`getEndCityPieces`

int getEndCityPieces(Piece *pieces, uint64_t seed, int chunkX, int chunkZ);

Generates the structural pieces of an End City. The pieces buffer must hold at least END_CITY_PIECES_MAX (421) elements. Returns the number of pieces generated.

pieces

Piece *

required

Output buffer of at least END_CITY_PIECES_MAX elements.

seed

uint64_t

required

World seed.

chunkX

int

required

Chunk X coordinate of the End City.

chunkZ

int

required

Chunk Z coordinate of the End City.

`getFortressPieces`

int getFortressPieces(Piece *list, int n, int mc, uint64_t seed, int chunkX, int chunkZ);

Generates up to n structural pieces of a Nether Fortress. A buffer of ~400 is sufficient in practice. Returns the number of pieces generated.

list

Piece *

required

Output buffer.

int

required

Maximum number of pieces to generate.

int

required

Minecraft version.

seed

uint64_t

required

World seed.

chunkX

int

required

Chunk X coordinate of the Fortress origin.

chunkZ

int

required

Chunk Z coordinate.

`getFixedEndGateways`

void getFixedEndGateways(int mc, uint64_t seed, Pos src[20]);

Writes the 20 fixed inner gateway positions (in generation order) to src. These are the gateways that appear each time the Ender Dragon is defeated.

int

required

Minecraft version.

seed

uint64_t

required

World seed.

src

Pos[20]

required

Output array of 20 positions.

`getHouseList`

uint64_t getHouseList(int *houses, uint64_t seed, int chunkX, int chunkZ);

Determines the number of each house type generated in a village (MC < 1.14). Pass an array of length HOUSE_NUM (9) for houses. Returns the random seed state after the computation.

houses

int *

required

Output array of length HOUSE_NUM (9) indexed by house-type enum.

seed

uint64_t

required

World seed.

chunkX

int

required

Chunk X coordinate of the village origin.

chunkZ

int

required

Chunk Z coordinate.

Seed filters

`setupBiomeFilter`

void setupBiomeFilter(
    BiomeFilter *bf,
    int mc, uint32_t flags,
    const int *required, int requiredLen,
    const int *excluded, int excludedLen,
    const int *matchany, int matchanyLen);

Builds a BiomeFilter from lists of required, excluded, and match-any biome IDs. Biomes must not appear in more than one list. Pass NULL and 0 for unused lists.

BiomeFilter *

required

Output filter to populate.

int

required

Minecraft version.

flags

uint32_t

Generator flags (e.g. BF_APPROX for aggressive pre-filtering).

required

const int *

Array of biome IDs that must all be present. Pass NULL if none.

requiredLen

int

Length of required.

excluded

const int *

Array of biome IDs that must not be present. Pass NULL if none.

excludedLen

int

Length of excluded.

matchany

const int *

Array of biome IDs where at least one must be present. Pass NULL if none.

matchanyLen

int

Length of matchany.

`checkForBiomes`

int checkForBiomes(
    Generator         *g,
    int               *cache,
    Range              r,
    int                dim,
    uint64_t           seed,
    const BiomeFilter *filter,
    volatile char     *stop);

Generates the range r and checks whether it satisfies filter. Returns 0 if the filter fails, 1 if generation completed and passed, or 2 if it passed with incomplete generation. The generator is left in a partially initialized state after the call; re-apply a seed before further use.

Generator *

required

Generator set up for the correct version (seed applied internally).

cache

int *

Working buffer and biome output. Pass NULL to skip output.

Range

required

Range to check.

dim

int

required

Dimension: 0 Overworld, -1 Nether, +1 End.

seed

uint64_t

required

World seed.

filter

const BiomeFilter *

required

Filter produced by setupBiomeFilter.

stop

volatile char *

Abort flag. Set to non-zero from another thread to interrupt. Pass NULL if unused.

`checkForBiomesAtLayer`

int checkForBiomesAtLayer(
    LayerStack        *ls,
    Layer             *entry,
    int               *cache,
    uint64_t           seed,
    int                x,
    int                z,
    unsigned int       w,
    unsigned int       h,
    const BiomeFilter *filter);

Specialization of checkForBiomes for a LayerStack (Overworld, MC ≤ 1.17). The layer stack is modified in place.

LayerStack *

required

Layered generator (will be modified).

entry

Layer *

required

Generation entry point.

cache

int *

Output buffer or NULL.

seed

uint64_t

required

World seed.

int

required

X origin of the area.

int

required

Z origin of the area.

unsigned int

required

Width.

unsigned int

required

Height.

filter

const BiomeFilter *

required

Biome filter.

`monteCarloBiomes`

int monteCarloBiomes(
    Generator         *g,
    Range              r,
    uint64_t          *rng,
    double             coverage,
    double             confidence,
    int (*eval)(Generator *g, int scale, int x, int y, int z, void *data),
    void              *data);

Samples biomes at random positions within r and checks that at least coverage fraction of them satisfy eval. Uses a statistical confidence level to bound the number of samples. Returns non-zero if the coverage threshold is met.

Generator *

required

Seeded biome generator.

Range

required

Region to sample.

rng

uint64_t *

required

Random seed for sampling positions.

coverage

double

required

Minimum fraction of successful evaluations, in [0, 1].

confidence

double

required

Statistical confidence level, e.g. 0.95 for 95%.

eval

function pointer

required

Evaluation callback: returns 1 for success, 0 for failure, -1 to skip, or any other value to abort.

data

void *

User data passed to eval.

`getBiomeCenters`

int getBiomeCenters(
    Pos           *pos,
    int           *siz,
    int            nmax,
    Generator     *g,
    Range          r,
    int            match,
    int            minsiz,
    int            tol,
    volatile char *stop);

Finds center positions of biome regions matching match within the area r (requires scale = 4, sy = 1). Returns the number of entries written.

pos

Pos *

required

Output array of up to nmax center positions.

siz

int *

Output array of biome region sizes. Pass NULL to ignore.

nmax

int

required

Maximum number of output entries.

Generator *

required

Initialized Overworld generator.

Range

required

Area to examine (scale = 4, sy = 1).

match

int

required

Biome ID to search for.

minsiz

int

required

Minimum biome region size to report.

tol

int

required

Border tolerance in scaled units.

stop

volatile char *

Abort flag. Pass NULL if unused.

Biome noise finders (1.18+)

`getParaRange`

int getParaRange(const DoublePerlinNoise *para, double *pmin, double *pmax,
    int x, int z, int w, int h, void *data, int (*func)(void*,int,int,double));

Determines the value range of a climate noise parameter over the area (x, z, w, h) at 1:4 scale. Results are written to pmin and pmax (nullable). Returns non-zero on error.

para

const DoublePerlinNoise *

required

Climate noise parameter to evaluate.

pmin

double *

Output minimum. Pass NULL to skip.

pmax

double *

Output maximum. Pass NULL to skip.

int

required

X origin.

int

required

Z origin.

int

required

Width.

int

required

Height.

data

void *

User data for the optional callback.

func

function pointer

Optional callback called at each iteration. Return non-zero to abort.

`getBiomeParaExtremes`

const int *getBiomeParaExtremes(int mc);

Returns a pointer to an array of min/max parameter values that bound biome transitions for the given version.

int

required

Minecraft version (1.18+).

`getBiomeParaLimits`

const int *getBiomeParaLimits(int mc, int id);

Returns min/max noise parameter pairs (temperature, humidity, continentalness, erosion, depth, weirdness) at which biome id can generate, as 12 consecutive integers.

int

required

Minecraft version (1.18+).

int

required

Biome ID.

`getPossibleBiomesForLimits`

void getPossibleBiomesForLimits(char ids[256], int mc, int limits[6][2]);

Marks non-zero in ids for every biome that can generate within the given set of climate parameter limits.

ids

char[256]

required

Output array indexed by biome ID. Non-zero means the biome is possible.

int

required

Minecraft version (1.18+).

limits

int[6][2]

required

Min/max pairs for temperature, humidity, continentalness, erosion, depth, and weirdness.

`canBiomeGenerate`

int canBiomeGenerate(int layerId, int mc, uint32_t flags, int biomeID);

Returns non-zero if biomeID may generate at the given layer entry point.

layerId

int

required

Layer ID (e.g. L_BIOME_256, L_VORONOI_1).

int

required

Minecraft version.

flags

uint32_t

Generator flags.

biomeID

int

required

Biome ID to test.

`getAvailableBiomes`

void getAvailableBiomes(uint64_t *mL, uint64_t *mM, int layerId, int mc, uint32_t flags);

Fills the bitfields mL (IDs 0–63) and mM (IDs 128–191) with all biomes that can generate in the given version and layer.

uint64_t *

required

Output bitfield for biome IDs 0–63.

uint64_t *

required

Output bitfield for biome IDs 128–191.

layerId

int

required

Layer ID. Also supports L_OCEAN_TEMP_256 and 1.18+ (where layerId is ignored).

int

required

Minecraft version.

flags

uint32_t

Generator flags.

Generator API

Finders API

Documentation Index

​Key structs

​StructureConfig

​StrongholdIter

​StructureType enum

​Finding structure positions

​getStructureConfig

​getStructurePos

​getFeaturePos (inline)

​getFeatureChunkInRegion (inline)

​getLargeStructurePos (inline)

​getMineshafts

​isSlimeChunk (inline)

​Strongholds and spawn

​initFirstStronghold

​nextStronghold

​getSpawn

​estimateSpawn

​locateBiome

​getShadow (inline)

​Validating structure positions

​isViableStructurePos

​isViableFeatureBiome

​isViableStructureTerrain

​Structure properties

​getVariant

​getEndCityPieces

​getFortressPieces

​getFixedEndGateways

​getHouseList

​Seed filters

​setupBiomeFilter

​checkForBiomes

​checkForBiomesAtLayer

​monteCarloBiomes

​getBiomeCenters

​Biome noise finders (1.18+)

​getParaRange

​getBiomeParaExtremes

​getBiomeParaLimits

​getPossibleBiomesForLimits

​canBiomeGenerate

​getAvailableBiomes

Build docs developers (and LLMs) love

Key structs

`StructureConfig`

`StrongholdIter`

`StructureType` enum

Finding structure positions

`getStructureConfig`

`getStructurePos`

`getFeaturePos` (inline)

`getFeatureChunkInRegion` (inline)

`getLargeStructurePos` (inline)

`getMineshafts`

`isSlimeChunk` (inline)

Strongholds and spawn

`initFirstStronghold`

`nextStronghold`

`getSpawn`

`estimateSpawn`

`locateBiome`

`getShadow` (inline)

Validating structure positions

`isViableStructurePos`

`isViableFeatureBiome`

`isViableStructureTerrain`

Structure properties

`getVariant`

`getEndCityPieces`

`getFortressPieces`

`getFixedEndGateways`

`getHouseList`

Seed filters

`setupBiomeFilter`

`checkForBiomes`

`checkForBiomesAtLayer`

`monteCarloBiomes`

`getBiomeCenters`

Biome noise finders (1.18+)

`getParaRange`

`getBiomeParaExtremes`

`getBiomeParaLimits`

`getPossibleBiomesForLimits`

`canBiomeGenerate`

`getAvailableBiomes`