Pular para o conteúdo principal

Rewards

Fila de recompensas para jogadores offline com menu de resgate, concessões via cron e eventos de resgate.

Privadasv0.2.0Economia e criação
RequerTypeWriter0.9.0-beta-177 (BTC build)GUIMySQLMiniPlaceholdersopcional

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

Suporte

Visão geral​

O Rewards mantém, por jogador, uma fila de recompensas que foram conquistadas mas ainda não coletadas. Em vez de entregar um item ou executar um comando na hora, você coloca uma recompensa na fila. O jogador a coleta depois, a partir de um menu, quando estiver online e tiver espaço no inventário. Nada se perde se o jogador estiver offline ou com o inventário cheio quando a recompensa for concedida.

Uma recompensa é um modelo que você define uma vez (uma reward definition: item de exibição, lore, slots livres exigidos, ações a executar no resgate). Concedê-la adiciona um pequeno registro à fila; resgatá-la remove o registro e dispara as ações do TypeWriter que você ligou à definição. Como o efeito do resgate é uma lista de ações do TypeWriter, uma recompensa pode entregar itens, dinheiro, uma etapa de quest ou qualquer outra coisa que o TypeWriter possa disparar.

A fila é armazenada em um único artifact. Quando a extensão MySQL fornece o Redis, os servidores que compartilham o mesmo armazenamento são avisados para recarregar o artifact após cada salvamento, de modo que uma recompensa concedida em um servidor pode ser resgatada em outro.

Recursos​

  • Resgate adiado — as recompensas esperam na fila até o jogador resgatá-las.
  • Reward definitions — um modelo reutilizável por tipo de recompensa, com item de exibição, nome, lore e uma exigência de slots livres.
  • Ações de resgate — um resgate dispara qualquer lista de ações do TypeWriter em vez de um comando de console.
  • Menu de resgate independente — um inventário paginado com slots de recompensa, slot de informações, botões de página, resgate em massa e botão de voltar.
  • Botões incorporáveis — os slots de recompensa e um botão de resgate em massa podem ser colocados em qualquer página GUI por meio de tipos de botão.
  • Concessões por cron — btc_give_reward pode conceder uma recompensa no máximo uma vez por período de cron, por jogador (recompensas diárias, semanais).
  • Evento de resgate — uma entry de evento dispara a cada resgate com o id da recompensa, dados personalizados e contadores.
  • Fact de contagem de pendentes e placeholders — use a fila em criteria, scoreboards e menus.
  • Anti-spam — um cooldown de 500 ms entre resgates do mesmo jogador.

Instalação​

  1. Instale a extensão GUI (o nome do plugin no build é GuiAndDialogs) e a extensão MySQL, ambas declaradas como dependências do Rewards. O Redis só é usado para a atualização entre servidores e não é necessário em um único servidor.
  2. Coloque o JAR do Rewards em plugins/Typewriter/extensions/ e reinicie o servidor.
  3. Opcionalmente, instale o MiniPlaceholders para usar os placeholders rewards em texto MiniMessage.

Primeiros passos​

Dê uma recompensa diária de login que os jogadores coletam em um menu.

  1. No painel web do TypeWriter, abra uma page static e adicione um Rewards Artifact. Adicione apenas um: os placeholders e os botões incorporados usam o primeiro que encontrarem.
  2. Adicione uma entry Rewards Config (também apenas uma) para ajustar as mensagens e o layout da lore das recompensas.
  3. Adicione uma Reward Definition. Defina rewardId como daily_login, source como daily_login, escolha um displayItem e ligue as ações que entregam a recompensa em onClaimActions.
  4. Crie uma ação Give Reward. Ligue o artifact e o reward, ative useCron e defina cronExpression como 0 0 0 * * * para uma vez por dia. Dispare-a a partir de um evento de entrada ou de um NPC.
  5. Crie uma ação Open Rewards Menu com o mesmo artifact e dispare-a a partir de um comando ou de um NPC.
  6. Publique. Um jogador que dispara a concessão recebe uma recompensa pendente; clicar nela no menu a resgata.
Contando recompensas

Use Has Pending Rewards em um criteria para mostrar uma notificação apenas enquanto o jogador tem algo a coletar.

Como funciona​

A fila armazena apenas o rewardId, o horário da concessão e os dados personalizados. O item exibido no menu e as ações a executar são sempre lidos da definição no momento da exibição ou do resgate. Uma recompensa na fila cuja definição foi excluída não é exibida e não pode ser resgatada.

As recompensas podem ser exibidas de duas formas que compartilham a mesma lógica de resgate.

Menu independente. Open Rewards Menu abre seu próprio inventário com rows de 1 a 6. As recompensas pendentes preenchem rewardSlotsConfig em ordem (um intervalo, ou uma lista explícita de slots quando useRange está desativado). Quando há mais recompensas que slots, o menu é paginado com os opcionais previousPageButton e nextPageButton. Os opcionais infoSlot, bulkClaimButton e backButton recebem números de slots, um item, um nome e uma lore em MiniMessage. backButton.command é executado como o jogador (sem a barra inicial); deixe-o vazio para simplesmente fechar o menu. Os slots vazios são preenchidos com backgroundItem quando definido. Os números de slot vão de 0 (canto superior esquerdo) a 8 na primeira linha, depois 9 a 17 e assim por diante.

Botões em qualquer página GUI. Em um menu GUI, defina o buttonType de um item como um dos marcadores do Rewards. O item que você configura mantém sua posição e seu estilo; nos slots de recompensa, ele é substituído pelo item de exibição da própria recompensa.

Tipo de botãoComportamento
rewards_button:REWARD_SLOT#<n>Mostra a n-ésima recompensa pendente do espectador (contando a partir de 0); o clique esquerdo a resgata. Depois da última recompensa, o slot fica vazio.
rewards_button:BULK_CLAIMO clique esquerdo resgata todas as recompensas pendentes para as quais o jogador tem espaço.

Regras de resgate, nos dois modos:

  • A recompensa exige requiredInventorySlots slots vazios no inventário do jogador (0 significa sem verificação). Se não houver espaço suficiente, o resgate é recusado e inventoryFullMessage é enviada.
  • Um resgate dispara os onClaimActions da definição e depois dispara todas as entries de evento Reward Claimed. Um resgate em massa vai da última recompensa da fila até a primeira e dispara o evento uma vez com o id de recompensa bulk_claim.
  • As mensagens de sucesso e de resgate em massa vêm da entry Rewards Config. Para os botões incorporados, a primeira entry Rewards Config encontrada é a usada.

A lore de um item de recompensa é construída a partir do additionalLore da definição, depois um separador e as linhas de origem e de slots livres, e então uma dica final; os rótulos vêm da entry Rewards Config.

Placeholders​

Expansão rewards do MiniPlaceholders, utilizável em texto MiniMessage como tags.

PlaceholderRetorna
<rewards_pending>Número de recompensas pendentes do jogador.
<rewards_pending:rewardId>Número de recompensas pendentes com este rewardId.
<rewards_source:source>Número de recompensas pendentes cuja definição tem este source (sem diferenciar maiúsculas de minúsculas). Recompensas com uma definição excluída não são contadas.
<rewards_claimed_total>Número de recompensas que o jogador resgatou no total.

O id da recompensa é um argumento da tag: escreva <rewards_pending:daily_login>, não <rewards_pending_daily_login>. Todos os placeholders não retornam nada se não existir um Rewards Artifact.

Entries​

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

Ações2
Eventos1
Fatos1
Artefatos1
Manifestos2

Solução de problemas​

O menu não abre e o log diz que a extensão GUI não está instalada. btc_open_rewards_menu precisa da extensão GUI em tempo de execução. Instale-a e reinicie. A ação também não faz nada, com um aviso, quando seu campo artifact está vazio.

Give Reward não faz nada. O log mostra um aviso quando a ação não tem artifact, nem reward, ou quando a definição ligada tem um rewardId vazio. Preencha os três campos.

Uma recompensa por cron é concedida apenas uma vez. Com useCron ativado, o horário da última concessão é armazenado por jogador e por entry de ação. A próxima concessão só acontece depois da próxima vez em que a expressão cron corresponder após esse momento. Teste com uma expressão curta ou use uma entry de ação diferente para cada agendamento.

Uma recompensa pendente está invisível ou não pode ser resgatada. O menu ignora as recompensas na fila cuja definição não pode ser encontrada pelo rewardId. Não altere o rewardId de uma definição depois que as recompensas foram concedidas.

Resgate recusado com a mensagem de inventário cheio. O jogador tem menos slots vazios que requiredInventorySlots. Observe que a verificação conta todos os slots vazios do objeto de inventário do jogador, incluindo os de armadura e de mão secundária.

Toasts, sons, noRewardsMessage e onClaimFailActions não têm efeito. Esses campos existem em Rewards Config e Reward Definition, mas o código desta versão nunca os lê. Apenas as mensagens de resgate, de inventário cheio e de resgate em massa e o layout da lore são aplicados.

As recompensas não aparecem em outro servidor. A atualização entre servidores depende do Redis da extensão MySQL e de ambos os servidores lerem o mesmo armazenamento do artifact. Sem o Redis, cada servidor só vê a própria cópia até ser reiniciado.

Extensões relacionadas​

  • GUI — renderiza os botões controlados por página e o menu independente.
  • MySQL — invalidação de cache via Redis entre servidores.