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

10 KiB
Raw Blame History

celseed

English | Русский

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 Minecraft biome/structure generation
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).

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


celseed (Русский)

Поиск сидов Minecraft для всех версий. Задайте фильтр — программа напечатает подходящие сиды.


Сборка

Требуется: gcc, make, libm.

git clone --recurse-submodules <url-репозитория>
make

В корне проекта появится исполняемый файл celseed.

Зависимости (git submodule)

Библиотека Назначение
cubiomes Генерация биомов и структур Minecraft
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).

Переменные

Имя Тип Описание
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: временные метки, цветовые уровни. --log-file — лог в файл, --log-level debug — подробный вывод.

Лицензия

MIT — см. LICENSE.