Hollow Knight AI Bot 🤖

Hollow Knight AI Bot — проект по обучению искусственного интеллекта (Deep Reinforcement Learning) сражению с боссами в игре Hollow Knight с использованием алгоритма PPO (Proximal Policy Optimization).

Архитектура

Проект состоит из двух основных компонентов:

1. C# Mod для Hollow Knight (Mod/HK_AI_Mod/)

Мод для Hollow Knight, экспортирующий телеметрию игры во временный JSON-файл (%TEMP%/hk_ai_data.json):

• Позиция игрока (X, Y)
• HP игрока
• Запас душ (MP/душа)
• HP босса (автоматически определяется как объект с наибольшим HP > 20)
• Позиция босса (X, Y)

2. Python-фреймворк для RL

Файл	Назначение
ai_controller.py	Эмуляция геймпада Xbox 360 через vgamepad (16 дискретных действий)
screen_capture.py	Захват экрана игры через mss + авто-наведение на окно Hollow Knight
ai_environment.py	Среда: объединяет видеопоток и телеметрию
hk_gym.py	Gymnasium-среда — ядро RL: пространство наблюдений, награды, логика эпизодов
train.py	Обучение PPO через Stable-Baselines3 с чекпоинтами
ai_receiver.py	Отладчик телеметрии в реальном времени

Для работы фреймворка в игру должен быть загружен мод!

Пространство действий (16 действий)

ID	Действие
0	Ничего
1	Влево
2	Вправо
3	Прыжок
4	Атака
5	Рывок (dash)
6	Прыжок + Атака
7	Рывок + Атака
8	Влево + Атака
9	Вправо + Атака
10	Влево + Прыжок
11	Вправо + Прыжок
12	Влево + Рывок
13	Вправо + Рывок
14	Пауза (ничего)
15	Прыжок + Рывок

Пространство наблюдений

• image: стек из 4 последних кадров 84×84 в градациях серого → (84, 84, 4)
• stats: 10 числовых параметров — HP, душа, HP босса, позиции, расстояние до босса, направление на босса

Функция награды

• +15 за каждую единицу урона боссу (×5 если атака)
• +1000 за победу над боссом
• -50 за получение урона игроком
• -200 за смерть игрока
• +3 за атаку с идеальной дистанции
• -0.05 за каждый шаг (штраф за промедление)
• Поощрение за движение к боссу

Установка и запуск

Требования

• Hollow Knight V1.5.78.1183 (Steam-версия)
• Modding API для Hollow Knight (установлен)
• Python 3.10+
• .NET Framework 4.7.2 (для сборки мода)
• Scarab (мод-менеджер)

Установка Python-зависимостей

pip install -r requirements.txt

Сборка и установка мода

1. Открой Mod/HK_AI_Mod/HK_AI_Mod.csproj в Visual Studio / Rider
2. Собери проект (Build)
3. Скопируй HK_AI_Mod.dll в папку модов Hollow Knight (hollow_knight/hollow_knight_Data/Managed/Mods/)

Запуск обучения

python train.py

• Модель автоматически загрузит последний чекпоинт (models/ppo_hk/hk_model_final.zip), если он существует
• Чекпоинты сохраняются каждые 20 000 шагов в models/ppo_hk/
• Во время обучения можно управлять через консоль:
  • r — включить авто-рестарт боя после смерти/победы
  • s — выключить авто-рестарт
  • q — выход

Отладка телеметрии

python ai_receiver.py

Параметры обучения (PPO)

Параметр	Значение
Алгоритм	PPO (Stable-Baselines3)
Политика	MultiInputPolicy
Learning rate	0.0003
n_steps	4096
batch_size	256
n_epochs	8
ent_coef	0.02
Всего шагов	2 000 000

Лицензия

MIT