ParkourBattle

ParkourBattle turns parkour into a competitive 1v1 (and admin-controlled) combat mode for Paper 1.21. Two players fight not only with weapons, but with movement and block placement: every jump matters. Land wrong — you take damage. Control space with blocks, force awkward angles, and punish hesitation.

This is not a generic minigame hub clone. It is a focused parkour duel engine with strict miss logic, optional in-place fights, kits, arenas, chest interactions, and a full admin/debug layer.

---

Core idea

Players battle while building and jumping. The server tracks battle blocks you placed. If you land on something that is not part of the fight (and not marked safe), it counts as a miss. Misses hurt — configurable damage, actionbar feedback, optional strict radius so “almost on the block” still counts as failure.

That single rule creates real tension: you cannot spam random scaffolding forever; every block is a commitment.

---

Features

Duels & flow

• Challenge / accept style battles between players
• Battle phases (setup → fight → end) queryable in-game
• Forfeit and rematch paths (including rematch when the round already ended, where supported)
• Leave / leave-all tools for admins when a match is stuck
• Spectators support and spectator listing
• Optional battle on the spot (no arena) with a short range invite window — useful for events and spontaneous fights
• HP and phase commands so staff and players can see match state quickly

Miss system (the heart of the plugin)

• Landing on a non-battle block during a fight = miss
• Configurable strict radius around blocks (anti “edge abuse”)
• Safe-stick: mark blocks that must never count as a miss (practice lines, event routes, admin tests)
• Debounced safe-stick toggles so one click does not spam 10 toggles
• Actionbar feedback on successful mark / miss reason (Adventure API with legacy fallback)
• Optional debug miss log (console + rotating file) for rules tuning
• Admin test marks outside live battles (creative testing), with pulse particles and teleport-to-mark

Blocks, chests & modifiers

• Place blocks as part of the duel geometry
• Chest-to-chest jumps can steal inventory from the opponent (configurable attacker/victim messages)
• Separate logic for standing on the chest block vs jumping onto it (modifier hooks)
• Large set of battle modifiers for servers that want ranked rules vs casual fun rules

Kits & arenas

• Kit apply from configured kit items
• Kit list from kits folder
• Arena registry: free / busy status
• Arena info command for staff
• Queue size visibility where enabled

UX & feedback

• Actionbar HUD lines: placed blocks, safe keys, miss reasons
• Optional particles on safe marks (pulse)
• Clear messages when chest-steal triggers
• Spectator and staff-friendly status commands

Admin & integrity

• /pkbattle doctor and --brief summaries (active battles, last-opponent map size, config flags)
• Last opponent tracking: peeks, clear, clearall, size/count, online filters
• Miss log tail/clear helpers
• Versioned config keys for debounce, miss radius, HUD toggles, soft behavior

---

Who is it for?

• Survival / mini-games servers that want skill-based PvP beyond flat arenas
• Event hosts (parkour tournaments, creator challenges, staff vs players)
• Servers already running the open combo (SimpleItems, GUIPro, PvPMonster, etc.) that need a combat mode where movement is the weapon

---

Requirements

• Paper 1.21+ (or a close fork)
• Java 21
• No ModelEngine / MythicMobs dependency

---

Configuration (high level)

Area	Examples
Miss	strict radius, actionbar ticks, debug log on/off
Safe-stick	hotbar slot, debounce ms, pulse particles
Chests	steal messages, enable/disable style rules
HUD	show placed/safe counts, miss reason duration
Kits / arenas	kit items, arena world positions

All critical knobs are meant to be tunable without a rebuild. Doctor commands expose the live values so you are not guessing.

---

Commands (overview)

Exact permissions and syntax can evolve by version; typical surface includes:

• Start / accept / leave duel flows
• /pkbattle hp, phase, forfeit, rematch
• /pkbattle kit, arenas, spectators
• /pkbattle lastopp (peeks, clear, size/count, help)
• /pkbattle admin doctor, misslog, testmarks
• Safe-stick is an item interaction in battle (and admin test mode)

Tab-complete is provided for the main admin subcommands.

---

Fairness & safety notes

• Miss rules are enforced server-side; clients cannot “choose” to ignore them
• Safe marks are intentional exceptions — keep them staff-controlled on competitive servers
• Debug miss logging is optional; leave it off in production unless you are tuning rules
• Soft-fail paths avoid hard crashes if a player disconnects mid-battle (battle cleanup)

---

What ParkourBattle is not

• Not a full bedwars/skywars clone
• Not an AI bot arena (see PvPMonster for player-like bots)
• Not a general GUI library (see GUIPro)
• Not a custom item framework (see SimpleItems)

It does one job hard: make parkour into a duel sport.

---

Support

When reporting issues, include:

1. Paper version
2. ParkourBattle version
3. Output of doctor / doctor --brief
4. Whether the problem is miss detection, kits, arenas, or chest-steal

---

License / combo

Developed as part of an open Paper 1.21 toolkit alongside SimpleItems, GUIPro, PvPMonster, CommandPortal, and ParticleStudio. Each plugin can run standalone; together they form a fuller combat + content stack.

ParkourBattle

ParkourBattle превращает паркур в соревновательный режим дуэлей для Paper 1.21. Игроки сражаются не только оружием, но движением и постановкой блоков: каждый прыжок важен. Приземлился не туда — получил урон. Контролируй пространство блоками, ломай удобные линии противнику и наказывай за суету.

Это не очередной клон «хаба мини-игр». Это сфокусированный движок паркур-дуэлей со строгой логикой промахов, опциональным боем «на месте», китами, аренами, взаимодействием с сундуками и нормальным админ/debug-слоем.

---

Главная идея

Во время боя игрок ставит блоки и прыгает. Сервер помнит боевые блоки. Если ты приземлился на то, что не относится к бою (и не помечено как safe), это промах. Промах бьёт по HP — урон настраивается, есть actionbar и опциональный строгий радиус, чтобы «почти попал на блок» не прокатывало.

Одно это правило меняет темп: нельзя бесконечно спамить случайные блоки — каждая постановка что-то значит.

---

Возможности

Дуэли и процесс

• Вызов / принятие боя между игроками
• Фазы боя (подготовка → бой → завершение), их можно смотреть командами
• Forfeit и rematch (в том числе когда раунд уже закончился — по возможности версии)
• Leave / leave-all для админов, если матч завис
• Зрители и списки spectators
• Опциональный бой прямо на месте (без арены) с коротким радиусом приглашения — удобно для ивентов
• Команды HP и phase, чтобы быстро видеть состояние матча

Система промахов (ядро плагина)

• Приземление не на боевой блок = miss
• Настраиваемый строгий радиус вокруг блока
• Safe-stick: пометить блоки, которые никогда не считаются промахом (трень, ивент-трассы, админ-тесты)
• Debounce на стик, чтобы один клик не давал пачку переключений
• Actionbar: причина промаха, успешная метка (Adventure, с запасным legacy-путём)
• Опциональный debug-лог промахов (консоль + файл с ротацией)
• Админские test marks вне живого боя, частицы и телепорт к метке

Блоки, сундуки и модификаторы

• Постановка блоков как геометрия дуэли
• Прыжки сундук → сундук могут забирать инвентарь соперника (сообщения атакующему/жертве)
• Разная логика «стою на блоке сундука» / «прыгнул на сундук»
• Много модификаторов под ranked или casual-правила

Киты и арены

• Выдача кита из конфига / папки kits
• Список китов
• Арены: free / busy
• Инфо по арене для стаффа
• Размер очереди (где включено)

UX

• HUD в actionbar: поставленные блоки, safe-метки, причины miss
• Частицы на safe-метках (pulse)
• Понятные сообщения при chest-steal
• Команды статуса для зрителей и админов

Админка и целостность

• /pkbattle doctor и --brief (активные бои, размер last-opponent map, флаги конфига)
• Last opponent: peeks, clear, clearall, size/count, фильтр online
• Хвост/очистка miss-лога
• Версионируемые ключи конфига: debounce, радиус miss, HUD, поведение

---

Для кого

• Сервера survival / mini-games, где нужен skill-based PvP, а не только плоская арена
• Ивенты: паркур-турниры, челленджи, staff vs players
• Сборки с открытым комбайном (SimpleItems, GUIPro, PvPMonster и т.д.), где бой должен требовать движение как навык

---

Требования

• Paper 1.21+ (или близкий форк)
• Java 21
• Без зависимости от ModelEngine / MythicMobs

---

Конфиг (укрупнённо)

Зона	Примеры
Miss	строгий радиус, время actionbar, debug-лог
Safe-stick	слот хотбара, debounce, частицы
Сундуки	сообщения steal, вкл/выкл правил
HUD	счётчики placed/safe, длительность miss-reason
Киты / арены	предметы кита, точки арен

Важные параметры крутятся без пересборки. Doctor показывает живые значения.

---

Команды (обзор)

Точный синтаксис зависит от версии; обычно есть:

• Старт / accept / leave дуэли
• /pkbattle hp, phase, forfeit, rematch
• /pkbattle kit, arenas, spectators
• /pkbattle lastopp (peeks, clear, size/count, help)
• /pkbattle admin doctor, misslog, testmarks
• Safe-stick — предметом в бою (и в admin test)

Tab-complete на основных админ-подкомандах.

---

Честность

• Промахи считаются на сервере
• Safe-метки — явные исключения; на ranked лучше оставить стаффу
• Debug-лог miss в проде обычно выключают
• При дисконнекте бой корректно чистится (без «вечных» арен)

---

Чем ParkourBattle не является

• Не клон bedwars/skywars
• Не AI-арена с ботами (для ботов — PvPMonster)
• Не библиотека GUI (GUIPro)
• Не фреймворк кастом-предметов (SimpleItems)

Одна задача: сделать из паркура дуэльный спорт.

---

Поддержка

В баг-репорте укажите:

1. Версию Paper
2. Версию ParkourBattle
3. Вывод doctor / doctor --brief
4. Суть: miss, киты, арены или сундуки

---

Комбайн

Плагин из открытого набора для Paper 1.21 вместе с SimpleItems, GUIPro, PvPMonster, CommandPortal и ParticleStudio. Может жить отдельно; в связке даёт более полный боевой и контентный стек.