First commit

This commit is contained in:
Arigadam 2026-10-12 10:23:10 +00:00
commit 9b0fe9b1b7
126 changed files with 31043 additions and 0 deletions

334
docs/api.md Normal file
View file

@ -0,0 +1,334 @@
# 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` по мере нахождения.