First commit
This commit is contained in:
commit
9b0fe9b1b7
126 changed files with 31043 additions and 0 deletions
345
docs/guide.md
Normal file
345
docs/guide.md
Normal 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)
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue