Add celseed: Minecraft seed finder with CEL filter expressions

Single-file C CLI program that searches Minecraft seeds using cubiomes
for biome/structure generation and a built-in CEL-subset expression
evaluator for filtering. Supports all MC versions from Beta 1.7 to 26.3.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Arigadam 2026-10-13 09:27:20 +00:00
commit 843f1ce8f3
8 changed files with 1286 additions and 0 deletions

254
README.md Normal file
View file

@ -0,0 +1,254 @@
# celseed
**English** | [Русский](#russian)
Minecraft seed finder for all versions. Give it a filter expression and it
prints seeds that match.
---
## Build
Requires: `gcc`, `make`, `libm`.
```
git clone --recurse-submodules <repo-url>
make
```
The binary `celseed` is created in the project root.
---
## Usage
```
celseed [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `--mc VERSION` | newest | Minecraft version, e.g. `1.21`, `1.18`, `1.7`, `b1.8` |
| `--filter EXPR` | *(none)* | CEL filter expression |
| `--count N` | 10 | Stop after N matches |
| `--from SEED` | 0 | Starting seed (signed int64) |
| `--to SEED` | *(unlimited)* | Ending seed (exclusive) |
| `--step N` | 1 | Seed increment |
| `--random` | off | Use random seeds instead of sequential |
| `--dim overworld\|nether\|end` | overworld | Dimension |
| `--large` | off | Enable large biomes |
| `--quiet` | off | Print only seed values |
| `--verbose` | off | Print index alongside value |
| `--list-versions` | — | List all supported versions |
---
## Filter expressions
The `--filter` expression is a subset of
[CEL (Common Expression Language)](https://cel.dev).
### Variables
| Name | Type | Description |
|------|------|-------------|
| `seed` | int | Current seed value |
### Functions
| Function | Returns | Description |
|----------|---------|-------------|
| `biome(x, z)` | string | Biome name at block coordinates |
| `biome_id(x, z)` | int | Numeric biome ID at block coordinates |
| `has_biome(name, x, z, r)` | bool | Biome exists within radius `r` around `(x, z)` |
| `structure(type, rx, rz)` | bool | Viable structure at region `(rx, rz)` |
| `struct_x(type, rx, rz)` | int | Structure block X coordinate |
| `struct_z(type, rx, rz)` | int | Structure block Z coordinate |
| `spawn_x()` | int | World spawn X coordinate |
| `spawn_z()` | int | World spawn Z coordinate |
### Operators
`&&` `||` `!` `==` `!=` `<` `<=` `>` `>=` `+` `-` `*` `/` `%`
### Structure types
`village` `mansion` `monument` `outpost` `desert_pyramid` `jungle_temple`
`swamp_hut` `igloo` `ocean_ruin` `shipwreck` `ruined_portal` `ancient_city`
`fortress` `bastion` `end_city` `stronghold` `trail_ruins` `trial_chambers`
---
## Examples
Find seeds where spawn is inside a jungle:
```
celseed --mc 1.21 --filter 'biome(0,0) == "jungle"'
```
Find seeds with a mushroom island within 500 blocks of origin:
```
celseed --mc 1.18 --filter 'has_biome("mushroom_fields", 0, 0, 500)' --count 5
```
Find seeds with a village and a mansion in region (0,0) and (1,0):
```
celseed --mc 1.16 --filter 'structure("village",0,0) && structure("mansion",1,0)'
```
Search random seeds for a jungle with a temple nearby:
```
celseed --random --filter 'biome(0,0) == "jungle" && structure("jungle_temple",0,0)'
```
Check seeds where spawn is near the origin:
```
celseed --filter 'spawn_x() > -200 && spawn_x() < 200 && spawn_z() > -200 && spawn_z() < 200'
```
Scan a specific seed range:
```
celseed --from -500000 --to 500000 --filter 'seed % 1000 == 0' --count 20
```
---
## Notes
- Biome and structure queries use cubiomes for fast generation without
launching Minecraft.
- `x`, `z` in `biome()` and `has_biome()` are block coordinates.
- `rx`, `rz` in `structure()` are region indices (each region is typically
32 chunks, i.e. 512 blocks, depending on structure type).
- The filter syntax follows CEL principles; the evaluator is implemented
in C as part of this tool (the `cel-c` submodule is included for reference).
---
## License
MIT – see [LICENSE](LICENSE).
---
<a name="russian"></a>
# celseed (Русский)
Поиск сидов Minecraft для всех версий. Задайте фильтр — программа напечатает подходящие сиды.
---
## Сборка
Требуется: `gcc`, `make`, `libm`.
```
git clone --recurse-submodules <url-репозитория>
make
```
В корне проекта появится исполняемый файл `celseed`.
---
## Использование
```
celseed [ОПЦИИ]
```
| Опция | По умолчанию | Описание |
|-------|--------------|----------|
| `--mc VERSION` | newest | Версия Minecraft, например `1.21`, `1.18`, `1.7`, `b1.8` |
| `--filter EXPR` | *(нет)* | Фильтр-выражение в стиле CEL |
| `--count N` | 10 | Остановиться после N совпадений |
| `--from SEED` | 0 | Начальный сид (знаковый int64) |
| `--to SEED` | *(без ограничений)* | Конечный сид (не включая) |
| `--step N` | 1 | Шаг перебора сидов |
| `--random` | выкл | Случайные сиды вместо последовательных |
| `--dim overworld\|nether\|end` | overworld | Измерение |
| `--large` | выкл | Большие биомы |
| `--quiet` | выкл | Печатать только значения сидов |
| `--verbose` | выкл | Печатать индекс рядом со значением |
| `--list-versions` | — | Список поддерживаемых версий |
---
## Фильтр-выражения
Выражение `--filter` — это подмножество
[CEL (Common Expression Language)](https://cel.dev).
### Переменные
| Имя | Тип | Описание |
|-----|-----|----------|
| `seed` | int | Текущее значение сида |
### Функции
| Функция | Возвращает | Описание |
|---------|-----------|----------|
| `biome(x, z)` | string | Название биома в блочных координатах |
| `biome_id(x, z)` | int | Числовой ID биома в блочных координатах |
| `has_biome(name, x, z, r)` | bool | Биом присутствует в радиусе `r` блоков от `(x, z)` |
| `structure(type, rx, rz)` | bool | Есть ли генерируемая структура в регионе `(rx, rz)` |
| `struct_x(type, rx, rz)` | int | Координата X структуры |
| `struct_z(type, rx, rz)` | int | Координата Z структуры |
| `spawn_x()` | int | Координата X точки спауна |
| `spawn_z()` | int | Координата Z точки спауна |
### Операторы
`&&` `||` `!` `==` `!=` `<` `<=` `>` `>=` `+` `-` `*` `/` `%`
### Типы структур
`village` `mansion` `monument` `outpost` `desert_pyramid` `jungle_temple`
`swamp_hut` `igloo` `ocean_ruin` `shipwreck` `ruined_portal` `ancient_city`
`fortress` `bastion` `end_city` `stronghold` `trail_ruins` `trial_chambers`
---
## Примеры
Сид, где спаун находится в джунглях:
```
celseed --mc 1.21 --filter 'biome(0,0) == "jungle"'
```
Сид с грибным островом в радиусе 500 блоков от начала координат:
```
celseed --mc 1.18 --filter 'has_biome("mushroom_fields", 0, 0, 500)' --count 5
```
Сид с деревней и особняком рядом:
```
celseed --mc 1.16 --filter 'structure("village",0,0) && structure("mansion",1,0)'
```
Случайные сиды с джунглями и храмом:
```
celseed --random --filter 'biome(0,0) == "jungle" && structure("jungle_temple",0,0)'
```
Спаун близко к центру мира:
```
celseed --filter 'spawn_x() > -200 && spawn_x() < 200 && spawn_z() > -200 && spawn_z() < 200'
```
---
## Примечания
- Биомы и структуры определяются через библиотеку cubiomes без запуска Minecraft.
- `x`, `z` в `biome()` и `has_biome()` — блочные координаты.
- `rx`, `rz` в `structure()` — индексы регионов (обычно 32 чанка = 512 блоков).
- Синтаксис фильтра следует принципам CEL; вычислитель реализован на C.
---
## Лицензия
MIT — см. [LICENSE](LICENSE).