BoatGP ― OP・運営ガイド¶
BoatGP の導入・config・items.yml・サーキット作成・権限・管理コマンドをまとめます。
基本情報¶
| 項目 | 値 |
|---|---|
| プラグイン名 | BoatGP |
| バージョン | 1.0.0 |
| api-version | 26.1.2 |
| メインコマンド | /race（エイリアス /boatgp） |
| 依存プラグイン | なし |
| 設定ファイル | plugins/BoatGP/config.yml、items.yml、messages.yml、surfaces.yml、circuits/<名前>.yml |
実装状況：Phase 2（アイテムバトル）
現在は Phase 2（アイテムバトル） までが実装済みです。カート物理・路面・チェックポイント判定・順位HUD・コース外復帰・簡易報酬に加え、アイテムシステム（6種）・アイテムボックス・ラバーバンド抽選・ボスバー表示・ロケットスタート が動作します。ベストタイム記録・リーダーボードなどは未実装です。詳細は下記「実装状況」の節を確認してください。
導入手順¶
- ビルドした
boatgp-1.0.0.jarをサーバーのplugins/フォルダに配置する。 - サーバーを起動すると
plugins/BoatGP/にconfig.yml/items.yml/messages.yml/surfaces.ymlが自動生成され、circuits/フォルダが作られる。 - レース専用ワールド（フラットまたはボイド推奨）を用意する。
- 後述の手順でサーキットを作成する（アイテムボックスの配置を含む）。
- 設定を変更したら
/race reloadで再読み込みする。
既存サーバーを更新する場合の注意（messages.yml）
messages.yml は 既存ファイルがあると新しいメッセージキーが自動追記されません。アップデートで sign:（看板。join-created / leave-created / start-created / info-created / look-at-sign / no-circuit / invalid-type）・admin.startspawn-set / finish-a-set / checkpoint-a-set・lobby.rejoin / lobby.waiting-next（連続プレイ）・show:（チェックポイント表示）・admin.checkpoint-deleted / finish-deleted / checkpoints-cleared / spawn-deleted / spawn-cleared（削除系）が追加されています。特に 情報看板を使う場合は sign.info-created / sign.invalid-type が必須 です。これらが空欄表示になる場合は、既存の messages.yml を一度退避してサーバー再起動で再生成するか、不足キーを追記してください。config.yml・items.yml・surfaces.yml の項目は今回変更ありません。
サーバー実装について
エンティティ（ボート）を多用するミニゲームのため、設計上は Paper の採用が推奨 されています。Spigot でも動作しますが、イベント処理・最適化の面で Paper が有利です。
config.yml 主要項目¶
レース設定（race）¶
| キー | 既定値 | 説明 |
|---|---|---|
race.min-players |
1 | レース開始に必要な最少人数（同梱configは実験用に1。通常運用は2以上推奨） |
race.max-players |
12 | 1レースの最大人数（実際の上限はスタートグリッド数で決まる） |
race.lobby-countdown |
30 | 最少人数到達後、ロビーで開始までカウントする秒数 |
race.start-countdown |
3 | スタートグリッド整列後の 3-2-1 カウント秒数 |
race.default-laps |
3 | サーキット側で周回数未指定の場合の既定周回数 |
race.finish-timeout |
60 | 1位ゴール後、残り走者を待つ制限時間（秒）。超過で強制終了 |
カート物理（kart）¶
| キー | 既定値 | 説明 |
|---|---|---|
kart.acceleration |
0.10 | 1tickあたり現在速度を目標速度へ近づける割合 |
kart.deceleration |
0.18 | 1tickあたりの減速割合 |
kart.default-grip |
0.85 | 既定グリップ（路面側で上書きされる） |
kart.stuck-speed-threshold |
0.04 | この移動量（blocks/tick）未満が続くとスタック判定 |
kart.stuck-ticks |
60 | スタックと判定するまでの継続tick数 |
kart.off-track-reset |
true | コース外・危険路面・落下・スタック時にチェックポイントへ復帰させるか |
kart.void-y |
0 | このY座標を下回ったら落下とみなし復帰 |
kart.corner-speed |
0.72 | 操舵中（パドル左右入力中）の速度倍率。小さいほどコーナーで減速して曲がりが詰まる（推奨 0.6〜0.85） |
ワールド・HUD・報酬¶
| キー | 既定値 | 説明 |
|---|---|---|
world.default |
"race_world" |
レース専用ワールド名（サーキットyml側の指定が優先） |
hud.update-interval |
10 | HUD（スコアボード）の更新間隔（tick／20=1秒） |
reward.enabled |
true | 順位連動の簡易報酬を有効にするか |
reward.places.p1 〜 p3 |
DIAMOND:3 ほか |
1〜3位の報酬アイテム（Material名:個数） |
reward.finish |
BREAD:2 |
4位以下の完走者への参加賞 |
報酬の指定形式
報酬は Material名:個数 の形式で指定します（例: DIAMOND:3）。経済プラグイン連携は行わず、報酬はすべてプラグイン内で完結します。reward.places.p4 以降を追加すれば、その順位専用の報酬も指定できます。
items.yml 主要項目（アイテムバトル）¶
アイテムシステムの設定は plugins/BoatGP/items.yml にまとめられています。/race reload で再読み込みされます。
アイテムボックス・ロケットスタート¶
| キー | 既定値 | 説明 |
|---|---|---|
item-box.cooldown-ticks |
80 | アイテムボックス通過後、再出現までのtick数（20=1秒） |
item-box.default-radius |
3.0 | additembox で半径を省略したときの既定判定半径 |
rocket-start.window-ticks |
11 | GO の何tick前から「良いタイミング」とみなすか |
rocket-start.boost-speed |
2.1 | ロケットスタート成功時のブースト速度 |
rocket-start.boost-ticks |
45 | ロケットスタート成功時のブースト継続tick数 |
アイテムの出現重み（ラバーバンド）¶
items.<アイテム> の weight-front / weight-mid / weight-back で、順位帯（上位／中位／下位）ごとの抽選重み を設定します。値が大きいほど出やすく、0 で出現しません。下位ほど強力なアイテムが出るよう重み付けされています。
| アイテム | weight-front（上位） | weight-mid（中位） | weight-back（下位） |
|---|---|---|---|
dash_mushroom（ダッシュキノコ） |
30 | 28 | 16 |
green_shell（みどりこうら） |
26 | 20 | 10 |
red_shell（あかこうら） |
4 | 18 | 24 |
banana（バナナ） |
34 | 19 | 8 |
star（スター） |
2 | 10 | 22 |
lightning（サンダー） |
0 | 5 | 20 |
各アイテムの display で、ボスバー等に表示される名前（& カラーコード対応）を設定できます。
アイテム効果パラメータ（effects）¶
| キー | 既定値 | 説明 |
|---|---|---|
effects.dash-boost-speed / dash-boost-ticks |
1.95 / 50 | ダッシュキノコの加速量・継続tick |
effects.green-speed / green-lifetime |
1.7 / 110 | みどりこうら（直進弾）の速度・寿命tick |
effects.red-speed / red-lifetime / red-homing |
1.45 / 150 / 0.30 | あかこうら（ホーミング弾）の速度・寿命・追尾の強さ |
effects.banana-lifetime |
700 | バナナ（後方トラップ）が残るtick数 |
effects.star-ticks / star-boost-speed |
150 / 1.8 | スターの無敵＋加速の継続tick・加速量 |
effects.lightning-slow-ticks |
70 | サンダーで全員が減速するtick数 |
effects.spinout-ticks |
32 | 命中時のスピンアウト継続tick |
effects.hit-radius |
2.2 | 弾・トラップ・体当たりの命中半径 |
アイテムの操作仕様
アイテムの発動は 降車操作（VehicleExitEvent）の再利用 で実装されています。レース中の降車ボタン押下＝所持アイテムの発動、カウントダウン中の降車ボタン押下＝ロケットスタート判定になります。Java版・統合版の双方で同じ操作になるよう設計されています。
路面定義（surfaces.yml）¶
路面は「見た目のブロック」ではなく「最高速＋グリップ」のパラメータで定義します。surfaces.yml でブロックの割り当てを自由に編集できます。
| 路面区分 | speed |
grip |
既定の対象ブロック |
|---|---|---|---|
standard（標準） |
0.85 | 0.90 | 石・石レンガ・コンクリート・草ブロック など |
ice（氷） |
1.25 | 0.55 | 青氷・氷塊・氷 |
boost（ブースト） |
1.90 | 0.95 | 薄水色／黄色コンクリート |
offroad（オフロード） |
0.35 | 0.80 | 砂・赤い砂・ソウルサンド・砂利・土の道 など |
danger（危険） |
0.0 | 0.50 | マグマ・マグマブロック・水（reset: true で復帰トリガー） |
未定義ブロック上の挙動は default-surface（既定 standard）で決まります。
サーキット作成手順¶
コマンド体系が刷新されました
従来の /race admin <サブ> 方式に加え、/race <サブ> のトップレベル形式 で実行できるようになりました（/race admin <サブ> も引き続き使えます）。また 変更は自動保存 されるため、save の実行は不要です。チェックポイント／ゴールラインは 半径の円ではなく「A→Bの2点で引くライン（ゲート）」 に変更され、コースを横切る直線として通過判定するようになりました。さらに 看板での参加・離脱・開始（setsign / setstart）と 初期スポーン（setstartspawn）に対応しています。
サーキットは /race コマンドで作成し、plugins/BoatGP/circuits/<名前>.yml に保存されます。yml の手書きは不要です。OP権限を持った状態でレース専用ワールドに入り、設置したい地点に立って（またはラインの端点に立って）コマンドを実行します。
標準フロー（create → setlobby → setstartspawn → setspawn → setfinish a/b → addcheckpoint a/b → additembox → setsign/setstart → laps）:
ラインの引き方（setfinish / addcheckpoint）
ゴールラインとチェックポイントは a（始点）→ b（終点）の2回 でコースを横切る直線として引きます。コースの片端に立って ... a、反対の端に立って ... b を実行してください。高さ（Y許容）は ... b [高さ] で指定でき、省略時は ±4.0 ブロックです。通過判定は「前tick→現tick の移動線がラインを横切ったか」で行うため、コース幅いっぱいにラインを張る とショートカット防止になります。addcheckpoint は先に setfinish でゴールラインを引いてから実行してください。
保存（自動）と有効化の条件
各設定コマンドは実行のたびに 即時自動保存 されます（save は不要、cancel で編集破棄）。レース開始に使える状態になる条件は ロビー地点・スタートグリッド1個以上・チェックポイント2個以上（ゴールライン＋通常CP） です。setstartspawn・アイテムボックス・看板は必須ではありません（初期スポーン未設定時は離脱時の戻り先がロビーになります）。/race status で不足項目を確認できます。
アイテムボックスの配置
additembox は 任意 です。置かないサーキットも走行できます（その場合アイテムは出現しません）。半径を省略すると items.yml の item-box.default-radius（既定3.0）が使われます。
チェックポイントとスタートグリッド
チェックポイントの index0 は必ずゴールライン（setfinish）です。addcheckpoint でコースの進行順にラインを追加します。スタートグリッド数（setspawn の数）が そのサーキットの実質の最大参加人数 になります（config.yml の race.max-players と、グリッド数の小さい方が上限）。設計上はコース幅7ブロック前後・壁の高さ3ブロック以上・1周400ブロック前後が目安です。
チェックポイントの可視化（/race show）¶
チェックポイント／ゴールラインは パーティクルの「ゲート（縦のカーテン）」 として表示されるようになりました。色はゴール/スタート=金、次に通過すべきCP=緑、その他=水色です。表示は 見ている本人だけ に出ます（他プレイヤーには見えません）。
- レース中の参加者には自動表示 されます（次に通過すべきCPが緑で強調）。
- OPは設定確認用に、同じワールドの全サーキットのゲートを プレビュー表示 できます。
表示範囲
ゲートは約60ブロック以内のものだけが描画されます。ライン（A→B）がコースを正しく横切っているか、/race show をONにして歩きながら確認すると設置ミスに気づきやすくなります。
チェックポイント・スタートグリッドの削除¶
設置をやり直したいとき用に、削除コマンドが追加されました（いずれも自動保存）。
看板の設置（参加・離脱・開始・情報）¶
プレイヤーは 看板のクリック でも参加・離脱・開始できます（コマンド /race join 等も併用可）。看板の作成には 2通りの方法 があります。どちらも boatgp.admin 権限が必要です。
方法A：コマンドで設定（参加・離脱・開始）¶
看板を設置し、看板を見ながら（6ブロック以内）以下を実行すると、プラグインが自動でテキストを書き込みます。
setsign / setstart は引数でサーキットを明示することもできます（省略時は編集中のサーキット）。
方法B：看板に直接書き込んで作成（参加・離脱・情報）¶
新規に設置する看板へ、行を手入力しても作成できます。1行目に [boatgp]（大文字小文字不問）、2行目に種別、3行目にサーキット名を入れて確定すると、プラグインが整形済みテキストへ自動的に書き換えます。
[boatgp]/join/<サーキット名>… 参加看板（コース名は登録済みである必要があります）[boatgp]/leave… 離脱看板（3行目は不要）[boatgp]/info/<サーキット名>… 情報看板（後述）
方法Bでは開始看板（START）は作れません
看板への直接書き込みで作れるのは join / leave / info の3種です。開始看板（START）はコマンド /race setstart でのみ作成 できます。2行目に上記以外を入れるとエラーになります。
情報看板（[BoatGP-Info]）¶
方法Bの info で作成する 情報看板 は、指定サーキットの 募集状況と参加人数を約5秒ごとに自動更新 して表示します（クリック動作はありません）。
- 表示内容：状態（募集中／開始間近／進行中／終了）と「現在人数 / グリッド数」。
- 設置後すぐに1度更新され、以降は5秒間隔で最新化されます。
看板の仕組み
クリック動作のある看板は1行目に [BoatGP] タグ、2行目に種別（JOIN / LEAVE / START）、3行目にコース名が入ります。情報看板は1行目が [BoatGP-Info] になります。クリック判定は 看板のテキスト で行うため、設置位置は自由です。setsign 実行時に編集中のサーキット（または引数で指定したサーキット）名が書き込まれます。開始看板は誰でもクリックできますが、強制開始は内部で boatgp.admin を確認します（参加者がいないと開始されません）。クリック看板には連打防止のため1秒のクールダウンがあります。
権限ノード¶
| 権限 | 既定 | 用途 |
|---|---|---|
boatgp.play |
全員 | レースに参加できる |
boatgp.admin |
OP | サーキットの作成・管理、レース強制操作（start/stop/reload/admin） |
管理コマンド¶
| コマンド | 権限 | 説明 |
|---|---|---|
/race start |
boatgp.admin |
自分が参加中のレースを強制開始する |
/race stop |
boatgp.admin または OP |
自分が参加中のレースを強制中止する（OP は権限ノードなしでも実行可） |
/race reload |
boatgp.admin |
config.yml・items.yml・surfaces.yml・サーキットを再読み込み |
/race create <名前> |
boatgp.admin |
新規サーキットを作成して選択する |
/race select <名前> |
boatgp.admin |
既存サーキットを編集対象に選択する（edit も可） |
/race setlobby / setstartspawn / setspawn |
boatgp.admin |
ロビー・初期スポーン・スタートグリッドを現在地に設定 |
/race setfinish <a\|b> / addcheckpoint <a\|b> |
boatgp.admin |
ゴールライン・チェックポイントを2点ラインで設定 |
/race delcheckpoint <番号> / delfinish / clearcheckpoints |
boatgp.admin |
チェックポイント／ゴールの削除・全消去 |
/race delspawn <番号> / clearspawn |
boatgp.admin |
スタートグリッドの削除・全消去 |
/race additembox [半径] / laps <数> / world [名前] |
boatgp.admin |
アイテムボックス追加・周回数・対象ワールド |
/race setsign <join\|leave> / setstart |
boatgp.admin |
看板を参加／離脱／開始看板に設定 |
/race show |
boatgp.admin |
チェックポイント表示プレビューのON/OFF（自分のみ） |
/race status |
boatgp.admin |
設定状況を確認する（info も可） |
/race admin <サブ> ... |
boatgp.admin |
上記設定コマンドの旧形式（互換のため引き続き使用可） |
/race join [サーキット名] |
boatgp.play |
レースに参加する（看板クリックでも可） |
/race leave |
boatgp.play |
レースから離脱する（看板クリックでも可） |
/race list |
全員 | サーキット一覧を表示する |
自動保存・強制開始・強制中止について
設定系コマンドは 実行のたびに自動保存 されるため save は不要です（/race cancel で編集破棄）。/race start と /race stop は コマンド実行者が参加中のレース に作用します。設定（config・items.yml・路面・サーキット）を変更したら /race reload で反映できます。
実装状況（Phase 2）¶
実装済みは Phase 2（アイテムバトル） までです。具体的には「カート物理（オート加速・路面システム）／ライン（A→B 2点）方式のチェックポイント・ラップ判定／チェックポイントのパーティクル可視化（レース中は自動・OPは /race show でプレビュー）／順位計算・サイドバーHUD／スタート演出（3-2-1-GO）／コース外・スタック復帰／順位連動の簡易報酬／サーキット作成・削除コマンド（フラット化・自動保存）／看板での参加・離脱・開始／初期スポーン（離脱時の戻り先）／レース終了後の自動ロビー帰還・連続プレイ／アイテムシステム6種・アイテムボックス・ラバーバンド抽選・ボスバー表示・ロケットスタート」が動作します。
未実装の主要機能（Phase 3 以降予定）
以下は 未実装 です。本番イベントでの利用前に必ず把握してください。
- ドリフト／ミニターボ
- コース別ベストタイム・勝利数などの記録永続化（SQLite）、リーダーボード
- カートスキン／トレイルなどのカスタマイズ
- 同時複数レースのインスタンス化、コース投票、トーナメントモード
なお、設計案にあった「ニセアイテムボックス・トリプルキノコ・ゲッソー・キラー」は現バージョンでは未実装で、コアアイテム6種（ダッシュキノコ・みどりこうら・あかこうら・バナナ・スター・サンダー）のみが動作します。
トラブルシューティング¶
レースに参加できない / サーキットが見つからない
/race list でサーキットが登録されているか確認してください。1件もない場合は /race create <名前> から作成が必要です。また、サーキットの対象ワールドが読み込まれていないと参加できません。
サーキットが「設定OK」にならない / レースが始められない
レース開始に使える条件は ロビー・スタートグリッド1個以上・チェックポイント2個以上 です。/race status で不足項目を確認し、/race setlobby / setspawn / setfinish a→b / addcheckpoint a→b で補ってください（変更は自動保存されます）。アイテムボックス・初期スポーン・看板は必須ではありません。
チェックポイント（ライン）が通過判定されない
ゴールライン・チェックポイントは a→b の2点で引いたライン をコースを横切る形で通過する必要があります。ラインがコース幅をまたいでいない、または高さ（Y許容）が足りないと通過になりません。/race setfinish a→反対側で setfinish b、addcheckpoint a→b の順で、コース幅いっぱいに引いてください。高さは ... b [高さ] で調整できます（既定±4.0）。
看板をクリックしても参加・開始できない
/race setsign join（または setstart）で看板を設定済みか確認してください。看板の1行目が [BoatGP] タグになっている必要があります（情報看板の [BoatGP-Info] はクリック動作がありません）。看板を直接書き込んで作る場合は1行目 [boatgp]・2行目 join/leave/info で確定します（START は /race setstart でのみ作成）。開始看板は内部で boatgp.admin 権限を確認するため、一般プレイヤーがクリックしても開始できません。クリック直後は1秒のクールダウンがあります。
アイテムボックスを通ってもアイテムが出ない
そのサーキットに additembox でアイテムボックスが追加されているか /race status で確認してください。また、プレイヤーが すでにアイテムを所持している とアイテムボックスは反応しません。取得直後のボックスは items.yml の item-box.cooldown-ticks（既定80tick）の間は再出現しません。
看板や設定のメッセージが空欄 / 表示されない
既存サーバーで messages.yml をそのまま使っている場合、新しい sign: や admin.startspawn-set などのキーが無いと空欄表示になります。messages.yml を退避して再生成するか、不足キーを追記してください（導入手順の注意書きを参照）。
アイテムの出現バランスを変えたい
items.yml の items.<アイテム>.weight-front / weight-mid / weight-back を編集し、/race reload で反映してください。0 にするとその順位帯では出現しなくなります。効果の強さは effects.* で調整できます。
レースが満員になる / 参加人数を増やしたい
実際の上限は スタートグリッド数 と config.yml の race.max-players の小さい方です。人数を増やしたい場合は /race setspawn でスタートグリッドを追加してください。
カートの挙動がおかしい / 壁をすり抜ける
カート駆動は setVelocity ベースのため、高速移動時にチャンク境界や壁ですり抜けが起きる可能性があります。設計上は 壁を厚く・高く（3ブロック以上）、サーキット範囲のチャンクを常時ロードすることが推奨されています。
コースアウト復帰が頻発する / 復帰してほしくない
危険路面・落下・スタックで直近チェックポイントへ復帰します。挙動を止めたい場合は config.yml の kart.off-track-reset を false に、落下判定のしきい値は kart.void-y で調整できます。スタック判定は kart.stuck-speed-threshold と kart.stuck-ticks で調整します。
氷やブーストが効かない / 路面の挙動を変えたい
路面はブロック種別で判定されます。surfaces.yml で対象ブロックや speed・grip を編集し、/race reload で反映してください。未定義ブロックは default-surface の挙動になります。