# 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) ```