Metadata-Version: 2.4
Name: active_cubiomes
Version: 0.1.1
Summary: Python/Cython bindings for cubiomes — fast Minecraft biome and structure generator
License-Expression: MIT
Project-URL: Homepage, https://github.com/xpple/cubiomes
Project-URL: Source, https://github.com/xpple/cubiomes
Project-URL: Tracker, https://github.com/xpple/cubiomes/issues
Keywords: minecraft,cubiomes,biomes,seed,worldgen,speedrun
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Cython
Classifier: Topic :: Games/Entertainment
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: numpy
Requires-Dist: numpy>=1.20; extra == "numpy"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: numpy>=1.20; extra == "dev"
Requires-Dist: cython>=3.0; extra == "dev"
Dynamic: license-file
Dynamic: requires-python

# active-cubiomes

Python/Cython bindings for [cubiomes](https://github.com/xpple/cubiomes) —
a fast C library that replicates Minecraft's world-generation algorithms
without running the game.

```
pip install active-cubiomes
```

> **Import name:** `import cubiomes`  (the distribution is `active-cubiomes`)

---

## Quick start

```python
from cubiomes import Generator, MCVersion, Dimension, BiomeID

g = Generator(MCVersion.MC_1_21)
g.apply_seed(Dimension.DIM_OVERWORLD, 123456789)

biome = g.get_biome_at(0, 63, 0)          # block coords
print(BiomeID(biome).name)                 # "river"

# 256×256 biome map at 1:4 scale
ids = g.gen_biomes(-128, -128, 256, 256)   # array.array('i')

import numpy as np
grid = np.array(ids, dtype=np.int32).reshape(256, 256)
```

## Structure finding

```python
from cubiomes import StructureType, get_structure_pos, is_viable_structure_pos

seed = 123456789
mc   = MCVersion.MC_1_21

for reg_x in range(-3, 4):
    for reg_z in range(-3, 4):
        pos = get_structure_pos(StructureType.Village, mc, seed, reg_x, reg_z)
        if pos and is_viable_structure_pos(StructureType.Village, g, *pos):
            print(f"Village at {pos}")
```

## Strongholds

```python
from cubiomes import iter_strongholds

for i, (x, z) in enumerate(iter_strongholds(g, seed=123456789)):
    print(f"Stronghold {i}: ({x}, {z})")
    if i >= 4:
        break
```

## Seed search CLI

```bash
# Seeds with mushroom fields AND badlands within 4 km
cubiomes-search --mc 1.21 --biome mushroom_fields badlands --biome-radius 4000 --count 5

# Quad witch-hut base
cubiomes-search --mc 1.21 --quad Swamp_Hut --quad-dist 128 --count 3

# Inspect one seed
cubiomes-search --seed 123456789 --info

# Village and Monument within 400 blocks of each other, JSON output
cubiomes-search --mc 1.21 --proximity Village Monument 400 --count 10 --format json
```

## Seed search Python API

```python
from cubiomes.search import (
    SearchCriteria, BiomeCondition, StructureCondition,
    SpawnCondition, StrongholdCondition, ProximityCondition,
    QuadStructureCondition, BiomeDensityCondition,
    SlimeDensityCondition, AnyOfBiomes, CustomCondition,
    SeedSearch,
)
from cubiomes import MCVersion, BiomeID, StructureType

criteria = SearchCriteria(
    mc=MCVersion.MC_1_21,
    biomes=[BiomeCondition(BiomeID.mushroom_fields, radius=2000)],
    conditions=[
        SpawnCondition(max_distance=500),
        StrongholdCondition(count=1, max_distance=2000),
        QuadStructureCondition(StructureType.Swamp_Hut, max_dist=128),
    ],
)

for result in SeedSearch(criteria).run(
    seed_range=(0, 100_000_000),
    count=5,
    workers=4,
):
    print(result)
```

## All condition types

| Class | CLI flag | Description |
|-------|----------|-------------|
| `BiomeCondition` | `--biome NAME...` | Biome must exist near origin (AND) |
| `AnyOfBiomes` | `--any-biome NAME...` | At least one biome (OR) |
| `StructureCondition` | `--structure NAME...` | Structure viable near origin |
| `SpawnCondition` | `--spawn-biome / --spawn-max-dist` | Spawn location/biome |
| `StrongholdCondition` | `--stronghold-radius` | First N strongholds in radius |
| `ProximityCondition` | `--proximity A B DIST` | Two structures near each other |
| `QuadStructureCondition` | `--quad STRUCT` | Quad-farm base (2×2 regions) |
| `BiomeDensityCondition` | `--biome-density BIOME FRAC` | Biome coverage fraction |
| `SlimeDensityCondition` | `--min-slime-chunks N` | Minimum slime chunks |
| `CustomCondition` | — (Python only) | Arbitrary `(seed, mc) → bool` function |

## Building from source

Requires GCC and Python ≥ 3.8:

```bash
git clone https://github.com/your-fork/active-cubiomes
cd active-cubiomes
pip install -e ".[dev]"
```

## License

The Python bindings are MIT licensed.
The bundled [cubiomes](https://github.com/xpple/cubiomes) C library
is also MIT licensed.
