# MannequinNPC

Minecraft の `minecraft:mannequin` を、ID付きのNPCとして作成・登録・管理する Paper/Folia プラグインです。

見た目や姿勢をコマンドから変更できるほか、プレイヤーを目で追う動作、右クリック時のメッセージ送信・コマンド実行、消滅後の再スポーンを設定できます。NPCの定義は `mannequins.yml` に保存されます。

## 主な機能

- プレイヤーの現在地への Mannequin 作成
- 既存の Mannequin エンティティの登録
- 姿勢、利き手、スキン、服レイヤー、名前、説明文などの変更
- 無敵化、移動固定、体力の設定
- 指定座標や近くのプレイヤーを向く視線制御
- 右クリックしたプレイヤーや会話中のプレイヤーへの追従
- 右クリックごとのメッセージ送信・コンソールコマンド実行
- アクションの順次実行とランダム実行
- エンティティ消滅時の自動再スポーン
- Paper Services Manager を介した `MannequinRegistry` の公開
- Folia のリージョンスケジューラを用いた定期的な視線更新

Mannequin 自体の仕様は [note-mannequin.md](./note-mannequin.md) にまとめています。

## 動作要件

| 項目 | 要件 |
| --- | --- |
| サーバー | Paper/Folia 26.1 系 |
| コンパイル対象API | `paper-api:26.1.2.build.49-beta` |
| Java | 25 |
| Minecraft | `minecraft:mannequin` を利用できるバージョン |

Kotlin標準ライブラリ、`kommand-lib`、`permits-lib` は Shadow JAR に同梱されるため、サーバーへ別途導入する必要はありません。

## ビルドと導入

このリポジトリは `kommand-lib` を Git submodule として参照します。単独で取得した場合は、先にサブモジュールを初期化してください。

```bash
git submodule update --init --recursive
./gradlew shadowJar
```

生成物は次の場所に出力されます。

```text
build/libs/MannequinNPC-1.0-min.jar
```

JARをサーバーの `plugins/` へ配置して起動してください。

crafters-toolbox 管理下のプロジェクトでは、プロジェクトルートから次のコマンドでビルドと配置を行えます。

```bash
crtb components update npc-mannequin
```

## クイックスタート

プレイヤーの現在位置と向きでNPCを作成し、見た目と会話を設定する例です。

```mcfunction
/mannequin create guide
/mannequin set guide profile player Notch
/mannequin set guide description set <gold>案内人
/mannequin set guide immovable on
/mannequin set guide invulnerable on
/mannequin set guide lookat near range 8
/mannequin set guide event add message <yellow>こんにちは、<player>さん！
```

設定後に `/mannequin` を実行すると、登録済みNPCの状態と保存位置を確認できます。チャット上のIDをクリックすると設定コマンドが、`offline` をクリックすると再スポーンコマンドが入力・実行されます。

## コマンド

メインコマンドは `/mannequin` です。次のエイリアスも利用できます。

- `/mnpc`
- `/mnq`
- `/npcmannequin`

`<id>` はプラグイン内でNPCを識別する任意の文字列です。IDはコマンド補完にも使われます。

### 登録と配置

| コマンド | 説明 |
| --- | --- |
| `/mannequin` | 登録済みNPCの一覧を表示します。 |
| `/mannequin list` | 登録済みNPCの一覧を表示します。 |
| `/mannequin create <id>` | 実行したプレイヤーの現在位置に新しいMannequinを作成します。 |
| `/mannequin register <id> <selector>` | セレクターに含まれる最初のMannequinを、現在の状態ごと登録します。 |
| `/mannequin register <id> <selector> --overwrite` | 同じIDの定義を、対象エンティティの状態で置き換えます。 |
| `/mannequin move <id>` | 保存位置を実行したプレイヤーの現在位置・向きへ変更し、存在するエンティティも移動します。 |
| `/mannequin apply <id>` | 保存済み設定を適用します。エンティティが見つからなければ保存位置に再生成します。 |
| `/mannequin remove <id>` | 登録だけを解除し、ワールド内のエンティティは残します。 |
| `/mannequin remove <id> --delete-entity` | 登録を解除し、関連付けられたエンティティも削除します。 |

既存エンティティを登録する例:

```mcfunction
/summon minecraft:mannequin ~ ~ ~
/mannequin register shopkeeper @e[type=minecraft:mannequin,sort=nearest,limit=1]
```

### 外観と基本状態

| コマンド | 説明 |
| --- | --- |
| `/mannequin set <id> pose <pose>` | 姿勢を変更します。 |
| `/mannequin set <id> mainhand <left\|right>` | 利き手を変更します。 |
| `/mannequin set <id> immovable <state>` | ノックバックなどによる移動を固定・解除します。 |
| `/mannequin set <id> invulnerable <state>` | ダメージ無効を設定します。 |
| `/mannequin set <id> health <value>` | 体力を設定します。入力範囲は `0`〜`1024` で、適用時に最大体力以下へ補正されます。 |
| `/mannequin set <id> name set <MiniMessage>` | カスタム名を設定します。 |
| `/mannequin set <id> name clear` | カスタム名を解除します。 |
| `/mannequin set <id> description set <MiniMessage>` | Mannequinの説明文を設定し、表示状態にします。 |
| `/mannequin set <id> description clear` | カスタム説明文を解除し、標準の説明文に戻します。 |
| `/mannequin set <id> description hide` | 説明文を非表示にします。 |
| `/mannequin set <id> description show` | 説明文を表示します。 |
| `/mannequin set <id> profile player <player>` | オンラインプレイヤー、または指定名からプロフィールを作成して適用します。 |
| `/mannequin set <id> profile clear` | 保存プロフィールを解除し、Mannequinの標準プロフィールに戻します。 |
| `/mannequin set <id> respawn-delay <seconds>` | 消滅後の再スポーン待ち時間を秒で設定します。負数で無効、`0` で即時です。 |

`<state>` は `true` / `false` / `on` / `off` を受け付けます。内部の真偽値パーサーは `yes` / `no` / `1` / `0` にも対応しています。

利用できる姿勢:

```text
standing
sleeping
sneaking
swimming
spin_attack
long_jumping
fall_flying
```

名前、説明文、メッセージには MiniMessage 形式を使用できます。

```mcfunction
/mannequin set guide name set <gold><bold>Guide</bold></gold>
/mannequin set guide description set <gray>右クリックで話す</gray>
```

### スキンレイヤー

| コマンド | 説明 |
| --- | --- |
| `/mannequin set <id> layers hide <layer>` | 指定レイヤーを非表示にします。 |
| `/mannequin set <id> layers show <layer>` | 指定レイヤーを表示します。 |
| `/mannequin set <id> layers clear` | すべてのレイヤーを表示状態に戻します。 |

利用できるレイヤー:

```text
cape
jacket
left_sleeve
right_sleeve
left_pants_leg
right_pants_leg
hat
```

## 右クリック時のアクション

登録済みMannequinをメインハンドで右クリックすると、設定されたアクションが1件実行されます。

| コマンド | 説明 |
| --- | --- |
| `/mannequin set <id> event add command <command>` | コンソールとして実行するコマンドを末尾に追加します。先頭の `/` は省略できます。 |
| `/mannequin set <id> event add message <MiniMessage>` | クリックしたプレイヤーだけに送るメッセージを末尾に追加します。 |
| `/mannequin set <id> event mode default` | プレイヤーごとに先頭から順次実行し、末尾の次は先頭へ戻ります。 |
| `/mannequin set <id> event mode random` | クリックごとにランダムな1件を実行します。 |
| `/mannequin set <id> event timeout <seconds>` | 順次実行の位置と会話追従を維持する時間を設定します。既定値は5秒です。 |
| `/mannequin set <id> event list` | モードとアクション一覧を表示します。プレイヤーには削除・並べ替え用のクリックUIも表示します。 |
| `/mannequin set <id> event remove <index>` | 指定インデックスのアクションを削除します。 |
| `/mannequin set <id> event swap <index1> <index2>` | 2件の順序を入れ替えます。 |

アクションのインデックスは `0` から始まります。コマンドとメッセージでは `<player>` がクリックしたプレイヤー名に置換されます。

```mcfunction
/mannequin set shop event add message <gold>いらっしゃいませ、<player>さん
/mannequin set shop event add command give <player> minecraft:bread 1
/mannequin set shop event mode default
/mannequin set shop event timeout 10
```

`command` アクションは常にコンソールから実行されます。プレイヤー本人の実行コンテキストが必要な場合は、次のように `execute as` を明示してください。

```mcfunction
/mannequin set shop event add command execute as <player> at @s run say hello
```

## 視線制御

| コマンド | 説明 |
| --- | --- |
| `/mannequin set <id> lookat pos <x> <y> <z>` | 固定座標を見るようにします。実行者がプレイヤーならそのワールド、コンソールなら `world` を使用します。 |
| `/mannequin set <id> lookat near range <radius>` | 半径内で最も近い非Spectatorプレイヤーを追います。範囲は `0`〜`64` ブロックです。 |
| `/mannequin set <id> lookat onclick <state>` | 右クリックしたプレイヤーを一時的に見る動作を切り替えます。 |
| `/mannequin set <id> lookat conversation <state>` | 順次アクションで会話中のプレイヤーを見る動作を切り替えます。 |
| `/mannequin set <id> lookat auto-turn on\|off` | 注視対象がいなくなった後、保存済みの向きへ戻る動作を切り替えます。 |
| `/mannequin set <id> lookat auto-turn wait <seconds>` | 元の向きへ戻り始めるまでの待ち時間を設定します。既定値は0.5秒です。 |
| `/mannequin set <id> lookat auto-turn take <seconds>` | 元の向きへ補間して戻る時間を設定します。`0` 以下では即座に戻ります。既定値は0.5秒です。 |
| `/mannequin set <id> lookat clear` | 固定座標、近距離追従、クリック追従を解除し、視線関連設定を既定値へ戻します。 |

複数の対象が有効な場合は、次の順で優先されます。

1. 直近に右クリックしたプレイヤー
2. 会話中のプレイヤー
3. 設定半径内で最も近いプレイヤー
4. 設定した固定座標

視線は2 tickごとに更新されます。クリック追従の継続時間には `auto-turn wait` の値が使われ、正数でない場合は2秒になります。会話追従は順次アクションの対話状態を利用するため、ランダムモードでは発生しません。

## パーミッション

すべてのコマンドは次のルート権限で保護されています。既定値は `false` なので、権限管理プラグインなどから明示的に付与してください。

```text
npc-mannequin.command.mannequin
```

`kommand-lib` と `permits-lib` によって、`npc-mannequin.command.mannequin.list` や `npc-mannequin.command.mannequin.set.pose` のようなリテラル単位のノードも動的に登録されます。現在のコマンド定義ではルート権限も実行条件になるため、運用時はまず上記のルート権限を付与してください。

## データ保存

NPC定義は次のファイルへYAML形式で保存されます。

```text
plugins/MannequinNPC/mannequins.yml
```

登録、移動、設定変更、削除のたびにファイル全体が更新されます。通常はコマンド経由で編集してください。ワールド上のエンティティが見つからなくなった場合でも、保存位置があれば `/mannequin apply <id>` で再生成できます。

現在、次の設定はコマンド実行中のエンティティには反映されますが、`mannequins.yml` へシリアライズされません。サーバー再起動後は既定値へ戻る点に注意してください。

- カスタム名 (`name`)
- 無敵状態 (`invulnerable`)
- 体力 (`health`)
- 再スポーン待ち時間 (`respawn-delay`)

姿勢、利き手、移動固定、説明文、スキンレイヤー、プロフィール、位置、視線制御、クリックアクションは永続化されます。

また、視線更新はFoliaのリージョンスケジューラに対応していますが、自動再スポーンの遅延処理は現在Bukkit Schedulerを使用しています。Folia環境では `respawn-delay` を利用せず、必要に応じて `/mannequin apply <id>` で再生成してください。

## 他プラグインから利用する

有効化時に `MannequinRegistry` が Paper の Services Manager へ登録されます。MannequinNPCへの依存とクラス参照を設定したプラグインから、登録済みNPCを取得・更新できます。

```kotlin
import net.hareworks.npc_mannequin.service.MannequinRegistry
import org.bukkit.Bukkit

val registry = Bukkit.getServicesManager()
    .load(MannequinRegistry::class.java)
    ?: error("MannequinNPC is not enabled")

val guide = registry.find("guide")
registry.updateSettings("guide") { settings ->
    settings.copy(immovable = true)
}
```

主な公開操作は `all`、`find`、`register`、`create`、`updateSettings`、`apply`、`relocate`、`remove`、`locate` です。

## プロジェクト構成

```text
src/main/kotlin/net/hareworks/npc-mannequin/
├── Plugin.kt                         # ライフサイクルとサービス登録
├── commands/MannequinCommands.kt    # コマンドツリー
├── mannequin/MannequinSettings.kt   # 永続化モデル
├── service/                          # 操作、登録、イベント、視線更新
├── storage/MannequinStorage.kt      # mannequins.yml の読み書き
└── text/TextSerializers.kt          # MiniMessage変換
```