satura/README.md
loki5512344 da99a448e1
Add placement strategies S3-S8, strategy settings GUI and themes
- Strategies: precise, fly_hover, ground_walk, baritone_walk, hold_rmb, burst
  (pending set + AIMD); engine batches via PlaceStrategy.batchSize/tickBatch
- GUI: strategy cycle, per-strategy option sliders, switchable themes (ThemePref)
- Move ColumnTarget to interaction.place.target; layer baseline is now empty
- Show blocks/s in status, action bar and GUI
- Tests for batching, precise support, fly hover, ground walk, burst, hold rmb
2026-10-31 17:48:43 +01:00

99 lines
6.2 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.

# Satura — авто-билдер для Minecraft (Fabric)
Клиентский мод: выделяешь область — мод сам ходит/летает и строит заданную форму.
GUI-меню, команды `.pos1/.pos2/.sel/.build`, навигация через Baritone (Aethereal),
инкрементальный подсчёт прогресса, ремонтные проходы по дырам.
| Что | Версия |
|---|---|
| Minecraft | 1.21.11 |
| Fabric Loader | 0.20.1 |
| Fabric API | 0.141.6+1.21.11 |
| Yarn mappings | 1.21.11+build.6 |
| Loom | 1.18.4 (нужна JVM 25 для запуска Gradle) |
| Java | 21 (target), 25 (JVM сборки) |
## Сборка и запуск
```bash
./gradlew build # jar в build/libs/satura-<версия>.jar
./gradlew check # тесты + checkstyle + pmd (гейт проекта)
./gradlew runClient # dev-запуск игры с модом
```
Gradle запускается на JVM 25: если дефолтная JVM другой версии, укажи её в
`gradle.properties` (`org.gradle.java.home`) или ключом `-Dorg.gradle.java.home=...`.
Для dev-запуска с Baritone положи `aethereal-1.21.11.jar` в `libs/`.
## Использование
### Клавиши (настраиваются в ванильных «Управлении», категория Satura)
| Клавиша | Действие |
|---|---|
| Right Shift | открыть/закрыть меню билдера |
| P | макрос: пауза / продолжить текущий билд |
### Команды (префикс `.`)
| Команда | Действие |
|---|---|
| `.pos1` / `.pos2` | задать углы области по позиции ног |
| `.sel clear` | сбросить выделение |
| `.build start` / `pause` / `resume` / `stop` / `status` | управление стройкой |
| `.build block <id>` | блок (`stone`, `minecraft:glass` или `hand` — блок из руки) |
| `.build shape box\|checker\|walls` | форма застройки области |
| `.build layers 1..3` | слоёв за один проход колонны |
| `.build strategy <id>` | стратегия постановки (см. таблицу ниже) |
| `.build set <ключ> <знач>` | параметр стратегии (`delayMs`, `reach`, `hover`, `flySpeed`, `bandLayers`, `burst`) |
### GUI (Right Shift)
Pos1/Pos2 — зафиксировать текущую позицию ног; Старт/Пауза/Продолжить/Стоп; форма;
стратегия (циклическая кнопка — панель параметров выбранной стратегии перестраивается
автоматически); слайдеры параметров стратегии; тема (оранжевый/белый/мятный/песочный
акцент, выбор сохраняется в `config/satura/render.json`); ID блока (Enter — применить).
Внизу — живой статус: этап, прогресс, блоков/с, дыры. Во время стройки тот же статус
раз в секунду дублируется над хотбаром.
### Стратегии постановки
| id | Что делает | Референс |
|---|---|---|
| `band_stack` (дефолт) | полёт над слоем, 1–3 слоя за визит колонны, клик под собой | yatwinkle |
| `column_drop` | то же, но по одному слою за визит | yatwinkle |
| `precise` | хавер над колонной + точный выбор опоры (UP → бока → DOWN), LOS-проверка, до 12 ретраев на ячейку | pveclient |
| `fly_hover` | полёт к точке стояния (клик + нормаль × 2.4), скорость `min(0.34k, max(0.08k, dist·0.35k))` | pveclient FLY |
| `ground_walk` | ходьба фейк-клавишами + пиллар-прыжки с постановкой под себя — для серверов без полёта | AutoBuild |
| `baritone_walk` | Baritone только ходит (`GoalXZ`, `allowBreak/Place=false`), ставим по подходе (precise) | AutoBuild |
| `hold_rmb` | ставит только пока зажата ПКМ (ручной контроль) | yatwinkle HOLD_RMB |
| `burst` | несколько кликов за тик (1–8), pending-сет с TTL 3 тика, AIMD сам снижает burst/растит задержку при отказах | свой |
Для серверов с анти-читом: `band_stack`/`column_drop`/`burst` шлют клики без доворота
камеры и летят через `setVelocity` — их могут флагать; безопасный дефолт — `precise`
или `ground_walk` (меньший `delayMs`, наземное перемещение).
Настройки хранятся в `config/satura/default.json` и применяются при старте.
## Архитектура
Слои зависимостей направлены строго вниз, циклы запрещены:
```
mixin → feature → interaction → core → util
gui → feature (только через фасад BuilderFeature)
```
- `core` — событие/команды/конфиг, ничего не знает о фичах;
- `feature/builder` — селекция, план (формы), скан (ColumnCache), движок, Baritone-мост;
- `interaction` — «руки»: постановка блоков (8 стратегий), инвентарь, движение;
- `gui` — экран и виджеты, общается с фичей только через фасад;
- `render` — GUI-рендер (rect/blur/outline/MSDF-текст), палитры `Theme` и рамка выделения в мире.
Правила кода: максимум 250 строк на `.java`-файл, максимум 4 файла на пакет,
магические числа — в константы, гейт сборки — `./gradlew check` (Checkstyle +
PMD). Подробный план развития — `todo.md`.
## Лицензия
GPL-3.0-only, см. `LICENSE`.