Rewards
概要
Rewards は、獲得したもののまだ受け取っていない報酬の、プレイヤーごとのキューを保持します。その場でアイテムを渡したりコマンドを実行したりする代わりに、報酬をキューに入れます。プレイヤーは後で、オンラインでインベントリに空きがあるときに、メニューから受け取ります。報酬が付与された時点で、プレイヤーがオフラインだったり、インベントリがいっぱいだったりしても、何も失われません。
報酬は、1 度だけ定義するテンプレート（報酬デフィニション: 表示アイテム、ロア、必要な空きスロット、受け取り時に実行するアクション）です。付与すると、小さなレコードがキューに追加され、受け取るとそのレコードが削除されて、デフィニションにリンクした TypeWriter のアクションがトリガーされます。受け取り時の効果は TypeWriter のアクションのリストなので、報酬は、アイテム、お金、クエストのステップなど、TypeWriter がトリガーできるあらゆるものを与えることができます。
キューは、1 つのアーティファクトに保存されます。MySQL エクステンションが Redis を提供している場合、同じストレージを共有するサーバーには、保存のたびにアーティファクトの再読み込みが通知されるため、あるサーバーで付与された報酬を、別のサーバーで受け取ることができます。
機能
- 受け取りの繰り延べ — 報酬は、プレイヤーが受け取るまで、キューで待機します。
- 報酬デフィニション — 報酬タイプごとの再利用可能なテンプレート。表示アイテム、名前、ロア、必要な空きスロット数を設定できます。
- 受け取りアクション — 受け取ると、コンソールコマンドの代わりに、任意の TypeWriter アクションのリストがトリガーされます。
- 単体の受け取りメニュー — 報酬スロット、情報スロット、ページボタン、一括受け取り、戻るボタンを備えた、ページ分割されたインベントリ。
- 埋め込み可能なボタン — 報酬スロットと一括受け取りボタンは、ボタンタイプを通じて、任意の GUI ページに配置できます。
- cron による付与 —
btc_give_rewardは、プレイヤーごとに、cron の期間につき最大 1 回、報酬を付与できます（毎日、毎週の報酬）。 - 受け取りイベント — 受け取りのたびに、報酬 ID、カスタムデータ、カウンターを持つイベントエントリーが発火します。
- 保留数のファクトとプレースホルダー — クライテリア、スコアボード、メニューでキューを利用できます。
- スパム対策 — 同じプレイヤーの受け取りの間に、500 ミリ秒のクールダウンがあります。
インストール
- GUI エクステンション（ビルドでのプラグイン名は
GuiAndDialogs）と MySQL エクステンションをインストールします。どちらも Rewards の依存関係として宣言されています。Redis は、サーバー間の更新にのみ使われ、単一のサーバーでは不要です。 - Rewards の JAR を
plugins/Typewriter/extensions/に配置し、サーバーを再起動します。 - 任意で、MiniMessage テキストで
rewardsプレースホルダーを使うために、MiniPlaceholders をインストールします。
はじめに
プレイヤーがメニューから受け取る、毎日のログイン報酬を設定します。
- TypeWriter の Web パネルでスタティックページを開き、Rewards Artifact を追加します。追加するのは 1 つだけにしてください。プレースホルダーと埋め込みボタンは、最初に見つかったものを使用します。
- メッセージと報酬のロアのレイアウトを調整するために、Rewards Config エントリーを追加します（これも 1 つだけ）。
- Reward Definition を追加します。
rewardIdをdaily_login、sourceをdaily_loginに設定し、displayItemを選んで、onClaimActionsに、報酬を与えるアクションをリンクします。 - Give Reward アクションを作成します。
artifactとrewardをリンクし、useCronを有効にして、1 日 1 回にするにはcronExpressionを0 0 0 * * *に設定します。参加イベントや NPC からトリガーします。 - 同じ
artifactを持つ Open Rewards Menu アクションを作成し、コマンドや NPC からトリガーします。 - Publish します。付与をトリガーしたプレイヤーには、保留中の報酬が 1 つ入り、メニューでそれをクリックすると受け取れます。
プレイヤーに受け取るものがある間だけ通知を表示するには、クライテリアで Has Pending Rewards を使用します。
仕組み
キューには、rewardId、付与時刻、カスタムデータのみが保存されます。メニューに表示されるアイテムと実行するアクションは、表示時または受け取り時に、常にデフィニションから読み取られます。デフィニションが削除されたキュー内の報酬は、表示されず、受け取ることもできません。
メニュー
Rewards は、同じ受け取りロジックを共有する、2 つの方法で表示できます。
単体のメニュー。 Open Rewards Menu は、rows が 1 から 6 の、専用のインベントリを開きます。保留中の報酬は、rewardSlotsConfig（範囲、または useRange がオフの場合は明示的なスロットのリスト）を順に埋めます。報酬の数がスロット数を超える場合、メニューはページ分割され、任意の previousPageButton と nextPageButton が使われます。任意の infoSlot、bulkClaimButton、backButton には、スロット番号、アイテム、MiniMessage の名前とロアを設定します。backButton.command は、プレイヤーとして（先頭のスラッシュなしで）実行されます。メニューを閉じるだけにするには、空のままにします。空のスロットは、backgroundItem が設定されている場合、それで埋められます。スロット番号は、左上の 0 から始まり、最初の行の 8 まで、次に 9 から 17、というように続きます。
任意の GUI ページ上のボタン。 GUI メニューで、アイテムの buttonType を Rewards のマーカーのいずれかに設定します。設定したアイテムは、位置とスタイルを保持し、報酬スロットでは、報酬自身の表示アイテムに置き換えられます。
| ボタンタイプ | 動作 |
|---|---|
rewards_button:REWARD_SLOT#<n> | 閲覧者の n 番目（0 から数えます）の保留中の報酬を表示します。左クリックで受け取ります。最後の報酬より先では、スロットは空になります。 |
rewards_button:BULK_CLAIM | 左クリックで、プレイヤーに空きがある限り、保留中のすべての報酬を受け取ります。 |
どちらのモードでも共通する、受け取りのルール:
- 報酬には、プレイヤーのインベントリに
requiredInventorySlots個の空きスロットが必要です（0 はチェックなし）。空きが足りない場合、受け取りは拒否され、inventoryFullMessageが送信されます。 - 受け取ると、デフィニションの
onClaimActionsがトリガーされ、その後、すべての Reward Claimed イベントエントリーが発火します。一括受け取りは、キューの最後の報酬から最初の報酬の順に進み、報酬 IDbulk_claimで、イベントを 1 回発火します。 - 成功メッセージと一括メッセージは、Rewards Config エントリーから取得されます。埋め込みボタンでは、最初に見つかった Rewards Config エントリーが使用されます。
報酬アイテムのロアは、デフィニションの additionalLore、続いて区切り線と、ソースおよび必要スロットの行、最後に締めのヒントから構成されます。ラベルは Rewards Config エントリーから取得されます。
プレースホルダー
MiniPlaceholders のエクスパンション rewards で、MiniMessage テキストでタグとして使用できます。
| プレースホルダー | 戻り値 |
|---|---|
<rewards_pending> | プレイヤーの保留中の報酬の数。 |
<rewards_pending:rewardId> | この rewardId を持つ保留中の報酬の数。 |
<rewards_source:source> | デフィニションがこの source を持つ保留中の報酬の数（大文字小文字は区別されません）。デフィニションが削除された報酬はカウントされません。 |
<rewards_claimed_total> | プレイヤーが受け取った報酬の合計数。 |
報酬 ID はタグの引数です。<rewards_pending_daily_login> ではなく、<rewards_pending:daily_login> と記述してください。Rewards Artifact が存在しない場合、すべてのプレースホルダーは何も返しません。
エントリー
7 件のエントリー（拡張機能のソースから生成）。
アクション2
- BTC Give RewardAdds a reward to a player's pending queue (with optional cron scheduling)
- BTC Open Rewards MenuOpens the rewards queue menu for a player
イベント1
- BTC Reward Claimed EventTriggered when a player successfully claims a reward
ファクト1
- BTC Has Pending RewardsReturns the count of pending rewards for a player
アーティファクト1
- BTC Rewards ArtifactStores pending rewards and claim history for all players
マニフェスト2
- BTC Reward DefinitionDefines a reward type that can be given and claimed by players
- BTC Rewards ConfigGlobal configuration for the rewards system (sounds, toasts, messages)
トラブルシューティング
メニューが開かず、ログに GUI Extension がインストールされていないと表示される。 btc_open_rewards_menu は、実行時に GUI エクステンションを必要とします。インストールして再起動してください。artifact フィールドが空の場合も、このアクションは警告を出して何もしません。
Give Reward が何も起こさない。 アクションに artifact または reward がない場合、あるいはリンクされたデフィニションの rewardId が空の場合、ログに警告が出力されます。3 つのフィールドを入力してください。
cron の報酬が 1 回しか付与されない。 useCron がオンの場合、最後の付与時刻は、プレイヤーごと、アクションエントリーごとに保存されます。次の付与は、その時点以降で、次に cron 式が一致した後にのみ行われます。短い式でテストするか、スケジュールごとに別のアクションエントリーを使用してください。
保留中の報酬が見えない、または受け取れない。 メニューは、rewardId でデフィニションが見つからないキュー内の報酬をスキップします。報酬が付与された後に、デフィニションの rewardId を変更しないでください。
インベントリがいっぱいのメッセージで、受け取りが拒否される。 プレイヤーの空きスロットが、requiredInventorySlots より少なくなっています。このチェックは、防具とオフハンドのスロットを含め、プレイヤーのインベントリオブジェクトのすべての空きスロットをカウントする点に注意してください。
トースト、サウンド、noRewardsMessage、onClaimFailActions が効かない。 これらのフィールドは Rewards Config と Reward Definition に存在しますが、このバージョンのコードは読み取りません。適用されるのは、受け取り、インベントリがいっぱい、一括のメッセージと、ロアのレイアウトだけです。
報酬が別のサーバーに表示されない。 サーバー間の更新は、MySQL エクステンションの Redis と、両方のサーバーが同じアーティファクトストレージを読み取ることに依存しています。Redis がない場合、各サーバーは、再起動するまで、自分のコピーしか見えません。