345 lines
11 KiB
Markdown
345 lines
11 KiB
Markdown
# 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)
|
||
```
|