BattlePass
Visão geral
O BattlePass adiciona uma trilha de progressão sazonal ao seu servidor. Uma temporada tem uma data de início e uma de fim e é dividida em semanas; cada semana libera uma lista de quests. Quando um jogador conclui uma dessas quests, ele ganha XP, e os limites de XP se transformam em níveis. As recompensas são agrupadas em tiers (por exemplo, um tier gratuito e um tier premium protegido por uma permissão) e são resgatadas em um menu.
Tudo é configurado a partir de uma única entry Battle Pass Definition no painel web: tiers, recompensas, semanas, limites de XP, cronograma, layout do menu e itens dos botões. Uma recompensa é apenas uma lista de triggers do TypeWriter, então pode dar itens, executar comandos, conceder um cosmético ou qualquer outra coisa que uma action possa fazer. As quests vêm da extensão Quest do TypeWriter.
A extensão roda na build BTC do TypeWriter (BTC Core, Paper/Folia) e é documentada aqui como referência. O progresso é salvo por meio de um artifact Battle Pass Data, mantido em um cache de memória para que menus e placeholders nunca esperem pelo armazenamento.
Recursos
- Temporadas — datas opcionais de início e fim, uma duração de semana em dias e um fuso horário IANA (UTC por padrão).
- Quests semanais — as semanas são liberadas automaticamente ou em uma data escolhida, e cada quest dá uma quantidade fixa de XP ao ser concluída.
- XP e níveis — uma lista de limites de XP define os níveis, com um teto de XP opcional.
- Recompensas em tiers — cada tier tem uma prioridade, uma permissão opcional e recompensas vinculadas a um nível exigido.
- Resgate seguro — um resgate é reservado antes de os triggers serem executados, então uma recompensa não pode ser entregue duas vezes.
- Menus configuráveis — slots, tamanhos e o item, nome e lore de cada botão, ou um layout totalmente personalizado construído sobre a extensão GUI.
- Comandos de admin — some, remova ou defina XP e níveis para você ou outros jogadores e leia o progresso de um jogador.
- Placeholders — nível, XP, contadores de recompensas e informações das semanas para scoreboards e menus.
- Mensagens editáveis — toda mensagem de chat pode ser alterada em uma entry BattlePass Messages.
- Pronto para rede — o progresso é armazenado por meio da extensão MySQL, com invalidação de cache via Redis quando disponível.
Instalação
- Instale a extensão Quest do TypeWriter, a extensão GUI (
GuiAndDialogsna build BTC) e a extensão MySQL. O TypeWriter não carrega o BattlePass sem elas. - Coloque o JAR do BattlePass em
plugins/Typewriter/extensions/e reinicie o servidor. - Crie as quests que deseja usar com a extensão Quest.
- Se quiser um tier premium, crie a permissão com o seu plugin de permissões (o nome é livre, você o digita no tier).
Primeiros passos
Crie uma temporada de quatro semanas com uma recompensa gratuita no nível 1:
- No painel web do TypeWriter, abra uma página de manifest e adicione um artifact Battle Pass Data. Deixe
artifactIdcomo gerado e mantenhastorage.modeemPLAYER. - Adicione uma entry Battle Pass Definition na mesma página. Dê a ela um
name, definadatacom o artifact e escolha umiconcomominecraft:book. - Em
xp, preenchalevelscom limites de XP crescentes (por exemplo100,250,500) e, opcionalmente,max. - Em
weeks, adicione uma semana comnumber1, umtitlee, emquests, escolha uma entry de Quest e dê a ela umxpReward. Repita para as semanas seguintes. - Em
schedule, definastart(por exemplo2026-11-01T00:00:00),weekDurationDaysetimezone(por exemploEurope/Paris). As semanas são então liberadas uma após a outra. - Em
tiers, adicione um tier comlevel1e, emrewards, adicione uma recompensa comlevelRequired1e umdisplayName. Vincule ostriggersque entregam a recompensa, por exemplo uma action que dá um item. - Adicione uma action Open Battle Pass apontando para a sua definition em
battlePasse dispare-a a partir de um NPC, um item ou um menu. Os jogadores também podem digitar/tw battlepass. - Publique, conclua uma quest da semana e abra o menu para resgatar a recompensa.
O level de um tier é seu número no menu de recompensas e deve ser único dentro de uma definition. O nível de jogador necessário para resgatar uma recompensa é o levelRequired da própria recompensa. Um tier pode ter uma permission: os jogadores sem ela veem suas recompensas como bloqueadas, é assim que se constrói uma trilha premium.
Cada recompensa tem um id. Se você o deixar vazio, a extensão gera um a partir do nível do tier e da posição da recompensa (tier-1-reward-1), mas, se você mover ou inserir recompensas depois, os ids gerados mudam e as recompensas já resgatadas pelos jogadores deixam de corresponder. Defina um id explícito em cada recompensa antes de a temporada começar e nunca o altere.
Como funciona
O XP só é ganho quando uma quest listada em uma das semanas da definition passa para COMPLETED, a semana está marcada como available, a semana está liberada e a temporada está em andamento. Uma quest com xpReward igual a 0 não dá nada. O nível é o número de limites de xp.levels que o jogador atingiu.
Uma recompensa pode ser resgatada quando a temporada já começou (o resgate continua possível depois do fim), o nível do jogador atinge levelRequired e ele tem a permission do tier, se houver uma. As recompensas são resgatadas uma única vez. Se os triggers de uma recompensa falharem, a recompensa permanece pendente e não é repetida automaticamente, pois os triggers podem ter efeitos colaterais.
Menus
Por padrão, a extensão abre seus próprios menus de inventário: um menu principal listando as semanas, um menu de quests para a semana selecionada e um menu de recompensas (tier).
- Menu principal — um botão por semana, botões de semana anterior e seguinte, um botão de recompensas, um botão de informações e um botão de fechar.
- Menu de quests — as quests da semana com seu estado (bloqueada, disponível, ativa, concluída), botões de página, um botão de ordenação e um botão de voltar.
- Menu de recompensas — as recompensas de cada tier com seu estado, botões de página e um botão de voltar; clicar em uma recompensa desbloqueada a resgata.
Os tamanhos e posições vêm de layout. Cada tamanho deve ser um múltiplo de 9 entre 9 e 54, e cada slot deve caber dentro dele. Os slots aceitam números únicos ou intervalos como 10-16. Deixe um slot vazio para usar a posição padrão (layout de 54 slots com as semanas na linha 2, as quests nas linhas 2 a 4 e fechar no slot 49) ou desative um botão com seu campo ...Enabled. Cada botão tem um item, um name e uma lore em buttons, nos quais você pode usar placeholders entre chaves, como {week_title}, {quest_name}, {tier_level} ou {reward_state}. A ajuda dos campos no painel lista os placeholders disponíveis para cada botão.
Se você definir baseMenuId, menuLayoutPool, menuViews ou menuMainLayoutId, o passe é aberto dentro da sua própria base de GUI, com três views (início, níveis, quests) cujos ids são definidos em menuHomeViewId, menuLevelsViewId e menuQuestsViewId. O editor do GUI passa então a oferecer itens battlepass_button:: WEEK_SLOT, TIER_MENU, REWARD_SLOT, CLAIM, QUEST_SLOT, SORT, INFO, PAGE_NEXT, PAGE_PREV, BACK e CLOSE. As descrições dos tipos de botão no editor estão em francês.
As interações de menu são internas à sessão do GUI: não são comandos do Bukkit e não podem ser digitadas pelos jogadores.
Comandos
Os comandos do BattlePass são subcomandos do comando do TypeWriter, então começam com /typewriter ou seu alias /tw. A permissão base é typewriter.battlepass. O argumento <pass> é o id ou o nome de uma Battle Pass Definition e tem preenchimento automático. O argumento opcional [targets] é um seletor de jogadores; sem ele, o comando se aplica a quem o executa.
| Comando | Descrição |
|---|---|
/tw battlepass | Abre o menu da primeira definition, ordenada por id. |
/tw battlepass menu | O mesmo que /tw battlepass. |
/tw battlepass open | O mesmo que /tw battlepass. |
/tw battlepass <pass> xp add <amount> [targets] | Adiciona XP (o sinal da quantidade é ignorado). |
/tw battlepass <pass> xp remove <amount> [targets] | Remove XP. |
/tw battlepass <pass> xp set <amount> [targets] | Define o XP (nunca abaixo de zero). |
/tw battlepass <pass> level add <amount> [targets] | Aumenta o nível. |
/tw battlepass <pass> level remove <amount> [targets] | Diminui o nível. |
/tw battlepass <pass> level set <amount> [targets] | Define o nível. |
/tw battlepass <pass> info [targets] | Mostra o XP e o nível de um jogador no passe. |
Permissões
| Permissão | Concede |
|---|---|
typewriter.battlepass | Todos os comandos /tw battlepass, incluindo o menu e os subcomandos de admin. |
permission do tier | Uma permissão de sua escolha, definida em um tier, necessária para resgatar as recompensas desse tier. |
Placeholders
Estas são tags MiniPlaceholders da expansão battlepass, utilizáveis em qualquer texto MiniMessage que suporte placeholders. Substitua def pelo id da entry Battle Pass Definition. Os contadores são números; valores verdadeiro ou falso são retornados como 1 ou 0.
| Placeholder | Retorna |
|---|---|
<battlepass_name:def> | O nome do passe. |
<battlepass_active:def> | 1 enquanto os jogadores podem ganhar XP (temporada em andamento), caso contrário 0. |
<battlepass_level:def> | O nível do jogador. |
<battlepass_xp:def> | O XP do jogador. |
<battlepass_xp_max:def> | O teto de XP, ou o maior limite quando nenhum teto está definido. |
<battlepass_xp_next:def> | O limite de XP do próximo nível. |
<battlepass_xp_remaining:def> | O XP que falta para o próximo nível. |
<battlepass_rewards:def> e <battlepass_rewards_total:def> | O número total de recompensas. |
<battlepass_rewards_claimed:def> | Recompensas já resgatadas. |
<battlepass_rewards_available:def> | Recompensas que o jogador pode resgatar agora. |
<battlepass_rewards_unclaimed:def> | Total de recompensas menos as resgatadas. |
<battlepass_rewards_pending:def> | Recompensas reservadas, mas ainda não entregues. |
<battlepass_week_state:def:N> | O rótulo de estado da semana N. |
<battlepass_week_active:def:N> | 1 quando a semana N não está bloqueada nem indisponível. |
<battlepass_week_available:def:N> | 1 quando a semana está marcada como available. |
<battlepass_week_title:def:N> | O título da semana N. |
<battlepass_week_description:def:N> | A descrição da semana N. |
<battlepass_week_release:def:N> | A data de liberação da semana N. |
<battlepass_week_release_in:def:N> | O tempo restante antes de a semana N ser liberada, vazio depois de liberada. |
Entries
5 entradas, geradas a partir do código-fonte da extensão.
Ações1
- Open Battle PassOpen a battle pass menu
Fatos1
- Battle Pass Quest ActiveCheck if a battle pass week is active
Artefatos1
- Battle Pass Data ArtifactStore battle pass runtime data
Manifestos1
- Battlepass DefinitionRegister a battle pass definition
Outras entradas1
- Battlepass MessagesBattlePass Messages
Solução de problemas
A extensão não carrega. O BattlePass exige as extensões Quest, GUI (GuiAndDialogs) e MySQL. Verifique o log de inicialização do TypeWriter em busca de uma dependência ausente.
O log diz "Ignoring invalid battle pass definition". A definition falhou na validação, então não é registrada e /tw battlepass diz "Aucun Battle Pass n'est actuellement chargé". A linha do log lista os problemas: um name em branco, um tamanho de menu que não é múltiplo de 9 entre 9 e 54, um slot fora do menu, níveis de tier, números de semana ou ids de recompensa duplicados, xp.levels não estritamente crescente, ou um schedule.start que não é anterior a schedule.end.
Concluir uma quest não dá XP. A quest deve estar listada em uma semana da definition com um xpReward acima de 0, a semana deve estar available e liberada, a temporada deve estar ativa e a definition precisa de um artifact data (o log avisa quando ele está ausente). Um timezone desconhecido recorre a UTC, e strings de data que não podem ser interpretadas são ignoradas.
Uma recompensa não pode ser resgatada. O nível deve atingir levelRequired, o jogador precisa da permission do tier, a temporada deve ter começado e a recompensa não pode já estar resgatada ou pendente. Se seus triggers falharam, o log informa "remains pending after delivery failure" e a recompensa permanece pendente até que um administrador decida o que fazer.
As recompensas resgatadas reaparecem após editar as recompensas. Os ids de recompensa que foram gerados a partir de posições mudaram. Dê a cada recompensa um id explícito e mantenha-o inalterado.
O progresso não é salvo. O artifactId do artifact deve continuar sendo um UUID válido gerado pelo painel web; a extensão se recusa a usar qualquer outra coisa. Não mova nem renomeie manualmente os arquivos armazenados.