プレイヤーディスガイズ
FreeMinecraftModelsは、オンラインの任意のプレイヤーをロード済みモデルにディスガイズできます。ディスガイズはコマンド、公開DisguiseAPI、およびディスガイズされたプレイヤーの透明化とモデルレンダリングを処理するプレイヤーごとのPlayerDisguiseEntityによって駆動されます。
コマンド
| コマンド | 権限 | 備考 |
|---|---|---|
/fmm disguise <modelID> | freeminecraftmodels.disguise.self | 送信者をディスガイズします。プレイヤー専用 |
/fmm disguise <modelID> <player> | freeminecraftmodels.disguise.self + freeminecraftmodels.disguise.others | 指名されたプレイヤーをディスガイズします。コンソールから動作 |
/fmm undisguise | freeminecraftmodels.disguise.self | 送信者のディスガイズを解除します。プレイヤー専用 |
/fmm undisguise <player> | freeminecraftmodels.disguise.self + freeminecraftmodels.disguise.others | 指名されたプレイヤーのディスガイズを解除します。コンソールから動作 |
/fmm disguiselist | freeminecraftmodels.disguise.others | ディスガイズされているすべてのプレイヤーと、それぞれがディスガイズされているモデルをリストします |
freeminecraftmodels.*ワイルドカードは、OPデフォルトでadmin、deleteall、disguise.self、disguise.othersを付与します。また、個別に登録されているfreeminecraftmodels.bypassregionprotection権限も付与します。
挙動
- すでにディスガイズされているプレイヤーをディスガイズすると、以前のディスガイズがクリーンに置き換えられます — 最初にディスガイズ解除する必要はありません。
- FMMは
setVisibleByDefault(false)で他の閲覧者からプレイヤーを隠し、透明化のポーション効果がまだなければ追加します。装備の表示上書きによって、インベントリを変更せずに他の閲覧者から防具と手持ちアイテムを隠します。自分の視点は装備の上書き対象外です。自分の体の描画は、引き続きクライアントの可視性処理に依存します。 - FMMは関連する効果の削除・変更イベントやリスポーンの1ティック後に透明化を再適用しますが、そのディスガイズが最初に効果を追加した場合に限ります。開始前から存在していた透明化効果は維持も復元もしません。解除するとデフォルトの可視性を
trueに戻し、FMMが追加した効果を削除して、現在の装備を再送信します。 - 装備を隠す表示は、新しく参加した閲覧者やワールド変更時に再送信されます。プレイヤーの実際の防具や手持ちアイテムは置き換えません。
- プレイヤーのヒットボックスは変わりません。装飾用のディスガイズはパケットによるインタラクションエンティティを作成せず、クリックハンドラーも何もしないため、攻撃や搭乗用の別の対象にはなりません。透明化はFMM外の挙動に影響することがあり、Mobのターゲット選択が変わらないとは限りません。
- ディスガイズはサーバー再起動、
/fmm reload、またはプレイヤーのログアウトを生き延びません — メモリ内で追跡され、DisguiseListeners.onQuitハンドラがPlayerQuitEventでディスガイズを削除します。死亡とワールド変更ではプレイヤーのディスガイズは解除されません。 /fmm reloadが成功すると、停止処理で有効なディスガイズが破棄されるため、再適用が必要です。候補コンテンツの準備中にリロードが拒否された場合、稼働中のランタイムは維持されます。
ディスガイズのアニメーション
各ディスガイズのコントローラーは、モデル付きエンティティ共通の再生エンジンが動作する前に、プレイヤーの状態からアニメーションを選択します。このエンジンを迂回するわけではありません。アニメーションの存在確認では大文字と小文字を区別するため、予約名は小文字で指定してください。
予約されたアニメーション名は5つあり、次の優先順位（上が最優先）で認識されます：
| 優先度 | アニメーション | 種類 | トリガー条件 |
|---|---|---|---|
| 1 | attack | 単発 | プレイヤーが腕を振ったとき |
| 2 | jump | 単発 | プレイヤーが上向きに動きながら地面を離れたとき |
| 3 | sneak | ループ | プレイヤーがスニークしているとき |
| 4 | walk | ループ | 垂直移動も含め、プレイヤーの位置が前ティックから0.01ブロックを超えて移動したとき |
| 5 | idle | ループ | 他のいずれにも当てはまらないとき |
知っておくべき挙動：
-
考慮されるのは、モデルが実際に持っているアニメーションだけです。
sneakアニメーションのないモデルは、単にwalkまたはidleへフォールスルーします。 -
単発アニメーションは即時の非ループ再生を要求し、固定の**20ティック（20 TPSで1秒）**の間、新しい選択をすべて停止します。このカウントダウンはアニメーションの実際の長さを測定しません。長いアニメーションは次の選択で中断されることがあり、短いものは選択再開前に終了することがあります。停止中の腕振りは1回の保留中の攻撃にまとめられ、ジャンプへの移行はキューに保存されません。
-
ループは選択されたアニメーションが実際に変化したときにのみ再発行されるため、歩き続けている間に毎ティック再スタートすることはありません。
-
通常のモデル付きエンティティにおける（現状では機能しない）jumpステートとは異なり、
jumpはディスガイズでは実際に組み込まれています。アニメーションを参照してください。 -
idleアニメーションを持たないディスガイズモデルは、ディスガイズのたびに警告をログに出力します：Disguise model '<model>' has no 'idle' animation — disguised players using this model will freeze on the last animation frame whenever no other action is active.ディスガイズとして使う予定のモデルには、必ず
idleアニメーションを同梱してください。
Bedrockクライアント
ディスガイズにはFMMによるカスタムモデルの描画が必要です。config.ymlのデフォルト値sendCustomModelsToBedrockClientsV2: trueはBedrockへのモデル送信を有効にします。falseにすると、プレイヤーは透明のままですがBedrockの閲覧者にモデルが届きません。廃止されたsendCustomModelsToBedrockClientsキーは読み込まれません。V2が有効でも、クライアントには変換済みリソースパックと正常に動作するGeyser/Floodgate連携が必要です。
DisguiseAPI
サードパーティプラグインはcom.magmaguy.freeminecraftmodels.api.DisguiseAPIを介してディスガイズをプログラム的に駆動できます。
import com.magmaguy.freeminecraftmodels.api.DisguiseAPI;
// Disguise (returns false if the model ID is not loaded)
boolean ok = DisguiseAPI.disguise(player, "dragon");
// Undisguise (returns true if a disguise was removed)
DisguiseAPI.undisguise(player);
// Queries
boolean isDisguised = DisguiseAPI.isDisguised(player);
String modelID = DisguiseAPI.getDisguiseModelID(player); // null if not disguised
// Unmodifiable snapshot of all disguised players
Collection<Player> all = DisguiseAPI.getDisguisedPlayers();
APIはパブリックでリファクタ安全なエントリポイントです。プラグインは内部のDisguiseManagerではなくDisguiseAPIを呼び出すべきです。
APIはコマンド権限の確認やモデルIDの正規化を行いません。オンラインのプレイヤーと、読み込み済みの正確なIDを渡してください。disguiseは置き換え先を作成しようとする前に既存のディスガイズを削除するため、不明なIDでは古いディスガイズを削除した後にfalseを返します。コマンドはモデルを先に確認するので、無効なIDを指定しても以前のディスガイズを維持します。APIの成功は作成を確認するもので、クライアントでの描画やリソースパックの受け入れを保証しません。
一般的なユースケース
- ロールプレイとRPGサーバー： シネマティックやクエストスクリプトのためにプレイヤーをボスモデルにディスガイズします。
- イベントホスティング： アナウンサーを巨大なカスタムモデルにディスガイズします。
- マウントと乗り物： クリエイティブな輸送セットアップのために
/fmm mountと/fmm disguiseを組み合わせます。 - EliteMobs統合： ボススクリプトは、一時的な変身効果のためにイベントをトリガーしたプレイヤーをディスガイズできます。
トラブルシューティング
/fmm disguise dragonを実行しても何も起こりません。
モデルIDはロード済みモデルと正確に一致する必要があります。/fmm adminまたはコマンドのタブ補完でモデル名を確認してください。他プレイヤーを対象とする形式では、モデルやプレイヤーを解決する前にfreeminecraftmodels.disguise.othersをチェックし、権限が不足していることを直接報告します。
/fmm reloadの後、ディスガイズが消えました。
完全なリロードが成功した場合は正常な挙動です。自動で再適用する必要があれば、初期化の40ティック後にメインスレッドで実行されるよう予約されるFmmReloadedEventを監視してください。準備段階で拒否された場合は、稼働中のランタイムを破棄しません。
Bedrockプレイヤーにディスガイズが見えません。 上記のBedrockクライアントを参照してください。
ディスガイズされたプレイヤーが他者に依然として見えています。 開始時にプレイヤーがすでに透明化していたか確認してください。FMMはその効果を管理せず、消えても復元しません。また、プレイヤーの可視性、効果、装備パケットを変更するプラグインも確認してください。FMMはプレイヤーの可視性、実際のポーション効果、装備の表示上書きを併用します。他のプラグインの設定を変更する前に、競合する挙動を確認してください。