# Mannequinエンティティ技術メモ

Minecraft Java Edition 1.21.9（The Copper Age）で正式追加された `minecraft:mannequin` の仕様を、データパック／プラグイン制作者向けに整理する。

## 更新タイムライン
- **2025-09-02 Snapshot 25w36a（Data Pack 86.0）**  
  コマンド専用の技術的エンティティとしてマンネキンが初登場。`below_score` 表示欄に「NPC」ラベルが常時出るプレイヤー型エンティティとして実装された。[^snapshot]
- **2025-09-16 Java 1.21.9 Pre-release 1（Data Pack 87.1）**  
  `description` のカスタマイズ機能と、スポナーなどのデータコンポーネント経由で `minecraft:profile` を受け取る処理が追加され、演出用途が一気に実用化。[^prerelease]
- **2025-09-30 Java 1.21.9 リリース**  
  Mannequin が正式仕様化。`fetchprofile` コマンドにより取得したプレイヤープロファイルを即時に適用できるなど、表示系データが安定した。[^release]

## 基本仕様とスポーン
- `/summon minecraft:mannequin` のみで生成できる。スポーンエッグや自然生成は存在しない。
- Living Entity として扱われるため、装備・手持ちアイテム、NBT 属性、ポーション効果、被ダメージ、ノックバックなどがプレイヤー同様に機能する。
- `below_score` 位置にはデフォルトで `entity.minecraft.mannequin.label`（表示テキスト「NPC」）が描画される。`description`／`hide_description` によって文言や表示有無を制御可能。
- `main_hand` フィールドで左右の利き手スイッチができ、視覚的な持ち手を固定できる。

## データフィールド一覧（1.21.9）
| フィールド | 型 / 値 | 既定値 | 用途 |
| --- | --- | --- | --- |
| `profile` | `minecraft:profile` 互換 | `{}` | 表示するプレイヤープロファイル、または独自マネキンプロファイル。詳細は後述。 |
| `hidden_layers` | 文字列リスト | `[]` | `cape`, `jacket`, `left_sleeve`, `right_sleeve`, `left_pants_leg`, `right_pants_leg`, `hat` から選び、レイヤーごとに表示を非表示化。 |
| `pose` | `standing`,`crouching`,`swimming`,`fall_flying`,`sleeping` | `standing` | 5 種類の静的姿勢を固定。 |
| `main_hand` | `left` / `right` | `right` | 利き手。手持ちアイテムの表示向きを切り替える。 |
| `immovable` | `true` / `false` | `false` | `true` でノックバックやピストン押し出しを無効化。 |
| `description` | Text Component | 既定（「NPC」） | `below_score` 表示欄に任意メッセージを表示。 |
| `hide_description` | `true` / `false` | `false` | `true` で `below_score` 表示自体を非表示に。 |

## `profile` フィールド詳細
- **プレイヤープロファイル指定**  
  `profile:{name:"ExamplePlayer"}` のように UUID／名前を渡すと、実プレイヤーと同じスキン・ケープ情報が適用される。
- **マネキン固有プロファイル**  
  `profile:{texture:"entity/player/wide/steve",cape:"entity/cape/mojang",elytra:"entity/elytra/phantom",model:"slim"}` のように、テクスチャパスやケープ、エリトラ、`wide`/`slim` モデルを直接定義できる。いずれかを省略した場合はデフォルトスキンもしくはプレイヤープロファイル上の値が使われる。
- **データコンポーネントとの連携**  
  Data Pack 87.1 以降はスポナーやアイテムの `minecraft:profile` コンポーネントからも同様の構造で渡せるため、プレイヤーヘッドと同じ仕組みでマネキンの見た目を配布できる。

## 表示・姿勢・移動制御の実装ポイント
- 姿勢は NBT 固定だが、必要ならコマンドチェーンで `data merge entity` を繰り返して状況に応じて切り替えできる。`swimming` と `fall_flying` は水平姿勢の検証や演出に便利。
- `immovable:1b` と `Invulnerable:1b` を併用するとデコレーション用途で事故を防げる。`NoGravity:1b` も併用すれば空中展示が容易。
- `hidden_layers` の組み合わせで帽子だけを非表示にしたり、半袖スキンの腕ラインを消すなど細部調整が可能。
- `description` に JSON テキストを渡すことで、クリックイベントや色付き案内文をマネキン直下に表示できる。`hide_description:1b` で完全なダミーにもできる。

## 代表的な NBT テンプレート
```mcfunction
/summon minecraft:mannequin ~ ~1 ~ {
  profile:{name:"PlayerName"},
  pose:"crouching",
  hidden_layers:["cape","hat"],
  main_hand:"left",
  immovable:1b,
  description:'{"text":"Quest NPC","color":"gold"}'
}
```

## 制作フロー上のTips
- **`fetchprofile` コマンド活用**：1.21.9で追加された `fetchprofile <player>` 実行後は、ログにプレイヤープロファイルをコピーしたり、その場でマネキンを召喚するクリックテキストが表示される。取得した JSON をデータパック内で流用すれば大量のスキンを手作業で収集する必要がない。[^release]
- **データパックのバージョンガード**：`pose` などは Data Pack 87.1 で追加されたため、`pack.mcmeta` の `data_pack_format` と併せて `execute if data` による存在チェックを入れると、古いワールドでも安全に無視できる。
- **スポナー／アイテム経由の配布**：`component:{minecraft:profile:{...}}` を持つスポーンエッグやコマンドブロックを用意しておくと、ワールド配布時に `/summon` 記述を隠蔽できる。

## 参考資料
[^snapshot]: [Minecraft Snapshot 25w36a/b – Java Team (2025-09-02)](https://www.minecraft.net/fr-fr/article/minecraft-snapshot-25w36a)
[^prerelease]: [Minecraft Java Edition 1.21.9 Pre-Release 1 – Minecraft Feedback (2025-09-16)](https://feedback.minecraft.net/hc/en-us/articles/39609762119053-Minecraft-Java-Edition-1-21-9-Pre-Release-1)
[^release]: [Minecraft Java Edition 1.21.9 – minecraft.net (2025-09-30)](https://www.minecraft.net/en-us/article/minecraft-java-edition-1-21-9)