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

345 lines
11 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 — руководство пользователя
**cubiomes** — это Python/Cython-биндинг к библиотеке
[cubiomes](https://github.com/xpple/cubiomes), обеспечивающей быструю генерацию
биомов и структур Minecraft без запуска самой игры.
---
## Установка
```bash
# Зависимости
pip install cython
# Сборка в режиме разработки (in-place)
git clone https://github.com/xpple/cubiomes.git _cubiomes_src
python setup.py build_ext --inplace
pip install -e .
```
---
## Концепции
### Генератор
Центральный объект — `Generator`. Он настраивается один раз под версию Minecraft,
а затем «заполняется» сидом и измерением методом `apply_seed`.
```python
from cubiomes import Generator, MCVersion, Dimension
g = Generator(MCVersion.MC_1_21) # создать под версию
g.apply_seed(Dimension.DIM_OVERWORLD, 123456789) # привязать сид
```
Один генератор можно переключать между сидами и измерениями вызовом `apply_seed`.
### Масштаб координат
Большинство функций принимают параметр `scale`:
| scale | что это | когда использовать |
|------:|---------|-------------------|
| `1` | блочные координаты (Voronoi) | точный биом одного блока |
| `4` | биомные координаты (по умолчанию) | карты биомов, поиск |
| `16` | крупный масштаб | быстрый обзор |
| `64` | очень крупный | проверка температурных зон |
| `256` | максимальный | грубая фильтрация |
> Биомные координаты = блочные ÷ 4. Передавайте `y=63//4=15` для уровня моря
> при scale=4.
---
## Использование генератора
### Биом в точке
```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(100, 63, 200, scale=1)
# Биомные координаты ÷4 (стандарт, быстрее)
biome = g.get_biome_at(25, 15, 50, scale=4)
print(BiomeID(biome).name) # → "forest"
```
### Карта биомов региона
```python
# Генерирует плоскую карту 256×256 в биомных координатах
ids = g.gen_biomes(x=-128, z=-128, sx=256, sz=256, scale=4)
# ids — array.array('i') длиной 256*256
# Индексирование: ids[z_index * sx + x_index]
# Конвертация в numpy (опционально):
import numpy as np
grid = np.array(ids, dtype=np.int32).reshape(256, 256)
# grid[z_index, x_index]
```
### Нахождение спавна
```python
spawn = g.estimate_spawn() # быстро, приблизительно
spawn = g.get_spawn() # медленно, точно (проверяет траву)
print(f"Spawn: {spawn}")
```
### Поиск биома в радиусе
```python
# Найти ближайший mushroom_fields в радиусе 8000 блоков от (0,0,0)
pos = g.locate_biome(0, 0, 0, radius=2000, valid_biomes=[BiomeID.mushroom_fields])
# radius здесь в биомных координатах (~8000 блоков)
```
### Центры регионов биома
```python
# Найти центры patch'ей biome badlands в области 512×512 биомных клеток
centers = g.get_biome_centers(
x=-256, z=-256, sx=512, sz=512,
match=BiomeID.badlands,
min_size=50, # минимум 50 биомных клеток
)
for x, z in centers:
print(f"Badlands patch center at biome coords ({x}, {z})")
```
---
## Структуры
### Позиция структуры
```python
from cubiomes import (
StructureType, get_structure_pos,
is_viable_structure_pos, get_structure_config,
)
seed = 123456789
mc = MCVersion.MC_1_21
# Найти позицию деревни в регионе (0, 0)
pos = get_structure_pos(StructureType.Village, mc, seed, reg_x=0, reg_z=0)
if pos:
print(f"Village generation attempt at {pos}")
# Проверить биомы (нужен инициализированный генератор)
g = Generator(mc)
g.apply_seed(Dimension.DIM_OVERWORLD, seed)
if is_viable_structure_pos(StructureType.Village, g, pos[0], pos[1]):
print("Village will actually spawn here!")
```
> **Регионы**: Minecraft делит мир на регионы (обычно 32×32 чанка).
> Проверяйте несколько регионов вокруг нужной зоны.
### Перебор регионов в области
```python
import math
def find_structures_near(seed, mc, struct_type, radius_blocks=2000):
"""Найти все структуры в радиусе radius_blocks от (0,0)."""
cfg = get_structure_config(struct_type, mc)
if not cfg:
return []
region_blocks = cfg["region_size"] * 16
max_reg = math.ceil(radius_blocks / region_blocks) + 1
g = Generator(mc)
g.apply_seed(Dimension.DIM_OVERWORLD, seed)
results = []
for rx in range(-max_reg, max_reg + 1):
for rz in range(-max_reg, max_reg + 1):
pos = get_structure_pos(struct_type, mc, seed, rx, rz)
if pos is None:
continue
x, z = pos
if abs(x) > radius_blocks or abs(z) > radius_blocks:
continue
if is_viable_structure_pos(struct_type, g, x, z):
results.append(pos)
return results
villages = find_structures_near(123456789, MCVersion.MC_1_21, StructureType.Village)
print(f"Villages within 2000 blocks: {villages}")
```
### Вариант структуры
```python
from cubiomes import get_variant
# Получить поворот, координаты, флаги (заброшенная и т.д.)
sv = get_variant(StructureType.Village, mc, seed,
block_x=pos[0], block_z=pos[1],
biome_id=BiomeID.plains)
if sv:
print(f"Rotation: {sv.rotation}") # 0=north, 1=east, 2=south, 3=west
print(f"Abandoned: {sv.abandoned}")
print(f"Bounding box pos: {sv.pos}, size: {sv.size}")
```
---
## Стронгхолды
```python
from cubiomes import iter_strongholds, init_first_stronghold
# Быстрая приблизительная позиция первого стронгхолда (±112 блоков)
approx = init_first_stronghold(MCVersion.MC_1_21, seed=123456789)
print(f"First stronghold approximately at {approx}")
# Точные позиции с биомной проверкой
g = Generator(MCVersion.MC_1_21)
g.apply_seed(Dimension.DIM_OVERWORLD, 123456789)
for i, (x, z) in enumerate(iter_strongholds(g, seed=123456789)):
dist = math.sqrt(x**2 + z**2)
print(f"Stronghold {i}: ({x}, {z}) ~{dist:.0f} blocks")
if i >= 9:
break
```
---
## Biome Filter (фильтрация сидов)
`BiomeFilter` + `check_for_biomes` используют многоуровневую фильтрацию
(от грубого scale=256 до точного scale=4), что на порядок быстрее простого
перебора с `gen_biomes`.
```python
from cubiomes import setup_biome_filter, BiomeID, MCVersion, Dimension
mc = MCVersion.MC_1_21
# Все три биома должны присутствовать в области 512×512
bf = setup_biome_filter(
mc,
required=[BiomeID.mushroom_fields, BiomeID.badlands, BiomeID.jungle],
)
g = Generator(mc)
for seed in range(10_000_000):
result = g.check_for_biomes(
x=-256, z=-256, sx=512, sz=512, scale=4,
dim=Dimension.DIM_OVERWORLD,
seed=seed,
biome_filter=bf,
)
if result: # 1 = полная проверка пройдена
print(f"Found: {seed}")
break
```
---
## Вспомогательные функции
### Слайм-чанки
```python
from cubiomes import is_slime_chunk
if is_slime_chunk(seed=123456789, chunk_x=0, chunk_z=1):
print("Slime chunk!")
```
### Теневой сид
```python
from cubiomes import get_shadow
shadow = get_shadow(seed)
# get_shadow(get_shadow(seed)) == seed — всегда
```
### Перемещение структур
```python
from cumiomes import move_structure
# Сместить базовый сид так, чтобы структуры сдвинулись на 1 регион по X
shifted = move_structure(base_seed, reg_x=1, reg_z=0)
```
### Хелперы биомов
```python
from cubiomes import (biome_exists, is_overworld_biome, get_dimension,
is_oceanic, is_mesa, is_snowy, get_category)
biome_exists(MCVersion.MC_1_20, BiomeID.cherry_grove) # False
biome_exists(MCVersion.MC_1_21, BiomeID.cherry_grove) # True
is_oceanic(BiomeID.deep_ocean) # True
is_mesa(BiomeID.badlands) # True
is_snowy(BiomeID.snowy_tundra) # True
get_dimension(BiomeID.the_end) # 1
```
---
## Измерения
```python
# Незер
g = Generator(MCVersion.MC_1_21)
g.apply_seed(Dimension.DIM_NETHER, seed)
biome = g.get_biome_at(0, 64, 0, scale=4)
print(BiomeID(biome).name) # → "nether_wastes"
# Энд
g.apply_seed(Dimension.DIM_END, seed)
biome = g.get_biome_at(0, 0, 0, scale=4)
```
---
## Многопоточность и производительность
- `Generator` **не является потокобезопасным** — создавайте отдельный экземпляр
на каждый поток/процесс.
- Для параллельного перебора используйте `multiprocessing` (не `threading`, GIL).
- `cubiomes.search.SeedSearch` уже делает это через `ProcessPoolExecutor`.
- `check_for_biomes` (многоуровневый фильтр) значительно быстрее, чем
`gen_biomes` + ручная проверка.
```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)],
)
search = SeedSearch(criteria)
for result in search.run(
seed_range=(0, 100_000_000),
count=10,
workers=4, # 4 параллельных процесса
batch_size=8192, # зёрна на один батч
):
print(result.seed, result.biome_positions)
```