MiniGame

Framework de minijogos: 26 modos de jogo, arenas, menus de lobby, parkour, recordes e integração com missões.

Privadasv0.1.0Combate e mobs

RequerTypeWriter0.9.0-beta-177 (BTC build)GUIQuestRegionMiniPlaceholdersopcional

Criada para a rede BornToCraft. Esta extensão é documentada como referência e não é distribuída.

Suporte

Visão geral

O MiniGame é um único framework que executa vários tipos de minigames a partir de entries do TypeWriter. Você descreve uma arena no painel web: o modo de jogo, os spawns do lobby e do jogo, os limites de jogadores, times, kit, rodadas e mensagens. Os jogadores então entram por meio de entries de ação e menus. A extensão cuida do lobby, da verificação de prontos, da contagem regressiva, do jogo em si, do pódio e da limpeza.

Todo jogo passa pela mesma sequência de fases: Lobby, Countdown, Playing, Ending, Cleanup. Cada jogo em andamento tem um contexto que guarda seus jogadores, times, pontuações e estado, de modo que rodadas, times e scoreboards se comportam do mesmo jeito em todos os modos. Os inventários são salvos antes do jogo e restaurados depois. As alterações em jogadores usam agendamento seguro para regiões, então a extensão roda em Paper e Folia.

Os resultados são mantidos em artifacts (vitórias, pontuações, melhores tempos, rankings) e expostos ao restante do seu servidor por objetivos de quest, facts, triggers e placeholders. O parkour, que era uma extensão separada, agora é um dos modos de jogo. Esta extensão é documentada como referência e roda no build BTC do TypeWriter.

Recursos

• 26 modos de jogo — PvP, parkour e movimento, sobrevivência, estratégia, modos de festa e arcade, todos selecionados com o campo gameType de uma arena.
• Motor de fases — lobby, contagem regressiva, jogo, encerramento e limpeza, com verificação de prontos, mínimo de jogadores, entrada tardia e espectadores.
• Times — NONE, SOLO, RED_BLUE ou times personalizados com nomes próprios, escolhidos no menu do lobby ou balanceados automaticamente.
• Rodadas e power-ups — rodadas opcionais que reanimam os jogadores entre uma rodada e outra e drops de power-ups cronometrados para os modos baseados em regras.
• Parkour — pontos de início, checkpoints ordenados e pontos finais com partículas, ações de falha, timers e recordes pessoais e da arena.
• Arenas dedicadas — entries de configuração extras para parkour, Dé à Coudre e arco e flecha.
• Menus — navegador de jogos, seleção de arena, lobby, seleção de time, estatísticas e menus de resultados.
• Persistência — vitórias, derrotas, pontuações, melhores tempos e melhores tempos gerais armazenados em artifacts, salvos de forma assíncrona.
• Integração com quests — um objetivo e um fact de conclusão, além de triggers para início de jogo, fim, entrada, eliminação, início de rodada e recordes.
• Scoreboard e mensagens — linhas de scoreboard configuráveis e mensagens de entrada, saída, eliminação e vitória com placeholders do jogo.

Instalação

1. Execute o build BTC do TypeWriter (BTC Core, Paper ou Folia).
2. Instale as extensões das quais o MiniGame depende: a extensão GUI da BTC (todos os menus a usam), Quest e Region.
3. Coloque o JAR do MiniGame em plugins/Typewriter/extensions/ e reinicie o servidor.
4. Instale o MiniPlaceholders se quiser os placeholders <minigame_...> fora do scoreboard. Eles são publicados pela ponte MiniPlaceholders da BTC, não pelo PlaceholderAPI.
5. Construa as arenas no mundo, crie uma região de proteção onde uma entry pedir uma (por exemplo, a piscina de uma arena de Dé à Coudre) e então configure as entries no painel web.

Primeiros passos

Este passo a passo configura uma arena de Spleef com estatísticas persistentes.

1. No painel web do TypeWriter, abra uma page manifest e adicione um artifact Wins statistics. Dê a ele um artifactId, por exemplo spleef_wins.
2. Na mesma page, adicione uma entry Minigame Arena. Defina gameType como SPLEEF e depois lobbySpawn, gameSpawn, spectatorSpawn e endTeleport com o seletor de posição.
3. Defina minPlayers e maxPlayers, autoStartCountdown (segundos antes de o jogo começar) e maxGameDuration (segundos).
4. Ative useRounds e defina maxRounds se quiser várias rodadas (os jogadores são reanimados e recolocados em gameSpawn a cada rodada). Adicione itens a kitItems e mantenha giveKit ativado.
5. Ligue winStatArtifact ao artifact do passo 1.
6. Abra uma page sequence. Adicione uma ação Open the minigame browser e dispare-a a partir de um diálogo de NPC, um item ou um comando. Ou use Join a minigame com arena definido como a sua arena para colocar o jogador direto no lobby.
7. Publique, entre na arena, clique em Ready no menu do lobby e aguarde a contagem regressiva. Quando o jogo terminar, o vencedor é anunciado e as estatísticas são salvas.

Começando com um jogador

O lobby só inicia a contagem regressiva quando pelo menos minPlayers jogadores clicaram em Ready. Defina minPlayers como 1 enquanto você testa sozinho.

Como funciona

1. Lobby. Os jogadores esperam em lobbySpawn. A contagem regressiva começa quando o número de jogadores marcados como prontos atinge minPlayers, após alguns segundos. A entrada tardia só é possível depois do lobby quando allowLateJoin está ativado.
2. Countdown. Dura autoStartCountdown segundos, com mensagens no chat. Se os jogadores saírem e a contagem cair abaixo do mínimo, o jogo volta ao lobby.
3. Playing. Os jogadores são teletransportados para gameSpawn, seu inventário é salvo e o kit é entregue. A fase termina, no máximo, após maxGameDuration segundos. onGameStart dispara.
4. Ending. O vencedor e os três primeiros são anunciados. Esta fase dura cerca de um sexagésimo de maxGameDuration, limitada entre 5 e 60 segundos.
5. Cleanup. Inventários, modo de jogo e vida são restaurados, os resultados são gravados nos artifacts, onGameEnd dispara e os jogadores voltam para endTeleport.

Os jogadores eliminados tornam-se espectadores e são movidos para spectatorSpawn quando allowSpectate está ativado e um spawn de espectador está definido.

Modos de jogo

O campo gameType da arena aceita os 26 valores abaixo. Três modos têm código próprio. Os outros 23 são baseados em regras: compartilham um único motor guiado por um modo de eliminação e uma condição de vitória. Um modo baseado em regras fornece as regras, o lobby, as rodadas e a pontuação. O conteúdo específico do nome do jogo (uma bandeira, ondas de mobs, um piso de lava que sobe, blocos de TNT, dispensers) não é gerado: você o constrói no mundo e o conecta com kits, regiões e triggers.

Modo	Categoria	Jogadores padrão	Eliminação	Condição de vitória
Sumo	PvP / Combate	2-8	Queda	Último vivo
Gladiator	PvP / Combate	2-12	Morte	Último vivo, power-ups a cada 20 s
Duels	PvP / Combate	2	Morte	Último vivo
KOTH	PvP / Combate	2-16	Timeout	Primeiro a pontuar, power-ups
Paintball	PvP / Combate	2-16	Morte	Maior pontuação
One in the Chamber	PvP / Combate	2-12	Morte	Maior pontuação
Parkour	Parkour / Movimento	1	Código dedicado	Chegar ao ponto final
Block Party	Parkour / Movimento	2-16	Piso sumiu	Último vivo, até 5 rodadas
TNT Run	Parkour / Movimento	2-16	Queda	Último vivo
Floor is Lava	Parkour / Movimento	2-16	Queda	Último vivo, até 3 rodadas
Falling Blocks	PvE / Sobrevivência	1-16	Queda	Sobreviver 120 s
Wave Survival	PvE / Sobrevivência	1-8	Morte	Sobreviver 180 s, power-ups
Zombie Apocalypse	PvE / Sobrevivência	1-8	Morte	Sobreviver 300 s, power-ups
Dodge the Arrows	PvE / Sobrevivência	1-16	Morte	Último vivo
Defend the Core	PvE / Sobrevivência	1-8	Morte	Último time vivo, 240 s
Capture the Flag	Estratégia	4-16	Morte	Primeiro a pontuar, 300 s
Infection	Estratégia	2-16	Marcado	Último vivo
Spleef	Estratégia	2-16	Piso sumiu	Último vivo, até 5 rodadas
Sheep Hunt	Estratégia	4-16	Marcado	Mais marcações, 180 s
TPP (Tag)	Festa / Diversão	2-16	Marcado	Último vivo
Freeze Tag	Festa / Diversão	2-16	Marcado	Último vivo
Hot Potato	Festa / Diversão	2-16	Timeout	Último vivo, 60 s
Dé à Coudre	Festa / Diversão	2-16	Código dedicado	Último jogador ou time vivo
Musical Chairs	Festa / Diversão	2-16	Timeout	Último vivo, até 10 rodadas
Archery	Reflexo / Arcade	1-16	Código dedicado	Primeiro a atingir o número de alvos, ou melhor pontuação dentro do limite de tempo
Quake	Reflexo / Arcade	2-16	Morte	Maior pontuação

O mínimo padrão só é usado quando o minPlayers da arena não é maior que zero. O máximo sempre vem do maxPlayers da arena.

Como os modos baseados em regras decidem

• Morte (Killed): um único golpe de outro jogador elimina a vítima, seja qual for o dano, e dá um ponto ao atacante. Atiradores de projéteis contam.
• Marcado (Tagged): um único golpe de outro jogador elimina a vítima e dá um ponto a quem marcou. Os companheiros de time são protegidos quando o fogo amigo está desativado.
• Queda (Falling): um jogador é eliminado quando está dez blocos abaixo de gameSpawn.
• Piso sumiu (Floor gone): um jogador é eliminado quando o bloco abaixo dele é ar.
• Timeout: nenhum timer elimina um jogador por si só. As rodadas com duração simplesmente terminam quando o tempo acaba, e as pontuações ou os sobreviventes decidem o vencedor.
• Power-ups: quando powerUpEnabled está ativado, um item de power-up aleatório cai a cada powerUpInterval segundos (no mínimo 5). Os oito tipos são Speed, Jump, Invisibility, Heal, Shield, Explosive Snowball, Double Jump e Super Strength.
• Rodadas: com useRounds ativado, os jogadores eliminados são reanimados e todos são recolocados em gameSpawn a cada rodada, até maxRounds. A extensão não reconstrói blocos entre as rodadas: restaure você mesmo um piso quebrado. onRoundStart dispara a cada rodada.

Parkour

O parkour é um modo solo com sua própria entry de configuração. Um Parkour Arena liga-se a uma Minigame Arena do tipo PARKOUR e lista seus pontos de início, checkpoints e pontos finais. O jogador inicia a corrida ficando em um ponto de início, deve passar pelos checkpoints em order crescente e então chega a um ponto final.

• failAction decide o que uma falha faz: START teletransporta de volta ao início, LAST_CHECKPOINT ao último checkpoint, QUIT abandona a corrida.
• timerType é NONE, GLOBAL (um time fixo em segundos) ou CHECKPOINT (time mais checkpointBonus segundos a cada checkpoint). Ficar sem tempo é uma falha.
• Uma corrida também falha quando o jogador troca de mundo, cai mais de 5 blocos abaixo do início ou fica a mais de 10 blocos do último checkpoint.
• Ao concluir, o tempo é enviado para os recordes: melhor pessoal, ranking da arena e os triggers onPersonalBest e onWorldRecord da arena. A arena então termina porque não resta ninguém correndo.

Dé à Coudre

Um Dé à Coudre Arena adiciona uma região de piscina, uma localização de salto e um spawn. mode é SINGLE (os jogadores saltam por turno), CONCURRENT (todos saltam ao mesmo tempo) ou TEAM. Os jogadores começam sem vida extra: um salto errado elimina o jogador, e um salto perfeito (pousar entre quatro blocos já usados) rende uma vida. Os placeholders lives, turn e queue mostram o estado.

Archery

Um Archery Arena lista posições de alvos e zonas de tiro. mode é MAX_TARGET (o primeiro a targetsToWin acertos) ou TIME_ATTACK (melhor pontuação dentro de timeLimitSeconds). A extensão coloca o targetBlock, o substitui por hitBlock quando atingido e entrega o bowItem e o arrowItem.

Menus

Os menus são menus de baú de 54 slots renderizados pela extensão GUI. Eles ficam vazios até que você adicione uma entry de ação que os abra.

Menu	Aberto por	Conteúdo
Navegador de jogos	Open the minigame browser	Uma linha com as seis categorias e depois os jogos da categoria selecionada. Um jogo só fica disponível quando existe uma arena desse tipo.
Seleção de arena	Open arena selection ou um clique no navegador	As arenas de um tipo de jogo com seu status (livre, aguardando, cheia, em jogo) e contagem de jogadores. Clicar entra.
Lobby	Open the lobby menu, ou automaticamente após entrar pelos menus	A descrição da arena, a lista de jogadores com estado de pronto e time, os botões Ready, Team, Start the game e Leave, além dos seus botões personalizados.
Seleção de time	O botão Team	Escolha um time ou seja atribuído a um aleatoriamente.
Estatísticas	Open statistics	Vitórias, derrotas, partidas jogadas e um top 10, por arena ou entre arenas. Exige winStatArtifact nas arenas.
Resultados	Open the results screen	Vencedor, duração, número de jogadores e pódio. Ligue a ação ao trigger onGameEnd da arena.

O botão Start the game só é exibido para jogadores com a permissão minigame.start. Uma entry Lobby Menu personaliza o título, oculta partes do menu e adiciona botões com um slot de 0 a 53 e uma showCondition.

Persistência e recordes

Os artifacts são carregados na inicialização e gravados de forma assíncrona, então salvar nunca bloqueia um tick de jogo. Os dados armazenados são mantidos por arena e por jogador.

• Wins statistics armazena vitórias, derrotas e partidas jogadas, salvas na limpeza para cada jogador do jogo.
• Scores statistics soma a pontuação de cada jogador na limpeza quando ela é maior que zero.
• Minigame state é gravado na limpeza com a fase final, o número de jogadores e o vencedor.
• Best time e Top times armazenam melhores marcas pessoais e o ranking; topTimesLimit define quantos tempos são mantidos. Hoje apenas o parkour produz tempos.

Reset records limpa os recordes de uma arena para o jogador que disparou (PLAYER) ou para todos (ARENA).

Integração com quests

O objetivo Complete minigames conta corridas cronometradas concluídas. Deixe arena vazio para contar todas as arenas, ou defina-o para contar uma. Ele guarda seu progresso em um fact que você fornece e pode disparar onComplete. O fact Minigame completions conta as conclusões separadamente para cada arena em que o jogador está, então um único fact pode servir a toda uma rede de arenas. Ambos reagem atualmente apenas a conclusões de parkour.

Permissões

Permissão	Concede
minigame.start	Exibe e permite o botão Start the game no menu do lobby.

Não há comandos: tudo é conduzido por entries e menus.

Placeholders

Os placeholders do jogo estão disponíveis de duas formas. Nas mensagens e nas linhas de scoreboard de uma arena, você pode usar tokens %name%. Em outros lugares do servidor, a ponte MiniPlaceholders da BTC publica os mesmos valores como <minigame_name> para um jogador que está em um jogo.

Placeholder	Retorna
arena e arena_id	O nome da arena e o entry id.
game_id	O id do jogo em andamento.
phase	O nome da fase atual.
players e alive	Jogadores no jogo e jogadores ainda vivos.
max_players	O limite de jogadores da arena.
winner	O nome do vencedor, ou "Personne" enquanto não houver um.
score	A pontuação do jogador.
alive_status	alive ou eliminated.
rank	A posição do jogador por pontuação, ou -.
lives, turn e queue	Vidas, saltador atual e ordem de salto, apenas para Dé à Coudre. - nos outros modos.
%player% (apenas em mensagens)	O nome do jogador, nas mensagens de entrada, saída e eliminação.

Entries

24 entradas, geradas a partir do código-fonte da extensão.

Ações9

• 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

Objetivos1

• Minigame Completion ObjectiveTerminer des mini-jeux

Fatos1

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

Artefatos5

• 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

Manifestos5

• 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

Definições3

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

Solução de problemas

Os menus não fazem nada ou estão vazios. Os menus precisam da extensão GUI e de uma entry de ação para abri-los. Verifique se existe uma arena do gameType correto: o navegador marca um tipo de jogo como indisponível quando nenhuma arena o usa.

O jogo fica no lobby para sempre. A contagem regressiva só inicia quando pelo menos minPlayers jogadores clicaram em Ready, não simplesmente quando estão presentes. Reduza minPlayers ou use Force start a minigame para iniciar a contagem.

"Vous êtes déjà dans une partie". Um jogador só pode estar em um jogo. Use primeiro Leave a minigame. Sair, desconectar e terminar um jogo liberam o jogador.

Ninguém nunca é eliminado nos modos KILL ou TAG. Teste no modo sobrevivência com um jogador que possa sofrer dano: no modo criativo, os jogadores são invulneráveis. As eliminações nesses modos vêm de dano causado por outro jogador, incluindo flechas e bolas de neve.

As estatísticas, as mortes ou o artifact de estado continuam vazios. Uma arena só grava nos artifacts que ela referencia: defina winStatArtifact, scoreArtifact e stateArtifact e dê a cada artifact um artifactId. Mortes e baixas não são registradas pelo código atual e mostram 0. Melhores tempos e tempos gerais só são gravados pelo parkour.

Uma corrida de parkour continua falhando. Cada checkpoint deve estar a até 10 blocos do anterior, e a corrida falha 5 blocos abaixo do ponto de início. Os checkpoints devem ser alcançados em order crescente, e o ponto final só conta depois do último checkpoint. Com radius em 0, o jogador deve ficar exatamente no bloco.

Um jogador não consegue sair da área do lobby. Enquanto espera (fases Lobby e Countdown), lobbyRadius (padrão 10 blocos ao redor de lobbySpawn) impede que os jogadores se afastem; ele não teletransporta, e um jogador que já está fora pode sempre voltar. Defina 0 para não limitar.

Um jogador é eliminado sem motivo aparente. region é a zona de jogo dos modos baseados em regras: sair dela durante uma partida elimina o jogador (a região não é aplicada em Archery, Parkour e Dé à Coudre, que têm fases próprias). Nos modos em que o chão desaparece (Spleef, Block Party), floorMaterial lista os nomes de material do Bukkit que contam como chão, separados por vírgulas: um jogador é eliminado assim que o bloco sob seus pés não é um deles. Vazio significa que qualquer bloco que não seja ar é chão, e nomes desconhecidos são ignorados com um aviso no console. Os chãos não são gerados a partir de floorMaterial; você os constrói.

A mensagem de vitória não é a esperada. winMessage é anunciada no fim da partida, com %winner% substituído pelo vencedor.

Um jogador não consegue entrar na arena. Quando todos os lobbies abertos de uma arena têm maxPlayers jogadores, a arena está cheia e a entrada é recusada: nenhuma segunda partida é aberta em paralelo. A ação Join a minigame envia então a sua fullMessage.

Extensões relacionadas