11 KiB
cubiomes — руководство пользователя
cubiomes — это Python/Cython-биндинг к библиотеке cubiomes, обеспечивающей быструю генерацию биомов и структур Minecraft без запуска самой игры.
Установка
# Зависимости
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.
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.
Использование генератора
Биом в точке
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"
Карта биомов региона
# Генерирует плоскую карту 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]
Нахождение спавна
spawn = g.estimate_spawn() # быстро, приблизительно
spawn = g.get_spawn() # медленно, точно (проверяет траву)
print(f"Spawn: {spawn}")
Поиск биома в радиусе
# Найти ближайший mushroom_fields в радиусе 8000 блоков от (0,0,0)
pos = g.locate_biome(0, 0, 0, radius=2000, valid_biomes=[BiomeID.mushroom_fields])
# radius здесь в биомных координатах (~8000 блоков)
Центры регионов биома
# Найти центры 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})")
Структуры
Позиция структуры
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 чанка). Проверяйте несколько регионов вокруг нужной зоны.
Перебор регионов в области
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}")
Вариант структуры
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}")
Стронгхолды
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.
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
Вспомогательные функции
Слайм-чанки
from cubiomes import is_slime_chunk
if is_slime_chunk(seed=123456789, chunk_x=0, chunk_z=1):
print("Slime chunk!")
Теневой сид
from cubiomes import get_shadow
shadow = get_shadow(seed)
# get_shadow(get_shadow(seed)) == seed — всегда
Перемещение структур
from cumiomes import move_structure
# Сместить базовый сид так, чтобы структуры сдвинулись на 1 регион по X
shifted = move_structure(base_seed, reg_x=1, reg_z=0)
Хелперы биомов
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
Измерения
# Незер
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+ ручная проверка.
# Пример параллельного поиска
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)