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