active-cubiomes/docs/guide.md
2026-10-12 10:23:10 +00:00

11 KiB
Raw Permalink Blame History

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)