跳至主要內容

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 工具列中的 Pets 按鈕、/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 時則帶有該物品模型。在外的寵物，其圖示會帶有附魔光澤。
  • 描述顯示物種、變體（與物種模型不同時）、年齡，以及寵物是否與玩家同行。
  • 點擊項目會帶寵物同行或送牠回家。帶出超過 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）處，以每 tick speed 個方塊（0.15）的速度，沿一條直線路徑飛行，並在 durationSeconds（90）的中途飛越玩家上方；當世界的模擬距離小於 12 個區塊時會更早，因為遷徙群在其成員仍會 tick 的地方啟動。
  • 成員是該物種的一般野生寵物，穿著完整的模型並帶有動畫，大小是物種大小的 migration.scale 倍，光線全亮，並可在 migrations.viewDistance（160）個方塊外被看到。客戶端仍需要遷徙群下方的區塊位於其渲染距離之內。
  • 在 CREATURES 模式下，能到達遷徙者身邊的玩家可以馴服它，這會讓它離開遷徙群。橫越結束時，仍在飛行的成員會被移除。

/fmm petmigrate [species] 會立即讓一個遷徙群飛過你上方，不論時間、天空或其他遷徙群。指定物種時，即使該物種沒有 migration: 區段也會啟動，但它的成員只有在執行 migrate 時才會沿著路線飛行。沒有指定物種時，會依 migration.weight 挑選一個遷徙物種。

遷徙區段​

鍵預設值意義
enabledtruefalse 會關閉該物種的遷徙，並保留其他值
model空每位成員使用的固定模型。空白時會從物種的變體中挑選，就像野生生成一樣
scale1遷徙者相對於物種 scale 的大小
animation空飛行時循環播放的動畫。空白時播放模型自己的 idle 和 walk
weight1有多個物種遷徙時，挑選此物種的頻率。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 的預設值：

locomotion預設行為
FLYINGmigrate、stay、follow_owner、drift、hover
GROUNDED、AMPHIBIOUSstay、follow_owner、wander、idle_look
AQUATICstay、follow_owner、swim
STATIONARYstay、follow_owner

清單會取代這些預設值而不是附加到它們之上，因此要加入模組的清單，也必須列出它想保留的預設值。behaviors: [] 完全不執行任何模組。不是清單的 behaviors 值會被忽略並顯示警告，而該物種會執行它的預設值。

變體行為​

把變體寫成對映，即可讓穿著它的寵物有更多模組或其他設定：

variants:
  - firefly
  - model: firefly_blue
    weight: 0.5
    behaviors:
      - night_glow: { light: 10 }
      - crop_drizzle
  • 變體對映接受 model、weight（預設 1）和 behaviors。其他任何鍵都會被忽略並顯示警告。
  • 穿著該變體的寵物會執行物種的清單（或其 locomotion 的預設值），再加上變體的項目。兩個清單都列出的模組會保留在物種清單中的位置，並在物種的設定之上套用變體的設定。變體的其他模組排在物種自己的模組之後。
  • 幼崽執行其變體的清單，即使它穿著 babyModel 也一樣。

設定值​

每個設定的型別就是其預設值的型別：數字、true 或 false、文字，或文字清單。

  • 意義明確的值可以用其他形式寫成：加了引號的數字，如 "8"、不分大小寫的 "true" 或 "false"，以及單一個字作為只有一個項目的清單。
  • 給予數字或 true/false 的文字設定，會取用 YAML 讀到的值，所以 on 和 yes 會變成 true。請把這類字詞放進引號中。
  • 清單以方括號寫成，如 [CAMPFIRE, SOUL_CAMPFIRE]，或每行一個項目、以 - 開頭。含有逗號或空格的文字不會被讀成清單。
  • 模組沒有的設定、沒有值的設定、含有空項目的清單，或型別錯誤的值，都會記錄一則指出寵物檔案的警告，並保留預設值。生物仍會載入。

內附模組​

模組優先度種類作用
migrate1行為飛行夜間遷徙路線
stay5行為守住被告知待命的位置
follow_owner10行為跟上主人
campfire15行為夜間繞著點燃的營火打轉
day_perch18行為白天停在樹葉或地面上休息
rain_bloom19行為與感測器在雨中膨脹，並更常漂移
drift20行為飛到其錨點周圍的隨機點
wander20行為走到其錨點周圍的可站立位置
swim20行為游到其錨點周圍的水下位置
hover30行為在兩次漂移之間原地起伏
idle_look30行為不時看向附近的玩家
night_glow感測器夜間照亮模型
sting感測器螫刺碰到它的玩家或敵對生物
crop_drizzle感測器讓它懸浮於其上的作物成長
owner_effect感測器給予主人藥水效果

優先度數字較小的行為，會從執行中且數字較大的行為手中接管，因此跟隨勝過營火，營火勝過漂移。感測器永遠不會移動寵物；它們與正在執行的任何行為並行執行。

寵物的錨點是它圍繞活動的對象：它的主人，野生寵物則是它生成的地點。寵物在未被告知待命，且為野生或位於其主人的 follow.distance 之內時，處於安頓狀態。

速度​

模組要求的速度是它的 speed 設定乘上 follow.speed。飛行本體以每 tick 那麼多個方塊飛行，最多 4；0.05 是每秒一個方塊。步行或游泳的本體則以原版導航前往，速度是該數字的 4 倍，作為其本體類型自身移動速度的倍數，且絕不低於該移動速度的四分之一。speed 為 0 時，步行型或游泳型會站著不動。

migrate​

當寵物飛行夜間遷徙時，它會以遷徙群的速度飛行遷徙群的路線，優先於所有其他行為。橫越結束或玩家馴服該寵物時，它就會停止。行為不執行它的物種永遠不會發起遷徙群。沒有設定。

stay​

在主人的待命點擊之後，寵物會輕輕起伏地守住該位置。每次起伏都停在本體自己的介質中：飛行型在空中，步行型在地面上，游泳型在水下，並保持它被告知待命時的深度。

設定預設值意義
speed0.03請參閱速度
bob_ticks40兩次起伏之間的 tick 數
bob_radius0.5一次起伏可以使它偏離該位置的方塊數

內附的移動行為在寵物被告知待命時都會等待，因此清單中沒有 stay 的寵物不會有起伏。

follow_owner​

讓已被擁有的寵物跟著主人，如跟隨、待命與漫遊所述。它從物種檔案讀取 follow.distance、follow.leashDistance、follow.teleportDistance 和 float.hoverHeight。

追趕傳送會降落在主人 2 個方塊之內，位於寵物自己的介質中：飛行型是它的懸浮區間，步行型是可站立的地面，游泳型是 6 個方塊範圍內的水，兩棲型則是地面，沒有地面時才是水。它只會讓寵物降落在比目前位置至少更靠近主人一個方塊之處，而步行型或游泳型則至少離主人一個方塊。沒有合適位置時，會在再過一個 stuck_ticks 之後重試。

設定預設值意義
speed0.25跟隨速度。請參閱速度。為 0 時，寵物只能靠追趕傳送跟上
leash_urgency1.6超過 follow.leashDistance 時的速度倍數
trail_back1.5寵物瞄準的主人身後方塊數
stuck_ticks60寵物傳送到主人身旁之前，連續沒有進展的 tick 數

drift​

供飛行物種使用。寵物飛到其錨點 follow.roamRadius 之內、位於其懸浮區間（地面上方 float.hoverHeight，上下浮動 float.hoverVariance）的隨機點，然後休息。

設定預設值意義
speed0.06請參閱速度
drift_ticks160一次漂移最多持續的 tick 數
stuck_ticks20漂移放棄之前沒有移動的 tick 數
rest_ticks60寵物在漂移之後休息的 tick 數
rest_random_ticks80額外加上隨機的 0 到此值減 1 個 tick 的休息

hover​

供飛行物種使用。當沒有其他移動行為在執行時，寵物會原地起伏：每隔 bob_ticks，它會上下移動最多 float.hoverVariance 的一半。偏離地面上方 float.hoverHeight 超過 correct_above 個方塊的寵物，會改為直接飛回該高度。它向下最多尋找 12 個方塊來找地面。

設定預設值意義
speed0.03請參閱速度
bob_ticks30兩次起伏之間的 tick 數
correct_above1.5偏離其懸浮高度到這麼多個方塊時，它會直接飛回

wander​

供步行物種使用。寵物走到其錨點附近的可站立位置，休息，然後再出發。野生寵物在它生成的地點 follow.roamRadius 之內挑選位置。已被擁有的寵物在其主人 follow.roamRadius 之內、且距離主人不超過 follow.distance 的 0.8 倍處挑選位置，這樣一抵達就不會立刻開始跟隨。一趟行走會在抵達該位置 1.5 個方塊之內時、經過 walk_ticks 之後，或連續 stuck_ticks 沒有移動之後結束。在水面或高處落差之上、沒有合適位置時，它會等完一段休息再重新尋找。

設定預設值意義
speed0.15請參閱速度
walk_ticks120一趟行走最多持續的 tick 數
stuck_ticks20行走放棄之前沒有移動的 tick 數
rest_ticks80寵物在行走之後休息的 tick 數
rest_random_ticks120額外加上隨機的 0 到此值減 1 個 tick 的休息

idle_look​

寵物不時會在 look_ticks 內看向 range 之內最近的玩家，然後休息。它只取得視線，因此任何移動寵物的行為都會接管它，而且它從不看向創造或旁觀模式的玩家。range 為 0 會將它關閉。STATIONARY 本體從不轉動視線，所以它的預設值不含這個模組。

設定預設值意義
range8它會看向玩家的方塊範圍
look_ticks40一次注視最多持續的 tick 數
rest_ticks100兩次注視之間的 tick 數
rest_random_ticks100額外加上隨機的 0 到此值減 1 個 tick 的注視間隔

swim​

供游泳物種使用。寵物游到其錨點附近水中、水面下 min_depth 到 max_depth 個方塊之間的位置，休息，然後再出發。它像 wander 一樣在錨點周圍挑選位置，而且只挑選水中。擱淺在陸地上的游泳型會在原地等待；已被擁有的游泳型則會在主人移開，且 follow_owner 的追趕在他們身旁找到水之後，回到水中。

設定預設值意義
speed0.15請參閱速度
min_depth / max_depth0.5 / 3水面下的方塊數，0 到 16
swim_ticks120一次游泳最多持續的 tick 數
stuck_ticks20游泳放棄之前沒有移動的 tick 數
rest_ticks40寵物在游泳之後休息的 tick 數
rest_random_ticks60額外加上隨機的 0 到此值減 1 個 tick 的休息

campfire​

夜間，安頓的寵物會飄向 radius 個方塊之內最近的點燃營火，並在它的煙霧中緩緩繞圈。已被擁有的寵物只會選擇離主人夠近、繞著它轉時絕不會觸發跟隨的火源。寵物每秒檢查一次火源是否仍然點燃。

設定預設值意義
radius12尋找火源的方塊範圍，1 到 32
height2.5寵物繞圈時位於火源上方的方塊數
ring0.8圓圈的半徑
night_onlytrue只在黃昏到黎明之間
wild / petstrue / true野生寵物和已被擁有的寵物是否聚集
blocks[CAMPFIRE, SOUL_CAMPFIRE]會被採用的火源。只有這兩種有效
soul_variants[]只受靈魂營火吸引的變體模型。其他所有變體則只接受一般營火。空白表示任何變體都接受任何列出的火源
search_seconds5兩次尋找火源之間的秒數。至少為 1
speed0.06請參閱速度

day_perch​

白天，安頓的寵物會降落到它下方最近的樹葉上，或正下方的地面上，並在那裡輕輕起伏地休息。它會在黃昏、雨落在它身上，以及主人走出跟隨範圍時起飛。已被擁有的寵物只會選擇位於其主人 follow.distance 之內的棲息處。當它找不到可以坐的地方（例如水面或高處落差）時，會在 5 秒後重新尋找。

設定預設值意義
height0.3它休息時位於樹葉或地面上方的方塊數，0 到 8
search_radius2向側邊尋找樹葉的方塊數，0 到 4
wild / petstrue / true野生寵物和已被擁有的寵物是否棲息
speed0.06距離棲息處超過一個方塊時的速度。請參閱速度
settle_speed0.03最後一個方塊的速度

rain_bloom​

當雨落在寵物身上時，它會膨脹，並更常在其錨點周圍漂移，漂得更高、更快。雨停或找到遮蔽處時，它會縮回原狀。雨會在暴風雨期間、開闊的天空下、足夠溫暖潮濕而會下雨的生物群系中落在寵物身上。膨脹是每 4 個 tick 執行一次的感測器；漂移則是優先度 19 的行為，所以在雨中它會取代 drift。

設定預設值意義
scale_multiplier1.25雨中相對於正常大小的大小，0.1 到 16
scale_seconds3膨脹或縮回所需的秒數
drift_frequency2.5它在兩次漂移之間的休息，比 rest_ticks 和 rest_random_ticks 所給的短多少倍，絕不少於 10 個 tick
rise1它漂移時額外升高的方塊數
speed_multiplier1.4它漂移的速度是原本的幾倍
speed0.06乘上 speed_multiplier 之前的漂移速度。請參閱速度
drift_ticks120一次漂移最多持續的 tick 數
stuck_ticks20漂移放棄之前沒有移動的 tick 數
rest_ticks / rest_random_ticks60 / 80被 drift_frequency 縮短的休息

night_glow​

夜間，模型的顯示骨骼會以固定的光線等級被照亮，不論寵物所在位置的光線如何。沒有太陽的世界視為夜晚。感測器每 2 秒檢查一次。僅限 Java 玩家：Bedrock 玩家看到的是處於世界光線下的模型。

設定預設值意義
night_onlytruefalse 表示日夜都發光
light15光線等級，0 到 15
lantern_bonelantern有此名稱骨骼的模型，在發光期間會循環播放 animation
animationglow燈籠骨骼的動畫

sting​

野生寵物會螫碰到它模型的玩家，創造或旁觀模式除外。已被擁有的寵物會螫進入其模型碰撞箱 reach 範圍之內的敵對生物，絕不螫玩家。成年寵物螫刺時會播放它們的 attack 動畫。觸碰每 4 個 tick 檢查一次，附近的生物則每 10 個 tick 檢查一次。

設定預設值意義
wild / petstrue / true野生寵物是否螫玩家，以及已被擁有的寵物是否螫敵對生物
effectSLOWNESS藥水效果，以名稱指定。NONE 表示沒有效果
duration_ticks60效果持續時間，單位為 tick，1 到 6000
amplifier0效果等級；0 是第 I 級
damage0每次螫刺的傷害，單位為半顆心
cooldown_seconds3這隻寵物能再次螫同一個受害者之前的秒數
reach0.5已被擁有的寵物仍會螫到生物的、與模型碰撞箱相距的方塊數，0 到 4。野生寵物的螫刺需要玩家碰到模型

不存在的 effect 名稱，每個物種和名稱只會記錄一次警告，而且該次螫刺不會套用任何效果。

crop_drizzle​

當寵物靜止懸浮在作物上方時，會有細雨落在作物上，且每隔 interval_seconds，作物可能成長一個階段。作物是 Minecraft 作物標籤中的方塊、地獄疙瘩和甜漿果叢。寵物只會透過空氣筆直向下看。成長會以 BlockGrowEvent 送出，因此保護和農耕外掛可以拒絕它。野生寵物和已被擁有的寵物皆適用。

設定預設值意義
chance0.1每個間隔作物成長的機率，0 到 1
interval_seconds5兩次嘗試之間的秒數。至少為 1；它每秒檢查一次，所以小數部分會等到下一個整秒
depth4向寵物下方尋找作物的方塊數，1 到 8

owner_effect​

當已被擁有的寵物在外，且位於其主人 range 個方塊之內時，主人會擁有一個藥水效果，例如夜視或水中呼吸。效果持續 15 秒並每秒更新，所以不會閃爍，並且會在寵物回家或主人離開其範圍後的 15 秒內消退。它會顯示圖示但不顯示粒子。如果主人已經擁有至少同樣強且持續時間至少同樣長的該效果（例如來自喝下的藥水），寵物就不會動它。

它適合穩定的效果：夜視、水中呼吸、速度、挖掘加速、抗火。依剩餘時間作用的效果，例如生命恢復、中毒和凋零，在每秒更新時會表現異常。

設定預設值意義
effectNIGHT_VISION藥水效果，以名稱指定
amplifier0效果等級；0 是第 I 級
range16與寵物相距的方塊數

舊的世界互動區段​

在行為模組出現之前寫成的寵物檔案，可能有 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 以外的任何值），或檔案已經列出其模組時，警告只會要求你移除它。

若要保留某項互動，請列出其模組並重新命名其設定：

舊區段模組重新命名的設定
campfirecampfirenightOnly 改為 night_only，soulVariants 改為 soul_variants，searchSeconds 改為 search_seconds
rainBloomrain_bloomscaleMultiplier 改為 scale_multiplier，scaleSeconds 改為 scale_seconds，driftFrequency 改為 drift_frequency，speedMultiplier 改為 speed_multiplier
glownight_glownightOnly 改為 night_only，lanternBone 改為 lantern_bone
stingstingdurationTicks 改為 duration_ticks，cooldownSeconds 改為 cooldown_seconds
dayPerchday_perchsearchRadius 改為 search_radius
drizzlecrop_drizzleintervalSeconds 改為 interval_seconds

其他設定的名稱不變。請刪除 enabled：把模組從清單中拿掉就是關閉它的方式。沒有 behaviors: 清單的檔案只會執行其 locomotion 的預設值，所以也要把那些列出來。以下是一個保留了營火和發光的飛行物種：

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

身分與外觀​

鍵預設值意義
isEnabledtruefalse 會略過該檔案
species檔名物種 ID，轉為小寫。玩家儲存的寵物和 /fmm petadmin 都使用它，所以一旦玩家擁有寵物，就請保持它穩定。當兩個檔案定義相同的 ID 時，會保留路徑排序在前的那個，且主控台會警告
model檔名寵物穿著的模型。模型未載入時主控台會警告，而寵物無法生成
name檔名顯示在寵物上方和訊息中的名稱。支援 & 顏色代碼
bodyALLAY承載模型的原版生物類型。移動時的碰撞以它的大小為準
scale1整體大小，至少 0.0625
health20本體的最大生命值，至少 1
iconGLOW_BERRIES選單圖示物品
iconItemModel空來自資源包、用於選單圖示的物品模型（namespace:path）
variants[]色彩變體，寫成 model、model:weight，或含有 model、weight 和 behaviors 的對映（請參閱變體行為）。野生生成依權重挑選一個，被馴服的寵物保留自己的變體，幼崽則取用親代的變體。空白表示只有 model。變體應共用相同的骨骼和動畫

馴服與繁殖​

鍵預設值意義
tamingFood[]能馴服野生成年寵物的物品名稱
breedingFood[]能讓已被擁有的成年寵物進入戀愛狀態的物品名稱
tameChance0.333一次餵食馴服成功的機率
babyModel空幼崽時穿著的模型，大小為 babyScale。空白表示使用變體模型
babyScale0.5幼崽相對於 scale 的大小
babyGrowthMinutes20幼崽長成成年寵物所需的分鐘數
breedingCooldownMinutes5親代再次繁殖之前的分鐘數
loveSeconds30被餵食的成年寵物等待伴侶的時間

移動​

follow 和 float 的值由內附的行為模組讀取，如表中所註。

鍵預設值意義
follow.distance5主人離得比這更遠時，follow_owner 才會跟隨。在此範圍之內，寵物處於安頓狀態並可自由漫遊
follow.leashDistance12超過此距離時 follow_owner 會加快
follow.teleportDistance24超過此距離時 follow_owner 會把寵物傳送到主人身旁
follow.roamRadius5drift、rain_bloom、wander 和 swim 會讓寵物離其錨點多遠
follow.speed1乘上除 migrate 之外所有內附行為的速度，至少 0.05
follow.staytrue按右鍵是否會叫寵物待命
float.hoverHeight1.5飛行寵物保持在地面上方的方塊數
float.hoverVariance0.75它偏離該高度的幅度
locomotionFLYING本體如何移動：FLYING、GROUNDED、AQUATIC、AMPHIBIOUS 或 STATIONARY。它也決定預設行為
centerOnBodyFLYING 和 AQUATIC 為 true請參閱傾斜與置中
orientation.styleUPRIGHTUPRIGHT、TOP_FIRST 或 FRONT_FIRST
orientation.startSpeed0.6低於此每秒方塊數時，模型保持直立
orientation.fullSpeed4.0達到此每秒方塊數時，模型會完全對準它的移動方向
orientation.maxTilt180傾斜的最大角度，單位為度。180 讓 top-first 模型可以倒轉過來
orientation.turnSpeed180傾斜每秒最多能改變的度數

野生生成​

這些鍵只適用於 CREATURES 模式。空清單表示允許所有項目。

鍵預設值意義
wildSpawn.enabledtrue該物種是否野生生活
wildSpawn.weight10相對於可能在同一位置生成的其他物種的權重。0 永遠不會生成。有舊版 chance 鍵（0 到 1）而沒有 weight 的檔案，使用 chance 乘以 10
wildSpawn.minGroup / maxGroup1 / minGroup群體大小
wildSpawn.placement取決於 locomotionGROUND、WATER、WATER_SURFACE 或 AIR。FLYING 預設為 AIR，AQUATIC 預設為 WATER，其餘預設為 GROUND。AIR 需要堅固、乾燥的頂部方塊，WATER_SURFACE 需要水的頂部方塊，兩者上方都要有兩個空閒方塊
wildSpawn.minLight / maxLight0 / 15該位置所需的光線等級
wildSpawn.cap4補充時，玩家周圍 8 個區塊之內此物種的野生寵物上限
wildSpawn.worlds[]世界名稱
wildSpawn.environments[]NORMAL、NETHER 或 THE_END
wildSpawn.biomes[]生物群系鍵，如 minecraft:plains
wildSpawn.timeANYANY、DAY 或 NIGHT，用於補充
wildSpawn.minY / maxY-64 / 320高度範圍

行為與遷徙​

鍵預設值意義
behaviors該 locomotion 的預設值該物種執行的行為模組及其設定。請參閱行為
migration無該物種在夜間遷徙中的外觀。請參閱遷徙區段

舊的區段 campfire、rainBloom、glow、sting、dayPerch 和 drizzle 會被忽略並顯示警告。請參閱舊的世界互動區段。

pets.yml 參考​

plugins/FreeMinecraftModels/pets.yml 會在第一次啟動時產生。/fmm reload 會套用變更。

鍵預設值意義
modeCOSMETICCOSMETIC 或 CREATURES。請參閱寵物模式
maxEquippedPets0玩家一次最多可以帶出幾隻寵物。0 表示沒有限制
petsInvulnerableToPlayerstrue已被擁有的寵物是否忽略來自其主人以外玩家的傷害
petsDiePermanentlyfalse死亡的寵物是否離開其主人的收藏
wildGenerationChance0.01新區塊獲得一組野生寵物的機率，0 到 0.9，每組之後重新擲一次
wildSpawnIntervalTicks400兩輪補充之間的 tick 數
wildSpawnChunkChance0.01一輪補充嘗試玩家附近某個區塊的機率
wildPetCapPerPlayer6玩家周圍 8 個區塊之內所有物種合計的野生寵物數量達到此值時，補充就會停止
migrations.enabledtrue夜間遷徙是否運作
migrations.chancePerNight0.15玩家在某一晚獲得遷徙群的機率，0 到 1
migrations.minFlockSize / maxFlockSize8 / 14遷徙群的大小
migrations.altitude28位於玩家或地面（取較高者）上方的方塊數
migrations.speed0.15每 tick 的方塊數（0.15 是每秒 3 個方塊）
migrations.durationSeconds90從遷徙群出現到被移除的秒數
migrations.viewDistance160玩家能看到遷徙群的方塊距離
migrations.maxActiveFlocks3整個伺服器同時在空中的遷徙群最大數量
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 petsfreeminecraftmodels.petstrue開啟你的寵物選單
/fmm petadmin mode [creatures|cosmetic]freeminecraftmodels.pets.adminop顯示寵物模式，或切換模式並儲存到 pets.yml
/fmm petadmin listfreeminecraftmodels.pets.adminop列出已載入的物種及其檔案、模型、本體、馴服食物與繁殖食物
/fmm petadmin spawn <species>freeminecraftmodels.pets.adminop在你注視的方塊（最遠 12 格）上方生成一隻野生寵物。僅限 CREATURES 模式
/fmm petadmin give <species>freeminecraftmodels.pets.adminop把該物種的一隻成年寵物加入你自己的收藏，並在你尚未達到 maxEquippedPets 時把牠帶出
/fmm petmigrate [species]freeminecraftmodels.pets.adminop立即讓一個遷徙群飛過你上方。請參閱夜間遷徙

這三個指令都僅限玩家使用。freeminecraftmodels.pets 管控寵物選單，所有玩家預設都擁有它。freeminecraftmodels.pets.admin 管控 /fmm petadmin 和 /fmm petmigrate，預設授予 OP，並隨 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 清單：寵物只會執行它所列出的模組，而清單會取代預設值。世界互動原本是區段的檔案，在列出它們的模組之前不會執行任何一個。

寵物的發光在 Bedrock 玩家那裡不會顯示。 發光只會照亮 Java 顯示骨骼。