npc-mannequin/note-mannequin.md

Mannequinエンティティ技術メモ

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

更新タイムライン

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

基本仕様とスポーン

• /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 テンプレート

/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 をデータパック内で流用すれば大量のスキンを手作業で収集する必要がない。³
• データパックのバージョンガード：pose などは Data Pack 87.1 で追加されたため、pack.mcmeta の data_pack_format と併せて execute if data による存在チェックを入れると、古いワールドでも安全に無視できる。
• スポナー／アイテム経由の配布：component:{minecraft:profile:{...}} を持つスポーンエッグやコマンドブロックを用意しておくと、ワールド配布時に /summon 記述を隠蔽できる。

参考資料

---

1. Minecraft Snapshot 25w36a/b – Java Team (2025-09-02) ↩︎

2. Minecraft Java Edition 1.21.9 Pre-Release 1 – Minecraft Feedback (2025-09-16) ↩︎

3. Minecraft Java Edition 1.21.9 – minecraft.net (2025-09-30) ↩︎