简体中文
组件参考
components 节点下所有可用的键, 每个键能填什么, 填上去有什么效果, 逐一列在下面
components 节点下的字段由 ComponentMapper 直接映射到 Minecraft 实体的属性或数据组件. 键名必须和列表逐字一致: 找不到处理器的键会被跳过 (不报错, 不打日志)
随包示例: 首次启动释放的 mobs/example_zombie.yml, 以及插件内置的 mobs/elite_zombie.yml, mobs/bone_lord.yml 都用到了下表中的字段, 你可以直接对照阅读
下表中的"必填"一律是"否": 整个 components 可以默认不写, 没写进去的键不会被应用. "默认值"一律是"—", 表示不写时保留原版或实体自己的状态. "取值范围"写"—"表示源码没有做校验 (数值会原样写入, 越界会怎样由原版属性或实体 API 决定)
生成与刷新的规则
- 仅生成时应用 (只在刷出的那一刻生效):
absorption,freeze_ticks,fire_ticks,potion_effect, 以及全部装备类字段 (helmet,chestplate,leggings,boots,main_hand,off_hand,equipment). 这些是消耗性状态,/emakimobs reload触发的刷新不会重置它们, 也不会补回损坏或已经失去的装备 max_health特殊处理: 刷出时先应用上限, 然后立刻把血量补满; 刷新时保留当前血量, 再按新上限截断 (上限升高不会回血, 上限降低会把血量截断到新上限)- 其余组件 (属性类与外观行为类) 每次刷新都会按配置重新写入
属性类字段
| 字段 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
max_health | double | 否 | — | — | 最大生命值 (原版属性 MAX_HEALTH) |
movement_speed | double | 否 | — | — | 移动速度 (原版僵尸约 0.23, 玩家 0.1) |
attack_damage | double | 否 | — | — | 近战攻击的伤害 |
attack_speed | double | 否 | — | — | 攻击的速度 |
attack_knockback | double | 否 | — | — | 攻击时把目标推开的力度 |
follow_range | double | 否 | — | — (格) | 追踪目标的最远距离 |
knockback_resistance | double | 否 | — | 0.0–1.0 (原版属性范围) | 抗击退的值, 1.0 就是完全免疫击退 |
armor | double | 否 | — | — | 护甲值 |
armor_toughness | double | 否 | — | — | 护甲韧性 |
luck | double | 否 | — | — | 幸运值 |
flying_speed | double | 否 | — | — | 飞行速度 (只对会飞的生物有用) |
scale | double | 否 | — | — | 实体渲染的缩放倍率, 1.0 是原版大小 |
step_height | double | 否 | — | — | 能直接跨上去的方块高度 |
jump_strength | double | 否 | — | — | 跳跃强度 (马这类可骑乘生物用) |
safe_fall_distance | double | 否 | — | — | 多高摔下来不会受伤 |
fall_damage_multiplier | double | 否 | — | — | 摔落伤害的倍率 |
burning_time | double | 否 | — | — | 着火后能烧多久的倍率 |
explosion_knockback_resistance | double | 否 | — | — | 爆炸击退抗性 |
spawn_reinforcements | double | 否 | — | 0.0–1.0 (原版属性范围) | 僵尸召唤援军的概率 |
oxygen_bonus | double | 否 | — | — | 水下呼吸的加成 |
water_movement_efficiency | double | 否 | — | — | 水中移动的效率 |
movement_efficiency | double | 否 | — | — | 地面移动的效率 |
NOTE
以上都是原版实体属性 (Attribute). 如果目标实体身上没有这个属性, 该项会被忽略 (比如给僵尸写 flying_speed)
外观与行为类字段
| 字段 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
custom_name | string | 否 | — | 任意字符串 | 实体展示的名字, 支持 MiniMessage 格式 (它和 display_name 字段不同, 这里会真正改写实体名牌) |
custom_name_visible | boolean | 否 | — | true / false | 是否始终显示名牌; 填 false 就只在靠近时显示 |
persistent | boolean | 否 | — | true / false | 是否让它一直留存 (不会因为区块里没有玩家而自然消失) |
silent | boolean | 否 | — | true / false | 是否屏蔽这只生物的音效 |
invulnerable | boolean | 否 | — | true / false | 是否无敌 (免疫所有伤害) |
no_ai | boolean | 否 | — | true / false | 填 true 时关掉 AI (生物不再移动和攻击) |
glowing | boolean | 否 | — | true / false | 是否发光 (显示轮廓) |
gravity | boolean | 否 | — | true / false | 是否受重力影响 |
collidable | boolean | 否 | — | true / false | 是否参与实体之间的碰撞 (推挤) |
fire_immune | boolean | 否 | — | true / false | 是否免疫火焰伤害; 填 true 时会写入实体 PDC, 并取消着火与火焰/岩浆类的伤害事件 |
visual_fire | boolean | 否 | — | true / false | 是否强制显示着火的外观效果 (不会产生实际伤害) |
absorption | double | 否 | — | — (点) | 初始的伤害吸收量 (黄心); 只在刷出时应用 |
freeze_ticks | int | 否 | — | — (tick) | 初始冰冻多少 tick (1 tick = 1/20 秒); 只在刷出时应用 |
fire_ticks | int | 否 | — | — (tick) | 初始着火多少 tick; 只在刷出时应用 |
掉落类字段
| 字段 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
loot_table | string | 否 | — | <命名空间>:<路径> 或裸路径 (会自动补 minecraft:) | 设置这只生物使用的原版/数据包掉落表: 这个值交给 Bukkit.getLootTable 解析, 查得到才会写入实体 (插件不注册数据包, 所以自定义命名空间的值查不到, 这时不报错, 也不做任何事). 它和 loot_tables/*.yml 没有关系 |
can_pick_up_loot | boolean | 否 | — | true / false | 这只生物能不能捡起地上的物品 |
remove_when_far | boolean | 否 | — | true / false | 玩家走远后是否自动移除 (会覆盖 persistent) |
自定义掉落表会替换原版掉落
loot_tables/<mob_id>.yml 只要同名文件存在就生效 (和 components 有没有写 loot_table 无关); 生效后, 死亡时会执行 event.getDrops().clear(), 清空全部原版掉落, 改由这张表的池产出 (击杀经验仍按 experience 保留)
- 想保留原版掉落, 就不要给这只生物创建同名 YAML 掉落表
- 两者互不影响:
loot_table只管原版/数据包掉落表本身; 写loot_table: "minecraft:entities/zombie"会设置原版表, 但同名 YAML 表存在时原版掉落还是会被替换
装备类字段
| 字段 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
main_hand | ItemConfig 或材质名 | 否 | — | 见下方 ItemConfig | 主手拿的物品 (只在刷出时应用) |
off_hand | ItemConfig 或材质名 | 否 | — | 同上 | 副手拿的物品 (只在刷出时应用) |
helmet | ItemConfig 或材质名 | 否 | — | 同上 | 头盔 (等同于 equipment.head, 只在刷出时应用) |
chestplate | ItemConfig 或材质名 | 否 | — | 同上 | 胸甲 (等同于 equipment.chest, 只在刷出时应用) |
leggings | ItemConfig 或材质名 | 否 | — | 同上 | 腿甲 (等同于 equipment.legs, 只在刷出时应用) |
boots | ItemConfig 或材质名 | 否 | — | 同上 | 靴子 (等同于 equipment.feet, 只在刷出时应用) |
equipment | map | 否 | — | 键为槽位名, 值为 ItemConfig 或材质名 | 用一个节点一次性配置多个槽位 (只在刷出时应用) |
equipment 下的槽位名支持以下写法 (大小写不敏感):
| 槽位 | 可用键名 |
|---|---|
| 主手 | main_hand, hand |
| 副手 | off_hand |
| 头部 | helmet, head |
| 胸部 | chestplate, chest |
| 腿部 | leggings, legs |
| 脚部 | boots, feet |
ItemConfig 支持这些字段:
| 字段 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
item | string | 否 | — | 原版材质名 (大小写不敏感, 可带 minecraft: 前缀) | 只接受"能当物品用"的原版材质; 匹配失败时这个槽位保持原样 |
drop_chance | double | 否 | — (保持原版默认掉落率) | 0.0–1.0 | 死亡时掉落这件装备的概率; 0.0 就是不掉落. 本地没有做钳制, 越界取值会怎样由原版装备 API 决定 |
yaml
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"特殊生物字段
| 字段 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
is_baby | boolean | 否 | — | true / false | 是不是幼年形态. 只对 Ageable 和 Zombie 生效, 其他生物忽略 |
creeper_powered | boolean | 否 | — | true / false | 是不是充能苦力怕. 只对苦力怕生效 |
creeper_explosion_radius | int | 否 | — | — | 爆炸半径. 只对苦力怕生效 |
angry | boolean | 否 | — | true / false | 是否处于愤怒状态. 只对狼生效 |
wolf_variant | string | 否 | — | minecraft:wolf_variant 注册表键 (如 pale, woods, ashen) | 狼的变种. 只对狼生效, 键认不出来时会忽略 |
horse_color | string | 否 | — | WHITE, CREAMY, CHESTNUT, BROWN, BLACK, GRAY, DARK_BROWN | 马的颜色. 只对马生效, 枚举值认不出来时会忽略 |
horse_style | string | 否 | — | NONE, WHITE, WHITE_FIELD, WHITE_DOTS, BLACK_DOTS | 马的花纹. 只对马生效 |
cat_type | string | 否 | — | minecraft:cat_variant 注册表键 (如 tabby, siamese, calico, all_black) | 猫的品种. 只对猫生效 |
parrot_variant | string | 否 | — | RED, BLUE, GREEN, CYAN, GRAY | 鹦鹉的变种. 只对鹦鹉生效 |
frog_variant | string | 否 | — | minecraft:frog_variant 注册表键 (如 temperate, warm, cold) | 青蛙的变种. 只对青蛙生效 |
axolotl_variant | string | 否 | — | LUCY, WILD, GOLD, CYAN, BLUE | 美西螈的变种. 只对美西螈生效 |
llama_color | string | 否 | — | CREAMY, WHITE, BROWN, GRAY | 羊驼的花色. 只对羊驼生效 |
llama_strength | int | 否 | — | 1–5 | 羊驼的力量值 (决定箱子能装多少). 只对羊驼生效 |
slime_size | int | 否 | — | — | 史莱姆的体型 (1 = 小, 2 = 中, 4 = 大). 只对史莱姆/岩浆怪生效 |
phantom_size | int | 否 | — | — | 幻翼的体型. 只对幻翼生效 |
fox_type | string | 否 | — | RED, SNOW | 狐狸的种类. 只对狐狸生效 |
rabbit_type | string | 否 | — | BROWN, WHITE, BLACK, BLACK_AND_WHITE, GOLD, SALT_AND_PEPPER, THE_KILLER_BUNNY | 兔子的种类. 只对兔子生效 |
mushroom_type | string | 否 | — | RED, BROWN | 蘑菇牛的种类. 只对蘑菇牛生效 |
panda_main_gene | string | 否 | — | NORMAL, LAZY, WORRIED, PLAYFUL, BROWN, WEAK, AGGRESSIVE | 熊猫的显性基因. 只对熊猫生效 |
panda_hidden_gene | string | 否 | — | 同上 | 熊猫的隐性基因. 只对熊猫生效 |
goat_screaming | boolean | 否 | — | true / false | 是不是尖叫山羊. 只对山羊生效 |
can_break_doors | boolean | 否 | — | true / false | 能不能破门. 只对僵尸类生效 |
villager_type | string | 否 | — | minecraft:villager_type 注册表键 (如 desert, plains, taiga) | 村民的生物群系类型. 只对村民/僵尸村民生效 |
villager_level | int | 否 | — | 1–5 | 村民的职业等级 (从新手到大师). 只对村民/僵尸村民生效 |
villager_profession | string | 否 | — | minecraft:villager_profession 注册表键 (如 armorer, farmer, librarian) | 村民的职业. 只对村民/僵尸村民生效 |
生物类型不匹配时跳过该项; 枚举值或注册表键认不出来时同样跳过 (不报错, 不打日志)
药水效果字段
| 字段 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
potion_effect | string 或 string list | 否 | — | 冒号分隔的效果串, 见下表 | 生物刷出时自带的药水效果 (只在刷出时应用). 只有一条效果时可以直接写字符串, 多条就写成字符串列表 |
每条效果是一个冒号分隔的字符串:
text
<效果类型>:<持续 tick>[:<效果等级>]| 段 | 必填 | 说明 |
|---|---|---|
| 效果类型 | 是 | 原版效果 ID, 大小写不敏感 (speed, regeneration, fire_resistance 等), 按 minecraft: 命名空间查表 |
| 持续 tick | 是 | 持续的时间, 单位是 tick; 必须能解析成整数 |
| 效果等级 | 否 | 省略时是 0 (也就是 I 级), 1 是 II 级 |
yaml
components:
potion_effect:
- "speed:99999:1"
- "regeneration:600"
# 单条效果也可以直接写成字符串
# potion_effect: "fire_resistance:1200"不支持映射写法
potion_effect 只解析上面那种冒号分隔的字符串. 写成 - type: SPEED / duration: / amplifier: 这类映射不会报错, 但整条效果会被丢掉. ambient, particles, icon 都不是可配置项. 效果类型认不出来, 缺少持续时间, 数字解析不了时, 该条同样会被跳过 (不报错, 不打日志)