====== MinecartSpeedPlus (YSSカスタム版) ======

===== 概要 =====
{{:仕様・機能:スクリーンショット_2026-05-10_071255.png?400|}}
MinecartSpeedPlus (MSP) は、トロッコの走行速度を看板を使って制御することが可能なプラグインです。
YSSサーバーでは、停車時間や自動発車、なめらかな加減速を看板から制御できるよう、当サーバー専用にカスタムしています。
バニラの物理演算を尊重しつつ、指定時間での滑らかな加減速（フェード）や定速維持（クルーズコントロール）、特定のアイテムを所持していると通過する「快速・急行システム」などを搭載しています。

また、現在のカスタム版では高速走行時の安定性を向上させるため、トロッコ内部の速度上限を拡張し、30m/s付近で速度が頭打ちになりにくいよう調整されています。
さらに、看板制御中のトロッコが高速カーブなどでレールから外れた場合、近くのレールへ戻す脱線保護機能も追加されています。

**【重要なお知らせ：丸石加速の廃止】**
以前まで存在していた**「丸石の上にパワードレールを置くと2倍速になる」仕様は、挙動安定化・脱線防止のために廃止されました。** 現在はすべて本プラグインの看板によって安全に速度が制御されます。
以前の加速システムを使用している路線管理者の方は、申し訳ありませんが、こちらの機能を使った制御への移行をお願いいたします。

===== 主な機能 =====
  * **速度変更と定速維持:** 看板を通過したトロッコの最高速度を変更し、自然減速させずにその速度を一定に保ちます。
  * **フェード機能:** 指定した秒数をかけて、滑らかに目標速度へ加速・減速します。
  * **ウェイト機能:** 駅のホームなどで指定秒数トロッコを完全停止させ、その後自動で再発進させます。
  * **快速・急行システム:** 指定のアイテムを左手（オフハンド）に持っていると、各駅停車の駅（wait）を無視して通過します。
  * **高速走行対応:** 通常のトロッコ速度上限を拡張し、オーバークロック速度でも頭打ちになりにくくしています。
  * **カーブ減速保護:** 高速でカーブへ進入した場合、設定された安全速度まで自動的に減速します。
  * **脱線復帰保護:** 看板制御中のトロッコがレール外へ出た場合、近くのレールへ戻す保護機能があります。

===== 使い方：看板の書き方 =====
信号が入力されている**パワードレール（加速レール）**に隣接するブロックに看板を設置し、以下のように記述します。通過したトロッコに自動で効果が付与されます。

==== 基本の速度変更 ====
通過した瞬間から指定した速度へ変更し、以降はその速度を維持して走り続けます（クルーズコントロール）。
<code>
[msp]
2.0
</code>
  * 1行目： ''[msp]'' （必須・大文字小文字問わず）
  * 2行目： 目標の速度倍率 （例：''1.0'' がバニラの通常速度、''2.0'' が2倍速、通常最高''4.0''まで）

==== フェード（徐行・加速）機能 ====
指定した秒数をかけて、ゆっくりと目標の速度へ変化します。
<code>
[msp]
1.5
fade 3.0
</code>
  * 3行目 または 4行目： ''fade <秒数>'' （例：''fade 3.0'' で3秒かけて1.5倍速へ加速します）
  * ※fadeの記載がない場合は、通過した瞬間に即座に目標速度に到達します。

==== 一時停止（ウェイト）からの再発進 ====
トロッコを一度「完全停止」させ、指定秒数後に元の進行方向へ自動で再発進させます。フェード機能との併用も可能です。
<code>
[msp]
1.0
wait 5
fade 2.0
</code>
  * 3行目 または 4行目： ''wait <秒数>'' （例：''wait 5'' で5秒間停止）
  * 上記の例では「5秒間停車したのち、2秒かけて1.0倍速まで滑らかに発進」します。

==== 快速・急行システム ====
プレイヤーがトロッコに乗車し、**左手（オフハンド）に指定の特急券アイテム「金インゴット」を持っている場合**、看板の ''wait'' 指定を無視して通過します。※速度変更のみが適用されます。

**【急行停車駅（必ず停まる駅）の作り方】**
急行列車も必ず停車させたい駅の場合は、看板に ''exp'' というキーワードを追記します。
<code>
[msp]
1.0
wait 5 exp
</code>
  * このように記述すると、金インゴットを持っていても通常通り5秒間停車します。
  * ''wait 5'' と ''exp'' は、別々の行に分けて書いても機能します。

**💡 応用テクニック：乗車中の降車駅変更**
特急券（金インゴット）の判定は、**駅の看板を通過する瞬間の左手の状態**でチェックされます。
この仕様を利用し、本来は通過してしまう各駅停車の駅であっても、**到着する前に金インゴットをインベントリにしまう（左手から外す）ことで、好きな駅を目的地として停車し降りることが可能**です。

===== コマンド =====
  * ''/msp <速度倍率>''
    * 説明： デフォルト速度倍率を一時的に変更します。
    * 注意： サーバーを再起動するとconfig.ymlの設定値に戻ります。
    * 権限： OPのみ

  * ''/msp reload''
    * 説明： config.yml を再読み込みします。
    * 権限： OPのみ

  * ''/msp item <アイテムID>''
    * 説明： 現在の版では、急行（特急券）アイテムは config.yml の ''express-item'' で管理します。
    * 注意： コマンドからの変更は行わず、設定ファイルを変更して ''/msp reload'' を実行してください。
    * 権限： OPのみ

===== 路線建設時の注意事項 =====
  - **パワードレール必須：** 本プラグインの看板機能は、**信号がONになっているパワードレールの隣に設置された場合のみ**反応します。
  - **停車駅は直線推奨：** ''wait'' 機能による再発進は、停止する直前の「進行方向」を思い出す仕組みです。カーブの直前などで停止させると挙動が不安定になる恐れがあります。必ず**平坦でまっすぐな直線レール**に停車駅を建設してください。
  - **高速カーブに注意：** カーブ減速保護と脱線復帰保護はありますが、極端な高速で曲線へ進入すると見た目の揺れや位置戻しが発生する場合があります。高速区間ではなるべく直線を長く取り、カーブ前に減速看板を設置してください。
  - **定期運航の禁止：** この機能を使って常にトロッコを運行させるのは**サーバーへの負荷増加**に繋がるため、**必ず利用者自らのトロッコ設置・撤去**を順守した運行形態をとるようにしてください。

===== 速度制限のオーバークロック =====
**本来設定できる最高速度は4.0倍(115.2km/h) までになりますが、看板の影響を受けるパワードレールの下に特定のブロックを設置することによって、最大で7.0倍(201.6km/h)までオーバークロックすることができます。**

オーバークロック速度帯は、一度加速すればその速度をずっと維持できるわけではなく、一定距離だけ高速状態を維持したあと、通常上限へ向けて徐々に減速します。
長距離で高速を維持したい場合は、適切な間隔でオーバークロック用のパワードレールを設置してください。

**ブロック別のオーバークロック性能表**

^ ブロックの種類      ^ 最高倍率  ^ 最高速度   ^ 最高速の継続距離  ^ 減速にかかる距離  ^
| エメラルドブロック  | 4.5倍     | 129.6km/h  | 64 ブロック       | 32 ブロック       |
| 金ブロック    | 5.0倍     | 144.0km/h  | 64 ブロック       | 32 ブロック       |
| ダイヤモンドブロック                 | 6.0倍     | 172.8km/h  | 96 ブロック       | 48 ブロック       |
| ネザライトブロック  | 7.0倍     | 201.6km/h  | 128 ブロック      | 64 ブロック       |

===== 高速走行・脱線保護について =====
現在のYSSカスタム版では、高速走行時の安定性を高めるため、以下の保護機能が追加されています。

==== カーブ減速保護 ====
トロッコがカーブを通過したことを検知した場合、設定速度を超えていると一時的に速度を落とします。
カーブを抜けたあと、設定された距離を走行すると元の速度へ復帰します。

標準設定：
<code>
derail-protection:
    enabled: true
    curve-max-multiplier: 2.5
    resume-distance: 16.0
</code>

==== 脱線復帰保護 ====
看板制御中のトロッコが高速走行などでレール外へ出た場合、近くのレールを探して戻します。
この機能は、通常のバニラ挙動のトロッコではなく、**MSP看板によって制御されたトロッコのみ**を対象にします。

標準設定：
<code>
derail-protection:
    snap-back-to-rail: true
    snap-back-search-radius: 2
</code>

  * ''snap-back-to-rail''： レール復帰保護を有効にするかどうか。
  * ''snap-back-search-radius''： 復帰先レールを探す範囲。通常は ''2'' のままで問題ありません。

===== 設定ファイル =====
主な設定項目は以下の通りです。

<code>
default-speed-multiplier: 1.0
normal-max-multiplier: 4.0
cruise-interval-ticks: 4
speed-scale: 15.0
express-item: GOLD_INGOT
</code>

  * ''default-speed-multiplier''： デフォルト速度倍率。
  * ''normal-max-multiplier''： 通常看板で指定できる最大速度倍率。
  * ''cruise-interval-ticks''： 低速時のクルーズコントロール処理間隔。小さいほど反応は良くなりますが、負荷は増えます。
  * ''speed-scale''： Bukkit経路で速度を補正するための係数。通常は変更不要です。
  * ''express-item''： 快速・急行判定に使うアイテム。

===== 管理者向けメモ =====
  * 速度倍率 ''1.0'' は、おおよそ通常速度相当です。
  * 現在の内部基準では ''1.0 = 約8m/s'' として扱われます。
  * 通常上限は ''4.0''、オーバークロック上限は設定ブロックに応じて最大 ''7.0'' です。
  * 極端な高速設定はチャンク読み込み、カーブ、サーバーTPSの影響を受けやすくなります。
  * 高速路線では、カーブ前の減速看板、長めの直線、十分なチャンク読み込み範囲を確保してください。