active-cubiomes/docs/search.md
2026-10-12 10:23:10 +00:00

17 KiB
Raw Permalink Blame History

cubiomes-search — CLI поиска сидов (с продвинутыми условиями)

cubiomes.search — модуль для поиска Minecraft-сидов, удовлетворяющих условиям по биомам, структурам и прочему. Работает как CLI-утилита и как Python-библиотека.


Запуск

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    Не выводить счётчик прогресса

Примеры использования

Проверить один сид

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 сидов с грибным островом и бедлендами

python -m cubiomes.search \
    --mc 1.21 \
    --biome mushroom_fields badlands \
    --biome-radius 3000 \
    --count 5

Деревня и монумент в 500 блоках от старта

python -m cubiomes.search \
    --mc 1.21 \
    --structure Village Monument \
    --struct-radius 500 \
    --count 3 \
    --show-spawn

Поиск в диапазоне с 4 процессами

python -m cubiomes.search \
    --seeds 0:100000000 \
    --mc 1.21 \
    --biome cherry_grove \
    --biome-radius 2000 \
    --workers 4 \
    --count 20 \
    --no-progress

Квад-база ведьминых хижин

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 [...]

Спавн близко к стартовой точке И деревня рядом

python -m cubiomes.search \
    --mc 1.21 \
    --spawn-max-dist 200 \
    --spawn-biome plains \
    --structure Village --struct-radius 500 \
    --count 5 --no-progress

Две структуры близко друг к другу

# Village и Ancient City в 500 блоках друг от друга
python -m cubiomes.search \
    --mc 1.21 \
    --proximity Village Ancient_City 500 \
    --struct-radius 3000 \
    --count 3

OR-биомы + минимум слайм-чанков

# Любой редкий биом рядом + минимум 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%

# Минимум 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

python -m cubiomes.search \
    --mc 1.21 \
    --structure Village \
    --struct-radius 300 \
    --count 10 \
    --format json \
    --show-spawn \
    --show-strongholds 3 \
    > results.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 для последующей обработки

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

Простой однострочный поиск

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)

Проверка одного сида

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)

Параллельный поиск с колбэком прогресса

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

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)

Полный пример с несколькими условиями:

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).