celseed/README.md
Arigadam 843f1ce8f3 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>
2026-10-13 09:27:20 +00:00

254 lines
8 KiB
Markdown
Raw 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.

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