# Verity Bedrock — локальные миры

Версия 0.3.1 для Windows Bedrock 1.26.30+ (целевая сборка 1.26.32.2).
Behavior Pack + Resource Pack + нативный фоновый мост Windows x64 / Linux x64.
Выделенный сервер Minecraft не нужен. Мост использует встроенный `/connect`,
не внедряет DLL и не зависит от адресов функций игрового EXE.
В мире нужны разрешённые команды (cheats). Достижения в таком мире отключаются.

## Установка в Windows

1. Распакуйте весь ZIP в постоянный каталог.
2. Запустите `Install-Windows.ps1` из PowerShell, либо импортируйте
   `Verity-Bedrock.mcaddon` двойным щелчком.
3. Скопируйте `config.example.json` в `config.json` (скрипты делают это,
   если файла ещё нет). Задайте рабочий `llm_key`; можно также использовать
   переменную окружения `VERITY_LLM_KEY`. Остальные адреса уже настроены.
4. В настройках локального мира включите Behavior Pack Verity и его ресурсы,
   разрешите команды. Для первой проверки используйте новый мир.
5. В настройках Minecraft → General включите **Enable WebSockets**.
   **Require Encrypted WebSockets** можно оставить включённым.
6. `Install-Windows.ps1` добавляет запуск при входе в Windows и запускает мост.
   Для установки без автозапуска передайте `-NoAutostart`.
7. Войдите в мир, закройте меню и чат, нажмите **F7**. Приложение введёт
   `/connect 127.0.0.1:19135/ws`. Саму команду также можно выполнить вручную.
8. Персонаж появляется автоматически. Напишите `привет` или `сделай день`.

Обновление с 0.1.0: завершите старый `verity-native.exe` через Диспетчер задач,
распакуйте 0.2.0 в постоянный каталог, перенесите свой `config.json` и `history/`,
запустите установщик при закрытом Minecraft. Не импортируйте одновременно
.mcaddon и копии тех же пакетов через установщик: используйте один способ.
Если 0.1.0 импортировалась двойным щелчком, удалите именно старые пакеты Verity
через Minecraft → Хранилище перед переходом на установщик. Миры не удаляйте.

Мост автоматически использует только заданные сервисы:

- LLM: `http://10.8.0.7:8317/v1/chat/completions`, `gpt-5.6-luna`.
- STT: `http://10.8.0.7:8562/v1/audio/transcriptions`,
  `koekaverna/faster-whisper-podlodka-turbo`.
- TTS: `http://10.8.0.7:8563/v1/audio/speech`, `tts-1` / `am_fenrir`
  (на сервере это русский мужской голос Евгений, Silero).

Мост слушает только loopback и отклоняет подключения из браузера.
Поддерживается шифрование WebSocket Bedrock. При выходе из игры он остаётся
фоновым процессом; завершить можно через Диспетчер задач (`verity-native.exe`).
При следующем входе в мир нажмите F7 или выполните `/connect`.
`Remove-Autostart.ps1` убирает только автозапуск. Приложение, миры и настройки сохраняются.
Автоматический ввод команды при появлении любого окна Minecraft не используется:
название окна не позволяет определить, открыт ли мир. `/connect` — команда Admin,
недоступная скриптам аддона; полностью автоматическое подключение пока не реализовано.
Повторный запуск моста не создаст второй слушающий сервер на том же порту.

## Голос

По умолчанию `mic_mode: "wake_word"`: при подключённом мире приложение
выделяет голосовые фразы, отправляет их вашему Whisper и отвечает только
на фразы с именем «Верити» / «Verity» или `custom_name`.
Например: «Верити, сделай день». Это распознавание обращения через STT,
а не отдельная локальная модель wake word. Для определения обращения в STT
попадают и произнесённые рядом фразы без имени; в LLM они не отправляются.
Нужен доступ Windows к микрофону для классических приложений.

**F8 удерживается во время речи**, отпускание завершает запись; максимум 20 секунд.
Клавиша работает в активном окне Minecraft. Настройки в `config.json`:

- `mic_mode`: `wake_word`, `ptt` (только удержание), `off` (микрофон выключен).
- `ptt_key`: Windows virtual-key code, 119 = F8, 86 = V.
- `vad_threshold`: порог громкости, по умолчанию 500; подберите под микрофон.
- `require_address`: false — обычный чат, true — текст начинается с «Верити».
- `voice_enabled`: включение озвучивания ответов, отдельно от микрофона.
- `custom_name`, `personality`: имя для голосового обращения и характер.

При ответе Верити и потере фокуса Windows-окна запись приостанавливается.
Пауза 0,8 секунды завершает голосовую фразу. Предпочтительны наушники:
подавление эха звуков самой игры не реализовано. Режим не ведёт архив аудио.
После изменения config.json перезапустите приложение.
Команда в чате `слушай` по-прежнему запускает однократную запись 6 секунд.

Linux/Wolf: нативный `verity-native-linux` должен работать в том же контейнере
и PulseAudio-сеансе, что игра. Нужны `ffmpeg` и `ffplay`.
Автоматическое обращение по имени работает при `mic_mode: "wake_word"`;
ручная запись — сообщением `слушай`. Горячие клавиши F7/F8 в Linux не реализованы.
Linux-мост рассчитан на отдельный игровой контейнер: контроль фокуса окна не выполняется.
В Linux-пакете есть `Start-Verity.sh`: без аргументов запускает мост,
с аргументами — мост вместе с командой игры, например
`./Start-Verity.sh bedrock-on-linux gui`. После завершения команды игры
завершает запущенный им мост. Распакуйте пакет в постоянный каталог,
задайте ключ в config.json и скопируйте папки из addon в
`development_behavior_packs/verity_bedrock` и
`development_resource_packs/verity_bedrock` нужного `com.mojang`.
Существующие миры скрипт не изменяет; аддон включается в настройках мира.
Проверьте доступность API **из игрового контейнера**: доступ с хоста
не гарантирует доступ из Docker.

Микрофон устройства Moonlight должен отдельно быть доставлен до игрового
контейнера. Этот пакет не добавляет передачу микрофона в Moonlight.

## Реализованная игровая логика

- Сферический персонаж и лица из Java-версии, следование/остановка.
- Текстовые диалоги, озвучивание, STT, история отдельно для мира и игрока.
- Карма 0–20, постоянная память, смена выражения лица.
- Контекст мира, инвентарь, соседние сущности, блок перед игроком, поиск руды.
- Время, погода, режим игры, сложность, ограниченный набор игровых правил.
- Отметка дома, возврат домой, телепортация, выдача предметов.
- Строительство до 256 блоков за действие, только в воздухе и вне игрока,
  с предварительной проверкой и откатом при ошибке.
- Отдельная сущность демона, хоррор-сценарий и завершение охоты; описание ниже.
- Музыка и звуки Java-версии, запуск/остановка любимой песни.
- Выбрасывание предметов, список предметов, возврат Верити в предмет-контроллер.
- Уменьшение кармы при ударе владельцем.
- Настройки мира: взаимодействие с Верити при приседании, либо
  `/scriptevent verity:settings` (после команды закройте чат и повторите взаимодействие,
  если Minecraft отклонил форму как занятую). Автопоявление, имя, характер, полоса кармы.
  Имя в игровом меню меняет персонажа; имя голосового обращения задаётся в config.json.

`Верити, очисти историю` очищает историю диалогов текущего мира и игрока.
Память и карма хранятся в динамических свойствах мира; файлы диалогов —
в `history/` рядом с конфигурацией моста. Логи — `verity.log`.
Не публикуйте config.json, history или логи с личными данными.

## Хоррор-сценарий 0.3.0

По умолчанию хоррор **выключен**, чтобы обновление не запускало разрушения
в существующем мире. Включается в настройках Верити (присесть + взаимодействовать
с шаром). Доступны отдельные переключатели темноты, убийства мобов,
животных/жителей, разрушения дверей/стекла, ночи, звуков и отключения игрока.

Срок задаётся в игровых днях **после включения сценария**, по умолчанию 5.
На половине срока появляются предвестники и исчезают разрешённые настройками
мобы в радиусе 32 блоков. На сроке появляется демон с 400 HP. На мирной сложности
он не появляется; творческий режим и наблюдатель не получают атак.

Демон преследует владельца сценария, обходит препятствия по осям, поднимается
у стены, задерживается у стекла и разрушает разрешённые препятствия на пути.
Удары наносят 19 единиц до учёта игровой защиты; захват замедляет и затем
отбрасывает игрока. Рядом с демоном могут погибать разрешённые мобы.
Приручённые животные исключены. Железные двери, сундуки и остальные блоки
не разрушаются. Загружены анимации Java: ожидание, подготовка, наблюдение
у окна, погоня, подъём, атака, бросок, поедание.

Шар при этом остаётся отдельным персонажем и теряет лицо. В первые пять минут
можно посмотреть на него с расстояния до 10 блоков и трижды попросить прощения
(между извинениями минимум две секунды). Победа над демоном или успокоение
даёт карму 20. Режим `normal`, выключение хоррора и мирная сложность прекращают
охоту. Прежний ход времени восстанавливается; темнота истекает за две секунды.
Вместо удаления эффектов других модов используется короткое обновляемое действие.

Прямое управление, если нужен сценарий без LLM:

- `/scriptevent verity:horror on` — включить отсчёт.
- `/scriptevent verity:horror now` — начать охоту сейчас, если хоррор включён.
- `/scriptevent verity:horror off` — выключить и убрать демона.
- `/scriptevent verity:horror reset` — завершить охоту и сбросить одноразовые события.
- `/scriptevent verity:horror status` — показать сохранённое состояние.

Через диалог доступны провокация на следующий день, её отмена до появления,
извинение, состояние и прекращение охоты. Автоматическое появление и провокация
срабатывают по одному разу до явного сброса. Состояние хранится в мире.

Отключение после смерти выключено по умолчанию. При включении используется
штатный `kick`; Bedrock не позволяет отключать хозяина локального мира.
Игра принудительно не закрывается. Эффект темноты заменяет Java-постобработку;
движение реализовано через Script API, а не Java pathfinding. Это адаптация
сценария, не побайтовая копия поведения Forge.

## Границы переноса

Полного соответствия Java ещё нет: вступительное видео, фонарь, оттенок шара,
поиск деревни/крепости и голосовой транспорт Moonlight не перенесены.
Нет общего поиска пути Forge и всех сочетаний специальных боевых целей.
Проверенные и непроверенные сценарии перечислены ниже.

## Подписанные обновления

Windows: `Start-Verity.ps1` проверяет обновление при запуске приложения,
если заполнены `update_url` и `update_public_key`. Во время работы Minecraft
обновление не устанавливается. ZIP проверяется по SHA-256 и подписи Ed25519,
распаковывается в отдельный каталог `updates/<версия>-<id>`. Установщик обновляет
только пакеты Verity и сохраняет прежние пакеты в `pack-backups`.
`config.json` и `history/` остаются в исходном каталоге. Файл `current-release.txt`
выбирает исполняемый файл; предыдущий указатель — `previous-release.txt`.
Автоматическая проверка выполняется при запуске моста, а не во время игры.

Канал обновлений уже задан в примере конфигурации:
`https://public.jivoy1988-home.jivoy1988.ru/minecraft/latest.json`.
Публичный ключ подписи включён в пакет. Для перехода с 0.2.0 один раз установите
новую сборку через Install-Windows.ps1: он добавит адрес и ключ в существующий
config.json, сохранив настройки API. `auto_update: false` отключает проверку.
Файлы раздаются из `/mnt/public/minecraft/`; версии в `releases/<версия>/`
неизменяемые. Манифест публикуется последним, после записи ZIP. Для публикации после сборки:

```sh
python3 bedrock/tools/release.py --key ~/.config/verity/release-signing.key \
  --directory /mnt/public/minecraft --version 0.3.1 \
  --base-url https://public.jivoy1988-home.jivoy1988.ru/minecraft
```

Нужен Python-пакет `cryptography`. Приватный ключ хранится вне раздачи.
Раздавайте **только** два ZIP и `latest.json`; весь build/bedrock публиковать
нельзя: там находится локальная конфигурация с ключом API.
Полученные `update_url` и публичный ключ укажите в клиентском config.json.
Linux: Start-Verity.sh использует Python 3 и запускает тот же проверяющий
механизм перед игрой. Пути профилей берутся из `game_data_paths` в config.json
или обнаруживаются под BOL_HOME. Пакеты копируются с резервированием и откатом;
миры не меняются. Если Minecraft уже запущен, установка откладывается.
Первый запуск также устанавливает пакеты, если профили обнаружены. Запускайте
игру через `./Start-Verity.sh bedrock-on-linux gui`, чтобы обновления проверялись
перед запуском. Сам Moonlight и его передача микрофона этим не меняются.

Откат Windows при закрытой игре и остановленном мосте: установите пакеты из
предыдущего каталога командой `Install-Windows.ps1 -NoAutostart`, затем верните
указатель из previous-release.txt в current-release.txt. Если указатель равен
`base`, удалите current-release.txt. Перед следующим запуском временно очистите
update_url, чтобы снова не загрузить отменённую версию.

## Разработка

Из корня репозитория:

```sh
(cd bedrock/native && go test -race ./...)
(cd bedrock/native && GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -ldflags='-H windowsgui' -o ../../build/bedrock/verity-native.exe .)
(cd bedrock/native && GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o ../../build/bedrock/verity-native-linux .)
python3 bedrock/tools/package.py
```

Go 1.21+, Python 3.11+. Результаты в `build/bedrock/`.
`verity-native-linux -config /path/config.json -check` проверяет LLM и
цепочку TTS → STT без Minecraft и сохраняет `test-voice.wav`.
Это не проверка захвата физического микрофона и игрового аудиовывода.

Протокол шифрования основан на Sandertv/mcwss (MIT), см. native/THIRD_PARTY.md.
Официальная команда: https://learn.microsoft.com/en-us/minecraft/creator/commands/commands/wsserver

## Проверено 31 октября 2026

- Bedrock 1.26.32.2 под WineGDK/Gamescope с NVIDIA, отдельная копия профиля
  и новый локальный мир. Исходные миры не изменялись.
- Загрузка обоих пакетов, появление сферического персонажа с лицом.
- Зашифрованный `/connect`, контекст мира, диалог через заданный LLM,
  установка дня и ночи через вызовы инструментов; служебный JSON скрыт.
- Постройка платформы 8×8 из дубовых досок по сообщению в чате:
  подтверждены ответ скрипта и появление блоков в мире. Большие запросы
  передаются частями по 200 символов hex, без вложенного JSON в команде.
- Go: проверка гонок, переход на шифрование с немедленным пакетом клиента,
  современный формат событий Bedrock, подтверждение действия перед ответом.
- JavaScript: 7 тестов (граница мира, входные значения, строительство и откат,
  память/карма, сборка сообщений из частей); проверка типов Script API 2.0.0.
- Windows x64 EXE собран. WinMM-микрофон, F8 и PowerShell-установка на настоящей
  Windows пока не проверены. Проверка игры выполнена с Linux-мостом.
- При совместной работе игры и Whisper на GTX 1060 6 GB обнаружен CUDA OOM.
  В compose.yaml для той же STT-модели включён `int8_float32` / CUDA;
  после перезапуска повторная цепочка LLM/TTS/STT прошла. В тестовом
  профиле дальность прорисовки снижена с 37 до 8 чанков.
- Озвучивание в игровом PulseAudio-сеансе подтверждено записью выхода:
  STT распознала в записи фразу ответа «Привет, теперь ночь».
  Физический микрофон и передача голоса через Moonlight не проверены.

В тестовом Docker доступ к LLM с хоста и из контейнера различался.
Временный локальный Unix-прокси использовался только для проверки;
он не входит в пакет. Основные адреса API в примере конфигурации не изменены.

## Проверки 0.2.0

- Go: обычный чат, обращение по имени, границы голосовой фразы, подпись обновлений,
  запрет записи ZIP в config/history, существующие проверки шифрования и инструментов;
  `go test -race` проходит. Windows x64 и Linux x64 собираются.
- Аддон: 8 тестов, включая автопоявление без дубликата и выключение автопоявления;
  проверка типов @minecraft/server 2.0.0 и @minecraft/server-ui 2.0.0.
- Физический микрофон, WinMM push-to-talk, F7, автозапуск и обновление на настоящей
  Windows требуют проверки. Сборка сама по себе не подтверждает эти сценарии.
- Полный перенос Java-логики не завершён; список ограничений выше остаётся актуальным.

В изолированном Bedrock 1.26.32.2 дополнительно проверены: загрузка 0.2.0,
шифрованное подключение, ответ «Привет! Я Верити. Чем займёмся?» на обычное
сообщение `hello` без имени и открытие формы игровых настроек.
Кадры: build/bedrock/verification/chat-0.2.png и settings-0.2.png.

## Проверки 0.3.0

- 19 тестов аддона: старые сценарии и жизненный цикл хоррора, мирная сложность,
  отмена провокации, успокоение, атаки, завершение, восстановление времени,
  выключение разрушений и убийств мобов.
- Python: установка Linux сохраняет миры и откатывает пакеты при ошибке.
- Go: проверки подписи, SHA-256 и сохранения конфигурации при повреждении загрузки;
  существующие проверки голоса и протокола проходят с детектором гонок.
- Windows PowerShell/WinMM и весь бой с физическим управлением на Windows
  остаются непроверенными; это отдельно от проверки аддона под Wine.

Ключ подписи релизов хранится в ~/.config/verity/release-signing.key и не публикуется.
Сохраните его: следующие обновления должны подписываться тем же ключом.
Публичные ZIP содержат только config.example.json с пустым LLM-ключом.

В настоящем Bedrock 1.26.32.2 под Wine проверены включение/выключение хоррора,
потеря лица шара, отдельная модель демона с анимацией и атака в выживании:
игра показала смерть от «Демона Верити», после чего демон был удалён.
Исправлена зависимость таймеров от перевода времени суток; таймеры используют
отдельный сохраняемый счётчик тиков. Проверка выполнена в отдельном мире;
исходные миры пользователя не изменялись.

0.3.1: Windows-скрипты явно читают JSON как UTF-8, чтобы PowerShell 5.1
сохранял русское имя, характер и пути без искажения кодировки.
