- Progress bar (deps/log.c submodule added): * Unicode block chars (██░░), braille spinner for indeterminate mode * Shows: percentage, found/total, seeds/sec (EMA), ETA * Auto-enables on TTY, suppressed when piped * Clears and redraws cleanly around log messages and matches - Logging via rxi/log.c: * Timestamped, colored levels: TRACE DEBUG INFO WARN ERROR FATAL * --log-level trace|debug|info|warn|error|off * --log-file FILE for persistent log (full timestamps, no colors) - New flags: --no-progress, --progress (force), --log-level, --log-file Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
285 lines
10 KiB
Markdown
285 lines
10 KiB
Markdown
# 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.
|
||
|
||
### Dependencies (included as git submodules)
|
||
|
||
| Library | Purpose |
|
||
|---------|---------|
|
||
| [cubiomes](https://github.com/Cubitect/cubiomes) | Minecraft biome/structure generation |
|
||
| [log.c](https://github.com/rxi/log.c) | Structured leveled logging |
|
||
|
||
---
|
||
|
||
## 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 |
|
||
| `--log-level LEVEL` | `info` | Log verbosity: `trace` `debug` `info` `warn` `error` `off` |
|
||
| `--log-file FILE` | *(none)* | Write full logs to FILE (always includes DEBUG+) |
|
||
| `--no-progress` | off | Disable progress bar |
|
||
| `--progress` | off | Force-enable progress bar (e.g. for recording) |
|
||
| `--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).
|
||
- The progress bar auto-enables when stderr is a terminal (TTY). It shows
|
||
a Unicode block bar (`██░░`), seeds/second speed, found count, and ETA.
|
||
- Logging uses [log.c](https://github.com/rxi/log.c) with timestamps and
|
||
colors. Use `--log-file` to persist logs. Use `--log-level debug` for
|
||
verbose output including expression parsing and generator setup.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT – see [LICENSE](LICENSE).
|
||
|
||
---
|
||
|
||
<a name="russian"></a>
|
||
|
||
# celseed (Русский)
|
||
|
||
Поиск сидов Minecraft для всех версий. Задайте фильтр — программа напечатает подходящие сиды.
|
||
|
||
---
|
||
|
||
## Сборка
|
||
|
||
Требуется: `gcc`, `make`, `libm`.
|
||
|
||
```
|
||
git clone --recurse-submodules <url-репозитория>
|
||
make
|
||
```
|
||
|
||
В корне проекта появится исполняемый файл `celseed`.
|
||
|
||
### Зависимости (git submodule)
|
||
|
||
| Библиотека | Назначение |
|
||
|------------|-----------|
|
||
| [cubiomes](https://github.com/Cubitect/cubiomes) | Генерация биомов и структур Minecraft |
|
||
| [log.c](https://github.com/rxi/log.c) | Структурированное логирование с уровнями |
|
||
|
||
---
|
||
|
||
## Использование
|
||
|
||
```
|
||
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` | выкл | Печатать индекс рядом со значением |
|
||
| `--log-level LEVEL` | `info` | Уровень логов: `trace` `debug` `info` `warn` `error` `off` |
|
||
| `--log-file FILE` | *(нет)* | Записывать логи в файл |
|
||
| `--no-progress` | выкл | Отключить прогресс бар |
|
||
| `--progress` | выкл | Принудительно включить прогресс бар |
|
||
| `--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.
|
||
- Прогресс бар автоматически включается когда stderr является терминалом.
|
||
Отображает Unicode-бар (`██░░`), скорость (сидов/сек), счётчик найденных и ETA.
|
||
- Логирование через [log.c](https://github.com/rxi/log.c): временные метки,
|
||
цветовые уровни. `--log-file` — лог в файл, `--log-level debug` — подробный вывод.
|
||
|
||
---
|
||
|
||
## Лицензия
|
||
|
||
MIT — см. [LICENSE](LICENSE).
|