# active-cubiomes Python/Cython bindings for [cubiomes](https://github.com/xpple/cubiomes) — a fast C library that replicates Minecraft's world-generation algorithms without running the game. ``` pip install active-cubiomes ``` > **Import name:** `import cubiomes` (the distribution is `active-cubiomes`) --- ## Quick start ```python from cubiomes import Generator, MCVersion, Dimension, BiomeID g = Generator(MCVersion.MC_1_21) g.apply_seed(Dimension.DIM_OVERWORLD, 123456789) biome = g.get_biome_at(0, 63, 0) # block coords print(BiomeID(biome).name) # "river" # 256×256 biome map at 1:4 scale ids = g.gen_biomes(-128, -128, 256, 256) # array.array('i') import numpy as np grid = np.array(ids, dtype=np.int32).reshape(256, 256) ``` ## Structure finding ```python from cubiomes import StructureType, get_structure_pos, is_viable_structure_pos seed = 123456789 mc = MCVersion.MC_1_21 for reg_x in range(-3, 4): for reg_z in range(-3, 4): pos = get_structure_pos(StructureType.Village, mc, seed, reg_x, reg_z) if pos and is_viable_structure_pos(StructureType.Village, g, *pos): print(f"Village at {pos}") ``` ## Strongholds ```python from cubiomes import iter_strongholds for i, (x, z) in enumerate(iter_strongholds(g, seed=123456789)): print(f"Stronghold {i}: ({x}, {z})") if i >= 4: break ``` ## Seed search CLI ```bash # Seeds with mushroom fields AND badlands within 4 km cubiomes-search --mc 1.21 --biome mushroom_fields badlands --biome-radius 4000 --count 5 # Quad witch-hut base cubiomes-search --mc 1.21 --quad Swamp_Hut --quad-dist 128 --count 3 # Inspect one seed cubiomes-search --seed 123456789 --info # Village and Monument within 400 blocks of each other, JSON output cubiomes-search --mc 1.21 --proximity Village Monument 400 --count 10 --format json ``` ## Seed search Python API ```python from cubiomes.search import ( SearchCriteria, BiomeCondition, StructureCondition, SpawnCondition, StrongholdCondition, ProximityCondition, QuadStructureCondition, BiomeDensityCondition, SlimeDensityCondition, AnyOfBiomes, CustomCondition, SeedSearch, ) from cubiomes import MCVersion, BiomeID, StructureType criteria = SearchCriteria( mc=MCVersion.MC_1_21, biomes=[BiomeCondition(BiomeID.mushroom_fields, radius=2000)], conditions=[ SpawnCondition(max_distance=500), StrongholdCondition(count=1, max_distance=2000), QuadStructureCondition(StructureType.Swamp_Hut, max_dist=128), ], ) for result in SeedSearch(criteria).run( seed_range=(0, 100_000_000), count=5, workers=4, ): print(result) ``` ## All condition types | Class | CLI flag | Description | |-------|----------|-------------| | `BiomeCondition` | `--biome NAME...` | Biome must exist near origin (AND) | | `AnyOfBiomes` | `--any-biome NAME...` | At least one biome (OR) | | `StructureCondition` | `--structure NAME...` | Structure viable near origin | | `SpawnCondition` | `--spawn-biome / --spawn-max-dist` | Spawn location/biome | | `StrongholdCondition` | `--stronghold-radius` | First N strongholds in radius | | `ProximityCondition` | `--proximity A B DIST` | Two structures near each other | | `QuadStructureCondition` | `--quad STRUCT` | Quad-farm base (2×2 regions) | | `BiomeDensityCondition` | `--biome-density BIOME FRAC` | Biome coverage fraction | | `SlimeDensityCondition` | `--min-slime-chunks N` | Minimum slime chunks | | `CustomCondition` | — (Python only) | Arbitrary `(seed, mc) → bool` function | ## Building from source Requires GCC and Python ≥ 3.8: ```bash git clone https://github.com/your-fork/active-cubiomes cd active-cubiomes pip install -e ".[dev]" ``` ## License The Python bindings are MIT licensed. The bundled [cubiomes](https://github.com/xpple/cubiomes) C library is also MIT licensed.