# cubiomes-search — CLI поиска сидов (с продвинутыми условиями) `cubiomes.search` — модуль для поиска Minecraft-сидов, удовлетворяющих условиям по биомам, структурам и прочему. Работает как CLI-утилита и как Python-библиотека. --- ## Запуск ```bash python -m cubiomes.search [OPTIONS] # или после pip install: cubiomes-search [OPTIONS] ``` --- ## Типы условий | Тип | Класс Python | CLI-флаг | |-----|-------------|---------| | Биом рядом с началом координат | `BiomeCondition` | `--biome NAME...` | | Хотя бы один из биомов (OR) | `AnyOfBiomes` | `--any-biome NAME...` | | Структура рядом с началом | `StructureCondition` | `--structure NAME...` | | Спавн в заданном радиусе/биоме | `SpawnCondition` | `--spawn-max-dist / --spawn-biome` | | Первые N стронгхолдов в радиусе | `StrongholdCondition` | `--stronghold-radius / --stronghold-count` | | Две структуры близко друг к другу | `ProximityCondition` | `--proximity A B D` | | Квад-база структуры | `QuadStructureCondition` | `--quad STRUCT` | | Плотность биома в области | `BiomeDensityCondition` | `--biome-density BIOME FRAC` | | Минимум слайм-чанков | `SlimeDensityCondition` | `--min-slime-chunks N` | | Произвольный код | `CustomCondition` | — (только Python API) | Все условия работают с **AND-семантикой** — сид должен пройти каждое из них. --- ## Аргументы командной строки ### Источник сидов (взаимоисключающие) | Аргумент | Описание | |---------|---------| | `--seed N` | Проверить один конкретный сид | | `--seeds START:STOP` | Перебрать диапазон (включительно) | | `--random-seeds` | Случайные 64-битные сиды (бесконечно) | Если ничего не указано — используется `--random-seeds`. ### Версия Minecraft ``` --mc VERSION Строка версии, например: '1.21', '1.18.2', 'b1.7' По умолчанию: 1.21 --large-biomes Использовать тип мира Large Biomes ``` ### Условия по биомам ``` --biome NAME [NAME ...] Один или несколько биомов, все должны присутствовать. Имена из BiomeID: mushroom_fields, badlands, cherry_grove, ... --biome-radius R Радиус поиска в биомных координатах (≈ R×4 блоков). По умолчанию: 1024 (~4096 блоков) --spawn-biome NAME Биом в точке спавна мира. ``` ### Условия по структурам ``` --structure NAME [NAME ...] Структуры, все должны быть жизнеспособны (с проверкой биома). Имена из StructureType: Village, Monument, Mansion, Desert_Pyramid, ... --struct-radius R Максимальное расстояние от начала координат в блоках. По умолчанию: 2048 ``` ### Прочие условия ``` --slime-chunk CX CZ Чанк (CX, CZ) должен быть слайм-чанком. --spawn-biome NAME Биом в точке спавна мира. --spawn-max-dist D Спавн мира не дальше D блоков от (0, 0). --stronghold-radius R Первый N стронгхолдов должны быть в радиусе R блоков от начала. --stronghold-count N Количество стронгхолдов для проверки (по умолчанию: 1). --proximity STRUCT_A STRUCT_B DIST STRUCT_A и STRUCT_B должны быть в DIST блоках друг от друга. Флаг повторяемый: --proximity Village Monument 400 --proximity Village Mansion 2000 --quad STRUCT Квад-база: 4 жизнеспособных экземпляра STRUCT в сетке 2×2 регионов, все в пределах --quad-dist блоков от общего центроида. --quad-dist R Максимальный радиус от центроида (по умолчанию: 128) --quad-max-regions N Поиск в ±N регионах от нуля (по умолчанию: 4) --biome-density BIOME FRACTION Не менее FRACTION (0–1) заданной области должно быть биомом BIOME. Область задаётся через --biome-density-area. --biome-density-area X Z SX SZ Биомные координаты области для --biome-density (по умолчанию: -256 -256 512 512) --min-slime-chunks N Минимум N слайм-чанков в области из --slime-area. --slime-area CX CZ CW CH Область чанков для --min-slime-chunks (по умолчанию: -4 -4 9 9) ``` ### Вывод ``` --count N Остановиться после N найденных сидов (0 = без ограничений) --format text | json | csv (по умолчанию: text) --show-spawn Включить приблизительный спавн в вывод --show-strongholds N Первые N стронгхолдов в вывод --info При --seed: подробная информация о сиде ``` ### Производительность ``` --workers N Параллельных процессов (по умолчанию: 1) --batch-size N Сидов на батч (по умолчанию: 4096) --no-progress Не выводить счётчик прогресса ``` --- ## Примеры использования ### Проверить один сид ```bash python -m cubiomes.search --seed 123456789 --info ``` ``` Seed: 123456789 (1.21.11) Shadow: 11066951453057188608 Spawn: (64, -48) biome=forest First 5 strongholds: [0] (-1116, -1596) (1947 blocks from origin) [1] (2468, -108) (2470 blocks from origin) ... Biomes at scale 4 (sample points): ( 0, 0) river ( 256, 0) ocean ... Common structures near origin: Village (-272, 160) (316 blocks) Monument (1200, 0) (1200 blocks) Slime chunks (9×9 area): 3 found (-3, -2) (0, 1) (2, 0) ``` --- ### Найти 5 сидов с грибным островом и бедлендами ```bash python -m cubiomes.search \ --mc 1.21 \ --biome mushroom_fields badlands \ --biome-radius 3000 \ --count 5 ``` --- ### Деревня и монумент в 500 блоках от старта ```bash python -m cubiomes.search \ --mc 1.21 \ --structure Village Monument \ --struct-radius 500 \ --count 3 \ --show-spawn ``` --- ### Поиск в диапазоне с 4 процессами ```bash python -m cubiomes.search \ --seeds 0:100000000 \ --mc 1.21 \ --biome cherry_grove \ --biome-radius 2000 \ --workers 4 \ --count 20 \ --no-progress ``` --- ### Квад-база ведьминых хижин ```bash python -m cubiomes.search \ --mc 1.21 \ --quad Swamp_Hut --quad-dist 128 \ --count 3 --seeds 0:100000000 --workers 4 ``` ``` seed=3256984 (1.21.11) struct Swamp_Hut_quad_0 block-coords (-1648, 2384) struct Swamp_Hut_quad_1 block-coords (-1392, 2336) struct Swamp_Hut_quad_2 block-coords (-1600, 2576) struct Swamp_Hut_quad_3 block-coords (-1344, 2528) quad Swamp_Hut center (-1496, 2456) positions [...] ``` ### Спавн близко к стартовой точке И деревня рядом ```bash python -m cubiomes.search \ --mc 1.21 \ --spawn-max-dist 200 \ --spawn-biome plains \ --structure Village --struct-radius 500 \ --count 5 --no-progress ``` ### Две структуры близко друг к другу ```bash # Village и Ancient City в 500 блоках друг от друга python -m cubiomes.search \ --mc 1.21 \ --proximity Village Ancient_City 500 \ --struct-radius 3000 \ --count 3 ``` ### OR-биомы + минимум слайм-чанков ```bash # Любой редкий биом рядом + минимум 6 слайм-чанков в 9×9 python -m cubiomes.search \ --mc 1.21 \ --any-biome mushroom_fields cherry_grove pale_garden \ --biome-radius 2000 \ --min-slime-chunks 6 \ --count 5 ``` ### Плотность биома > 20% ```bash # Минимум 20% площади 512×512 вокруг нуля — бэдлэнды python -m cubiomes.search \ --mc 1.21 \ --biome-density badlands 0.20 \ --biome-density-area -256 -256 512 512 \ --count 3 ``` ### Вывод в JSON ```bash python -m cubiomes.search \ --mc 1.21 \ --structure Village \ --struct-radius 300 \ --count 10 \ --format json \ --show-spawn \ --show-strongholds 3 \ > results.json ``` Пример JSON-объекта: ```json { "seed": 8, "mc": 32, "mc_name": "1.21.11", "biome_positions": {}, "structure_positions": { "Village": [16, -224] }, "spawn": [64, -48], "spawn_biome": 4, "strongholds": [[-1116, -1596], [2468, -108], [-908, 1636]] } ``` --- ### CSV для последующей обработки ```bash python -m cubiomes.search \ --mc 1.21 \ --structure Village Monument \ --struct-radius 1000 \ --seeds 0:5000000 \ --format csv \ --count 100 \ > seeds.csv ``` ``` seed,mc,biomes,structures,spawn_x,spawn_z,spawn_biome 1,,,"Village@-240,-912|Monument@816,-272",,, ``` --- ## Python API ### Простой однострочный поиск ```python from cubiomes.search import SearchCriteria, BiomeCondition, SeedSearch from cubiomes import MCVersion, BiomeID criteria = SearchCriteria( mc=MCVersion.MC_1_21, biomes=[ BiomeCondition(BiomeID.mushroom_fields, radius=2000), BiomeCondition(BiomeID.badlands, radius=3000), ], ) search = SeedSearch(criteria) result = search.run( seed_range=(0, 50_000_000), count=1, ).__next__() print(result.seed) print(result.biome_positions) ``` ### Проверка одного сида ```python from cubiomes.search import SearchCriteria, StructureCondition, SeedSearch from cubiomes import MCVersion, StructureType criteria = SearchCriteria( mc=MCVersion.MC_1_21, structures=[StructureCondition(StructureType.Village, radius=300)], ) result = SeedSearch(criteria).check_seed( 123456789, show_spawn=True, show_strongholds=3, ) if result: print(result) ``` ### Параллельный поиск с колбэком прогресса ```python from cubiomes.search import SearchCriteria, StructureCondition, SeedSearch from cubiomes import MCVersion, StructureType criteria = SearchCriteria( mc=MCVersion.MC_1_21, structures=[ StructureCondition(StructureType.Village, radius=500), StructureCondition(StructureType.Monument, radius=500), ], ) def on_progress(checked, found, rate): print(f"\r{checked:,} seeds checked | {found} found | {rate:,.0f}/s", end="", flush=True) results = [] for r in SeedSearch(criteria).run( seed_range=(0, 10_000_000), count=5, workers=4, progress_cb=on_progress, ): results.append(r) print(f"\nFound seed: {r.seed}") print(f"\nTotal results: {len(results)}") ``` ### Продвинутые условия через Python API ```python from cubiomes.search import ( SearchCriteria, SeedSearch, SpawnCondition, StrongholdCondition, ProximityCondition, QuadStructureCondition, BiomeDensityCondition, SlimeDensityCondition, AnyOfBiomes, CustomCondition, ) from cubiomes import MCVersion, BiomeID, StructureType, Dimension, Generator # ── SpawnCondition ───────────────────────────────────────────────────────── SpawnCondition(max_distance=500) # спавн ≤ 500 блоков от (0,0) SpawnCondition(biome_id=BiomeID.plains) # спавн в равнинах SpawnCondition(max_distance=300, biome_id=BiomeID.forest) # оба условия # ── StrongholdCondition ──────────────────────────────────────────────────── StrongholdCondition(count=1, max_distance=2000) # первый стронгхолд < 2000 блоков StrongholdCondition(count=3, max_distance=5000) # первые 3 стронгхолда < 5000 блоков # ── ProximityCondition ───────────────────────────────────────────────────── ProximityCondition( struct_a=StructureType.Village, struct_b=StructureType.Monument, max_dist=400, # максимальное расстояние между ними search_radius=3000, # радиус поиска от начала координат ) # ── QuadStructureCondition ───────────────────────────────────────────────── QuadStructureCondition( struct_type=StructureType.Swamp_Hut, max_dist=128, # все 4 хижины в 128 блоках от центроида max_regions=4, # искать в ±4 регионах от нуля ) # ── BiomeDensityCondition ────────────────────────────────────────────────── BiomeDensityCondition( biome_id=BiomeID.badlands, min_fraction=0.20, # минимум 20% площади x=-256, z=-256, sx=512, sz=512, scale=4, ) # ── SlimeDensityCondition ────────────────────────────────────────────────── SlimeDensityCondition( min_count=6, # минимум 6 слайм-чанков cx=-4, cz=-4, cw=9, ch=9, # область 9×9 чанков ) # ── AnyOfBiomes ──────────────────────────────────────────────────────────── AnyOfBiomes( biome_ids=[BiomeID.mushroom_fields, BiomeID.cherry_grove], radius=2000, ) # ── CustomCondition ──────────────────────────────────────────────────────── def my_filter(seed: int, mc: int): \"\"\"Returns dict on success, False on failure.\"\"\" g = Generator(mc) g.apply_seed(Dimension.DIM_OVERWORLD, seed) # ... any logic ... return {"my_data": 42} # True-y value with extra data CustomCondition(my_filter) ``` **Полный пример с несколькими условиями:** ```python criteria = SearchCriteria( mc=MCVersion.MC_1_21, # Базовые условия (AND) biomes=[BiomeCondition(BiomeID.mushroom_fields, radius=2000)], structures=[StructureCondition(StructureType.Village, radius=500)], # Продвинутые условия (AND) conditions=[ SpawnCondition(max_distance=300), StrongholdCondition(count=1, max_distance=2000), SlimeDensityCondition(min_count=5), AnyOfBiomes([BiomeID.cherry_grove, BiomeID.pale_garden], radius=3000), ], ) search = SeedSearch(criteria) for result in search.run(seed_range=(0, 100_000_000), count=5, workers=4): print(f"Seed {result.seed}:") print(f" Mushroom fields at: {result.biome_positions}") print(f" Village at: {result.structure_positions.get('Village')}") print(f" Spawn: {result.spawn}") print(f" Slime chunks: {result.extra.get('slime_chunk_count')}") print() ``` ### `SeedResult` атрибуты | Атрибут | Тип | Описание | |---------|-----|---------| | `seed` | `int` | Мировой сид | | `mc` | `int` | Версия MC | | `biome_positions` | `dict[str, (x,z)]` | Биомы в биомных координатах | | `structure_positions` | `dict[str, (x,z)]` | Структуры в блочных координатах | | `spawn` | `(x,z) | None` | Приблизительный спавн | | `spawn_biome` | `int | None` | Биом спавна | | `strongholds` | `list[(x,z)]` | Список стронгхолдов | | `as_dict()` | `dict` | JSON-сериализуемый словарь | --- ## Скорость поиска Ориентировочные значения на одном процессе: | Тип проверки | сидов/сек | |-------------|----------| | `is_slime_chunk` | ~50 000 000 | | `get_biome_at` (scale=4) | ~500 000 | | `gen_biomes` 64×64 (scale=4) | ~50 000 | | `check_for_biomes` (multi-scale) | ~200 000 | | `is_viable_structure_pos` | ~200 000 | С `--workers 4` скорость линейно масштабируется (примерно ×3.5–4).