FreeMinecraftModels 宠物
FreeMinecraftModels 可以把模型变成宠物物种。玩家可以用食物驯服宠物、让它们繁殖、带着它们同行、命令它们留在原地，并把它们保存在通过 /fmm pets 打开的收藏中。每个物种由放在其模型旁边的 <species>.pet.yml 文件定义，因此模型包会把它的宠物与模型一起安装、启用和禁用。宠物自己会做什么（从跟随主人到绕着营火打转），来自其文件所列出的 Lua 行为模块。服务器范围的宠物设置位于 pets.yml。
要求
- 宠物是一只承载着模型的隐藏原版生物，由 MagmaCore 的 Mind AI 驱动。这需要 FreeMinecraftModels 对该服务端版本的 NMS 支持，以及 Minecraft 1.21.4 或更新版本。没有这些时，控制台会在启动时记录一行以
Pets are off:开头的日志，/fmm pets则回应Pets are not available on this server.。 - FreeMinecraftModels 不自带任何宠物物种。只有当某个模型包或你添加了
.pet.yml文件之后，才会有宠物。 - 与任何模型一样，玩家需要生成的资源包。
宠物是如何构成的
- 身体是宠物文件中
body所指定的原版生物，默认是悦灵。它隐藏在模型内部，保持安静，也从不拾取物品。它的最大生命值就是宠物文件中的health。 - 点击落在玩家看到的模型上，而不是其内部较小的身体上。
- 宠物从不以任何东西为目标，生物也从不以宠物为目标。
- FreeMinecraftModels 的接触伤害对宠物是关闭的。宠物只会通过
sting模块伤害其他东西。 - 死亡的宠物不掉落任何东西，也不给予经验。
- 宠物的身体从不随其区块一起保存。玩家拥有的宠物会在其主人身边重新创建，野生宠物则等待在
data/wild_pets.yml中（参见野生宠物）。崩溃后留在区块中的宠物身体，会在该区块加载时被移除。 - 模型上方会显示物种的
name，幼崽前面带有Baby。
宠物模式
pets.yml 有两种模式：
| 模式 | 会发生什么 |
|---|---|
COSMETIC（默认） | 除了经过的夜间迁徙之外，世界中只存在玩家拥有的宠物。没有任何东西会作为野生生物生成，也无法驯服任何东西。玩家拥有的宠物不会被任何东西伤害 |
CREATURES | 宠物物种还会作为野生生物生活在世界中，像原版农场动物一样生成，玩家通过喂食来驯服它们。玩家拥有的宠物可能受到伤害，遵循伤害规则 |
可以用 /fmm setup 工具栏中的宠物按钮、/fmm petadmin mode creatures 或 /fmm petadmin mode cosmetic 切换模式，也可以编辑 pets.yml 中的 mode 并运行 /fmm reload。按钮和命令都会把新模式写入 pets.yml。
切换到 COSMETIC 会把仍然存活的野生宠物送入 data/wild_pets.yml。当服务器再次切换到 CREATURES 时，它们会回来。夜间迁徙在两种模式下都会飞行，但只有 CREATURES 允许玩家驯服迁徙者。
在 COSMETIC 模式下，玩家不能驯服宠物。/fmm petadmin give <species> 会把一只宠物加入运行该命令的玩家的收藏。繁殖在两种模式下都有效。
驯服
在 CREATURES 模式下，玩家用其物种的某个 tamingFood 物品右键点击野生成年宠物，即可驯服它。
- 每次喂食消耗一个物品，创造模式除外。
- 每次喂食都以
tameChance的几率驯服，默认是1/3，与狼和猫一样。喂食失败会显示烟雾和tameFailedMessage。 - 被驯服的宠物会加入玩家的收藏，并出现在玩家身边。它保留自己在野外时的颜色变体，并播放一次
interact动画。 - 当玩家已经带出
maxEquippedPets只宠物时，新宠物会改为回家，进入收藏。 tamingFood列表为空的物种无法被驯服。
拴绳对宠物的身体与对原版生物的作用相同。
繁殖与幼崽
- 当主人用某个
breedingFood物品右键点击成年宠物时，会消耗一个物品，并让该宠物进入求偶状态，持续loveSeconds，默认30秒。 - 同一物种、由同一位玩家拥有、都处于求偶状态且相距不超过 8 个方块的两只成年宠物，会生下一只幼崽。幼崽加入主人的收藏，并且除非主人已达到
maxEquippedPets，否则会出现在场上。 - 幼崽继承其中一个亲代的颜色变体。物种设置了
babyModel时它穿着该模型，否则穿着其变体模型，无论哪种，大小都是成年体型的babyScale。 - 两个亲代都要等待
breedingCooldownMinutes（默认5分钟）才能再次繁殖。在此期间喂食亲代会显示breedingCooldownMessage。 - 幼崽在出生后经过
babyGrowthMinutes（默认20分钟）长大。幼崽在家中时也会计时，成年体会在幼崽下次出场时出现。 - 幼崽不能繁殖，蜇刺时也不播放攻击动画。
幼崽出生时，亲代会播放它们的 interact 动画。
跟随、停留与游荡
使用自带行为时，场上的玩家宠物会停留在主人附近。下面的数值是 follow_owner、stay、drift 和 hover 模块以及物种的 follow 和 float 键的默认值：
- 一旦主人距离超过
follow.distance（5个方块），宠物就会跟随，目标是主人身后 1.5 个方块处；对飞行物种而言，该目标还会高出主人脚部float.hoverHeight。飞行者在follow.speed: 1时以每秒 5 个方块跟随，超过follow.leashDistance（12）后则以每秒 8 个方块跟随。它会在那个位置停止跟随，或在距离主人 3 个方块（跟随距离的 0.6）以内时停止。 - 超过
follow.teleportDistance（24）时，宠物会传送到主人身边。如果它连续 3 秒没有任何进展，也会传送：没有通往主人的路径，路径在栅栏或岸边就中断了、够不到主人，或者飞行者的前方有墙。追赶只会把宠物落在离主人更近的位置，绝不会让行走者或游泳者落在主人所在的那个方块上。 - 在跟随距离之内，飞行者会飘向主人周围
follow.roamRadius（5）范围内的随机点，并在两次漂移之间原地起伏，保持在地面上方float.hoverHeight处，上下浮动不超过float.hoverVariance。行走物种会闲逛，并时不时看向附近的玩家；游泳物种会在水下游动。 - 当主人用繁殖食物或拴绳以外的任何东西右键点击宠物时，它会像狗一样留在原地，并轻轻起伏。下一次这样的点击会让它再次跟随。把
follow.stay设为false可关闭此功能。其他玩家对玩家宠物的点击不起作用。
follow.speed 会乘到除迁徙飞行外的每个自带行为的速度上。飞行的身体被直接操控。其他身体则使用原版寻路走或游到相同的点；参见速度。不会游泳的宠物会悬停在水面和岩浆表面之上，而不是沉到底部。
野生宠物以同样的方式围绕它生成的地方游荡。
场上的宠物会在主人退出时离开世界，并在主人下次加入时重新出现在其身边。因区块卸载、世界切换或长距离传送而丢失的宠物，会在一秒内回到主人身边。
宠物菜单
/fmm pets 以箱子菜单的形式打开玩家的收藏，标题为 menuTitle。它最多显示 54 只宠物。
- 每个条目显示物种的
icon物品，物种设置了iconItemModel时则带有该物品模型。场上的宠物会带有附魔光效。 - 描述（lore）显示物种、变体（与物种模型不同时）、年龄，以及宠物是否在玩家身边。
- 点击条目会带上该宠物同行或让它回家。带出的宠物超过
maxEquippedPets时会被拒绝，并显示maxEquippedMessage。 - 没有宠物的玩家会收到
noPetsMessage，而不是菜单。
收藏保存在玩家身上，以 JSON 形式存放在玩家的持久数据中，因此它跟随玩家的存档文件，无需数据库。其物种已不再安装的宠物会留在收藏中，显示为屏障图标，并且不会出场。
伤害与死亡
| 宠物 | 伤害 |
|---|---|
玩家拥有，COSMETIC 模式 | 忽略所有伤害 |
玩家拥有，CREATURES 模式 | 忽略来自其主人的伤害。当 petsInvulnerableToPlayers 为 true（默认）时，忽略来自其他玩家的伤害。其他伤害照常生效 |
| 野生 | 像任何生物一样受到伤害 |
对无法受伤的宠物的左键点击不算攻击，因此模型不会闪红。
玩家拥有的宠物死亡时会回家，并可以从 /fmm pets 再次带出。设置 petsDiePermanently: true 后，它会改为离开收藏。死亡的野生宠物就消失了。
野生宠物
野生宠物只存在于 CREATURES 模式。它们像原版农场动物一样生活：大多数在区块生成时随世界而来，留在原地，并且从不消失。
为新区块填充
区块生成时，FreeMinecraftModels 会以 wildGenerationChance（0.01）进行判定。成功时，它会在随机一列周围的地表放置一个物种的一组宠物，该物种按 wildSpawn.weight 从可以在那里出现的物种中选出。每放置一组之后都会重复判定。大于 0.9 的值按 0.9 计，因此区块不会被无限填满。上限、玩家、时间和生物生成游戏规则都不会限制这种填充。
玩家周围的补充生成
每隔 wildSpawnIntervalTicks（400，不低于 20），会进行一轮补充，在每位不处于旁观模式的玩家周围 8 个区块内的已加载区块中添加野生宠物：
- 每个区块以
wildSpawnChunkChance（0.01）的几率尝试。 - 地点必须距离最近的玩家和世界出生点超过 24 个方块，且距该玩家不超过 128 个方块。
- 当该地点附近每位玩家 8 个区块内所有物种的野生宠物达到
wildPetCapPerPlayer（6）只时，补充生成停止。每个物种的wildSpawn.cap（4）会进一步限制该物种。 - 补充生成遵循世界的生物生成游戏规则以及每个物种的
wildSpawn.time。
迁徙者不计入这些上限。
野生宠物在哪里等待
当野生宠物所在区块卸载或停止 tick 时，它的物种、变体、位置和家会被存入 plugins/FreeMinecraftModels/data/wild_pets.yml。当有玩家处于该已加载区块 8 个区块范围内时，它会回来。每当世界保存，以及 FreeMinecraftModels 关闭或重载时，都会写入该文件。
其物种已不再安装的野生宠物会继续在文件中等待。被其他插件移除的存活野生宠物就消失了，如同死亡一样。
夜间迁徙
时不时会有一群迁徙物种在夜空中飞过玩家头顶，并在飞越之后离开。当一个物种的 locomotion 为 FLYING、其宠物文件有 migration: 部分，并且其行为运行 migrate（FLYING 的默认值包含它）时，该物种就会迁徙。物种有变体时，迁徙者可能穿着的每个变体都必须运行 migrate。有 migration: 部分却不满足这些条件的物种永远不会发起迁徙群，并会在加载时记录一条警告，除非它的 migration.weight 为 0 或 migration.enabled 为 false。
- 计划在夜间每 5 秒在普通（主世界类型）世界中查看一次。每位玩家每晚按
migrations.chancePerNight（0.15）判定一次。判定成功会在当晚剩余时间里选一个时刻，要足够早，使整个飞越过程在黎明前结束。 - 在那个时刻，如果玩家处于露天之下，没有其他迁徙群处于其
migrations.viewDistance范围内，并且空中的迁徙群少于migrations.maxActiveFlocks（3）个，迁徙群就会开始。否则它会不断重试，直到夜晚结束。 - 一个迁徙群有
minFlockSize到maxFlockSize个成员（8到14），在玩家和其下方地面中较高者之上altitude个方块（28）处，以每 tickspeed个方块（0.15）飞行，沿一条直线路径，在durationSeconds（90）的中点飞越玩家头顶；当世界的模拟距离小于 12 个区块时则更早，因为迁徙群从其成员仍会 tick 的位置开始。 - 成员是该物种的普通野生宠物，穿着完整的模型并带有动画，大小是物种大小的
migration.scale倍，被点亮到完全明亮，并可在migrations.viewDistance（160）个方块外被看到。客户端仍需要迁徙群下方的区块处于其渲染距离之内。 - 在
CREATURES模式下，接近迁徙者的玩家可以驯服它，这会让它脱离迁徙群。飞越结束时，仍在飞行的成员会被移除。
/fmm petmigrate [species] 会立刻让一个迁徙群飞过你的头顶，无论时间、天空或其他迁徙群如何。指定物种时，即使该物种没有 migration: 部分也会启动，但其成员只有在运行 migrate 时才会沿路线飞行。不指定物种时，它按 migration.weight 选择一个迁徙物种。
迁徙部分
| 键 | 默认值 | 含义 |
|---|---|---|
enabled | true | false 会关闭该物种的迁徙，并保留其他值 |
model | 空 | 每个成员使用的固定模型。为空时像野生生成一样从物种的变体中挑选 |
scale | 1 | 迁徙者相对于物种 scale 的大小 |
animation | 空 | 飞行时循环播放的动画。为空时播放模型自己的 idle 和 walk |
weight | 1 | 多个物种迁徙时，选中该物种的频率。0 会让它不进入夜间计划 |
行为
宠物自己做的一切都来自行为模块：位于 plugins/FreeMinecraftModels/pet_behaviors/ 的 Lua 文件。FreeMinecraftModels 自带 15 个模块，并在启动时以及 /fmm reload 时，只要该文件夹中没有同名文件，就把每个模块写入其中。被删除的自带模块会在下次加载时回来。文件夹中已有的模块永远不会被覆盖，无论是否编辑过，所以它保留写入时的版本：删除你的副本并重载，即可获得你的 FreeMinecraftModels 版本自带的那个版本。
每只宠物运行其物种文件所列出的模块，并使用该物种的设置。/fmm reload 会重新读取模块和宠物文件，并让每只宠物重新用上它们。若要修改模块或编写你自己的模块，参见宠物行为模块。
behaviors 列表
behaviors:
- migrate
- stay
- follow_owner
- campfire: { radius: 20, night_only: false }
- drift
- hover
- sting:
effect: POISON
damage: 1
- 每个条目是一个模块名称（即去掉
.lua的文件名），或者是带设置的名称：写在同一行，如name: { setting: value }，或写在下面几行，相对名称缩进两个空格。 - 条目中省略的设置保留模块的默认值。默认值列在自带模块下，也在每个
.lua文件的顶部。 - 宠物只运行其列表中列出的内容。省略某个模块，该物种就永远不会做那件事。
- 列表的顺序不决定运行哪个行为。决定这一点的是每个模块的优先级，而宠物文件无法更改它：请复制该模块并在那里更改优先级。顺序只在两个模块冲突时才有意义，此时保留第一个。
- 被列出两次的模块只运行一次，使用第一个条目的设置，并且控制台会发出警告。
没有列表时的默认值
没有 behaviors: 列表的物种文件，会运行其运动方式的默认值：
locomotion | 默认行为 |
|---|---|
FLYING | migrate、stay、follow_owner、drift、hover |
GROUNDED、AMPHIBIOUS | stay、follow_owner、wander、idle_look |
AQUATIC | stay、follow_owner、swim |
STATIONARY | stay、follow_owner |
列表会替换这些默认值，而不是在其基础上追加，因此添加了某个模块的列表，也必须写出它要保留的默认值。behaviors: [] 表示完全不运行任何模块。不是列表的 behaviors 值会被忽略并给出警告，该物种运行其默认值。
变体行为
把变体写成映射，可以让穿着它的宠物拥有更多模块或不同的设置：
variants:
- firefly
- model: firefly_blue
weight: 0.5
behaviors:
- night_glow: { light: 10 }
- crop_drizzle
- 变体映射接受
model、weight（默认1）和behaviors。任何其他键都会被忽略并给出警告。 - 穿着该变体的宠物，运行物种的列表（或其运动方式的默认值）加上该变体的条目。两个列表都提到的模块保持其在物种列表中的位置，并在物种的设置之上采用变体的设置。变体的其他模块排在物种自己的模块之后。
- 幼崽运行其变体的列表，即使它穿着
babyModel。
设置值
每个设置的类型与其默认值相同：数字、true 或 false、文本，或文本列表。
- 含义明确的值可以用另一种形式接受：带引号的数字（如
"8"）、任意大小写的"true"或"false"，以及单个单词表示的单项列表。 - 给文本设置传入数字或
true/false时，会采用 YAML 读取到的值，所以on和yes会变成true。请把这类单词放在引号里。 - 列表请用方括号书写，如
[CAMPFIRE, SOUL_CAMPFIRE]，或每行一项并以-开头。包含逗号或空格的文本不会被当作列表读取。 - 模块没有的设置、没有值的设置、含有空条目的列表，或类型错误的值，都会记录一条指出宠物文件名称的警告，并保留默认值。该生物仍会加载。
自带模块
| 模块 | 优先级 | 类型 | 作用 |
|---|---|---|---|
migrate | 1 | 行为 | 飞行夜间迁徙路线 |
stay | 5 | 行为 | 保持在被命令停留的位置 |
follow_owner | 10 | 行为 | 跟上主人 |
campfire | 15 | 行为 | 夜间绕着点燃的营火打转 |
day_perch | 18 | 行为 | 白天停歇在树叶或地面上 |
rain_bloom | 19 | 行为和传感器 | 雨中膨胀，并更频繁地漂移 |
drift | 20 | 行为 | 飞向其锚点周围的随机点 |
wander | 20 | 行为 | 走向其锚点周围的可站立地点 |
swim | 20 | 行为 | 游向其锚点周围水下的地点 |
hover | 30 | 行为 | 在两次漂移之间原地起伏 |
idle_look | 30 | 行为 | 时不时看向附近的玩家 |
night_glow | 传感器 | 夜间点亮模型 | |
sting | 传感器 | 蜇触碰它的玩家或敌对生物 | |
crop_drizzle | 传感器 | 让它悬停其上的作物生长 | |
owner_effect | 传感器 | 给予其主人一个药水效果 |
优先级数字较小的行为，会接管正在运行的、数字较大的行为，所以跟随优先于营火，营火优先于漂移。传感器从不移动宠物；它们与正在运行的任何行为同时运行。
宠物的锚点是它围绕游荡的对象：它的主人，或者对野生宠物而言是它生成的地方。当宠物没有被命令停留，并且是野生的或距离主人在 follow.distance 以内时，它处于安定状态。
速度
模块请求的速度是其 speed 设置乘以 follow.speed。飞行的身体每 tick 飞行那么多个方块，最多 4；0.05 即每秒一个方块。行走或游泳的身体用原版导航前往那里，以该数字的 4 倍作为其身体类型自身移动速度的倍率，且速度绝不低于自身移动速度的四分之一。speed 为 0 时，行走者或游泳者静止不动。
migrate
宠物飞行夜间迁徙时，会以迁徙群的速度飞行迁徙群的路线，优先于其他所有行为。飞越结束或玩家驯服该宠物时它会停止。其行为不运行它的物种永远不会发起迁徙群。没有设置。
stay
在主人的停留点击之后，宠物会保持该位置并轻轻起伏。每次起伏都停留在身体自己的介质中：飞行者在空中，行走者在地面上，游泳者在水下，并保持被命令停留时所在的深度。
| 设置 | 默认值 | 含义 |
|---|---|---|
speed | 0.03 | 参见速度 |
bob_ticks | 40 | 两次起伏之间的 tick 数 |
bob_radius | 0.5 | 一次起伏可以让它偏离该位置的方块数 |
自带的移动行为在宠物被命令停留时都会等待，所以列表中没有 stay 的宠物不会起伏。
follow_owner
让玩家的宠物与其主人待在一起，如跟随、停留与游荡所述。它从物种文件读取 follow.distance、follow.leashDistance、follow.teleportDistance 和 float.hoverHeight。
追赶传送会落在主人 2 个方块以内、宠物自己的介质中：飞行者落在其悬停带，行走者落在可站立的地面，游泳者落在 6 个方块以内的水中，两栖身体则落在地面，没有地面时落在水中。落点必须比宠物当前位置离主人至少近一个方块，并且行走者或游泳者的落点至少离主人一个方块。当没有任何位置合适时，它会在再过 stuck_ticks 之后重试。
| 设置 | 默认值 | 含义 |
|---|---|---|
speed | 0.25 | 跟随速度。参见速度。为 0 时，宠物只通过追赶传送跟上 |
leash_urgency | 1.6 | 超过 follow.leashDistance 后的速度倍数 |
trail_back | 1.5 | 宠物以主人身后多少个方块为目标 |
stuck_ticks | 60 | 宠物在传送到主人身边之前，连续没有进展的 tick 数 |
drift
用于飞行物种。宠物飞向其锚点周围 follow.roamRadius 范围内、位于其悬停带（地面上方 float.hoverHeight，上下浮动不超过 float.hoverVariance）之内的随机点，然后休息。
| 设置 | 默认值 | 含义 |
|---|---|---|
speed | 0.06 | 参见速度 |
drift_ticks | 160 | 一次漂移最多持续的 tick 数 |
stuck_ticks | 20 | 一次漂移在放弃之前没有移动的 tick 数 |
rest_ticks | 60 | 宠物在一次漂移之后休息的 tick 数 |
rest_random_ticks | 80 | 额外增加随机的 0 到该值减 1 的休息 tick 数 |
hover
用于飞行物种。当没有其他移动行为在运行时，宠物会原地起伏：每隔 bob_ticks，它向上或向下移动最多 float.hoverVariance 的一半。偏离地面上方 float.hoverHeight 超过 correct_above 个方块的宠物，会直接回到那个高度。它向下最多查找 12 个方块来寻找地面。
| 设置 | 默认值 | 含义 |
|---|---|---|
speed | 0.03 | 参见速度 |
bob_ticks | 30 | 两次起伏之间的 tick 数 |
correct_above | 1.5 | 偏离其悬停高度多少个方块时，它会直接回到该高度 |
wander
用于行走物种。宠物走向其锚点附近的一个可站立地点，休息，然后再次出发。野生宠物在它生成地点的 follow.roamRadius 范围内选择地点。玩家的宠物在主人的 follow.roamRadius 范围内、且不超过 follow.distance 的 0.8 的范围内选择地点，因此它一到达就不会马上开始跟随。一次行走会在距其目标地点 1.5 个方块以内、经过 walk_ticks 之后，或经过 stuck_ticks 没有移动之后结束。在水面或长距离落差上，当没有任何地点合适时，它会等完一次休息再重新寻找。
| 设置 | 默认值 | 含义 |
|---|---|---|
speed | 0.15 | 参见速度 |
walk_ticks | 120 | 一次行走最多持续的 tick 数 |
stuck_ticks | 20 | 一次行走在放弃之前没有移动的 tick 数 |
rest_ticks | 80 | 宠物在一次行走之后休息的 tick 数 |
rest_random_ticks | 120 | 额外增加随机的 0 到该值减 1 的休息 tick 数 |
idle_look
宠物时不时会在 look_ticks 内看向 range 以内最近的玩家，然后休息。它只接管视线，所以任何移动宠物的行为都会接管过去，并且它从不看向创造或旁观模式的玩家。range 为 0 时关闭。STATIONARY 身体从不转动视线，所以其默认值不含此模块。
| 设置 | 默认值 | 含义 |
|---|---|---|
range | 8 | 它会看向此距离（方块）以内的玩家 |
look_ticks | 40 | 一次注视最多持续的 tick 数 |
rest_ticks | 100 | 两次注视之间的 tick 数 |
rest_random_ticks | 100 | 额外增加随机的 0 到该值减 1 的两次注视之间的 tick 数 |
swim
用于游泳物种。宠物游向其锚点附近水中、水面下 min_depth 到 max_depth 个方块之间的一个地点，休息，然后再次出发。它像 wander 一样在锚点周围选择地点，并且只选水中的地点。搁浅在陆地上的游泳者会在原地等待；玩家的游泳宠物会在其主人移开、且 follow_owner 的追赶在他们身边找到水之后回到水中。
| 设置 | 默认值 | 含义 |
|---|---|---|
speed | 0.15 | 参见速度 |
min_depth / max_depth | 0.5 / 3 | 水面下的方块数，0 到 16 |
swim_ticks | 120 | 一次游动最多持续的 tick 数 |
stuck_ticks | 20 | 一次游动在放弃之前没有移动的 tick 数 |
rest_ticks | 40 | 宠物在一次游动之后休息的 tick 数 |
rest_random_ticks | 60 | 额外增加随机的 0 到该值减 1 的休息 tick 数 |
campfire
夜间，处于安定状态的宠物会飘向 radius 个方块内最近的点燃的营火，并在其烟雾中缓缓打转。玩家的宠物只会选择离主人足够近的火堆，使得绕着它打转永远不会触发跟随。宠物每秒检查一次火是否仍然点燃。
| 设置 | 默认值 | 含义 |
|---|---|---|
radius | 12 | 寻找火堆的方块数，1 到 32 |
height | 2.5 | 宠物在火堆上方多少个方块处打转 |
ring | 0.8 | 圆圈的半径 |
night_only | true | 仅在黄昏到黎明之间 |
wild / pets | true / true | 野生宠物和玩家的宠物是否聚集 |
blocks | [CAMPFIRE, SOUL_CAMPFIRE] | 算作火堆的方块。只有这两种有效 |
soul_variants | [] | 只被灵魂营火吸引的变体模型。此时其他所有变体只会选普通营火。为空表示任何变体都可以选任何列出的火堆 |
search_seconds | 5 | 两次寻找火堆之间的秒数。至少为 1 |
speed | 0.06 | 参见速度 |
day_perch
白天，处于安定状态的宠物会降落到它下方最近的树叶上，或紧邻其下方的地面上，并在那里休息，轻轻起伏。黄昏时、被雨淋到时，以及主人走出跟随范围时，它会飞起。玩家的宠物只会选择距主人 follow.distance 以内的栖息处。当它找不到可以坐的地方（例如水面或长距离落差）时，会在 5 秒后重新寻找。
| 设置 | 默认值 | 含义 |
|---|---|---|
height | 0.3 | 它休息时位于树叶或地面上方的方块数，0 到 8 |
search_radius | 2 | 向侧面寻找树叶的方块数，0 到 4 |
wild / pets | true / true | 野生宠物和玩家的宠物是否栖息 |
speed | 0.06 | 距栖息处超过一个方块时的速度。参见速度 |
settle_speed | 0.03 | 最后一个方块的速度 |
rain_bloom
当雨淋在宠物身上时，它会膨胀，并更频繁、更高、更快地在锚点周围漂移。雨停或它找到遮蔽处时，它会缩回原样。当天气为降雨、宠物处于露天之下，并且所在生物群系温暖潮湿到会下雨时，雨才会淋到宠物。膨胀是每 4 个 tick 运行一次的传感器；漂移是优先级为 19 的行为，因此在雨中它取代 drift。
| 设置 | 默认值 | 含义 |
|---|---|---|
scale_multiplier | 1.25 | 雨中相对于正常大小的大小，0.1 到 16 |
scale_seconds | 3 | 膨胀或缩回所用的秒数 |
drift_frequency | 2.5 | 两次漂移之间的休息比 rest_ticks 和 rest_random_ticks 给出的短多少倍，但不低于 10 tick |
rise | 1 | 它漂移时高出多少个方块 |
speed_multiplier | 1.4 | 它漂移时快多少倍 |
speed | 0.06 | 应用 speed_multiplier 之前的漂移速度。参见速度 |
drift_ticks | 120 | 一次漂移最多持续的 tick 数 |
stuck_ticks | 20 | 一次漂移在放弃之前没有移动的 tick 数 |
rest_ticks / rest_random_ticks | 60 / 80 | 被 drift_frequency 缩短的休息 |
night_glow
夜间，模型的显示骨骼会以固定的光照等级被点亮，无论宠物所在位置的光照如何。没有太阳的世界视为夜晚。该传感器每 2 秒检查一次。仅限 Java 版玩家：基岩版玩家看到的模型使用世界光照。
| 设置 | 默认值 | 含义 |
|---|---|---|
night_only | true | false 表示昼夜都发光 |
light | 15 | 光照等级，0 到 15 |
lantern_bone | lantern | 带有此名称骨骼的模型在发光时会循环播放 animation |
animation | glow | 灯笼骨骼的动画 |
sting
野生宠物会蜇触碰其模型的玩家，创造或旁观模式除外。玩家的宠物会蜇进入其模型碰撞箱 reach 范围内的敌对生物，而从不蜇玩家。成年宠物蜇刺时会播放它们的 attack 动画。每 4 个 tick 检查一次触碰，每 10 个 tick 检查一次附近的生物。
| 设置 | 默认值 | 含义 |
|---|---|---|
wild / pets | true / true | 野生宠物是否蜇玩家，以及玩家的宠物是否蜇敌对生物 |
effect | SLOWNESS | 药水效果，按名称。NONE 表示没有效果 |
duration_ticks | 60 | 效果持续的 tick 数，1 到 6000 |
amplifier | 0 | 效果等级；0 为 I 级 |
damage | 0 | 每次蜇的伤害，以半颗心为单位 |
cooldown_seconds | 3 | 这只宠物能再次蜇同一个受害者之前的秒数 |
reach | 0.5 | 玩家的宠物仍会蜇某个生物时，该生物距模型碰撞箱的方块数，0 到 4。野生宠物蜇人需要玩家触碰模型 |
不存在的 effect 名称，会对每个物种和名称各记录一次警告，并且这次蜇不施加任何效果。
crop_drizzle
当宠物静止悬停在作物上方时，一场小雨会落在作物上，并且每隔 interval_seconds，作物都可能生长一个阶段。作物是 Minecraft 的 crops 标签中的方块，以及下界疣和甜浆果丛。宠物只会透过空气垂直向下看。生长会作为 BlockGrowEvent 发出，因此保护插件和农业插件可以拒绝它。野生宠物和玩家的宠物都适用。
| 设置 | 默认值 | 含义 |
|---|---|---|
chance | 0.1 | 每个间隔作物生长的几率，0 到 1 |
interval_seconds | 5 | 两次尝试之间的秒数。至少为 1；每秒检查一次，因此小数会等到下一个整秒 |
depth | 4 | 在宠物下方多少个方块内寻找作物，1 到 8 |
owner_effect
当玩家的宠物在场上、且与主人相距在 range 个方块以内时，主人会获得一个药水效果，例如夜视或水下呼吸。该效果持续 15 秒并每秒更新一次，因此永远不会闪烁，并且在宠物回家或主人离开其范围后 15 秒内消退。它显示图标但没有粒子。如果主人已经有强度不低于它、持续时间不短于它的同一效果（例如来自他们喝下的药水），宠物就不会去动它。
它适合持续性的效果：夜视、水下呼吸、速度、急迫、防火。作用于剩余时间的效果（例如再生、中毒和凋零）在每秒更新时会出现异常。
| 设置 | 默认值 | 含义 |
|---|---|---|
effect | NIGHT_VISION | 药水效果，按名称 |
amplifier | 0 | 效果等级；0 为 I 级 |
range | 16 | 距宠物的方块数 |
旧的世界互动部分
在行为模块出现之前编写的宠物文件，可能有 campfire:、rainBloom:、glow:、sting:、dayPerch: 或 drizzle: 部分。它们现在不起任何作用，并且每个都会在文件加载时记录一条警告：
firefly.pet.yml: the campfire section is ignored now that world interactions are behavior modules; list the campfire module under behaviors: instead (see plugins/FreeMinecraftModels/pet_behaviors/campfire.lua for its settings).
单独的一行 glow: true 会得到同样的警告，措辞为 the glow setting。当该部分被关闭（enabled: false，或 glow: 设置为 true 以外的任何值），或文件已经列出了它的模块时，警告只会要求你把它删除。
若要保留某项互动，请列出它的模块并重命名其设置：
| 旧部分 | 模块 | 重命名的设置 |
|---|---|---|
campfire | campfire | nightOnly 改为 night_only，soulVariants 改为 soul_variants，searchSeconds 改为 search_seconds |
rainBloom | rain_bloom | scaleMultiplier 改为 scale_multiplier，scaleSeconds 改为 scale_seconds，driftFrequency 改为 drift_frequency，speedMultiplier 改为 speed_multiplier |
glow | night_glow | nightOnly 改为 night_only，lanternBone 改为 lantern_bone |
sting | sting | durationTicks 改为 duration_ticks，cooldownSeconds 改为 cooldown_seconds |
dayPerch | day_perch | searchRadius 改为 search_radius |
drizzle | crop_drizzle | intervalSeconds 改为 interval_seconds |
其他设置保留原名。去掉 enabled：不在列表中列出某个模块，就是关闭它的方式。没有 behaviors: 列表的文件只运行其运动方式的默认值，所以也要把这些列出来。对于保留了营火和发光的飞行物种：
behaviors:
- migrate
- stay
- follow_owner
- campfire: { radius: 12 }
- drift
- hover
- night_glow
migration: 仍然是宠物文件的一个部分；参见迁徙部分。
倾斜与居中
飞行和游泳的生物通常在随行进而倾斜、并围绕自己的中心转动时看起来更好：
orientation设置模型在行进时如何倾斜。UPRIGHT（默认）只朝向它前进的方向。TOP_FIRST以顶部领先，像水母一样：它倾向行进方向，巡航时侧躺，下潜时倒转。FRONT_FIRST适合鸟和鱼：它爬升和下潜时俯仰，转弯时侧倾。宠物停下时，每种样式都会恢复直立。参见行进朝向。centerOnBody把模型绘制成其立方体的中心位于其隐藏身体的中心，而不是站在身体的脚下。这样模型围绕身体移动、转向和倾斜，其点击框位于玩家看到的位置。它对FLYING和AQUATIC物种默认为true，对其他物种默认为false。参见让模型以身体为中心。
物种文件参考
把 <species>.pet.yml 放在 plugins/FreeMinecraftModels/models/ 下的任意位置，通常紧挨着它所使用的模型。FreeMinecraftModels 会在启动时和 /fmm reload 时读取每个名称以 .pet.yml 结尾的文件。.pet.yml 之前的文件名是默认的物种 ID。
isEnabled: true
species: firefly
model: firefly
name: '&eFirefly'
body: ALLAY
scale: 1.0
health: 20
icon: GLOW_BERRIES
iconItemModel: ''
tamingFood:
- GLOW_BERRIES
breedingFood:
- GLOW_BERRIES
tameChance: 0.34
babyModel: ''
babyScale: 0.5
babyGrowthMinutes: 20
breedingCooldownMinutes: 5
loveSeconds: 30
variants:
- firefly
- firefly_blue:0.5
follow:
distance: 5
leashDistance: 12
teleportDistance: 24
roamRadius: 5
speed: 1.0
stay: true
float:
hoverHeight: 1.5
hoverVariance: 0.75
locomotion: FLYING
centerOnBody: true
orientation:
style: FRONT_FIRST
startSpeed: 0.6
fullSpeed: 4.0
maxTilt: 180
turnSpeed: 180
wildSpawn:
enabled: true
weight: 10
minGroup: 1
maxGroup: 3
placement: AIR
minLight: 0
maxLight: 15
cap: 4
worlds: []
environments:
- NORMAL
biomes:
- minecraft:plains
time: NIGHT
minY: -64
maxY: 320
behaviors:
- migrate
- stay
- follow_owner
- campfire: { radius: 12 }
- drift
- hover
- night_glow: { light: 15 }
migration:
scale: 2.0
身份与外观
| 键 | 默认值 | 含义 |
|---|---|---|
isEnabled | true | false 会跳过该文件 |
species | 文件名 | 物种 ID，小写。玩家保存的宠物和 /fmm petadmin 都使用它，所以一旦玩家拥有宠物，就要保持它稳定。当两个文件定义了同一个 ID 时，保留路径靠前的那个，并且控制台会发出警告 |
model | 文件名 | 宠物穿着的模型。当它未加载时控制台会发出警告，并且该宠物无法生成 |
name | 文件名 | 显示在宠物上方和消息中的名称。支持 & 颜色代码 |
body | ALLAY | 承载模型的原版生物类型。移动时的碰撞以它的大小为准 |
scale | 1 | 整体大小，至少为 0.0625 |
health | 20 | 身体的最大生命值，至少为 1 |
icon | GLOW_BERRIES | 菜单图标物品 |
iconItemModel | 空 | 来自资源包的、用于菜单图标的物品模型（namespace:path） |
variants | [] | 颜色变体，写成 model、model:weight，或带有 model、weight 和 behaviors 的映射（参见变体行为）。野生生成按权重挑选一个，被驯服的宠物保留自己的变体，幼崽继承一个亲代的变体。为空表示只有 model。变体应共享相同的骨骼和动画 |
驯服与繁殖
| 键 | 默认值 | 含义 |
|---|---|---|
tamingFood | [] | 可驯服野生成年宠物的物品名称 |
breedingFood | [] | 可让玩家的成年宠物进入求偶状态的物品名称 |
tameChance | 0.333 | 一次喂食驯服成功的几率 |
babyModel | 空 | 幼崽阶段穿着的模型，大小为 babyScale。为空时使用变体模型 |
babyScale | 0.5 | 幼崽相对于 scale 的大小 |
babyGrowthMinutes | 20 | 幼崽长成成年体所需的分钟数 |
breedingCooldownMinutes | 5 | 亲代再次繁殖之前的分钟数 |
loveSeconds | 30 | 被喂食的成年宠物等待伴侣的时长 |
移动
follow 和 float 的值由自带的行为模块读取，如所注明。
| 键 | 默认值 | 含义 |
|---|---|---|
follow.distance | 5 | 主人距离超过此值时 follow_owner 开始跟随。在此之内，宠物处于安定状态并可自由游荡 |
follow.leashDistance | 12 | 超过此值 follow_owner 会加快速度 |
follow.teleportDistance | 24 | 超过此值 follow_owner 会把宠物传送到主人身边 |
follow.roamRadius | 5 | drift、rain_bloom、wander 和 swim 让宠物离开其锚点多远 |
follow.speed | 1 | 乘到除 migrate 外每个自带行为的速度上，至少为 0.05 |
follow.stay | true | 右键点击是否让宠物停留 |
float.hoverHeight | 1.5 | 飞行宠物保持在地面上方的方块数 |
float.hoverVariance | 0.75 | 它偏离该高度的最大幅度 |
locomotion | FLYING | 身体如何移动：FLYING、GROUNDED、AQUATIC、AMPHIBIOUS 或 STATIONARY。它还决定默认行为 |
centerOnBody | FLYING 和 AQUATIC 为 true | 参见倾斜与居中 |
orientation.style | UPRIGHT | UPRIGHT、TOP_FIRST 或 FRONT_FIRST |
orientation.startSpeed | 0.6 | 低于此速度（方块每秒）时模型保持直立 |
orientation.fullSpeed | 4.0 | 达到此速度（方块每秒）时它与行进方向完全对齐 |
orientation.maxTilt | 180 | 最大倾斜角度，单位为度。180 允许顶部领先的模型倒转 |
orientation.turnSpeed | 180 | 其倾斜每秒最多可以变化的度数 |
野生生成
这些键只在 CREATURES 模式下适用。空列表表示允许一切。
| 键 | 默认值 | 含义 |
|---|---|---|
wildSpawn.enabled | true | 该物种是否作为野生生物生活 |
wildSpawn.weight | 10 | 相对于可在同一地点生成的其他物种的权重。0 表示永不生成。带有旧的 chance 键（0 到 1）且没有 weight 的文件，使用 chance 乘以 10 |
wildSpawn.minGroup / maxGroup | 1 / minGroup | 群体大小 |
wildSpawn.placement | 来自 locomotion | GROUND、WATER、WATER_SURFACE 或 AIR。FLYING 默认为 AIR，AQUATIC 默认为 WATER，其余默认为 GROUND。AIR 需要一个坚实、干燥的顶部方块，WATER_SURFACE 需要一个水的顶部方块，两者上方都要有两个空闲方块 |
wildSpawn.minLight / maxLight | 0 / 15 | 该地点所需的光照等级 |
wildSpawn.cap | 4 | 补充生成时，玩家周围 8 个区块内该物种野生宠物的最大数量 |
wildSpawn.worlds | [] | 世界名称 |
wildSpawn.environments | [] | NORMAL、NETHER 或 THE_END |
wildSpawn.biomes | [] | 生物群系键，例如 minecraft:plains |
wildSpawn.time | ANY | 用于补充生成，ANY、DAY 或 NIGHT |
wildSpawn.minY / maxY | -64 / 320 | 高度范围 |
行为与迁徙
| 键 | 默认值 | 含义 |
|---|---|---|
behaviors | 运动方式的默认值 | 该物种运行的行为模块及其设置。参见行为 |
migration | 无 | 该物种在夜间迁徙中的外观。参见迁徙部分 |
旧的 campfire、rainBloom、glow、sting、dayPerch 和 drizzle 部分会被忽略并给出警告。参见旧的世界互动部分。
pets.yml 参考
plugins/FreeMinecraftModels/pets.yml 会在首次启动时生成。/fmm reload 会应用更改。
| 键 | 默认值 | 含义 |
|---|---|---|
mode | COSMETIC | COSMETIC 或 CREATURES。参见宠物模式 |
maxEquippedPets | 0 | 一位玩家可以同时带出多少只宠物。0 表示没有限制 |
petsInvulnerableToPlayers | true | 玩家的宠物是否忽略来自其主人以外玩家的伤害 |
petsDiePermanently | false | 死亡的宠物是否离开其主人的收藏 |
wildGenerationChance | 0.01 | 新区块得到一组野生宠物的几率，0 到 0.9，每组之后重新判定 |
wildSpawnIntervalTicks | 400 | 两轮补充生成之间的 tick 数 |
wildSpawnChunkChance | 0.01 | 一轮补充生成尝试玩家附近某个区块的几率 |
wildPetCapPerPlayer | 6 | 玩家周围 8 个区块内所有物种的野生宠物达到多少只时，补充生成停止 |
migrations.enabled | true | 夜间迁徙是否运行 |
migrations.chancePerNight | 0.15 | 某位玩家在某一晚得到一个迁徙群的几率，0 到 1 |
migrations.minFlockSize / maxFlockSize | 8 / 14 | 迁徙群大小 |
migrations.altitude | 28 | 高于玩家或地面（取较高者）的方块数 |
migrations.speed | 0.15 | 每 tick 的方块数（0.15 即每秒 3 个方块） |
migrations.durationSeconds | 90 | 从迁徙群出现到被移除的秒数 |
migrations.viewDistance | 160 | 玩家能看到迁徙群的方块距离 |
migrations.maxActiveFlocks | 3 | 整个服务器同时处于空中的最大迁徙群数量 |
migrations.species | [] | 可以迁徙的物种 ID。为空表示每一个能迁徙的物种（参见夜间迁徙） |
消息支持 & 颜色代码。$pet 是宠物的名称，maxEquippedMessage 中的 $amount 是上限。
| 键 | 默认值 |
|---|---|
tamedMessage | &aYou tamed a $pet&a! It follows you now. &f/fmm pets &amanages your pets. |
tameFailedMessage | &7The $pet &7eats it, but is not tamed yet. |
stayMessage | &7Your $pet &7stays here. |
followMessage | &7Your $pet &7follows you again. |
menuTitle | &2Your pets |
noPetsMessage | &7You have no pets yet. Tame a wild creature by feeding it its favorite food. |
equippedMessage | &a$pet &ais with you. |
unequippedMessage | &7$pet &7went home. |
maxEquippedMessage | &cYou can only have $amount pets with you at once. |
breedingCooldownMessage | &7Your $pet &7is not ready to breed again yet. |
bornMessage | &aA $pet &awas born! |
命令与权限
| 命令 | 权限 | 默认 | 用途 |
|---|---|---|---|
/fmm pets | freeminecraftmodels.pets | true | 打开你的宠物菜单 |
/fmm petadmin mode [creatures|cosmetic] | freeminecraftmodels.pets.admin | op | 显示宠物模式，或切换模式并保存到 pets.yml |
/fmm petadmin list | freeminecraftmodels.pets.admin | op | 列出已加载的物种及其文件、模型、身体、驯服食物和繁殖食物 |
/fmm petadmin spawn <species> | freeminecraftmodels.pets.admin | op | 在你注视的方块上方（最远 12 格）生成一只野生宠物。仅限 CREATURES 模式 |
/fmm petadmin give <species> | freeminecraftmodels.pets.admin | op | 把该物种的一只成年宠物加入你自己的收藏，并在你未达到 maxEquippedPets 时把它带出 |
/fmm petmigrate [species] | freeminecraftmodels.pets.admin | op | 立即让一个迁徙群飞过你的头顶。参见夜间迁徙 |
这三个命令都仅限玩家执行。freeminecraftmodels.pets 控制宠物菜单，所有玩家默认都拥有它。freeminecraftmodels.pets.admin 控制 /fmm petadmin 和 /fmm petmigrate，默认授予服务器操作员，并随 freeminecraftmodels.* 一并授予。驯服、繁殖和命令宠物停留都不需要权限。
故障排查
在控制台中搜索 pet behavior、pet_behaviors 和 .pet.yml，可以找到有关行为模块的警告。每条警告都会指出需要修复的宠物文件或模块文件。
控制台显示 Pets are off。
服务端版本没有 FreeMinecraftModels 的 NMS 支持，或者低于 Minecraft 1.21.4。
控制台显示 Pet <species> (<file>) names model <model>, which is not loaded.
model 键指定的模型 ID 没有加载。其模型没有加载的变体不会记录任何内容；穿着该变体的宠物会改穿物种的 model。请检查模型的文件名（它就是模型 ID），以及该模型的重载日志。
控制台显示 Could not spawn pet <species>: <cause>。
该物种的宠物因所给原因而无法进入世界，例如模型未加载、行为无法启动，或身体无法生成。无论生成重试多少次，每个物种和原因在下次重载之前都只记录一次。
控制台显示 the <section> section is ignored now that world interactions are behavior modules。
宠物文件仍然带有旧的世界互动部分，或者一行 glow: true（警告中称之为 the glow setting）。参见旧的世界互动部分。
控制台显示 there is no pet behavior <name> in pet_behaviors/。
behaviors 列表指定了一个没有文件的模块。请检查拼写；有最接近的名称时，警告会给出建议。该生物仍会加载，只是没有那个模块。
控制台显示 the pet behavior <name> failed to load。
模块文件有错误。之前的一条警告会指出文件，对于 Lua 错误还会指出行号。请修复后运行 /fmm reload，或者删除损坏的自带模块，让 FreeMinecraftModels 重新写入它。
控制台显示 the pet behavior <module> has no setting <setting> 或 <module>.<setting> must be ...。
behaviors 列表中的某个设置拼写错误，或类型错误。警告会列出该模块的设置，或它所需的类型，并且保留默认值。参见设置值。
控制台显示 cannot run alongside the ones listed before it。
列表中的两个模块无法同时运行，通常是因为两者声明了相同的记忆、行为或传感器，就像把复制的模块与其原件并排列出时那样。列表中靠前的运行，另一个被排除。参见宠物行为模块。
没有出现野生宠物。
检查 mode 是否为 CREATURES，以及 /fmm petadmin list 是否显示该物种。然后检查 wildSpawn：enabled、大于 0 的 weight，以及它允许的世界、环境、生物群系、光照和高度。区块只在生成时被填充一次，所以已探索的区域只能通过补充生成来填充，而补充生成默认很慢，并且受上限限制。/fmm petadmin spawn <species> 会放置一只，用来检查宠物本身。
玩家无法打开 /fmm pets。
他们需要 freeminecraftmodels.pets，除非权限插件将其收回，否则每位玩家默认都拥有它。参见命令与权限。
迁徙群从不飞过天空。
迁徙群在夜间的主世界类型世界中，飞过处于露天之下的玩家，并且仅限带有 migration: 部分、且其行为运行 migrate 的 FLYING 物种。无法迁徙的物种会在加载时记录 has a migration section, but ... 以及修复方法。/fmm petmigrate <species> 会立即发送一个。
某只宠物什么都不做，或在更新之后不再做某件事。
检查它的 behaviors 列表：宠物只运行它指定的模块，而列表会替换默认值。如果宠物文件中的世界互动原先写成各个部分，那么在列出对应的模块之前，这些互动一个都不会运行。
宠物的发光在基岩版玩家那里不显示。 该发光只点亮 Java 版显示骨骼。