Vote System
概要
Vote System は、サーバーに投票機能を追加します。投票はボートデフィニションで定義し、タイトル、選択肢のリスト、任意の終了日時、投票が締め切られた後に表示されるメッセージを持ちます。各プレイヤーは、TypeWriter のアクション（ダイアログの選択肢、NPC、メニューのクリック）またはコマンドで、投票ごとに 1 回だけ投票できます。投票内容は TypeWriter アーティファクトに保存されます。
結果は PlaceholderAPI のプレースホルダーとして利用できるため、スコアボード、ホログラム、メニューに表示でき、スタッフ向けにはコマンドでも確認できます。これは、プレイヤー同士の投票であり、サーバーリスト投票サイトへのリンクではありません。
機能
- 複数の選択肢を持つ投票 — 各選択肢には専用のテキストがあり、プレースホルダーと色を含められます。
- プレイヤーごとに 1 票 — 同じ投票への 2 回目の投票は拒否されます。ただし、Vote Config で再投票用の
cooldownSecondsを設定した場合を除きます。 - 終了日時 — 指定した日時に、投票を自動的に締め切ります。
- 終了メッセージとブロックメッセージ — 遅れて投票した人には投票が終了したことを、早すぎる再投票をした人には待つ必要があることを伝えます。どちらも MiniMessage です。
- 投票アクション — トリガーしたプレイヤーの票を投じ、投票が記録されたときにのみシーケンスを続行します。
- ステータスメッセージ — プレイヤーがすでに投票したかどうかに応じて、異なるメッセージを送信します。
- リアルタイムの結果 — 合計、選択肢ごとの票数、プレイヤーが選んだ選択肢をプレースホルダーで取得できます。
- スタッフ用コマンド — プレイヤーの代わりに投票する、結果を読む、投票をリセットする。
インストール
- プレースホルダーで結果を表示したい場合は、PlaceholderAPI をインストールします。
- Vote System の JAR を
plugins/Typewriter/extensions/に配置し、サーバーを再起動します。
はじめに
次のマップのテーマを決める投票を実施します。
- TypeWriter の Web パネルでマニフェストページを開き、Vote Data アーティファクトを追加します。デフォルトの
artifactId（vote_storage）は保持します。 - Vote Definition を追加します。
displayNameをNext map themeに設定し、optionsに 3 つのエントリー（たとえばDesert、Snow、Jungle）を追加して、dataにアーティファクトをリンクします。 endDateを2026-12-31T23:00:00Zのような UTC の日時に、closedMessageを短いテキストに設定します。終了のない投票にするには、endDateを空のままにします。- シーケンスページを開きます。選択肢ごとに Vote Action を追加し、
definitionをリンクして、optionIndexを0、1、2のいずれかに設定します。選択肢のインデックスは 0 から始まります。 - 各アクションを、ダイアログの選択肢、NPC とのインタラクション、メニューのボタンに接続し、お礼のメッセージや報酬を、アクションの
triggersに設定します。これらは、投票が記録されたときにのみ実行されます。 - 必要に応じて、すでに投票したプレイヤーに知らせるため、選択肢の前に Vote Message を追加します。
- Publish します。スコアボードで投票数を表示するには、
%typewriter_vote_total_<definition id>%を使用します。
投票内容は、ボートデフィニションのエントリー ID から導出されるキーで保存されます。エントリーを削除したり、その ID を変更したりすると、保存された票は見つからなくなります。
コマンド
すべてのコマンドは /typewriter（エイリアス /tw）のサブコマンドです。<definition> は、ボートデフィニションの ID または名前です。
| コマンド | パーミッション | 説明 |
|---|---|---|
/typewriter vote <definition> <option> [target] | typewriter.vote.cast | 選択肢に投票します。選択肢は 1 から始まります。target を指定すると、選択したプレイヤーの票を投じます。 |
/typewriter vote stats [definition] | typewriter.vote.stats | 1 つまたはすべての投票について、選択肢ごとの票数と合計を表示します。 |
/typewriter vote reset <definition> | typewriter.vote.reset | 投票のすべての票を削除します。 |
いずれも typewriter.vote も必要です。
編集可能なテキスト
ゲーム内に表示されるテキストで、コードに固定されているものはありません。1 つの投票のメッセージは、そのエントリーのフィールドです。Vote Definition の closedMessage と、Vote Message の 2 つのメッセージです。/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} （投票の ID） |
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 は選択肢ごとに 1 回繰り返され、その結果が stats_separator で連結されて stats_line の {options} になります。stats_option_fallback はテキストを持たない選択肢の {label} で、cast_option_fallback は投票が記録されたときに送信されるメッセージ内での、そのような選択肢の名前です。最後の 2 つのスニペットはコマンドエラーで、ゲームが赤色で表示します。MiniMessage を使わないプレーンテキストです。
投票が終了している場合、/tw vote はスタッフに投票の closedMessage を表示します（cast_failed が使われるのは、そのメッセージが空のときだけです）。cast_failed は、データエントリがない場合や選択肢が範囲外の場合にも使われます。
パーミッション
| パーミッション | 許可される内容 |
|---|---|
typewriter.vote | /typewriter vote コマンドへのアクセス。 |
typewriter.vote.cast | コマンドでの投票。 |
typewriter.vote.stats | コマンドでの結果の閲覧。 |
typewriter.vote.reset | 投票のリセット。 |
投票アクションは、これらのパーミッションを確認しません。エントリーが実行されるだけで動作します。
プレースホルダー
<id> は、ボートデフィニションのエントリー ID に置き換えてください。PlaceholderAPI が必要です。
| プレースホルダー | 戻り値 |
|---|---|
%typewriter_vote_display_<id>% | 投票の displayName。 |
%typewriter_vote_option_<id>_<n>% | 1 から数えて n 番目の選択肢のテキスト。 |
%typewriter_vote_total_<id>% | 投票の総数。 |
%typewriter_vote_stats_<id>% | すべての選択肢の票数をカンマで区切ったもの。 |
%typewriter_vote_stats_<id>_<n>% | 1 から数えて n 番目の選択肢の票数。 |
%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 が送られます。Vote Config で debug をオンにすると、拒否の理由がすべてログに記録されます。
間違った選択肢に票が入る。 投票アクションは選択肢を 0 から数えますが、コマンドとプレースホルダーは 1 から数えます。
投票が締め切られない。 endDate は、2026-12-31T23:00:00Z のように、末尾が Z の UTC の ISO-8601 形式のインスタントでなければなりません。他の形式の値は無視され、投票は開いたままになります。
エントリー名を変更したら、結果が空になった。 票は、デフィニションのエントリー ID に紐付いています。古い ID に戻すか、投票をリセットしてやり直してください。
プレースホルダーがそのまま表示される。 PlaceholderAPI がインストールされていること、ID がデフィニションのエントリー ID であることを確認してください。エクステンションは、最初の投票より前にプレースホルダーが要求された場合でも、デフィニションを見つけます。
メッセージの色がおかしい。 Vote Message のステータスメッセージ、closedMessage、blockedMessage は、プレースホルダーを解決した後に MiniMessage として読み込まれます。&c コードではなく <red>テキスト</red> と書いてください。
プレイヤーが 2 回投票できてしまう。 Vote Config の cooldownSeconds が 0 より大きい場合、クールダウン終了後はそれが想定どおりの動作です。そうでなければ、確認はプレイヤーごと、投票ごとに行われます。同じ選択肢を持つ複数の投票定義を使うと、別々の投票が作成されます。