celseed/README.md
Arigadam 14a294b768 Add progress bar and structured logging
- 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>
2026-10-13 10:35:52 +00:00

285 lines
10 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.

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