组件参考

components 节点下的字段由 ComponentMapper 直接映射到 Minecraft 实体属性或数据组件。

属性类字段

字段	类型	说明
max_health	double	最大生命值。
movement_speed	double	移动速度（原版默认约 0.25）。
attack_damage	double	近战攻击伤害。
attack_speed	double	攻击速度。
attack_knockback	double	攻击击退力度。
follow_range	double	追踪目标的最大距离（格）。
knockback_resistance	double	抗击退值，范围 0.0–1.0。
armor	double	护甲值。
armor_toughness	double	护甲韧性。
luck	double	幸运值。
flying_speed	double	飞行速度（适用于飞行生物）。
spawn_reinforcements	double	僵尸召唤援军概率，范围 0.0–1.0。
step_height	double	可直接跨上的方块高度。
jump_strength	double	跳跃强度（马等可骑乘生物）。
safe_fall_distance	double	不产生摔落伤害的下落高度。
fall_damage_multiplier	double	摔落伤害倍率。
burning_time	double	着火后的燃烧时长倍率。
explosion_knockback_resistance	double	爆炸击退抗性。
oxygen_bonus	double	水下呼吸加成。
water_movement_efficiency	double	水中移动效率。
movement_efficiency	double	地面移动效率。

NOTE

以上均为原版实体属性（Attribute）。属性在目标实体上不存在时该项被忽略。max_health 生效后会把当前生命值补满到新上限。

外观与行为类字段

字段	类型	说明
custom_name	string	实体展示名，支持 MiniMessage 格式。
custom_name_visible	boolean	是否始终显示名牌；false 则仅靠近时显示。
persistent	boolean	是否持久化（不因区块无玩家而自然消失）。
silent	boolean	是否屏蔽所有生物音效。
invulnerable	boolean	是否无敌（免疫所有伤害）。
no_ai	boolean	是否禁用 AI（生物停止移动和攻击）。
glowing	boolean	是否发光（显示轮廓）。
gravity	boolean	是否受重力影响。
fire_ticks	int	初始着火 tick 数。
freeze_ticks	int	初始冰冻 tick 数（细雪效果）。
absorption	double	初始伤害吸收量（黄心）。
visual_fire	boolean	是否强制显示着火视觉效果（不产生实际伤害）。

掉落类字段

字段	类型	说明
loot_table	string	关联的掉落表键，格式 <namespace>:entities/<mob_id>，对应 loot_tables/<mob_id>.yml。
can_pick_up_loot	boolean	生物是否能捡起地上的物品。
remove_when_far	boolean	玩家远离后是否自动移除（覆写 persistent）。

装备类字段

字段	类型	说明
main_hand	ItemConfig	主手物品，顶层快捷写法。
off_hand	ItemConfig	副手物品，顶层快捷写法。
helmet	ItemConfig	头盔，顶层快捷写法（等价于 equipment.head）。
chestplate	ItemConfig	胸甲，顶层快捷写法（等价于 equipment.chest）。
leggings	ItemConfig	腿甲，顶层快捷写法（等价于 equipment.legs）。
boots	ItemConfig	靴子，顶层快捷写法（等价于 equipment.feet）。
equipment.<槽位>	ItemConfig	用一个 equipment 节点统一配置多个槽位。

equipment 下的槽位名接受以下写法（大小写不敏感）：

槽位	可用键名
主手	main_hand、hand
副手	off_hand
头部	helmet、head
胸部	chestplate、chest
腿部	leggings、legs
脚部	boots、feet

每个 ItemConfig 支持：

字段	说明
item	物品 ID，仅支持原版材质名称，格式 minecraft:<id>（如 minecraft:diamond_sword）。
drop_chance	死亡时掉落概率，范围 0.0–1.0；0.0 表示不掉落。

components:
  main_hand:
    item: "minecraft:iron_sword"
    drop_chance: 0.05
  helmet:
    item: "minecraft:iron_helmet"
    drop_chance: 0.0
  equipment:
    legs:
      item: "minecraft:iron_leggings"
      drop_chance: 0.0
    # 只指定物品时可以省略 ItemConfig，直接写材质名
    feet: "minecraft:iron_boots"

未知组件键被静默忽略

components 下的键要与本页表格逐字一致。ComponentMapper 按键名查处理器，查不到就跳过该项，既不报错也不打日志。拼错的键（例如把 no_ai 写成 noai）不会有任何提示。

特殊生物字段

字段	适用生物	说明
scale	全部	实体渲染缩放倍率（1.0 为原版大小）。
fire_immune	全部	是否免疫火焰伤害。
collidable	全部	是否参与实体碰撞（推挤）。
is_baby	部分生物	是否为幼年形态。
creeper_powered	苦力怕	是否为充能苦力怕。
creeper_explosion_radius	苦力怕	爆炸半径。
angry	狼	是否处于愤怒状态。
wolf_variant	狼	狼的变种，取 minecraft:wolf_variant 注册表键（如 pale、woods、ashen）。
horse_color	马	马匹颜色（WHITE、CREAMY、CHESTNUT、BROWN、BLACK、GRAY、DARK_BROWN）。
horse_style	马	马匹花纹（NONE、WHITE、WHITE_FIELD、WHITE_DOTS、BLACK_DOTS）。
cat_type	猫	猫品种，取 minecraft:cat_variant 注册表键（如 tabby、siamese、calico、all_black）。
parrot_variant	鹦鹉	鹦鹉变种（RED、BLUE、GREEN、CYAN、GRAY）。
frog_variant	青蛙	青蛙变种（TEMPERATE、WARM、COLD）。
axolotl_variant	美西螈	美西螈变种（LUCY、WILD、GOLD、CYAN、BLUE）。
llama_color	羊驼	羊驼花色（CREAMY、WHITE、BROWN、GRAY）。
llama_strength	羊驼	羊驼力量值（1–5，决定箱子容量）。
slime_size	史莱姆/岩浆怪	史莱姆大小（1 = 小，2 = 中，4 = 大）。
phantom_size	幻翼	幻翼体型。
fox_type	狐狸	狐狸种类（RED、SNOW）。
rabbit_type	兔子	兔子种类（BROWN、WHITE、BLACK、BLACK_AND_WHITE、GOLD、SALT_AND_PEPPER、THE_KILLER_BUNNY）。
mushroom_type	蘑菇牛	蘑菇牛种类（RED、BROWN）。
panda_main_gene	熊猫	熊猫显性基因（NORMAL、LAZY、WORRIED、PLAYFUL、BROWN、WEAK、AGGRESSIVE）。
panda_hidden_gene	熊猫	熊猫隐性基因，取值同上。
goat_screaming	山羊	是否为尖叫山羊。
can_break_doors	僵尸类	是否能破门。
villager_type	村民/僵尸村民	村民生物群系类型，取 minecraft:villager_type 注册表键（如 desert、plains、taiga）。
villager_level	村民/僵尸村民	村民职业等级（1–5，新手到大师）。
villager_profession	村民/僵尸村民	村民职业，取 minecraft:villager_profession 注册表键（如 armorer、farmer、librarian）。

生物类型不匹配时该项被跳过；枚举或注册表键无法识别时同样被跳过。

药水效果字段

字段	类型	说明
potion_effect	string 或 string list	生物生成时自带的药水效果。单条效果可直接写字符串，多条写字符串列表。

每条效果是一个冒号分隔的字符串：

<效果类型>:<持续 tick>[:<效果等级>]

段	必填	说明
效果类型	是	原版效果 ID，大小写不敏感（speed、regeneration、fire_resistance 等）。
持续 tick	是	持续时间，单位 tick。
效果等级	否	省略时为 0（即 I 级），1 为 II 级。

components:
  potion_effect:
    - "speed:99999:1"
    - "regeneration:600"
  # 单条效果也可以直接写成字符串
  # potion_effect: "fire_resistance:1200"

不支持映射写法

potion_effect 只解析上面的冒号字符串。写成 - type: SPEED / duration: / amplifier: 这类映射不会报错，但整条效果被丢弃。ambient、particles、icon 不是可配置项。效果类型无法识别、缺少持续时间、数字无法解析时，该条同样被静默跳过。