プレイヤー体験に直結する「しもべ」機能の全体図です。実体、見た目、装備、スキン、AI、GUI、保存がどう分担されるかをまとめています。
levelservantnpccitizensgui
このページは手書き密度を上げたサブシステム解説です。 クラス単体の一覧では見えにくい、モジュール横断の処理遷移を図と文章で読めるようにしています。
読むときの姿勢
- まず図で境界を把握する
- 次に関連クラスの章立て解説へ降りる
- 最後にメソッド詳細で個別実装を確認する
サブシステム解説
なぜ読むのが難しいか
この機能は「Mob 実体」「見た目プレイヤー表現」「ロードアウト保存」「追従 AI」が同時進行するため、一箇所だけ見ても挙動を説明しづらいです。章立てページでは各クラスを個別に見られますが、このガイドではそれらの接続順を重視しています。
入口
召喚やGUI起動はコマンド・クリック・ログイン復元など複数入口がありますが、最終的には LevelServantService へ寄り、そこから Citizens あり/なしで表示実装が分岐します。
モジュール横断の処理遷移図
召喚から見た目確立まで
player action
→
LevelServantService.summonFor
→
servant 実体生成
→
refreshStats / vitals
→
attachOrRefreshVisual
→
CitizensBridge or PlayerNpcBridge
保存と復元
→
loadout cache
→
skin cache
→
visualStates
→
assist target state
スポーン直後は見た目・体力・装備が一気に整うわけではなく、複数段階で補正が入ります。召喚直後だけ壊れる症状はここを追うと分かりやすいです。
通常追従と戦闘参加のループ
tick
→
maintainBehaviour
→
follow anchor 計算
→
move / teleport / face
→
target resolve
→
attack / support
分岐
→
maintainCitizensBehaviour
→
maintainManualPlayerBehaviour
Citizens の有無で下段の経路が変わります。片方だけ修正すると環境差バグになるので、追従・戦闘まわりは両経路をセットで見るのが前提です。
装備GUIから反映まで
GUI open
→
renderEquipmentMenu
→
click / drag
→
saveLoadout
→
applyLoadoutToServant
→
refreshAppearance
GUI は画面だけの処理ではなく、保存と見た目更新をまたぎます。見た目だけ変わる・再ログインで戻る、のような症状はこの列を順に見ると切り分けしやすいです。
変更時の注意点
- Citizens あり/なしの二経路は、挙動差の温床です。メイン修正後は両ブリッジの掃除・更新・姿勢同期を確認した方が安全です。
- Bukkit の属性反映はタイミング競合が起きやすく、pending vital 系の遅延再試行に意味があります。即時反映だけに寄せると再発しやすいです。
- 見た目が壊れているのか、実体 AI が壊れているのかを最初に分けると調査が速くなります。