Wave Defense Mod - v0.2.53.4

Installation

Install Forge 1.20.1 (47.2.0+ recommended).
Copy the built wavedefense-0.2.53.4.jar into the mods/ folder.
Optional: install Mine and Slash (mmorpg mod, v6.1.0+) to unlock per-location mob level / XP / resistance settings.
Start the client or dedicated server.

Key Bindings

Key	Action
`V`	Open the main Wave Defense menu
`B`	Open the shop directly
`G`	Leave the current location

Main Features

PvE Wave Defense

Configurable locations with player spawn, optional scatter radius, and mob spawn points.
Configurable waves with mob type, count, equipment, effects, spawn chance, and scaling.
Optional delay before the first wave and between later waves.
Point system for kills, starting points, purchases, sales, rewards, and completion bonuses.
Inventory backup and restore on entry/exit.
Starting items and completion rewards.
Global shop mode or point-based shop mode.
Loot spawn points with event triggers.
Optional auto-activation zone with countdown and particles.
Optional location boundary with timer, damage, teleport-back, or instant surrender modes.
Optional portal system for penalty waves.
TextDisplay info panels for wave, timer, mob count, players, and points.
30-second grace period when the last player leaves mid-wave — wave resumes if someone rejoins.

Mine and Slash compatibility (optional)

When Mine and Slash (mmorpg mod, v6.1.0+) is installed, each PvE location gains extra per-location settings in the Special tab of the location editor:

Setting	Effect
Mob Level	Sets the MnS level of every mob spawned in this location
XP Drop Bonus %	Adds a PERCENT `bonus_exp` modifier to every spawned mob
Fire Resist	Adds a FLAT `fire_resist` modifier
Water Resist	Adds a FLAT `water_resist` modifier
Lightning Resist	Adds a FLAT `lightning_resist` modifier
Chaos Resist	Adds a FLAT `chaos_resist` modifier
Physical Resist	Adds a FLAT `physical_resist` modifier

All values default to 0 (no override — MnS uses its own defaults).
The section is hidden entirely when Mine and Slash is not installed.

PvP Modes

PvP locations use team spawn points and per-location PvP settings.

Supported sub-modes:

Standard: team rounds with buy phase, countdown, active phase, win/loss points, and round count.
Deathmatch: respawns during the match and victory by kill target.
Battle Royale: random spawn assignment, shrinking border, border particles, and last-player-wins flow.

PvP settings include:

team spawn points with optional spawn radius;
minimum player count;
friendly fire;
team auto-balance;
wait effects;
starting points;
kill points and death penalty;
round start delay;
round start/win/loss points;
Deathmatch kill target;
Battle Royale border radius, shrink interval, particles, and border damage.

Admin Editors

The mod is designed to be configured in game through GUI screens:

location editor;
PvP location editor;
wave list editor;
wave mob editor;
wave trigger editor;
mob selection;
starting items;
completion rewards;
shop editor;
shop item editor;
shop availability trigger editor;
shop point editor;
loot spawn editor;
import/export screens;
HUD editor.
player PvP team selection screen.

Current UI direction for 0.2.43+:

fewer long unstructured forms;
grouped sections for Basic, Spawns, Waves, Shop, Loot, Boundary, Portal, HUD, and PvP;
consistent scroll behavior across all large screens;
no clicks on hidden scrolled-out widgets;
better player shop browsing with list and tile/grid modes;
parity between useful PvE location settings and PvP location settings;
clearer PvP team selection with scrollable cards for locations with many teams.

Shop System

The shop supports:

multiple item stacks per shop entry;
buy and sell price;
category;
optional NBT matching for sell checks;
availability triggers;
global shop items;
per-point shop items;
import/export through NBT files.

Player-facing UI:

tile/grid view with item icons, compact prices, category filtering, and clear buy/sell actions;
classic list view remains available from the same shop screen.

Trigger System

Triggers are used by waves, loot, shops, and location events.

Examples:

wave events: WAVE_START, WAVE_END, WAVE_N, WAVE_COMPLETE;
timers: TIMER_60, TIMER_120, TIMER_300, TIMER_CUSTOM;
mob events: MOB_KILL, MOBS_KILLED_N, MOBS_REMAINING_LOW;
player events: PLAYER_JOIN, PLAYER_DEATH, PLAYER_ENTER_ZONE, PLAYER_HAS_ITEM;
PvP events: ROUND_START, ROUND_END, BUY_PHASE, MATCH_START, MATCH_END, TEAM_WIPE, KILL_STREAK_3;
shop events: SHOP_LOCATION_START, SHOP_WAVE_START, SHOP_WAVE_N, SHOP_PLAYER_HAS_ITEM.

Commands

Command	Description
`/wavedefense`	Main command
`/wd`	Alias
`/wavedefense kick <players>`	Force-remove players from a location
`/wavedefense tp <location> <players>`	Teleport players to a location
`/wavedefense menu <player> [admin]`	Open a menu for a player
`/wavedefense reload`	Reload saved location data

Configuration

In-game (recommended)

Open the Mods menu → select Wave Defense → click Config.
A five-tab GUI covers every setting without editing any file manually:

Tab	Settings
General	HUD overlay, default wave time, UI tooltips, lobby timer, location game mode
PvP	Hide enemy nametags, default rounds, default buy time
Mobs & Shop	Mob equipment toggle, armor drop chance, shop categories, shop hotkey
Limits	Max mob types, waves, spawn points, shop items, loot spawns (1–9999)
Debug	Admin debug messages, server log verbosity

Changes are written to disk immediately on Save & Close.

File (manual)

Common config file:

config/wavedefense-common.toml

Wave Defense — Детальний опис моду

1. Загальна концепція

Wave Defense — це арена-рушій для сервера Minecraft 1.20.1 Forge. Адміністратор сервера створює «локації» — ізольовані арени з незалежними правилами. Кожна локація може бути або PvE (хвилі мобів), або PvP (командний бій). Гравець входить у локацію через меню (V), грає сесію, виходить — і все налаштоване виключно через GUI без редагування файлів.

2. Типи локацій

2.1 PvE — «Захист від хвиль»

Гравці відбивають хвилі ворожих мобів. Після кожної хвилі — пауза, потім наступна. Ціль — пережити всі сконфігуровані хвилі.

Основний цикл:

Вхід → Лобі (таймер) → Хвиля 1 → Пауза → Хвиля 2 → … → Хвиля N → Перемога

Що відбувається всередині сесії:

Гравці телепортуються до точки спавну локації
Застосовується початкове спорядження (якщо налаштовано)
Нараховуються початкові очки
Запускається таймер лобі (зазвичай 5 с, очікує приєднання)
Хвиля за хвилею спавняться моби з налаштованим обладнанням, ефектами, шансами
Убивство моба → очки гравцю; закінчення хвилі → нагорода хвилі
Прохід усіх хвиль → екран перемоги → видача нагород → телепорт на вихід

2.2 PvP — «Командний бій»

Гравці розподіляються по командах і змагаються. Наявні 5 підрежимів:

Підрежим	Суть
Standard	Раунди: фаза покупок → відлік → бій. Перемагає команда, яка виграє більше раундів
Deathmatch	Необмежені respawn'и, перемагає хто першим набере N вбивств
Battle Royale	Кожен за себе / команди; кордон поля зменшується, останній гравець / команда виграє
Capture the Point	Команди захоплюють і утримують кілька точок; очки нараховуються поки точка під контролем
King of the Hill	Те саме, але одна спірна точка

3. Що бачить і робить гравець

3.1 Вхід у локацію

Натискає V → відкривається PlayerMenuScreen
Бачить список усіх відкритих локацій з позначками [PvE] / [PvP]
Клікає на локацію:
- PvE → одразу приєднується
- PvP → спочатку відкривається екран вибору команди (PvpTeamSelectScreen)
Телепортується до точки спавну, отримує початкове спорядження і очки
Починається таймер лобі (якщо є інші гравці, таймер вже тікає — гравець бачить залишок)

3.2 Під час PvE-сесії

HUD (правий верхній кут) показує:
- Назву локації
- Номер хвилі: Хвиля 3 / 10
- Кількість мобів: зелено → жовто → червоно при зменшенні
- Таймер до наступної хвилі з прогрес-баром
- Очки гравця
- Список учасників команди
Магазин (клавіша B): витрачає очки на предмети; доступність предметів залежить від тригерів (наприклад, «тільки після хвилі 3»)
Вихід (клавіша L): добровільна здача — інвентар відновлюється до стану перед входом, підбір лоту — за налаштуванням
При загибелі: відновлення (залежить від keepInventory локації)
Якщо останній гравець виходить під час хвилі → 30-секундна пауза очікування (grace period); якщо хтось повертається — сесія продовжується

3.3 Під час PvP-сесії

Загальне:

HUD показує: поточну фазу (BUY / ACTIVE / WAITING), рахунок раунду, таймери, очки
Ворожі нікнейми сховані (через Minecraft Scoreboard API + рендер-хук)

Standard / DM / BR:

BUY фаза: отримують очки раунду, відкривається магазин
COUNTDOWN: відлік 3-2-1
ACTIVE: бій; кожне вбивство = очки; кожна смерть = штраф очок
Вибування (BR) або знищення команди (Standard) = кінець раунду
Результат раунду + нові очки → наступний раунд або кінець матчу

Capture the Point / King of the Hill:

Є захоплювані точки на карті (позначені частинками)
Зайти в радіус точки → почати захоплення (прогрес-бар у HUD)
Якщо обидві команди стоять на точці → захоплення заморожується (contested)
Захоплена точка нараховує очки команді кожну секунду
HUD праворуч: список точок з власником, прогрес-баром і лічильником очок, таймер раунду
Перемога: або перша команда набрала scoreToWin, або найвищий рахунок після таймера

3.4 Рейтинг (Leaderboard)

Кнопка 🏆 Рейтинг у головному меню гравця (видима тільки поза локацією)
Відкриває LeaderboardScreen:
- Вибір локації (кнопки-ряд зі скролом колесом)
- Вкладки режимів: PvE | Standard | DM | BR | Capture | KotH
- Таблиця топ-10: # | Гравець | Очки | <доп. метрика> | Час | Дата
- PvE: очки + хвилі; PvP: очки + вбивства

4. Що налаштовує адміністратор

4.1 Відкриття адмін-меню

Натискає V (клавіша меню) → бачить кнопку адміна (потребує рівень оператора 2)
Або команда /wavedefense menu <player> admin

4.2 AdminMenuScreen — керування локаціями

Поле вводу назви (лише a-z, 0-9, -, _)
Кнопки: Створити, Редагувати, Видалити (2 кліки), Імпорт / Експорт
Список усіх локацій зі скролом

4.3 LocationEditorScreen — PvE-локація (вкладки)

Вкладка «Основне»

Параметр	Опис
Назва	Унікальний ідентифікатор
Точка спавну гравців	`X Y Z` + кнопка 📌 (взяти поточну позицію)
Радіус розкиду спавну	0 = точний спавн; > 0 = випадковий радіус навколо точки
Зберігати інвентар	Якщо вимк. — інвентар гравця зберігається та відновлюється
Enforce GameMode	Ставить Survival при вході, повертає оригінальний при виході
Початкові предмети	Редагує список предметів для роздачі при вході
Нагороди за завершення	Предмети / очки для гравців, що виконали умову

Вкладка «Хвилі»

Список хвиль. Кожна хвиля містить:

Параметр	Значення
Список мобів	Тип моба, кількість, зростання/хвилю, шанс спавну, очки за вбивство
Обладнання моба	Шолом, нагрудник, штани, черевики, основна рука, допоміжна рука
Ефекти моба	Список `ефект:підсилення:тривалість`
Радіус спавну	Персональний для цього типу або від локації
Точка спавну хвилі	Конкретна `X Y Z` замість спільних точок спавну
Нагорода хвилі	Очки за проходження, potion-ефект для гравців, команда з плейсхолдерами
Тригер активації	Хвиля активується не по черзі, а по події (PLAYER_JOIN, TIMER_60, MOBS_KILLED_N тощо)
З якої хвилі	Мінімальний номер хвилі для активації тригера
Кулдаун тригера	Секунди / хвилі / одноразово

Вкладка «Магазин»

Параметр	Опис
Режим	GLOBAL (один магазин) або POINT (кілька точок-магазинів)
Список товарів	До 4 предметів в одному записі, ціна купівлі/продажу
Категорія товару	ALL / WEAPON / ARMOR / CONSUMABLE / OTHER
Тригер доступності	Товар стає доступним тільки після події (наприклад, хвиля 5)
NBT-matching	Продаж тільки предмету з точним NBT
Точки магазину	`POINT` режим: позиція, радіус доступу, власний список товарів

Вкладка «Спеціальне» (Boundary)

Параметр	Опис
Boundary enabled	Ввімкнути кордон
Радіус кордону	1–9999 блоків
Наслідок виходу	TIMER_SURRENDER / DAMAGE / TELEPORT_BACK / INSTANT_SURRENDER
Таймер здачі	Секунд до примусової здачі (при TIMER_SURRENDER)
Ушкодження кордону	Пошкодження в секунду (при DAMAGE)
Частинки кордону	Тип, кількість, висота стіни часток

Вкладка «Спеціальне» (Auto-Zone)

Параметр	Опис
Auto-activate enabled	Зона автоматично запускає сесію
Центр зони	`X Y Z` або точка спавну
Радіус зони	5–9999 блоків
Час активації	Секунд відлічується до старту (0 = негайно)
Відкрита після старту	Секунд після старту, поки нові гравці можуть увійти
Частинки зони	Тип, кількість, швидкість, інтервал

Вкладка «Спеціальне» (Portal)

Параметр	Опис
Portal enabled	Ввімкнути портальну систему
Штрафна хвиля	-1 = послідовно; 0+ = конкретна хвиля зі списку
Таймер порталу	Секунд до зникнення (штраф якщо не зайшов)
Зникає після проходження	Чи зникає портал після очищення штрафної хвилі
Таймер respawn	Мінімум 30 с між порталами
Відкритий після старту	Гравці можуть заходити N секунд після появи
Зберегти лут при виході	Гравець зберігає предмети при виході з порталу

Вкладка «Спеціальне» (Info Panels)

TextDisplay сутності у грі:

Spawn panel: у точці спавну гравців — показує хвилю, мобів, таймер, кількість гравців, лобі-таймер, першу хвилю
Mob spawn panels: у кожній точці спавну мобів — хвиля, таймер, кількість мобів
Для кожної панелі: зміщення по Y, масштаб тексту, перемикачі видимості рядків

Вкладка «Mine & Slash» (якщо встановлений mmorpg v6.1.0+)

Параметр	Ефект
Mob Level	Рівень MnS для кожного спавненого моба
XP Drop Bonus %	`bonus_exp` PERCENT-модифікатор
Fire / Water / Lightning / Chaos / Physical Resist	FLAT-модифікатор відповідного опору

4.4 PvpLocationEditorScreen — PvP-локація (вкладки)

Вкладка «Загальне»

Параметр	Опис
Точки спавну команд	`X Y Z`, назва команди, радіус розкиду
Мін. гравців	Матч не починається поки менше N гравців
Friendly fire	Шкода між членами команди
Авто-баланс	Рівномірний розподіл гравців по командам
Ефекти очікування	Slowness+Blindness або Spectator Mode поки чекають
Початкові очки	Очки при вході

Вкладка «Правила» (по підрежиму)

Standard:

Параметр	Опис
Кількість раундів	Загальна кількість раундів у матчі
Час покупки	Тривалість BUY-фази (секунди)
Затримка початку раунду	Відлік перед ACTIVE
Очки за перемогу раунду	Нагорода команді-переможцю
Очки за поразку	(штраф або 0)
Очки за вбивство / смерть	Персональні очки

Deathmatch:

Параметр	Опис
Вбивства для перемоги	Перша команда/гравець з N вбивствами виграє
Час покупки	Аналогічно Standard

Battle Royale:

Параметр	Опис
Радіус кордону	Початковий радіус (мін. 10 блоків)
Інтервал стиснення	Кожні N секунд радіус зменшується на 1 блок
Тип частинок кордону	Вид ефекту по периметру
Кількість часток	Щільність стіни
Ушкодження кордону	Пошкодження в секунду поза кордоном

Capture the Point / King of the Hill:

Параметр	Опис
Очки для перемоги	Перша команда з N очками виграє (режим first-to-score)
Очки/сек	Скільки очків нараховується за кожну точку за секунду
Тривалість раунду	Секунди (для timer-режиму)
Режим перемоги	First-to-score АБО Most-score at timer end

Вкладка «Точки захоплення» (тільки CtP/KotH)

Список точок + редактор кожної:

Параметр	Значення
Назва точки	Відображається в HUD і чаті (макс. 20 символів)
Позиція	`X Y Z` або 📌
Радіус захоплення	1–30 блоків
Час захоплення	1–120 секунд для перехоплення точки
Тип частинок	Преселект: smoke / flame / end_rod / witch / portal / snow / squid_ink
Кількість частинок	Кільце часток навколо точки

4.5 Адмін-команди

Команда	Дія
`/wavedefense` або `/wd`	Головна команда
`/wd tp <локація> <гравці>`	Телепортувати гравців у локацію
`/wd kick <гравці>`	Примусово вивести гравців з локації
`/wd menu <гравець> [admin]`	Відкрити меню для гравця (або адмін-меню)
`/wd reload`	Перезавантажити дані локацій з диска

5. Детальний опис механік

5.1 Система тригерів

Тригери використовуються у хвилях, луті, магазинах. Можна задати умову AND (обидва тригери повинні спрацювати одночасно), кулдаун, одноразовість.

Доступні тригери:

Категорія	Тригери
Гравець	JOIN, DEATH, ENTER_ZONE, OPEN_CHEST, OPEN_DOOR, LOW_HEALTH, FULL_INVENTORY, HAS_ITEM (кастомний ID), HAS_DIAMOND/IRON/SWORD
Таймер	TIMER_60, TIMER_120, TIMER_300, TIMER_CUSTOM (довільна кількість секунд)
Хвилі	WAVE_START, WAVE_END, WAVE_N (конкретна хвиля), WAVE_COMPLETE, WAVES_SURVIVED_5/10/20/N
Моби	MOB_KILL, MOBS_KILLED_10/50/100/N, HALF_MOBS_DEAD, MOBS_REMAINING_LOW
PvP	ROUND_START, ROUND_END, BUY_PHASE, TEAM_WIPE, KILL_STREAK_3, MATCH_START, MATCH_END
Локація	LOCATION_START, LOCATION_END
Магазин	SHOP_LOCATION_START, SHOP_WAVE_START, SHOP_WAVE_N, SHOP_PLAYER_HAS_ITEM

5.2 Система очок

Очки — внутрішня валюта, не пов'язана з рівнем гравця
Нараховуються: при вбивстві моба, при вбивстві гравця (PvP), за проходження хвилі, за виграш раунду
Знімаються: штраф за смерть (PvP)
Витрачаються: в магазині
Нагороди за завершення: конкретні предмети видаються гравцям з ≥ N очок

5.3 Рейтинг (Leaderboard)

Дані зберігаються у <world>/data/wavedefense_leaderboards.dat.

Режим	Primary Score	Secondary
PvE	Набрані очки	Хвилі пройдено
PvP Standard / DM / BR	Очки	Вбивства
PvP CtP / KotH	Очки об'єктиву	Вбивства

Топ-10 на локацію на режим. Атомарний запис (.tmp → rename).

5.4 Backup інвентарю

При вході (якщо keepInventory = false):

Повний інвентар (27 слотів + броня + offhand) зберігається у NBT
Гравець отримує початкові предмети
При виході (перемога / здача) — інвентар відновлюється точно: слоти, броня, offhand, ефекти

5.5 Масштабування складності (Auto-Scaler)

Ведеться статистика виграшів/поразок по локації
Якщо гравці стабільно виграють → множник для кількості мобів збільшується
Якщо стабільно програють → зменшується
Дані зберігаються між перезапусками сервера

6. Варіанти конфігурації локацій (приклади)

Назва	Режим	Особливості
Новачок-арена	PvE	3 хвилі, слабкі зомбі, без кордону, глобальний магазин
Ендгейм-фортеця	PvE	20 хвиль, кожна хвиля з тригером `KILL_STREAK_3` для бонусних мобів, boundary damage, портал у хвилі 10
Auto-зона	PvE	Сесія запускається автоматично коли гравці підходять ближче 10 блоків, без лобі-таймера
KotH Аліна	PvP KotH	Одна точка в центрі, 300 очок для перемоги, 5 хв таймер, частинки end_rod
5-точок CtP	PvP CtP	5 точок по карті, 200 очок для перемоги, contested freeze
Battle Royale	PvP BR	20 точок спавну, кордон 100 блоків → стискується до 10, damage 2/сек
Deathmatch PvP	PvP DM	Без раундів, 30 вбивств для перемоги, фаза покупок кожні 3 хвилини
MnS-рейд	PvE	Моби рівня 50, підвищений fire resist, бонус XP 200%, тільки для гравців з MnS

7. Мережева архітектура (коротко)

Протокол v8, ~34 типи пакетів
Всі адмін-пакети перевіряються на hasPermissions(2) на сервері
Лістинг файлів експорту (RequestWaveExportListPacket) — тільки з дозволом оп.
SyncCtpStatePacket надсилається кожні 20 тіків (1 с) для HUD CtP/KotH
SyncPlayerDataPacket — стан гравця, таймери, очки
SyncPvpStatePacket — фаза PvP, рахунок, таймер

8. Локалізація

8 мов: EN · UK · DE · FR · ES · PL · PT-BR · ZH-CN