mdbd/DBD_Plugin_TZ.md

DEAD BY DAYLIGHT — Minecraft Plugin

Техническое Задание (ТЗ)

Полная реализация механик оригинальной игры 4v1

---

Содержание

1. Общее описание проекта
2. Распределение ролей и старт игры
3. Механики выжившего
4. Генераторы
5. Механики киллера
6. Паллеты и окна
7. Выходные ворота и люк
8. Предметы для выживших
9. Bloodpoints и прогрессия
10. Система перков
11. Эндгейм и итоги матча
12. Пользовательский интерфейс
13. Конфигурация
14. Команды и права
15. Архитектура плагина
16. Приоритет разработки

---

1. Общее описание проекта

1.1 Цель плагина

Плагин реализует полноценную мини-игру Dead by Daylight (4v1) на Minecraft-сервере. Используется готовая карта, предоставленная заказчиком. Плагин управляет всем игровым процессом: распределением ролей, механиками выживших и киллера, победными условиями, интерфейсом и звуками.

1.2 Технические требования

Параметр	Значение
Платформа	Paper / Spigot 1.20.x+
Язык	Java 17+
Зависимости	ProtocolLib, Citizens2 (опционально), PacketEvents
Кол-во игроков	5 (1 киллер + 4 выживших)
Карта	Предоставляется отдельно (worldname задаётся в config.yml)
Gamemode	Adventure mode на протяжении всей игры

---

2. Распределение ролей и старт игры

2.1 Лобби и ожидание

• Лобби-мир отдельный от игровой карты.
• Минимум для старта: 5 игроков (настраивается: min_players, max_players).
• Таймер ожидания: 60 секунд после набора минимума (countdown_seconds).
• Если игроков < минимума — таймер сбрасывается.
• В лобби показывается статус: сколько игроков зашло / нужно.

2.2 Назначение ролей

• Один игрок случайно становится Киллером (Killer).
• Остальные 4 становятся Выжившими (Survivors).
• Реализовать систему очереди: если игрок давно не был киллером — шанс повышается.
• Роли объявляются через Title + Subtitle (красный текст для киллера, белый для выжившего).
• Роль киллера не раскрывается другим выжившим до спавна (5-секундная задержка перед телепортом киллера).

2.3 Спавн

• Спавн-точки прописаны в config.yml (4 точки для выживших + 1 для киллера).
• Выжившие телепортируются одновременно.
• Киллер телепортируется через 5 секунд после выживших (grace period).
• Во время grace period киллер видит таймер в ActionBar.
• Генераторы, хуки, выходы и другие объекты расставляются при старте игры по координатам из config.yml.

⚠ Все координаты (спавны, хуки, генераторы, выходы, подвал) задаются в config.yml — не хардкодятся в коде.

---

3. Механики выжившего (Survivor)

3.1 Состояния здоровья

Выживший имеет три состояния — переходы строго последовательные:

Состояние	Описание	Визуал в Minecraft
Healthy (здоров)	Может бежать, прыгать, взаимодействовать	Полное здоровье, без эффектов
Injured (ранен)	Оставляет следы крови, издаёт стоны, скорость чуть снижена	Частицы крови, звук боли каждые 3 сек
Downed (повален)	Ползёт по полу, не может бежать или взаимодействовать	Crawl-анимация (Sneak + замедление), скорость 30%
Hooked (на крюке)	Привязан к крюку, ждёт спасения	Заморожен, анимация качания на крюке
Dead (мёртв)	Выбывает из игры	Spectator mode

3.2 Переходы состояний

• Healthy → Injured: одно попадание от киллера.
• Injured → Downed: второе попадание от киллера.
• Downed → Hooked: киллер подбирает (ПКМ) и несёт к крюку.
• Hooked → Dead: истекло 2 стадии крюка, никто не спас.
• Injured → Healthy: использование аптечки или спасение с крюка.

3.3 Передвижение

• Healthy: обычная скорость + возможность спринта.
• Injured: скорость снижена на 5% (speed effect).
• Downed: только ползти — отрицательный Speed, принудительный Sneak, без прыжков.
• Спринт (Exhaustion): можно спринтовать конечное время (exhaustion_seconds, по умолчанию 3 сек спринта, затем 5 сек кулдауна).

⚠ Спринт — ключевая механика для чейса. Реализовать через isSprinting() + кастомный кулдаун.

3.4 Исцеление (Healing)

• Аптечка (Med-Kit): зажать ПКМ 10 секунд, прогресс-бар в ActionBar.
• Исцеление другим выжившим: подойти вплотную, зажать ПКМ 16 секунд (медленнее, чем аптечкой).
• Если движение прервалось (игрок отошёл, получил удар) — прогресс сбрасывается.
• Иконка прогресса в ActionBar: [████░░░░░░] Исцеление 40%

3.5 Механика крюка (Hook)

После того как киллер повесил выжившего на крюк:

Стадия	Длительность	Событие
Stage 1	60 секунд	Выживший висит. Можно спасти. В ActionBar — таймер.
Stage 1 → 2	Автоматически	Если не спасли за 60 сек — переход на Stage 2.
Stage 2	60 секунд	Выживший борется с Сущностью. Каждые 2 сек — Skill Check (QTE).
Stage 2 провален	Мгновенно	Выживший умирает — переход в Spectator.
Спасение с крюка	2 секунды	Другой выживший снимает с крюка (прогресс-бар). Стадия запоминается.

• Один и тот же выживший может быть повешен максимум 3 раза (hook_count). На 3-й раз — мгновенная смерть.
• Крюки в подвале (Basement) не уничтожаются и дают бонусные Bloodpoints.

⚠ Skill Check на Stage 2 — случайное появление индикатора в Title. Игрок должен нажать Shift или Drop в нужный момент. Промах — мгновенная смерть.

3.6 Спасение с крюка

• Выживший подходит к крюку с союзником на расстояние 2 блока.
• Зажимает ПКМ (или Sneak) в течение 2 секунд — прогресс в ActionBar.
• Спасённый получает статус Injured (или остаётся Injured).
• Спасатель не получает защиты — может быть немедленно атакован.
• Borrowed Time: если киллер стоит рядом с крюком в момент спасения — спасённый получает 10 сек защиты Endurance (не переходит в Downed с первого удара).

3.7 Ползание (Dying State)

• Повалённый выживший ползёт со скоростью 30% от нормальной.
• Может ползти к другому выжившему — тот может его поднять (Recovery, 4 секунды).
• После Recovery выживший встаёт в статусе Injured.
• Самовосстановление невозможно без специального перка.
• Повалённый выживший издаёт стоны (слышимые киллеру).

---

4. Генераторы (Generators)

4.1 Общие правила

• На карте спавнится 7 генераторов, нужно починить 5.
• Количество настраивается: total_generators, required_generators в config.yml.
• Починённые генераторы светятся (частицы + звук).
• Киллер видит ауру всех непочиненных генераторов (через частицы или Sidebar).

4.2 Процесс починки

• Выживший подходит к генератору и зажимает ПКМ — начинается починка.
• Прогресс отображается в ActionBar.
• Базовое время починки: 80 секунд (один выживший).
• Два выжившего на генераторе: скорость ×1.5 (gen_coop_multiplier).
• Три и более: скорость ×2.0 (ограничено).
• Если выживший отошёл или получил удар — прогресс частично откатывается (regression).

4.3 Skill Checks (Проверки навыка)

• В Title показывается круговой индикатор (симулируется через Title-анимации).
• Игрок должен нажать Drop (Q) в нужный момент (попасть в зелёную зону).
• Успешный Skill Check: +5% к прогрессу генератора + бонусные Bloodpoints.
• Провальный Skill Check: взрыв — генератор теряет 10% прогресса, громкий звук (слышен киллеру в радиусе 40 блоков).
• Частота skill check: раз в 20–40 секунд (рандомно).

⚠ Звук провального skill check — важнейший инструмент для киллера. Реализовать через playSound() с большим радиусом.

4.4 Регрессия генератора

• Если все выжившие отошли от работающего генератора — он начинает откатываться (0.25% в секунду).
• Киллер может ударить по генератору (ПКМ) — Kick: мощная регрессия 2.5% в секунду на 30 секунд.
• Регрессию можно остановить — выживший подходит и нажимает ПКМ.
• Взорванный генератор издаёт звук и выбрасывает частицы взрыва.

---

5. Механики киллера (Killer)

5.1 Базовые характеристики

Параметр	Значение	Настройка
Скорость	115% от скорости выжившего	killer_speed
Terror Radius	32 блока	terror_radius
Урон атаки	Переводит в Injured / Downed	Не числовой — по состоянию
Кулдаун атаки	2.5 секунды	attack_cooldown
Перенос выжившего	92% скорости	carry_speed

5.2 Terror Radius и Red Stain

• Terror Radius — зона 32 блока вокруг киллера. Выжившие в этой зоне слышат сердцебиение.
• Интенсивность звука увеличивается при сближении (3 уровня: далеко / близко / рядом).
• Red Stain — красное свечение на земле за киллером (частицы). Показывает направление взгляда.
• Реализация Red Stain: каждые 0.5 сек спавнить Dust-частицы красного цвета позади головы киллера.

5.3 Атака и удар

• Базовая атака: ЛКМ по выжившему. Урон по состояниям (Healthy→Injured или Injured→Downed).
• После удара — кулдаун 2.5 сек (замедление на 0.5 сек).
• Нельзя атаковать сквозь окна / паллеты (проверка LineOfSight).
• Bloodlust: если киллер преследует выжившего >15 секунд без попадания — бонус скорости:
  • Тир 1: +3%
  • Тир 2: +5%
  • Тир 3: +8%
  • Тиры сбрасываются при ударе или смене цели.

5.4 Подъём и перенос выжившего

• Когда выживший Downed — киллер нажимает ПКМ для подъёма (2.5 сек анимации).
• Во время переноса: киллер замедлен до 92% скорости, не может атаковать.
• Выживший сидит на киллере (через ArmorStand или Mount).
• Чтобы повесить: киллер подходит к хуку и нажимает ПКМ.
• Wiggle (вырывание): выживший нажимает Sneak/Jump быстро — прогресс побега в ActionBar. При 100% — выживший падает рядом в Downed статусе.
• Время вырывания: 16 секунд (wiggle_duration).

5.5 Взаимодействие с генераторами

• Киллер нажимает ПКМ на генератор — Kick (регрессия, см. раздел 4.4).
• Киллер видит ауру всех незаконченных генераторов в Sidebar (иконки + расстояние).

5.6 Подвал (Basement)

• Специальная зона на карте с 4 крюками.
• Крюки в подвале нельзя саботировать.
• Перевод выжившего в подвал засчитывается быстрее + бонус Bloodpoints.

---

6. Паллеты (Pallets) и Окна (Windows)

6.1 Паллеты

• Паллеты — деревянные барьеры на карте (блоки, отмеченные в конфиге).
• Выживший подходит к паллете и нажимает ПКМ — паллета падает (standing → dropped).
• Если киллер коснулся упавшей паллеты — Stun 2.5 сек (звук, частицы).
• Киллер может сломать паллету: зажать ПКМ на 3 секунды. Паллета исчезает навсегда.
• Количество паллет на карте конечно. Статус каждой хранится в памяти.
• Выживший может пробежать через упавшую паллету (Vault, 0.6 сек).

6.2 Окна (Windows)

• Окна — прыжковые зоны в стенах карты (координаты в конфиге).
• Выживший запрыгивает в окно: 1 секунда анимации Vault (замедление → ускорение).
• Киллер тоже может прыгнуть в окно, но медленнее (1.5 сек).
• Fake Vault (Mindgame): игрок может зайти в начало вота и выйти обратно.

⚠ Паллеты и окна — основа loop-механики чейса. Без правильного расположения на карте игра будет несбалансированной.

---

7. Выходные ворота (Exit Gates) и Люк (Hatch)

7.1 Выходные ворота

• После починки 5 генераторов активируются 2 выходных ворот (gate_locations).
• Рубильник ворот загорается (смена блока, звук).
• Выживший взаимодействует с рубильником 20 секунд (прогресс в ActionBar).
• Если прервать — прогресс не откатывается (в отличие от генераторов).
• Открытые ворота остаются открытыми навсегда.
• Выживший пересекает границу выхода → ESCAPED! (Title).
• Эндгейм-коллапс: через 2 минуты после открытия первых ворот — все оставшиеся выжившие умирают.

7.2 Люк (Hatch)

• Люк появляется, когда выживших меньше, чем непочиненных генераторов.
• Правило: если X выживших живы и < X генераторов починено — люк открыт.
• Последний выживший всегда видит открытый люк.
• Координата люка — hatch_location в конфиге.
• Прыжок в люк = Escape (побег через люк).
• Киллер может закрыть люк (ПКМ). После этого активируется End Game Collapse.
• Закрытый люк можно открыть выжившим с Ключом (Key) за 2.5 секунды.

---

8. Предметы (Items) для выживших

Предметы выдаются игрокам перед игрой или находятся в Сундуках (Chests) на карте. Максимум 1 предмет в руках.

Предмет	Действие	MC-предмет	Ограничение
Med-Kit	Лечит Injured → Healthy за 10 сек	Red Dye / Custom	1 заряд
Flashlight	Слепит киллера (Blindness 2 сек)	Glowstone Dust / Custom	8 использований
Toolbox	Ускоряет починку гена на 30%	Iron Pickaxe / Custom	1 генератор
Key	Открывает закрытый люк	Gold Nugget / Custom	1 использование
Map	Показывает ауру генераторов выжившим	Paper / Custom	Пассивно

8.1 Сундуки

• На карте расставлено N сундуков (chest_locations в конфиге).
• Каждый сундук при открытии выдаёт случайный предмет (весовая таблица в loot_table.yml).
• Открытие: 3 секунды (прогресс-бар). Один сундук — один предмет навсегда.
• Киллер может видеть ауры сундуков (опционально, через перк).

---

9. Bloodpoints и прогрессия

Bloodpoints — внутриигровая валюта, начисляется за действия в раунде. Хранятся в базе данных (SQLite или YAML).

Действие	Выживший (BP)	Киллер (BP)
Починить генератор (полностью)	+1000	—
Успешный Skill Check	+150	—
Спасти с крюка	+800	—
Исцелить союзника	+600	—
Сбежать	+5000	—
Повесить выжившего на крюк	—	+800
Повалить выжившего	—	+500
Пожертвовать выжившего (3 стадии)	—	+2000
Сломать паллету	—	+200
Ударить по генератору (Kick)	—	+100

• Bloodpoints отображаются в Title после окончания матча.
• Статистика сохраняется в базе данных.

---

10. Система перков (Perks)

Перки — пассивные и активные способности. Каждый игрок берёт 4 перка перед матчем (в GUI-меню выбора).

10.1 Перки Выживших (минимум 10)

Перк	Эффект
Self-Care	Позволяет лечить себя без аптечки (вдвое медленнее)
Dead Hard	При нажатии Sneak во время спринта — кратковременный рывок (0.5 сек неуязвимости)
Borrowed Time	После спасения с крюка — 10 сек защита Endurance
Sprint Burst	При начале спринта — ускорение ×1.5 на 3 сек (кулдаун 40 сек)
Iron Will	Убирает звуки стонов в Injured состоянии
Spine Chill	Предупреждение (иконка + звук), если киллер смотрит на выжившего с 36 блоков
Resilience	В Injured/Downed — скорость починки +9%, скорость вота +9%
Kindred	После повешения на крюк — все союзники видят ауру киллера
Prove Thyself	За каждого выжившего на генераторе — скорость +15% (стакается)
Adrenaline	При открытии 5-го генератора — мгновенно Healthy + Sprint Burst 5 сек

10.2 Перки Киллера (минимум 10)

Перк	Эффект
Hex: Ruin	Все генераторы регрессируют вдвое быстрее (пока горит тотем)
Corrupt Intervention	3 самых дальних генератора заблокированы 2 минуты в начале игры
Pop Goes the Weasel	После повешения — следующий Kick откатывает 25% прогресса гена
Deadlock	После починки любого гена — самый прогрессивный ген блокируется на 30 сек
No Way Out	После повешения — добавляется задержка при открытии ворот (+12/24/36 сек)
Scourge Hook: Pain Resonance	Повешение на Scourge Hook взрывает ближайший ген (−25%)
Nowhere to Hide	После Kick гена — ауры выживших видны 4 сек в радиусе 24 блоков
Lethal Pursuer	В начале игры — видеть ауры всех выживших 7 секунд
BBQ & Chili	После повешения — видеть ауры выживших >40 блоков на 4 сек
Tinkerer	Когда ген достигает 70% — уведомление + Undetectable на 12 сек

⚠ Перки реализовать через EventListener. Каждый перк — отдельный класс, реализующий интерфейс IPerk с методами onEquip(), onTrigger(), onRemove().

10.3 Тотемы (Totems)

• На карте 5 тотемов (totem_locations в конфиге).
• Dull Totem: выживший ломает за 14 секунд — начисляются Bloodpoints.
• Hex Totem: активируется при использовании Hex-перка. Пока горит — перк активен.
• При уничтожении Hex Totema — связанный перк деактивируется навсегда.

---

11. Эндгейм и итоги матча

11.1 Условия победы

Сторона	Победа	Поражение
Выжившие	Минимум 2 выживших сбежали (ворота или люк)	Все выжившие мертвы до побега
Киллер	Все 4 выжившие принесены в жертву / умерли	2+ выжившие сбежали

11.2 Экран результатов

• Все игроки телепортируются в лобби.
• В Chat выводится таблица: игрок, роль, Bloodpoints, статус (Escaped / Sacrificed).
• Title на 5 секунд: ПОБЕДА / ПОРАЖЕНИЕ.
• Личная статистика матча: генераторы, спасения, хуки, урон.

11.3 Эндгейм Коллапс (End Game Collapse)

• Активируется при: открытии ворот ИЛИ закрытии люка.
• Таймер 120 секунд показывается всем в ActionBar красным текстом.
• По истечении — все оставшиеся выжившие мгновенно умирают.

---

12. Пользовательский интерфейс (HUD)

12.1 ActionBar

• Постоянно: статус игрока (❤ Healthy / 🩸 Injured / 💀 Downed).
• При взаимодействии: прогресс-бар починки / лечения / спасения.
• Эндгейм Коллапс: красный таймер обратного отсчёта.

12.2 Sidebar (Scoreboard)

• Выжившие: количество починенных генераторов (⚡ 2/5), сколько выживших живо (👥 3/4).
• Киллер: сколько выживших на крюке / мертво, прогресс генераторов.

12.3 Title / Subtitle

• Оповещения: генератор починен, выживший на крюке, ворота открыты.
• Начало игры: роль + краткая инструкция.
• Skill Check: вспышка в Title с таймером.

12.4 Звуки

• Terror Radius: нарастающее сердцебиение по мере приближения киллера (3 уровня).
• Генератор: звук работы при починке, взрыв при провале skill check или Kick.
• Спасение с крюка: звук успеха.
• Люк: звук открытия / закрытия.
• Ворота: звук активации, гудение.

⚠ Рекомендуется базовый Resource Pack для кастомных звуков. Без него — стандартные MC-звуки как замена.

---

13. Конфигурация (config.yml)

Секция	Ключ	Тип	По умолчанию
game	min_players	int	5
game	max_players	int	5
game	countdown_seconds	int	60
game	world_name	string	dbd_map
game	lobby_world	string	lobby
killer	killer_speed	double	1.15
killer	terror_radius	int	32
killer	attack_cooldown	double	2.5
killer	carry_speed	double	0.92
killer	wiggle_duration	double	16.0
survivor	sprint_duration	double	3.0
survivor	sprint_cooldown	double	5.0
survivor	heal_self_time	double	10.0
survivor	heal_other_time	double	16.0
generator	total_generators	int	7
generator	required_generators	int	5
generator	repair_time	double	80.0
generator	gen_coop_multiplier	double	1.5
generator	regression_rate	double	0.25
hook	stage1_duration	int	60
hook	stage2_duration	int	60
hook	max_hook_count	int	3
endgame	collapse_duration	int	120

Дополнительные файлы конфигурации:

• locations.yml — все спавн-точки, координаты генераторов, хуков, тотемов, сундуков, ворот, люка.
• loot_table.yml — весовая таблица предметов в сундуках.
• perks.yml — настройки перков (кулдауны, длительности).

---

14. Команды и права

Команда	Описание	Право
/dbd join	Войти в очередь на игру	dbd.play
/dbd leave	Выйти из очереди / матча	dbd.play
/dbd forcestart	Принудительно запустить игру	dbd.admin
/dbd stop	Принудительно остановить игру	dbd.admin
/dbd setkiller <игрок>	Назначить игрока киллером	dbd.admin
/dbd setspawn <killer|survivor1..4>	Установить спавн-точку (по курсору)	dbd.admin
/dbd setgen <id>	Отметить блок как генератор	dbd.admin
/dbd sethook <id>	Отметить блок как крюк	dbd.admin
/dbd setgate <1|2>	Отметить зону ворот	dbd.admin
/dbd sethatch	Отметить блок как люк	dbd.admin
/dbd reload	Перезагрузить конфиг	dbd.admin
/dbd stats [игрок]	Посмотреть статистику	dbd.play

---

15. Архитектура плагина

15.1 Структура пакетов

Пакет	Назначение
com.dbd.plugin.core	Главный класс, GameManager, EventBus
com.dbd.plugin.game	GameSession, GameState, RoleAssigner, RoundTimer
com.dbd.plugin.roles	KillerController, SurvivorController, PlayerState
com.dbd.plugin.mechanics	GeneratorManager, HookManager, PalletManager, HatchManager, GateManager
com.dbd.plugin.perks	IPerk, PerkRegistry, PerkLoader, [все перки]
com.dbd.plugin.items	IItem, ItemRegistry, ChestManager
com.dbd.plugin.ui	HUDManager, ActionBarManager, TitleManager, SoundManager
com.dbd.plugin.data	DatabaseManager, PlayerStats, LocationsConfig
com.dbd.plugin.commands	DBDCommand, TabCompleter

15.2 Ключевые принципы

• Каждый раунд — отдельный объект GameSession со своим состоянием.
• Все механики управляются через BukkitScheduler (tick-based системы).
• Перки реализованы через Event-Driven подход (не хардкод в механиках).
• Конфиги не перезаписывают пользовательские настройки при обновлении (saveDefaultConfig).
• Логирование всех событий в отдельный лог-файл (logs/dbd.log).

⚠ Плагин должен корректно обрабатывать disconnect игрока во время матча — замена ботом или перераспределение ролей.

---

16. Приоритет разработки

Этап	Функционал	Статус
MVP (Этап 1)	Старт/стоп игры, роли, спавн, базовые состояния выжившего, атака киллера	🔴 В разработке
Этап 2	Генераторы (починка, прогресс, регрессия, skill check), хуки (все стадии)	🔴 В разработке
Этап 3	Паллеты, окна, перенос, вырывание, люк, ворота, эндгейм	🔴 В разработке
Этап 4	Предметы, сундуки, тотемы, базовые перки (10 survivor + 10 killer)	🔴 В разработке
Этап 5	Полный HUD, звуки, Terror Radius, Red Stain, Bloodpoints, база данных	🔴 В разработке
Этап 6	Балансировка, все остальные перки, тест-раунды, оптимизация	🔴 В разработке

---

ТЗ подготовлено с учётом всех оригинальных механик Dead by Daylight (4v1) | Версия 1.0