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

536 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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