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

134 lines
3.8 KiB
Markdown
Raw Permalink 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.

# 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.