Vote System
Visão geral
O Vote System adiciona votações ao seu servidor. Uma votação é uma vote definition: um título, uma lista de opções, uma data de término opcional e uma mensagem exibida quando a votação é encerrada. Cada jogador pode votar uma vez por votação, a partir de uma ação do TypeWriter (uma opção de diálogo, um NPC, um clique em menu) ou com um comando. Os votos são armazenados em um artifact do TypeWriter.
Os resultados estão disponíveis como placeholders do PlaceholderAPI, então você pode exibi-los em um scoreboard, em um holograma ou em um menu, e com um comando para a equipe. Trata-se de uma votação entre os seus jogadores, e não de um link para sites de votação de listas de servidores.
Recursos
- Votações com várias opções — cada opção tem seu próprio texto, que pode conter placeholders e cores.
- Um voto por jogador — um segundo voto na mesma votação é recusado, a menos que você defina um
cooldownSecondsde novo voto em Vote Config. - Data de término — encerre uma votação automaticamente em uma data e hora determinadas.
- Mensagens de encerramento e de bloqueio — avisam quem vota tarde que a enquete acabou e quem vota de novo cedo demais que precisa esperar. Ambas são MiniMessage.
- Ação de voto — registre um voto para o jogador que disparou a ação e continue sua sequência somente quando o voto tiver sido registrado.
- Mensagem de status — envie uma mensagem diferente conforme o jogador já tenha votado ou não.
- Resultados ao vivo — totais, contagens por opção e a opção escolhida pelo jogador, como placeholders.
- Comandos de equipe — vote por um jogador, leia os resultados e redefina uma votação.
Instalação
- Instale o PlaceholderAPI se quiser exibir os resultados com placeholders.
- Coloque o JAR do Vote System em
plugins/Typewriter/extensions/e reinicie o servidor.
Primeiros passos
Faça uma votação sobre o tema do próximo mapa:
- No painel web do TypeWriter, abra uma page manifest e adicione um artifact Vote Data. Mantenha o
artifactIdpadrão (vote_storage). - Adicione uma Vote Definition. Defina
displayNamecomoNext map theme, adicione três entradas aoptions(por exemploDesert,Snow,Jungle) e ligue o artifact emdata. - Defina
endDatecomo uma data e hora em UTC, como2026-12-31T23:00:00Z, eclosedMessagecomo um texto curto. DeixeendDatevazio para uma votação sem fim. - Abra uma page sequence. Adicione uma Vote Action para cada opção: ligue a
definitione definaoptionIndexcomo0,1ou2. O índice da opção começa em 0. - Conecte cada ação a uma opção de diálogo, a uma interação com NPC ou a um botão de menu, e coloque sua mensagem de agradecimento ou recompensa nos
triggersda ação. Eles só são executados quando o voto é registrado. - Opcionalmente, adicione uma Vote Message antes das opções, para lembrar os jogadores que já votaram.
- Publique. Use
%typewriter_vote_total_<definition id>%em um scoreboard para exibir o número de votos.
Os votos de uma votação são armazenados sob uma chave derivada do entry id da sua vote definition. Se você excluir a entry ou alterar seu id, os votos armazenados dela deixam de ser encontrados.
Comandos
Todos os comandos são subcomandos de /typewriter (alias /tw). <definition> é o id ou o nome de uma vote definition.
| Comando | Permissão | Descrição |
|---|---|---|
/typewriter vote <definition> <option> [target] | typewriter.vote.cast | Vota em uma opção. As opções começam em 1. Com target, vota pelos jogadores selecionados. |
/typewriter vote stats [definition] | typewriter.vote.stats | Mostra os votos por opção e o total, de uma votação ou de todas. |
/typewriter vote reset <definition> | typewriter.vote.reset | Apaga todos os votos de uma votação. |
Todos eles também exigem typewriter.vote.
Textos editáveis
Nenhum texto exibido no jogo está fixo no código. As mensagens de uma votação são campos das suas entradas: closedMessage da Vote Definition e as duas mensagens de Vote Message. O que os comandos /typewriter vote respondem é um snippet do TypeWriter, então você pode reescrevê-lo, traduzi-lo ou mudar as cores sem recompilar nada. Abra plugins/Typewriter/snippets.yml, encontre a chave em content.vote, altere o valor e execute /tw reload. A extensão registra todos os seus snippets com o texto padrão ao iniciar, então eles aparecem no arquivo após a primeira inicialização. Mantenha os padrões e nada muda.
As respostas dos comandos são MiniMessage. Elas são enviadas com o prefixo de resposta do Typewriter (Typewriter »), que vem do engine e não faz parte desses snippets. Um {name} em um texto é substituído pelo valor indicado na tabela; um placeholder que não existe permanece como escrito, e um valor nunca é examinado de novo em busca de placeholders. O log do console do servidor continua em inglês.
Snippet (em content.vote.) | Padrão | Placeholders |
|---|---|---|
usage | <gray>Usage: /tw vote <definition> <option> [target]</gray> | nenhum |
option_unavailable | <red>Option {option} is not available for {definition}.</red> | {option} (o número digitado), {definition} (o id da votação) |
already_voted | <red>{player} cannot vote in {definition} yet.</red> | {player}, {definition} |
cast_option_fallback | option {number} | {number} (posição da opção, a partir de 1) |
recorded_for_voter | Your vote for <blue>{definition}</blue> has been recorded as <green>{option}</green>. | {definition}, {option} (o texto da opção) |
recorded_by_other | Recorded vote for <blue>{player}</blue> in {definition}: {option}. | {player}, {definition}, {option} |
recorded_for_self | Vote registered for {definition}: {option}. | {definition}, {option} |
cast_failed | <red>Unable to register the vote for {player} in {definition}.</red> | {player}, {definition} |
reset_done | <green>Votes reset for {definition}.</green> | {definition} |
no_definitions | There are no active vote definitions. | nenhum |
stats_line | Stats for {name} [{definition}]: {options} | total: {total} | {name} (o displayName, ou o nome da entrada quando vazio), {definition}, {options}, {total} |
stats_option | {number}: {votes} ({label}) | {number}, {votes}, {label} (o texto da opção) |
stats_option_fallback | Option {number} | {number} |
stats_separator | , | nenhum |
entry_not_found | Could not find entry {entry} | {entry} (o que foi digitado) |
entry_rejected | Entry did not pass filter | nenhum |
stats_option é repetido uma vez por opção e os resultados são unidos com stats_separator para formar {options} de stats_line. stats_option_fallback é o {label} de uma opção sem texto, e cast_option_fallback é o nome dessa opção nas mensagens enviadas quando um voto é registrado. Os dois últimos snippets são erros de comando, exibidos em vermelho pelo jogo: são texto simples, sem MiniMessage.
Quando a enquete está encerrada, /tw vote mostra o closedMessage da enquete ao membro da equipe (cast_failed só é usado se essa mensagem estiver vazia). cast_failed também responde a uma entrada de dados ausente ou a uma opção fora do intervalo.
Permissões
| Permissão | Concede |
|---|---|
typewriter.vote | Acesso ao comando /typewriter vote. |
typewriter.vote.cast | Registrar um voto com o comando. |
typewriter.vote.stats | Ler os resultados com o comando. |
typewriter.vote.reset | Redefinir uma votação. |
A ação de voto não verifica essas permissões: ela só precisa que a entry seja executada.
Placeholders
Substitua <id> pelo entry id da vote definition. Eles exigem o PlaceholderAPI.
| Placeholder | Retorna |
|---|---|
%typewriter_vote_display_<id>% | O displayName da votação. |
%typewriter_vote_option_<id>_<n>% | O texto da opção de número n, começando em 1. |
%typewriter_vote_total_<id>% | O número total de votos. |
%typewriter_vote_stats_<id>% | Os votos de cada opção, separados por vírgulas. |
%typewriter_vote_stats_<id>_<n>% | Os votos da opção de número n, começando em 1. |
%typewriter_vote_player_<id>% | O texto da opção em que o jogador votou, ou nada se ele não votou. |
%typewriter_vote_has_voted_<id>% | 1 se o jogador não pode votar de novo por enquanto (votou e a espera não terminou), senão 0. |
%typewriter_vote_closed_<id>% | 1 depois que a data final passou, senão 0. |
%typewriter_vote_remaining_<id>% | Segundos inteiros até a data final; 0 sem data final ou depois que ela passou. |
vote_votes_<id> funciona como vote_stats_<id>.
Entries
7 entradas, geradas a partir do código-fonte da extensão.
Ações2
- Vote ActionVote Action
- Vote MessageVote Message
Eventos1
- Vote Cast EventVote Cast Event
Fatos1
- Vote FactVote Fact
Artefatos1
- Vote DataVote Data
Manifestos2
- Vote ConfigVote System Configuration
- Vote DefinitionVote Definition
Vote Cast Event e Vote Fact existem, mas nada os lê ainda: o evento nunca é disparado e o fact não é preenchido pelos votos. Vote Config é lido: define o cooldown de novo voto e o log de debug.
Solução de problemas
O voto não é registrado. A ação e o comando falham silenciosamente quando algo está faltando: a vote definition deve ter um artifact ligado em data, a opção deve existir, o jogador não deve ter votado antes (ou o cooldown dele deve ter terminado, veja Vote Config) e a votação não deve ter passado do seu endDate. Quando a votação está encerrada, o closedMessage é enviado ao jogador. Quando o jogador ainda precisa esperar, o blockedMessage é enviado. Ative debug em Vote Config para registrar o motivo de cada recusa.
A opção errada recebe o voto. A ação de voto conta as opções a partir de 0, enquanto o comando e os placeholders contam a partir de 1.
A votação nunca encerra. endDate deve ser um instante ISO-8601 em UTC terminado em Z, como 2026-12-31T23:00:00Z. Um valor em outro formato é ignorado e a votação continua aberta.
Os resultados ficam vazios depois que renomeei a entry. Os votos estão ligados ao entry id da definição. Restaure o id antigo ou redefina a votação e comece de novo.
Um placeholder aparece sem ser substituído. Verifique se o PlaceholderAPI está instalado e se o id é o entry id da definição. A extensão também encontra uma definição quando um placeholder é solicitado antes do primeiro voto.
As cores de uma mensagem parecem erradas. As mensagens de status de Vote Message, o closedMessage e o blockedMessage são lidos como MiniMessage depois que os placeholders são resolvidos: escreva <red>texto</red>, não códigos &c.
Os jogadores conseguem votar duas vezes. A verificação é por jogador e por votação. Usar várias vote definitions com as mesmas opções cria votações separadas.