Crate
概要
Crate は、サーバーにルートクレートを追加します。クレートは、それぞれにレアリティを持つ報酬のリストを持ち、プレイヤーは仮想キーを消費して開封します。当選する報酬は、アニメーションが始まる前にサーバー側で抽選されるため、開封中にプレイヤーが何をしても、結果を変えることはできません。クレートを開けるとマイルストーンにカウントされ、一定回数の開封後に、追加の報酬をトリガーできます。
報酬は TypeWriter のトリガーなので、アイテムを渡す、コマンドを実行する、コスメティックを付与する、シーケンスを開始する、といったことができます。開封の様子は、プレイヤーの目の前のワールド内に、浮かぶアイテムディスプレイによる報酬のプレビュー、またはカード選びのミニゲームとして表示されます。メニューでは、プレイヤーがクレートと、それぞれが出し得る報酬を閲覧できます。
このエクステンションは、TypeWriter の BTC ビルド（BTC Core、Paper/Folia）上で動作し、ここでは参考情報として文書化されています。
機能
- 重み付き報酬 — レアリティに重みがあり、各報酬の確率がメニューに表示されます。
- 仮想キー — キーはクレートのデータアーティファクトでプレイヤーごとにカウントされ、開封のたびに 1 つ消費されます。
- 安全な開封 — キーは先に確保され、報酬が公開されたときにのみ消費されます。切断、タイムアウト、再起動があった場合は返却されます。
- マイルストーン — 一定回数の開封後に、追加の報酬をトリガーします。
- カードのミニゲーム — 報酬がすでに決まっている状態で、プレイヤーが伏せられたカードのグリッドから 1 枚をめくります。
- ワールド内のプレビュー — 報酬が、
PAGINATED、FLEX、SIMPLEのレイアウトで、任意の NPC とホログラム付きでプレイヤーの周囲に浮かびます。 - メニュー — グローバルなクレートメニューと、クレートごとの報酬メニュー。フレーム、ページ送り、カスタムボタンを備えています。
- 統計 — 開封回数、キー、使用したキー、最後の開封、マイルストーンを、プレースホルダーとして利用できます。
インストール
- TypeWriter の Basic エクステンションと GUI エクステンション（BTC ビルドでは
GuiAndDialogs）をインストールします。これらがないと、Crate は読み込まれません。 - Crate の JAR を
plugins/Typewriter/extensions/に配置し、サーバーを再起動します。 - スタッフに、「パーミッション」セクションのパーミッションを付与します。
はじめに
3 つの報酬を持つクレートを作成し、自分にキーを付与します。
- TypeWriter の Web パネルでマニフェストページを開き、Crate Data アーティファクトを追加します。生成された
artifactIdは保持し、クレートごとに 1 つのアーティファクトを使用します。 - Crate エントリーを追加します。
dataArtifactにアーティファクトを設定し、noKeyMessageを記述します。 raritiesに、重み70のCommonと、重み30のRareを追加します。rewardsに 3 つの報酬を追加します。それぞれに、rarity、プレビューに表示するitem、nameを設定し、actionに報酬を渡すトリガーを指定します。itemを自動的に渡すにはgrantItemをオンのままにし、アクションがアイテムを渡す場合はオフにします。rewardSlotsに、報酬メニューのインベントリスロット（0 から数えます）を、たとえば10-12のように列挙します。報酬スロットがないクレートは、開封を拒否します。iconに、グローバルメニュー内のクレートのxとy、item、nameを設定します。- クレートを指す Open Crate アクションを追加し、NPC、ブロック、アイテムからトリガーします。
- Publish してから、
/tw crate give <crate entry id> 5を実行して、クレートを開きます。クレートを閲覧するには/tw crate menuを使用します。
クレートの報酬メニューでは、報酬をクリックすると、キーを消費することも統計に記録されることもなく、その報酬の action が直接トリガーされます。報酬のアクションが価値のあるものを渡す場合は、プレイヤーが報酬メニューにアクセスできないようにするか、メニューをスタッフ専用にしてください。
キーは /tw crate give <crate> <amount> [targets] で追加します。キー専用のアクションはありませんが、コマンドアクションでこのコマンドを実行できます。たとえば、クエストの報酬やショップから実行できます。
仕組み
報酬の確率は、そのレアリティの重みを、すべての報酬の重みの合計で割ったものです。レアリティが rarities に記載されていない報酬の重みは 1 です。報酬が公開されると、キーが消費され、開封回数と使用キー数のカウンターが増え、通過したマイルストーンが発火し、その後、アイテムが渡され（grantItem がオンの場合）、報酬の action が実行されます。プレイヤーは、同時に 1 つの開封しか行えません。
メニュー
- グローバルメニュー —
/tw crate menuで開きます。クレートごとに 1 つのアイコンを、アイコンのx（0 から 8）とy（0 から 5）の位置に表示し、アイコンをクリックすると、そのクレートの報酬メニューが開きます。任意の Crate Main Menu エントリーで、サイズ、タイトル、フレーム、ボタン、1 ページあたりのアイテム数、ページ送り矢印用に確保する列を設定します。 - 報酬メニュー — アイコンをクリックするか、Open Crate Menu アクションで開きます。
rewardSlotsにある報酬を、名前、ロア、任意の確率行とレアリティ行（chanceLoreとrarityLore、{chance}と{rarity}を使用）とともに表示します。guiLayoutはPAGINATED、FLEX（中央揃え、4 列）、SIMPLEのいずれかです。frameItem、itemsPerPage、paginationColumnでフレームとページ送りを調整し、buttonsでアクション付きのカスタムボタンを追加します。
ボタンにはタイプ（INFORMATION、NEXT、PREVIOUS、FILL）と位置があります。FILL ボタンは、すべての空きスロットにコピーされます。crate_button: マーカー（CRATE_OPEN、CRATE_PREVIEW、CRATE_GLOBAL_BROWSE、CRATE_REWARD_SLOT、NAV_BACK、NAV_CLOSE）は GUI エディターで提供されますが、このバージョンでは、プレースホルダーアイテムを表示するだけです。
設定
Crate に設定ファイルはありません。すべてエントリーで設定します。プレイヤーデータは Crate Data アーティファクトに保存されます。キー、開封回数、使用キー数、最後の開封時刻、マイルストーン、保留中の開封です。書き込みは非同期で行われ、クラッシュで残った保留中の開封は、起動時に復旧されます（キーは返却されます）。
コマンド
すべてのコマンドは TypeWriter コマンドのサブコマンドであるため、/typewriter または /tw で始まります。<crate> はクレートのエントリーで、自動補完されます。
| コマンド | 説明 | パーミッション |
|---|---|---|
/tw crate menu | グローバルクレートメニューを開きます。 | typewriter.crate.menu |
/tw crate open <crate> | キーを 1 つ使って、クレートを開きます。 | typewriter.crate.open |
/tw crate give <crate> [targets] | 自分または選択したプレイヤーに、キーを 1 つ付与します。 | typewriter.crate.give |
/tw crate give <crate> <amount> [targets] | 複数のキーを付与します。 | typewriter.crate.give |
/tw crate remove <crate> [targets] | キーを 1 つ削除します。プレイヤーが持っている場合のみ。 | typewriter.crate.remove |
/tw crate remove <crate> <amount> [targets] | 複数のキーを削除します。プレイヤーが十分に持っている場合のみ。 | typewriter.crate.remove |
基本パーミッション typewriter.crate が、コマンド全体を保護します。エクステンションは、メニューのクリックで使用される内部コマンド /cratemenu を登録しますが、手で入力するためのものではありません。
パーミッション
| パーミッション | 許可される内容 |
|---|---|
typewriter.crate | /tw crate コマンドへのアクセス。 |
typewriter.crate.menu | /tw crate menu。 |
typewriter.crate.open | /tw crate open。 |
typewriter.crate.give | /tw crate give。 |
typewriter.crate.remove | /tw crate remove。 |
プレースホルダー
これらは、crate エクスパンションの MiniPlaceholders タグです。id は、クレートのエントリー ID に置き換えてください。不明なクレートは、空の値を返します。
| プレースホルダー | 戻り値 |
|---|---|
<crate_openings:id> | プレイヤーによる、このクレートの開封回数。 |
<crate_keys:id> | プレイヤーが持っているキー。 |
<crate_keys_used:id> | プレイヤーが使用したキー。 |
<crate_last_open:id> | 最後の開封の時刻。1970 年 1 月 1 日からのミリ秒。 |
<crate_milestone:id> | 到達した最も高いマイルストーン。 |
hologramLines では、代わりにトークン {openings}、{keys}、{last_open}、{milestone} を使用します。
エントリー
6 件のエントリー（拡張機能のソースから生成）。
アクション2
- Open CrateOuvre une caisse
- Open Crate MenuOuvre le menu d'une caisse
アーティファクト1
- Crate ArtifactDonnées de caisse
マニフェスト3
- CrateDéfinition d’une caisse
- Crate Main MenuApparence du menu principal
- Crate Minigame CardsMini-jeu Caisse : Cartes
トラブルシューティング
"This crate is not configured correctly"。 クレートが検証に失敗しました。サーバーログに理由が一覧表示されます。報酬がない、レアリティの重みが無効（0 より大きくなければなりません）、rewardSlots がない、またはスロットが 0 から 53 の範囲外か重複している、ボタンや icon が 9 × 6 のグリッドの外にある、マイルストーンが 0 回か重複している、などです。同じチェックが起動時にも実行され、警告が書き込まれます。
プレイヤーに noKeyMessage が表示される。 プレイヤーがそのクレートのキーを持っていないか、クレートに dataArtifact がありません。/tw crate give でキーを付与し、アーティファクトのリンクを確認してください。
"You are already opening a crate"。 そのプレイヤーの開封が進行中です。報酬が公開されるか、プレイヤーが切断すると終了します。
開封後に、統計とキーが変わらない。 これらが変わるのは、報酬が公開されたときのみです。それより前にプレイヤーが退出したり、サーバーが停止したりした場合は、キーが返却され、カウンターは変わりません。
プレビューに何も表示されない、または間違った報酬が表示される。 プレビューは、各報酬の item を使用します。item が空の報酬はスキップされ、preview.maxVisibleRewards が同時に表示される数を制限します。preview.distance と *Location のオフセットで、ディスプレイの位置を動かせます。
カードのミニゲームが始まらない。 クレートの minigame フィールドに、Crate Minigame: Cards エントリーをリンクしてください。columns は最大 10、rows も最大 10 で、cardCount の上限は 100 です。
報酬が 2 回渡される。 action がアイテムを渡さない場合にのみ、grantItem をオンにしてください。
関連エクステンション
- GUI — クレートメニューで使用されるメニューエンジン。