MiniGame

Фреймворк мини-игр: 26 режимов, арены, меню лобби, паркур, рекорды и интеграция с квестами.

Приватныеv0.1.0Бои и мобы

ТребуетсяTypeWriter0.9.0-beta-177 (BTC build)GUIQuestRegionMiniPlaceholdersнеобязательно

Создано для сети BornToCraft. Это расширение описано для справки и не распространяется.

Поддержка

Обзор

MiniGame — это единый фреймворк, который запускает множество видов мини-игр из записей TypeWriter. Вы описываете арену в веб-панели: игровой режим, точки появления в лобби и в игре, ограничения по числу игроков, команды, набор (kit), раунды и сообщения. Затем игроки присоединяются через записи-действия и меню. Расширение берёт на себя лобби, проверку готовности, обратный отсчёт, саму игру, пьедестал и очистку.

Каждая игра проходит одну и ту же последовательность фаз: Lobby, Countdown, Playing, Ending, Cleanup (лобби, обратный отсчёт, игра, завершение, очистка). У каждой запущенной игры есть один контекст, в котором хранятся её игроки, команды, счёт и состояние, поэтому раунды, команды и скорборды ведут себя одинаково в каждом режиме. Инвентари сохраняются перед игрой и восстанавливаются после неё. Изменения игроков используют планирование, безопасное для регионов, поэтому расширение работает на Paper и Folia.

Результаты хранятся в артефактах (победы, счёт, лучшее время, рейтинги) и доступны остальной части вашего сервера через цели квестов, факты, триггеры и плейсхолдеры. Паркур, который раньше был отдельным расширением, теперь является одним из игровых режимов. Это расширение описано для ознакомления и работает на сборке BTC для TypeWriter.

Возможности

• 26 игровых режимов — PvP, паркур и перемещение, выживание, стратегия, вечеринки и аркады, все выбираются полем gameType арены.
• Движок фаз — лобби, обратный отсчёт, игра, завершение и очистка, с проверкой готовности, минимумом игроков, поздним присоединением и зрителями.
• Команды — NONE, SOLO, RED_BLUE или пользовательские команды с вашими названиями, выбираются из меню лобби или балансируются автоматически.
• Раунды и усиления — необязательные раунды, возрождающие игроков между раундами, и выпадение усилений по таймеру для режимов на основе правил.
• Паркур — точки старта, упорядоченные контрольные точки и точки финиша с частицами, действиями при провале, таймерами и личными рекордами и рекордами арены.
• Специализированные арены — дополнительные записи конфигурации для паркура, Dé à Coudre и стрельбы из лука.
• Меню — браузер игр, выбор арены, лобби, выбор команды, статистика и результаты.
• Сохранение данных — победы, поражения, счёт, лучшее время и лучшие времена хранятся в артефактах и сохраняются асинхронно.
• Интеграция с квестами — цель и факт завершения, а также триггеры начала игры, конца, присоединения, выбывания, начала раунда и рекордов.
• Скорборд и сообщения — настраиваемые строки скорборда и сообщения о присоединении, выходе, выбывании и победе с игровыми плейсхолдерами.

Установка

1. Запустите сборку BTC для TypeWriter (BTC Core, Paper или Folia).
2. Установите расширения, от которых зависит MiniGame: расширение BTC GUI (его используют все меню), Quest и Region.
3. Поместите JAR-файл MiniGame в plugins/Typewriter/extensions/ и перезапустите сервер.
4. Установите MiniPlaceholders, если хотите использовать плейсхолдеры <minigame_...> вне скорборда. Они публикуются через мост BTC MiniPlaceholders, а не PlaceholderAPI.
5. Постройте арены в мире, создайте регион защиты там, где запись его требует (например, бассейн арены Dé à Coudre), затем настройте записи в веб-панели.

Начало работы

В этом пошаговом примере настраивается арена Spleef с постоянной статистикой.

1. В веб-панели TypeWriter откройте страницу manifest и добавьте артефакт Wins statistics. Задайте ему artifactId, например spleef_wins.
2. На той же странице добавьте запись Minigame Arena. Задайте gameType равным SPLEEF, затем lobbySpawn, gameSpawn, spectatorSpawn и endTeleport с помощью выбора позиции.
3. Задайте minPlayers и maxPlayers, autoStartCountdown (секунды до начала игры) и maxGameDuration (секунды).
4. Включите useRounds и задайте maxRounds, если хотите несколько раундов (игроки возрождаются и возвращаются в gameSpawn в каждом раунде). Добавьте предметы в kitItems и оставьте giveKit включённым.
5. Свяжите winStatArtifact с артефактом из шага 1.
6. Откройте страницу sequence. Добавьте действие Open the minigame browser и запускайте его из диалога NPC, предметом или командой. Либо используйте Join a minigame с arena, равным вашей арене, чтобы сразу отправить игрока в лобби.
7. Опубликуйте (Publish), присоединитесь к арене, нажмите Ready в меню лобби и дождитесь обратного отсчёта. Когда игра закончится, будет объявлен победитель и сохранена статистика.

Запуск с одним игроком

Обратный отсчёт в лобби идёт только тогда, когда как минимум minPlayers игроков нажали Ready. Задайте minPlayers равным 1, пока тестируете в одиночку.

Как это работает

1. Lobby. Игроки ждут в lobbySpawn. Обратный отсчёт начинается, когда число игроков, отметивших готовность, достигает minPlayers, через несколько секунд. Позднее присоединение возможно только после лобби и при включённом allowLateJoin.
2. Countdown. Длится autoStartCountdown секунд с сообщениями в чате. Если игроки уходят и их число падает ниже минимума, игра возвращается в лобби.
3. Playing. Игроки телепортируются в gameSpawn, их инвентарь сохраняется, и выдаётся набор. Фаза заканчивается не позднее чем через maxGameDuration секунд. Срабатывает onGameStart.
4. Ending. Объявляются победитель и тройка лучших. Эта фаза длится около одной шестидесятой от maxGameDuration, с ограничением от 5 до 60 секунд.
5. Cleanup. Инвентари, игровой режим и здоровье восстанавливаются, результаты записываются в артефакты, срабатывает onGameEnd, и игроки возвращаются в endTeleport.

Выбывшие игроки становятся зрителями и перемещаются в spectatorSpawn, когда включён allowSpectate и задана точка появления зрителей.

Игровые режимы

Поле gameType арены принимает 26 значений ниже. У трёх режимов собственный код. Остальные 23 — режимы на основе правил: они используют один движок, управляемый режимом выбывания и условием победы. Режим на основе правил даёт вам правила, лобби, раунды и подсчёт очков. Содержимое, специфичное для названия игры (флаг, волны мобов, поднимающаяся лава, блоки TNT, раздатчики), не генерируется: вы строите его в мире и связываете с наборами, регионами и триггерами.

Режим	Категория	Игроки по умолчанию	Выбывание	Условие победы
Sumo	PvP / Бой	2-8	Падение	Последний выживший
Gladiator	PvP / Бой	2-12	Убит	Последний выживший, усиления каждые 20 с
Duels	PvP / Бой	2	Убит	Последний выживший
KOTH	PvP / Бой	2-16	Тайм-аут	Первый, набравший очки, усиления
Paintball	PvP / Бой	2-16	Убит	Больше всего очков
One in the Chamber	PvP / Бой	2-12	Убит	Больше всего очков
Parkour	Паркур / Перемещение	1	Специализированный код	Дойти до точки финиша
Block Party	Паркур / Перемещение	2-16	Пол исчез	Последний выживший, до 5 раундов
TNT Run	Паркур / Перемещение	2-16	Падение	Последний выживший
Floor is Lava	Паркур / Перемещение	2-16	Падение	Последний выживший, до 3 раундов
Falling Blocks	PvE / Выживание	1-16	Падение	Продержаться 120 с
Wave Survival	PvE / Выживание	1-8	Убит	Продержаться 180 с, усиления
Zombie Apocalypse	PvE / Выживание	1-8	Убит	Продержаться 300 с, усиления
Dodge the Arrows	PvE / Выживание	1-16	Убит	Последний выживший
Defend the Core	PvE / Выживание	1-8	Убит	Последняя выжившая команда, 240 с
Capture the Flag	Стратегия	4-16	Убит	Первый, набравший очки, 300 с
Infection	Стратегия	2-16	Осален	Последний выживший
Spleef	Стратегия	2-16	Пол исчез	Последний выживший, до 5 раундов
Sheep Hunt	Стратегия	4-16	Осален	Больше всего осаливаний, 180 с
TPP (Tag)	Вечеринка / Веселье	2-16	Осален	Последний выживший
Freeze Tag	Вечеринка / Веселье	2-16	Осален	Последний выживший
Hot Potato	Вечеринка / Веселье	2-16	Тайм-аут	Последний выживший, 60 с
Dé à Coudre	Вечеринка / Веселье	2-16	Специализированный код	Последний игрок или команда
Musical Chairs	Вечеринка / Веселье	2-16	Тайм-аут	Последний выживший, до 10 раундов
Archery	Рефлексы / Аркада	1-16	Специализированный код	Первый, набравший целевое число, или лучший счёт за отведённое время
Quake	Рефлексы / Аркада	2-16	Убит	Больше всего очков

Минимум по умолчанию используется, только если minPlayers арены не больше нуля. Максимум всегда берётся из maxPlayers арены.

Как принимают решения режимы на основе правил

• Убит (Killed): один удар другого игрока выбивает жертву, независимо от урона, и приносит атакующему одно очко. Стрелки засчитываются.
• Осален (Tagged): один удар другого игрока выбивает жертву и приносит осалившему одно очко. Товарищи по команде защищены, когда дружественный огонь выключен.
• Падение (Falling): игрок выбывает ниже десяти блоков под gameSpawn.
• Пол исчез (Floor gone): игрок выбывает, когда блок под ним становится воздухом.
• Тайм-аут (Timeout): ни один таймер сам по себе не выбивает игрока. Раунды с длительностью просто заканчиваются, когда время вышло, а победителя определяют счёт или выжившие.
• Усиления: когда включён powerUpEnabled, случайный предмет-усиление выпадает каждые powerUpInterval секунд (не менее 5). Восемь типов: Speed, Jump, Invisibility, Heal, Shield, Explosive Snowball, Double Jump и Super Strength.
• Раунды: при включённом useRounds выбывшие игроки возрождаются, а все возвращаются в gameSpawn на каждый раунд, вплоть до maxRounds. Расширение не восстанавливает блоки между раундами: восстанавливайте разрушенный пол сами. onRoundStart срабатывает в каждом раунде.

Паркур

Паркур — это одиночный режим с собственной записью конфигурации. Parkour Arena связывается с Minigame Arena типа PARKOUR и перечисляет свои точки старта, контрольные точки и точки финиша. Игрок начинает забег, встав на точку старта, должен пройти контрольные точки в порядке возрастания order, а затем дойти до точки финиша.

• failAction определяет, что делает провал: START телепортирует обратно на старт, LAST_CHECKPOINT — к последней контрольной точке, QUIT — прекращает забег.
• timerType — это NONE, GLOBAL (фиксированное time в секундах) или CHECKPOINT (time плюс checkpointBonus секунд на каждой контрольной точке). Истечение времени считается провалом.
• Забег также проваливается, когда игрок меняет мир, падает более чем на 5 блоков ниже старта или находится дальше 10 блоков от последней контрольной точки.
• По завершении время передаётся в рекорды: личный рекорд, рейтинг арены и триггеры onPersonalBest и onWorldRecord на арене. Затем арена заканчивается, потому что никого не осталось на трассе.

Dé à Coudre

Dé à Coudre Arena добавляет регион бассейна, место прыжка и точку появления. mode — это SINGLE (игроки прыгают по очереди), CONCURRENT (все прыгают одновременно) или TEAM. Игроки начинают без запасной жизни: неудачный прыжок выбивает игрока, а идеальный прыжок (приземление между четырьмя уже использованными блоками) приносит одну жизнь. Плейсхолдеры lives, turn и queue показывают состояние.

Archery

Archery Arena перечисляет позиции мишеней и зоны стрельбы. mode — это MAX_TARGET (первый, кто сделает targetsToWin попаданий) или TIME_ATTACK (лучший счёт за timeLimitSeconds). Расширение ставит targetBlock, заменяет его на hitBlock при попадании и выдаёт bowItem и arrowItem.

Меню

Меню — это сундучные меню на 54 слота, отрисовываемые расширением GUI. Они остаются пустыми, пока вы не добавите запись-действие, которая их открывает.

Меню	Чем открывается	Содержимое
Браузер игр	Open the minigame browser	Ряд из шести категорий, затем игры выбранной категории. Игра доступна, только если существует арена этого типа.
Выбор арены	Open arena selection или клик в браузере	Арены одного типа игры с их статусом (свободна, ожидание, полна, идёт игра) и числом игроков. Клик присоединяет.
Лобби	Open the lobby menu или автоматически после присоединения из меню	Описание арены, список игроков с состоянием готовности и командой, кнопки Ready, Team, Start the game и Leave, а также ваши пользовательские кнопки.
Выбор команды	Кнопка Team	Выберите команду или получите случайную.
Статистика	Open statistics	Победы, поражения, сыгранные игры и топ-10, по арене или по всем аренам. Требует winStatArtifact на аренах.
Результаты	Open the results screen	Победитель, длительность, число игроков и пьедестал. Привяжите действие к триггеру onGameEnd арены.

Кнопка Start the game показывается только игрокам с правом minigame.start. Запись Lobby Menu настраивает заголовок, скрывает части меню и добавляет кнопки со slot от 0 до 53 и showCondition.

Сохранение данных и рекорды

Артефакты загружаются при запуске и записываются асинхронно, поэтому сохранение никогда не блокирует тик игры. Сохранённые данные хранятся для каждой арены и каждого игрока.

• Wins statistics хранит победы, поражения и сыгранные игры, сохраняется при очистке для каждого игрока игры.
• Scores statistics добавляет счёт каждого игрока при очистке, когда он больше нуля.
• Minigame state записывается при очистке с финальной фазой, числом игроков и победителем.
• Best time и Top times хранят личные рекорды и рейтинг; topTimesLimit задаёт, сколько времён сохраняется. Сегодня времена производит только паркур.

Reset records очищает рекорды арены для игрока, запустившего действие (PLAYER), или для всех (ARENA).

Интеграция с квестами

Цель Complete minigames считает завершённые забеги на время. Оставьте arena пустым, чтобы считать все арены, или задайте его, чтобы считать одну. Она хранит свой прогресс в предоставленном вами факте и может запускать onComplete. Факт Minigame completions считает завершения отдельно для каждой арены, в которой находится игрок, поэтому один факт может обслуживать целую сеть арен. Сейчас оба реагируют только на завершения паркура.

Права

Право	Что даёт
minigame.start	Показывает и разрешает кнопку Start the game в меню лобби.

Команд нет: всё управляется записями и меню.

Плейсхолдеры

Игровые плейсхолдеры доступны в двух формах. В сообщениях и строках скорборда арены можно использовать токены %name%. В остальных местах сервера мост BTC MiniPlaceholders публикует те же значения как <minigame_name> для игрока, находящегося в игре.

Плейсхолдер	Возвращает
arena и arena_id	Название арены и идентификатор записи.
game_id	Идентификатор запущенной игры.
phase	Название текущей фазы.
players и alive	Игроки в игре и игроки, всё ещё живые.
max_players	Ограничение числа игроков арены.
winner	Имя победителя или «Personne», пока его нет.
score	Счёт игрока.
alive_status	alive или eliminated.
rank	Место игрока по счёту или -.
lives, turn и queue	Жизни, текущий прыгун и порядок прыжков, только для Dé à Coudre. - в других режимах.
%player% (только в сообщениях)	Имя игрока в сообщениях о присоединении, выходе и выбывании.

Записи

Записей: 24, сгенерированы из исходного кода расширения.

Действия9

• Minigame ForcestartForcer le démarrage d'un mini-jeu
• Minigame JoinRejoindre un mini-jeu
• Minigame LeaveQuitter un mini-jeu
• Minigame Open ArenasOuvrir la sélection d'arène
• Minigame Open BrowserOuvrir le navigateur de mini-jeux
• Minigame Open LobbyOuvrir le menu du lobby
• Minigame Open ResultsOuvrir les résultats de la partie
• Minigame Open StatsOuvrir les statistiques de mini-jeux
• Minigame Reset RecordsRéinitialiser les records d'une arène

Цели1

• Minigame Completion ObjectiveTerminer des mini-jeux

Факты1

• Minigame Completion FactCompte les complétions d'un joueur, par arène

Артефакты5

• Minigame Best Time ArtifactStocke le meilleur temps personnel de chaque joueur par arène
• Minigame ScoresStatistiques de scores
• Minigame StateÉtat d'un mini-jeu
• Minigame Top Times ArtifactStocke le classement des meilleurs temps d'une arène
• Minigame WinsStatistiques de victoires

Манифесты5

• Archery ArenaArène de tir à l'arc
• Deacoudre ArenaDé à Coudre Arena
• Minigame ArenaArène de mini-jeu
• Minigame Lobby MenuMenu du lobby
• Parkour ArenaArène de Parkour

Определения3

• Parkour CheckpointCheckpoint du parkour
• Parkour End PointPoint d'arrivée du parkour
• Parkour Start PointPoint de départ du parkour

Устранение неполадок

Меню ничего не делают или пусты. Меню нужны расширение GUI и запись-действие, которая их открывает. Проверьте, что существует арена с нужным gameType: браузер помечает тип игры как недоступный, если ни одна арена его не использует.

Игра навсегда остаётся в лобби. Обратный отсчёт начинается только когда как минимум minPlayers игроков нажали Ready, а не просто когда они присутствуют. Уменьшите minPlayers или используйте Force start a minigame, чтобы запустить обратный отсчёт.

«Vous êtes déjà dans une partie». Игрок может участвовать только в одной игре. Сначала используйте Leave a minigame. Выход, отключение и завершение игры освобождают игрока.

В режимах KILL или TAG никто никогда не выбывает. Тестируйте в режиме выживания с игроком, который может получать урон: в творческом режиме игроки неуязвимы. Выбывание в этих режимах происходит от урона другого игрока, включая стрелы и снежки.

Статистика, убийства или артефакт состояния остаются пустыми. Арена пишет только в те артефакты, на которые ссылается: задайте winStatArtifact, scoreArtifact и stateArtifact и дайте каждому артефакту artifactId. Убийства и смерти текущим кодом не записываются и показывают 0. Лучшие времена и топ времён пишет только паркур.

Забег паркура постоянно проваливается. Каждая контрольная точка должна находиться в пределах 10 блоков от предыдущей, а забег проваливается на 5 блоков ниже точки старта. Контрольные точки нужно проходить в порядке возрастания order, а точка финиша засчитывается только после последней контрольной точки. При radius, равном 0, игрок должен стоять на точном блоке.

Игрок не может выйти за пределы лобби. Пока игроки ждут (фазы Lobby и Countdown), lobbyRadius (по умолчанию 10 блоков вокруг lobbySpawn) не даёт им отойти; он не телепортирует, а игрок, уже оказавшийся снаружи, всегда может вернуться. Укажите 0, чтобы снять ограничение.

Игрок выбывает без видимой причины. region — игровая зона режимов на основе правил: выход из неё во время игры исключает игрока (регион не применяется в Archery, Parkour и Dé à Coudre, у которых свои фазы). В режимах, где исчезает пол (Spleef, Block Party), floorMaterial перечисляет через запятую названия материалов Bukkit, считающихся полом: игрок исключается, как только блок под его ногами не входит в этот список. Пустое значение означает, что любой блок, кроме воздуха, — это пол; неизвестные названия игнорируются с предупреждением в консоли. Полы не генерируются из floorMaterial; вы строите их сами.

Сообщение о победе не такое, как ожидалось. winMessage объявляется в конце игры, %winner% заменяется победителем.

Игрок не может войти на арену. Когда в каждом открытом лобби арены находится maxPlayers игроков, арена заполнена, и вход отклоняется: вторая игра параллельно не открывается. Действие Join a minigame тогда отправляет свой fullMessage.

Связанные расширения