First commit

This commit is contained in:
Arigadam 2026-10-12 10:23:10 +00:00
commit 9b0fe9b1b7
126 changed files with 31043 additions and 0 deletions

345
docs/guide.md Normal file
View file

@ -0,0 +1,345 @@
# 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)
```