536 lines
17 KiB
Markdown
536 lines
17 KiB
Markdown
# 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).
|