Vote System
Обзор
Vote System добавляет на ваш сервер опросы. Опрос — это определение голосования: заголовок, список вариантов, необязательная дата окончания и сообщение, которое показывается, когда опрос закрыт. Каждый игрок может проголосовать в опросе один раз, из действия TypeWriter (вариант ответа в диалоге, NPC, клик в меню) или командой. Голоса хранятся в артефакте TypeWriter.
Результаты доступны как плейсхолдеры PlaceholderAPI, поэтому вы можете показывать их на скорборде, в голограмме или в меню, а для персонала — командой. Это голосование среди ваших игроков, а не ссылка на сайты голосования в рейтингах серверов.
Возможности
- Опросы с несколькими вариантами — у каждого варианта свой текст, который может содержать плейсхолдеры и цвета.
- Один голос на игрока — второй голос в том же опросе отклоняется, если только вы не задали
cooldownSecondsдля повторного голосования в Vote Config. - Дата окончания — автоматически закрывайте опрос в заданные дату и время.
- Сообщения о закрытии и о блокировке — сообщают опоздавшим, что голосование окончено, а тем, кто голосует повторно слишком рано, что нужно подождать. Оба в формате MiniMessage.
- Действие голосования — подаёт голос за игрока, запустившего его, и продолжает вашу последовательность, только если голос был записан.
- Сообщение о статусе — отправляйте разное сообщение в зависимости от того, голосовал ли игрок уже.
- Результаты в реальном времени — итоги, количество голосов по вариантам и вариант, выбранный игроком, в виде плейсхолдеров.
- Команды для персонала — проголосовать за игрока, прочитать результаты и сбросить опрос.
Установка
- Установите PlaceholderAPI, если хотите показывать результаты через плейсхолдеры.
- Поместите JAR-файл Vote System в
plugins/Typewriter/extensions/и перезапустите сервер.
Начало работы
Проведите опрос о теме следующей карты:
- В веб-панели TypeWriter откройте страницу manifest и добавьте артефакт Vote Data. Сохраните
artifactIdпо умолчанию (vote_storage). - Добавьте Vote Definition. Задайте
displayNameравнымNext map theme, добавьте три элемента вoptions(например,Desert,Snow,Jungle) и свяжите артефакт вdata. - Задайте
endDateкак дату и время в UTC, например2026-12-31T23:00:00Z, аclosedMessage— коротким текстом. ОставьтеendDateпустым для опроса без окончания. - Откройте страницу sequence. Добавьте действие Vote Action для каждого варианта: свяжите
definitionи задайтеoptionIndexравным0,1или2. Индекс варианта начинается с 0. - Подключите каждое действие к варианту ответа в диалоге, взаимодействию с NPC или кнопке меню и поместите своё сообщение с благодарностью или награду в
triggersдействия. Они выполняются только тогда, когда голос записан. - По желанию добавьте Vote Message перед вариантами, чтобы напомнить уже проголосовавшим игрокам.
- Опубликуйте. Используйте
%typewriter_vote_total_<definition id>%на скорборде, чтобы показывать количество голосов.
Голоса опроса хранятся под ключом, производным от идентификатора записи его определения голосования. Если вы удалите запись или измените её идентификатор, сохранённые голоса больше не будут найдены.
Команды
Все команды — это подкоманды /typewriter (псевдоним /tw). <definition> — это идентификатор или название определения голосования.
| Команда | Право | Описание |
|---|---|---|
/typewriter vote <definition> <option> [target] | typewriter.vote.cast | Проголосовать за вариант. Варианты начинаются с 1. С target голосует за выбранных игроков. |
/typewriter vote stats [definition] | typewriter.vote.stats | Показать голоса по вариантам и итог, для одного опроса или для всех. |
/typewriter vote reset <definition> | typewriter.vote.reset | Удалить все голоса опроса. |
Всем им также нужно typewriter.vote.
Редактируемые тексты
Ни один текст, показываемый в игре, не зашит в код. Сообщения одного голосования — это поля его записей: closedMessage у Vote Definition и два сообщения у Vote Message. Ответы команд /typewriter vote — это сниппеты TypeWriter, поэтому их можно переформулировать, перевести или перекрасить без пересборки. Откройте plugins/Typewriter/snippets.yml, найдите ключ в content.vote, измените значение и выполните /tw reload. Расширение регистрирует все свои сниппеты с текстом по умолчанию при запуске, поэтому после первого запуска они появляются в файле. Оставьте значения по умолчанию, и ничего не изменится.
Ответы команд написаны в MiniMessage. Они отправляются с префиксом ответа Typewriter (Typewriter »), который приходит из движка и не входит в эти сниппеты. {name} в тексте заменяется значением, указанным в таблице; несуществующий плейсхолдер остаётся как написан, а в значении плейсхолдеры повторно не ищутся. Журнал консоли сервера остаётся на английском.
Сниппет (в content.vote.) | По умолчанию | Плейсхолдеры |
|---|---|---|
usage | <gray>Usage: /tw vote <definition> <option> [target]</gray> | нет |
option_unavailable | <red>Option {option} is not available for {definition}.</red> | {option} (введённый номер), {definition} (идентификатор голосования) |
already_voted | <red>{player} cannot vote in {definition} yet.</red> | {player}, {definition} |
cast_option_fallback | option {number} | {number} (номер варианта, начиная с 1) |
recorded_for_voter | Your vote for <blue>{definition}</blue> has been recorded as <green>{option}</green>. | {definition}, {option} (текст варианта) |
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. | нет |
stats_line | Stats for {name} [{definition}]: {options} | total: {total} | {name} (displayName или название записи, если оно пустое), {definition}, {options}, {total} |
stats_option | {number}: {votes} ({label}) | {number}, {votes}, {label} (текст варианта) |
stats_option_fallback | Option {number} | {number} |
stats_separator | , | нет |
entry_not_found | Could not find entry {entry} | {entry} (введённое значение) |
entry_rejected | Entry did not pass filter | нет |
stats_option повторяется для каждого варианта, а результаты соединяются через stats_separator, образуя {options} в stats_line. stats_option_fallback — это {label} варианта без текста, а cast_option_fallback — название такого варианта в сообщениях, отправляемых при записи голоса. Последние два сниппета — ошибки команд, которые игра показывает красным: это обычный текст, без MiniMessage.
Когда голосование закрыто, /tw vote показывает сотруднику closedMessage голосования (cast_failed используется, только если это сообщение пустое). cast_failed также отвечает при отсутствии записи данных или при варианте вне диапазона.
Права
| Право | Что даёт |
|---|---|
typewriter.vote | Доступ к команде /typewriter vote. |
typewriter.vote.cast | Голосование командой. |
typewriter.vote.stats | Чтение результатов командой. |
typewriter.vote.reset | Сброс опроса. |
Действие голосования эти права не проверяет: ему нужно только, чтобы запись выполнилась.
Плейсхолдеры
Замените <id> идентификатором записи определения голосования. Им нужен PlaceholderAPI.
| Плейсхолдер | Возвращает |
|---|---|
%typewriter_vote_display_<id>% | displayName опроса. |
%typewriter_vote_option_<id>_<n>% | Текст варианта номер n, начиная с 1. |
%typewriter_vote_total_<id>% | Общее число голосов. |
%typewriter_vote_stats_<id>% | Голоса каждого варианта через запятую. |
%typewriter_vote_stats_<id>_<n>% | Голоса варианта номер n, начиная с 1. |
%typewriter_vote_player_<id>% | Текст варианта, за который проголосовал игрок, или ничего, если он не голосовал. |
%typewriter_vote_has_voted_<id>% | 1, если игрок пока не может голосовать повторно (он проголосовал, и пауза не истекла), иначе 0. |
%typewriter_vote_closed_<id>% | 1 после даты окончания, иначе 0. |
%typewriter_vote_remaining_<id>% | Целые секунды до даты окончания; 0, если даты нет или она прошла. |
vote_votes_<id> работает как vote_stats_<id>.
Записи
Записей: 7, сгенерированы из исходного кода расширения.
Действия2
- Vote ActionVote Action
- Vote MessageVote Message
События1
- Vote Cast EventVote Cast Event
Факты1
- Vote FactVote Fact
Артефакты1
- Vote DataVote Data
Манифесты2
- Vote ConfigVote System Configuration
- Vote DefinitionVote Definition
Vote Cast Event и Vote Fact существуют, но пока их никто не читает: событие никогда не срабатывает, а факт не заполняется голосами. Vote Config читается: он задаёт перезарядку повторного голосования и журнал отладки.
Устранение неполадок
Голос не записывается. Действие и команда молча не срабатывают, когда чего-то не хватает: у определения голосования должен быть связан артефакт data, вариант должен существовать, игрок не должен был уже голосовать (или его перезарядка должна истечь, см. Vote Config), а опрос не должен выйти за свой endDate. Если опрос закрыт, игроку отправляется closedMessage. Если игроку ещё нужно подождать, отправляется blockedMessage. Включите debug в Vote Config, чтобы записывать в лог причину каждого отказа.
Голос засчитывается не тому варианту. Действие голосования считает варианты с 0, а команда и плейсхолдеры — с 1.
Опрос никогда не закрывается. endDate должен быть моментом времени в формате ISO-8601 в UTC, заканчивающимся на Z, например 2026-12-31T23:00:00Z. Значение в другом формате игнорируется, и опрос остаётся открытым.
Результаты пусты после переименования записи. Голоса привязаны к идентификатору записи определения. Верните старый идентификатор или сбросьте опрос и начните заново.
Плейсхолдер отображается как есть. Проверьте, что PlaceholderAPI установлен и что идентификатор — это идентификатор записи определения. Расширение также находит определение, когда плейсхолдер запрашивается до первого голоса.
Цвета в сообщении выглядят неправильно. Сообщения о статусе из Vote Message, closedMessage и blockedMessage читаются как MiniMessage после подстановки плейсхолдеров: пишите <red>текст</red>, а не коды &c.
Игроки могут проголосовать дважды. Проверка выполняется для каждого игрока и для каждого опроса. Использование нескольких определений голосования с одинаковыми вариантами создаёт отдельные опросы.