# 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` означает «отсутствует». Примеры: ```python 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 | ### Флаги генератора ```python LARGE_BIOMES = 0x1 # мир с большими биомами NO_BETA_OCEAN = 0x2 FORCE_OCEAN_VARIANTS = 0x4 ``` ### Флаги BiomeFilter ```python BF_APPROX = 0x01 # агрессивная фильтрация (возможны false-negative) BF_FORCED_OCEAN = 0x04 ``` --- ## Класс `Generator` ```python class Generator(mc: int, flags: int = 0) ``` Основной объект генерации биомов. Аллоцирует C-структуру `Generator` (24 КБ) и освобождает её при удалении. ### Свойства (только чтение) | Свойство | Тип | Описание | |---------|-----|---------| | `mc` | `int` | Версия MC | | `dim` | `int` | Текущее измерение | | `seed` | `int` | Текущий сид | | `flags` | `int` | Флаги генератора | ### Методы #### `apply_seed(dim, seed)` Привязать сид и измерение. Должен вызываться перед любой генерацией. ```python 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:** ```python 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` ```python class BiomeFilter(mc, required=None, excluded=None, match_any=None, flags=0) ``` Предпочтительный способ создания — через `setup_biome_filter()`. --- ## Класс `StrongholdIterator` Итератор стронгхолдов. Создаётся через `iter_strongholds()`. ```python 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. ```python 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` | снежный биом | --- ## Модуль `cubiomes.search` Быстрый поиск сидов. Подробности — в [docs/search.md](search.md). ### Классы данных ```python @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` ```python 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` по мере нахождения.