BattlePass
概要
BattlePass は、サーバーにシーズン制の進行トラックを追加します。シーズンには開始日と終了日があり、週に分割されます。各週は、クエストのリストを解放します。プレイヤーがそのクエストの 1 つを完了すると、XP を獲得し、XP のしきい値がレベルになります。報酬はティア(たとえば、無料ティアと、権限で保護されたプレミアムティア)にまとめられ、メニューから受け取ります。
すべては、Web パネルの 1 つの Battle Pass Definition エントリで設定します。ティア、報酬、週、XP のしきい値、スケジュール、メニューのレイアウト、ボタンのアイテムです。報酬は、TypeWriter のトリガーのリストにすぎないため、アイテムを与えたり、コマンドを実行したり、コスメティックを付与したり、アクションができるあらゆることを行えます。クエストは、TypeWriter の Quest 拡張機能から提供されます。
この拡張機能は、BTC ビルドの TypeWriter(BTC Core、Paper/Folia)上で動作し、ここでは参考情報として文書化されています。進行状況は Battle Pass Data アーティファクトを通じて保存され、メモリキャッシュに保持されるため、メニューやプレースホルダーがストレージを待つことはありません。
機能
- シーズン — 任意の開始日と終了日、日数での週の長さ、IANA タイムゾーン(デフォルトは UTC)。
- 週ごとのクエスト — 週は自動的に、または選んだ日付に解放され、各クエストは完了すると、固定量の XP を与えます。
- XP とレベル — XP のしきい値のリストでレベルが定義され、XP の上限も任意で設定できます。
- 段階別の報酬 — 各ティアは、優先度、任意の権限、そして必要レベルに結び付けられた報酬を持ちます。
- 安全な受け取り — 受け取りは、トリガーが実行される前に予約されるため、報酬が二重に配布されることはありません。
- 設定可能なメニュー — スロット、サイズ、すべてのボタンのアイテム、名前、ロア。または、GUI 拡張機能の上に作られた、完全なカスタムレイアウト。
- 管理者用コマンド — 自分または他のプレイヤーの XP とレベルを、追加、削除、設定でき、プレイヤーの進行状況を読み取れます。
- プレースホルダー — スコアボードやメニュー用の、レベル、XP、報酬のカウンター、週の情報。
- 編集可能なメッセージ — すべてのチャットメッセージは、BattlePass Messages エントリで変更できます。
- ネットワーク対応 — 進行状況は MySQL 拡張機能を通じて保存され、Redis が利用できる場合は、Redis 経由でキャッシュが無効化されます。
インストール
- TypeWriter の Quest 拡張機能、GUI 拡張機能(BTC ビルドでは
GuiAndDialogs)、MySQL 拡張機能をインストールします。これらがないと、TypeWriter は BattlePass を読み込みません。 - BattlePass の JAR を
plugins/Typewriter/extensions/に置き、サーバーを再起動します。 - 使いたいクエストを、Quest 拡張機能で作成します。
- プレミアムティアが欲しい場合は、権限プラグインで権限を作成します(名前は自由で、ティアに入力します)。
はじめに
レベル 1 で無料の報酬がある、4 週間のシーズンを作成します。
- TypeWriter の Web パネルで manifest ページを開き、Battle Pass Data アーティファクトを追加します。
artifactIdは生成されたままにし、storage.modeはPLAYERのままにします。 - 同じページに Battle Pass Definition エントリを追加します。
nameを付け、dataにアーティファクトを設定し、iconにminecraft:bookなどを選びます。 xpのlevelsに、増加する XP のしきい値(たとえば100、250、500)を入力し、必要に応じてmaxも設定します。weeksに、numberが1で、titleを持つ週を追加し、questsで Quest エントリを選んでxpRewardを設定します。次の週についても繰り返します。scheduleで、start(たとえば2026-11-01T00:00:00)、weekDurationDays、timezone(たとえばEurope/Paris)を設定します。すると、週は順番に解放されていきます。tiersに、levelが1のティアを追加し、rewardsに、levelRequiredが1でdisplayNameを持つ報酬を追加します。報酬を与えるtriggers(たとえば、アイテムを与えるアクション)をリンクします。battlePassで自分の definition を指す Open Battle Pass アクションを追加し、NPC、アイテム、メニューからトリガーします。プレイヤーは/tw battlepassと入力することもできます。- パブリッシュし、その週のクエストを完了して、メニューを開いて報酬を受け取ります。
ティアの level は、報酬メニューでの番号で、definition 内で一意でなければなりません。報酬を受け取るために必要なプレイヤーのレベルは、報酬自身の levelRequired です。ティアには permission を設定できます。それを持たないプレイヤーには、そのティアの報酬がロック中として表示されます。これが、プレミアムトラックの作り方です。
各報酬には id があります。空のままにすると、拡張機能が、ティアのレベルと報酬の位置から ID を生成します(tier-1-reward-1)。しかし、その後で報酬を移動したり挿入したりすると、生成される ID がずれ、プレイヤーの受け取り済みの報酬と一致しなくなります。シーズンが始まる前に、すべての報酬に明示的な id を設定し、決して変更しないでください。
仕組み
XP を獲得できるのは、definition のいずれかの週に列挙されたクエストが COMPLETED になり、その週が available に設定され、その週が解放されていて、シーズンが進行中の場合だけです。xpReward が 0 のクエストは、何も与えません。レベルは、プレイヤーが到達した xp.levels のしきい値の数です。
報酬を受け取れるのは、シーズンが始まっていて(終了後も受け取りは可能です)、プレイヤーのレベルが levelRequired に達していて、ティアの permission が設定されている場合は、それを持っているときです。報酬は 1 回だけ受け取れます。報酬のトリガーが失敗した場合、報酬は保留のままとなり、トリガーには副作用がある可能性があるため、自動では再試行されません。
メニュー
デフォルトでは、拡張機能は独自のインベントリメニューを開きます。週を一覧表示するメインメニュー、選択した週のクエストメニュー、報酬(ティア)メニューです。
- メインメニュー — 週ごとに 1 つのボタン、前の週と次の週のボタン、報酬ボタン、情報ボタン、閉じるボタン。
- クエストメニュー — その週のクエストを、状態(ロック中、利用可能、進行中、完了)とともに表示し、ページボタン、並べ替えボタン、戻るボタンがあります。
- 報酬メニュー — 各ティアの報酬を、状態とともに表示し、ページボタンと戻るボタンがあります。解放済みの報酬をクリックすると、受け取れます。
サイズと位置は layout から決まります。各サイズは、9〜54 の 9 の倍数で、各スロットはその内側に収まっている必要があります。スロットには、単一の数値、または 10-16 のような範囲を指定できます。デフォルトの位置を使うには、スロットを空のままにします(54 スロットのレイアウトで、週は 2 行目、クエストは 2〜4 行目、閉じるはスロット 49)。ボタンをオフにするには、その ...Enabled フィールドを使います。各ボタンは、buttons に、item、name、lore を持ち、{week_title}、{quest_name}、{tier_level}、{reward_state} のような、波括弧のプレースホルダーを使えます。各ボタンで使えるプレースホルダーは、パネルのフィールドヘルプに一覧があります。
baseMenuId、menuLayoutPool、menuViews、menuMainLayoutId を設定すると、パスは、代わりに独自の GUI の土台の中で開かれ、3 つのビュー(ホーム、レベル、クエスト)の ID は、menuHomeViewId、menuLevelsViewId、menuQuestsViewId で設定します。すると GUI エディタには、battlepass_button: のアイテムが表示されます。WEEK_SLOT、TIER_MENU、REWARD_SLOT、CLAIM、QUEST_SLOT、SORT、INFO、PAGE_NEXT、PAGE_PREV、BACK、CLOSE です。エディタ内のボタンタイプの説明は、フランス語です。
メニューのインタラクションは、GUI セッションの内部のものです。Bukkit のコマンドではなく、プレイヤーが入力することはできません。
コマンド
BattlePass のコマンドは、TypeWriter のコマンドのサブコマンドであり、/typewriter またはそのエイリアスの /tw で始まります。基本の権限は typewriter.battlepass です。<pass> 引数は、Battle Pass Definition の ID または名前で、自動補完されます。省略可能な [targets] 引数は、プレイヤーのセレクターです。省略すると、コマンドは送信者に適用されます。
| コマンド | 説明 |
|---|---|
/tw battlepass | ID でソートした最初の definition のメニューを開きます。 |
/tw battlepass menu | /tw battlepass と同じです。 |
/tw battlepass open | /tw battlepass と同じです。 |
/tw battlepass <pass> xp add <amount> [targets] | XP を加算します(量の符号は無視されます)。 |
/tw battlepass <pass> xp remove <amount> [targets] | XP を減算します。 |
/tw battlepass <pass> xp set <amount> [targets] | XP を設定します(0 未満にはなりません)。 |
/tw battlepass <pass> level add <amount> [targets] | レベルを上げます。 |
/tw battlepass <pass> level remove <amount> [targets] | レベルを下げます。 |
/tw battlepass <pass> level set <amount> [targets] | レベルを設定します。 |
/tw battlepass <pass> info [targets] | プレイヤーの、そのパスでの XP とレベルを表示します。 |
権限
| 権限 | 許可される内容 |
|---|---|
typewriter.battlepass | メニューと管理者用サブコマンドを含む、すべての /tw battlepass コマンド。 |
ティアの permission | ティアに設定する、自由に選べる権限。そのティアの報酬を受け取るために必要です。 |
プレースホルダー
これらは、battlepass エクスパンションの MiniPlaceholders のタグで、プレースホルダーに対応する任意の MiniMessage テキストで使えます。def を、Battle Pass Definition エントリの ID に置き換えてください。カウンターは数値で、真偽値は 1 または 0 として返されます。
| プレースホルダー | 返す値 |
|---|---|
<battlepass_name:def> | パスの名前。 |
<battlepass_active:def> | プレイヤーが XP を獲得できる間(シーズン進行中)は 1、それ以外は 0。 |
<battlepass_level:def> | プレイヤーのレベル。 |
<battlepass_xp:def> | プレイヤーの XP。 |
<battlepass_xp_max:def> | XP の上限。上限が設定されていない場合は、最も高いしきい値。 |
<battlepass_xp_next:def> | 次のレベルの XP のしきい値。 |
<battlepass_xp_remaining:def> | 次のレベルに到達するために不足している XP。 |
<battlepass_rewards:def> と <battlepass_rewards_total:def> | 報酬の総数。 |
<battlepass_rewards_claimed:def> | すでに受け取った報酬。 |
<battlepass_rewards_available:def> | プレイヤーが今受け取れる報酬。 |
<battlepass_rewards_unclaimed:def> | 報酬の総数から、受け取り済みの報酬を引いたもの。 |
<battlepass_rewards_pending:def> | 予約されたが、まだ配布されていない報酬。 |
<battlepass_week_state:def:N> | 週 N の状態ラベル。 |
<battlepass_week_active:def:N> | 週 N がロック中でも利用不可でもない場合は 1。 |
<battlepass_week_available:def:N> | 週が available に設定されている場合は 1。 |
<battlepass_week_title:def:N> | 週 N のタイトル。 |
<battlepass_week_description:def:N> | 週 N の説明。 |
<battlepass_week_release:def:N> | 週 N の解放日。 |
<battlepass_week_release_in:def:N> | 週 N が解放されるまでの残り時間。解放後は空。 |
エントリ
5 件のエントリー（拡張機能のソースから生成）。
アクション1
- Open Battle PassOpen a battle pass menu
ファクト1
- Battle Pass Quest ActiveCheck if a battle pass week is active
アーティファクト1
- Battle Pass Data ArtifactStore battle pass runtime data
マニフェスト1
- Battlepass DefinitionRegister a battle pass definition
その他のエントリー1
- Battlepass MessagesBattlePass Messages
トラブルシューティング
拡張機能が読み込まれない。 BattlePass には、Quest、GUI(GuiAndDialogs)、MySQL の拡張機能が必要です。TypeWriter の起動ログで、不足している依存関係を確認してください。
ログに「Ignoring invalid battle pass definition」と出る。 definition が検証に失敗したため、登録されず、/tw battlepass は「Aucun Battle Pass n'est actuellement chargé」と表示します。ログの行には、問題点が列挙されます。空の name、9〜54 の 9 の倍数ではないメニューサイズ、メニューの外にあるスロット、重複したティアのレベル、週の番号、報酬の ID、厳密に増加していない xp.levels、schedule.end より前になっていない schedule.start などです。
クエストを完了しても XP が入らない。 クエストが、definition の週に、0 より大きい xpReward とともに列挙されていて、その週が available で解放されており、シーズンが有効で、definition に data アーティファクトがある必要があります(ない場合、ログに警告が出ます)。不明な timezone は UTC にフォールバックし、解析できない日付の文字列は無視されます。
報酬を受け取れない。 レベルが levelRequired に達していて、プレイヤーがティアの permission を持っていて、シーズンが始まっていて、報酬が受け取り済みでも保留中でもない必要があります。トリガーが失敗した場合、ログに「remains pending after delivery failure」と報告され、管理者が対応を決めるまで、報酬は保留のままです。
報酬を編集した後、受け取り済みの報酬が再び現れる。 位置から生成された報酬の ID が変わりました。すべての報酬に明示的な id を設定し、変更しないでください。
進行状況が保存されない。 アーティファクトの artifactId は、Web パネルが生成した有効な UUID のままである必要があります。拡張機能は、それ以外を使うことを拒否します。保存されたファイルを手で移動したり名前を変更したりしないでください。