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

11 KiB
Raw Blame History

API Reference

Полный список всех классов и функций пакета cubiomes.


Перечисления (cubiomes.enums)

MCVersion

Версии Minecraft. Используйте как целое число везде, где нужна версия.

Константа Значение Описание
MC_B1_7 1 Beta 1.7
MC_B1_8 2 Beta 1.8
MC_1_0 … MC_1_17 3–21 MC 1.0 – 1.17 (последний патч)
MC_1_18 22 MC 1.18.2 (новая система биомов)
MC_1_19 24 MC 1.19.4
MC_1_20 25 MC 1.20.6
MC_1_21 32 MC 1.21.11 (алиас → последний 1.21.x)
MC_26_3 35 MC 26.3 (Chaos Cubed)
MC_NEWEST 35 Алиас последней версии

Dimension

Константа Значение
DIM_NETHER -1
DIM_OVERWORLD 0
DIM_END +1
DIM_UNDEF 1000

BiomeID

Все биомы Minecraft. Доступны как современные имена (windswept_hills), так и исторические алиасы (extremeHills). Значение NONE = -1 означает «отсутствует». Примеры:

BiomeID.plains          # 1
BiomeID.mushroom_fields # 14
BiomeID.deep_dark       # 183
BiomeID.pale_garden     # 186
BiomeID(37).name        # "badlands"

StructureType

Константа Значение Примечание
Village 5 overworld
Monument 8 overworld ocean
Mansion 9 overworld dark forest
Outpost 10 overworld
Ancient_City 13 overworld deep
Fortress 18 nether
Bastion 19 nether
End_City 21 end
Trial_Chambers 25 overworld
Stronghold 27 overworld
… … см. enums.py

Флаги генератора

LARGE_BIOMES         = 0x1   # мир с большими биомами
NO_BETA_OCEAN        = 0x2
FORCE_OCEAN_VARIANTS = 0x4

Флаги BiomeFilter

BF_APPROX       = 0x01  # агрессивная фильтрация (возможны false-negative)
BF_FORCED_OCEAN = 0x04

Класс Generator

class Generator(mc: int, flags: int = 0)

Основной объект генерации биомов. Аллоцирует C-структуру Generator (24 КБ) и освобождает её при удалении.

Свойства (только чтение)

Свойство Тип Описание
mc int Версия MC
dim int Текущее измерение
seed int Текущий сид
flags int Флаги генератора

Методы

apply_seed(dim, seed)

Привязать сид и измерение. Должен вызываться перед любой генерацией.

g.apply_seed(Dimension.DIM_OVERWORLD, 123456789)

get_biome_at(x, y, z, scale=4) → int

Биом в одной точке. Возвращает BiomeID или -1 при ошибке.

scale=1  → x, y, z в блочных координатах (Voronoi, медленнее)
scale=4  → x, y, z в биомных координатах (стандарт)

gen_biomes(x, z, sx, sz, scale=4, y=0, sy=0) → array.array

Генерация карты биомов прямоугольной области. Возвращает плоский array.array('i') с sx × max(sy,1) × sz элементами.

Индексация:

  • 2D (sy ≤ 1): result[z_i * sx + x_i]
  • 3D (sy > 1): result[y_i * sx * sz + z_i * sx + x_i]

Конвертация в NumPy:

import numpy as np
arr = np.array(g.gen_biomes(-128, -128, 256, 256), dtype=np.int32).reshape(256, 256)

get_spawn() → tuple[int, int]

Точный спавн мира. Медленно — итерирует биомы.

estimate_spawn() → tuple[int, int]

Приблизительный спавн. Быстрее get_spawn.

locate_biome(x, y, z, radius, valid_biomes) → tuple[int, int]

Найти позицию с заданным биомом в квадратном радиусе. radius в масштабе 1:4.

get_biome_centers(x, z, sx, sz, match, min_size=0, tolerance=4, max_results=256) → list

Найти центры патчей биома. Зона задаётся в биомных координатах (scale=4). Возвращает список (x, z).

check_for_biomes(x, z, sx, sz, scale, dim, seed, biome_filter, y=0, sy=1) → int

Многоуровневая проверка зоны на соответствие BiomeFilter.

Возврат Значение
0 не соответствует
1 соответствует (полная проверка)
2 соответствует (неполная)

Класс BiomeFilter

class BiomeFilter(mc, required=None, excluded=None, match_any=None, flags=0)

Предпочтительный способ создания — через setup_biome_filter().


Класс StrongholdIterator

Итератор стронгхолдов. Создаётся через iter_strongholds().

it = iter_strongholds(g, seed)
x, z = next(it)          # первый стронгхолд
it.index                  # текущий счётчик
it.next_approx            # приблизительная позиция следующего

Класс StructureVariant

Метаданные экземпляра структуры. Создаётся через get_variant().

Свойство Тип Описание
rotation int 0=north, 1=east, 2=south, 3=west
abandoned bool заброшенная деревня
giant bool гигантский разрушенный портал
underground bool подземный вариант
basement bool иглу с подвалом
biome int биомный вариант
pos (x,y,z) позиция начала структуры
size (sx,sy,sz) размер bounding box

Функции поиска структур

get_structure_config(struct_type, mc) → dict | None

Конфигурация структуры для версии MC.

cfg = get_structure_config(StructureType.Village, MCVersion.MC_1_21)
# {"salt": ..., "region_size": 34, "chunk_range": 8, "dim": 0, "rarity": 0.0}

get_structure_pos(struct_type, mc, seed, reg_x, reg_z) → tuple | None

Блочная позиция попытки генерации структуры в регионе. Возвращает None, если структура не может появиться в этом регионе.

is_viable_structure_pos(struct_type, gen, block_x, block_z, flags=0) → bool

Проверить биомные требования для структуры. Генератор должен быть инициализирован с правильным сидом и измерением.

is_viable_feature_biome(mc, struct_type, biome_id) → bool

Может ли данный биом принять данную структуру.

get_variant(struct_type, mc, seed, block_x, block_z, biome_id=-1) → StructureVariant | None

Получить метаданные (поворот, флаги) экземпляра структуры.

get_mineshafts(mc, seed, chunk_x, chunk_z, chunk_w, chunk_h, max_count=1024) → list

Позиции шахт в прямоугольной области (в чанках).


Функции стронгхолдов и спавна

iter_strongholds(gen, seed48) → StrongholdIterator

Итератор точных позиций стронгхолдов (с биомной проверкой).

init_first_stronghold(mc, seed48) → tuple[int, int]

Быстрая приблизительная позиция первого стронгхолда (±112 блоков, без биом-чека).


Функции биомного фильтра

setup_biome_filter(mc, required=None, excluded=None, match_any=None, flags=0) → BiomeFilter

Создать фильтр. Аргументы принимают списки BiomeID.

  • required — все биомы обязаны присутствовать
  • excluded — ни одного из этих биомов
  • match_any — хотя бы один должен присутствовать

Вспомогательные функции

Сиды

Функция Описание
is_slime_chunk(seed, chunk_x, chunk_z) → bool слайм-чанк
get_shadow(seed) → int теневой сид; get_shadow(get_shadow(s)) == s
move_structure(base_seed, reg_x, reg_z) → int сдвиг структур на регионы
chunk_generate_rnd(world_seed, cx, cz) → int ГПСЧ пещер/структур
get_population_seed(mc, world_seed, x, z) → int сид декораций чанка

Свойства биомов

Функция Описание
biome_exists(mc, biome_id) → bool существует ли биом в версии
is_overworld_biome(mc, biome_id) → bool генерируется ли в Оверворлде
get_dimension(biome_id) → int измерение биома
get_mutated(mc, biome_id) → int hills/modified вариант (-1 если нет)
get_category(mc, biome_id) → int климатическая категория
are_similar(mc, id1, id2) → bool схожий климат
is_mesa(biome_id) → bool badlands/mesa тип
is_shallow_ocean(biome_id) → bool мелкий океан
is_deep_ocean(biome_id) → bool глубокий океан
is_oceanic(biome_id) → bool любой океан
is_snowy(biome_id) → bool снежный биом

Быстрый поиск сидов. Подробности — в docs/search.md.

Классы данных

@dataclass
class BiomeCondition:
    biome_id: int
    radius: int = 1024    # в биомных координатах
    scale: int = 4

@dataclass
class StructureCondition:
    struct_type: int
    radius: int = 2048    # в блоках

@dataclass
class SearchCriteria:
    mc: int = MCVersion.MC_1_21
    dim: int = Dimension.DIM_OVERWORLD
    biomes: list[BiomeCondition] = ...
    structures: list[StructureCondition] = ...
    slime_chunk: tuple | None = None
    large_biomes: bool = False
    spawn_biome: int | None = None

SeedSearch

class SeedSearch(criteria: SearchCriteria)

check_seed(seed, show_spawn=False, show_strongholds=0) → SeedResult | None

Проверить один сид.

run(seed_range=None, seeds=None, count=1, workers=1, ...) → Iterator[SeedResult]

Итерация с параллельной обработкой. Возвращает SeedResult по мере нахождения.