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

334 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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` по мере нахождения.