client.CharacterPetManager

public final class CharacterPetManager extends Object

角色「寵物（pet）」子系統的協作者，由 P5 God class 拆分自 MapleCharacter。

本類別封裝對角色寵物清單 pets（所有已擁有寵物）與已召喚槽位快照 petStore （登入時待召喚的 CASH 欄位）的存取，涵蓋寵物的增刪查（getPets()/addPet(MaplePet)/ removePet(MaplePet)）、已召喚寵物的列舉與槽位計算（getSummonedPets()/getSummonedPet(int)/ getPetSlotNext()/getPetIndex(MaplePet)/getPetIndexById(int)）、召喚與卸下（spawnPet(byte)/spawnSavedPets()/unequipPet(MaplePet, boolean)/unequipAllPets()），以及寵物自動 HP／MP／解毒設定的封包推送（updatePetAuto()）。

MapleCharacter 以**逐字搬移**的方式把這些方法移入此處，並對每個對外公開方法保留 **簽名完全相同**的委派（delegate），因此所有 Java 呼叫端與 ~2,700 支腳本完全不受影響。協作者僅持有對所屬角色的回參考，透過同 package 存取其 pets／petStore／client／ map 等成員與 getInventory／getMap／getPosition／getIntNoRecord 等公開方法；pets／petStore 這兩個欄位本身仍宣告並初始化於 MapleCharacter （載入／存檔／跨頻道搬移會直接存取），僅放寬為 package-private 供本協作者存取。

Method Summary

Modifier and Type

Method

Description

void

addPet(MaplePet pet)

將寵物加入角色的寵物清單。

final byte

getPetIndex(int petId)

依寵物唯一 ID（uniqueId）查詢其召喚槽位索引。

final byte

getPetIndex(MaplePet petz)

取得指定寵物實例的召喚槽位索引。

final byte

getPetIndexById(int petId)

依寵物道具 ID（petItemId）查詢其召喚槽位索引。

final List<MaplePet>

getPets()

取得角色目前擁有的所有寵物清單。

final int

getPetSlotNext()

計算下一隻寵物應使用的召喚槽位索引，必要時騰出空間。

final byte[]

getPetStores()

取得角色登入時保存的待召喚寵物槽位快照。

final MaplePet

getSummonedPet(int index)

依召喚槽位索引取得對應的已召喚寵物。

final List<MaplePet>

getSummonedPets()

取得角色目前已召喚（出戰）的寵物，依召喚槽位順序排列。

void

removePet(MaplePet pet)

從角色的寵物清單移除指定寵物。

void

spawnPet(byte slot)

召喚指定 CASH 欄位槽位的寵物（便利多載）。

void

spawnPet(byte slot, boolean lead)

召喚指定 CASH 欄位槽位的寵物，可指定領隊旗標（便利多載）。

void

spawnPet(byte slot, boolean lead, boolean broadcast)

召喚指定 CASH 欄位槽位的寵物（完整實作）。

final void

spawnSavedPets()

召喚登入時保存的待召喚寵物。

final void

unequipAllPets()

卸下角色目前所有已召喚的寵物。

void

unequipPet(MaplePet pet, boolean hunger)

卸下單一已召喚的寵物。

void

updatePetAuto()

向角色推送寵物自動補 HP／MP／解毒（自動藥水）的設定封包。

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- getPets
  
  public final List<MaplePet> getPets()
  
  取得角色目前擁有的所有寵物清單。
  直接回傳所屬角色底層的 pets 清單（非防禦性複本），對回傳值的增刪會直接影響角色狀態。
  
  Returns:
  
  角色擁有的寵物清單（可能為空，但不為 null）
- addPet
  
  public void addPet(MaplePet pet)
  
  將寵物加入角色的寵物清單。
  若該寵物已存在於清單中，會先移除舊項再重新加入，藉此確保同一寵物只出現一次並移至清單尾端。直接修改所屬角色的 pets 清單。
  
  Parameters:
  
  pet - 欲加入的寵物
- removePet
  
  public void removePet(MaplePet pet)
  
  從角色的寵物清單移除指定寵物。
  移除前會先將該寵物的召喚狀態重設為未召喚（setSummoned(0)），再從所屬角色的 pets 清單移除。
  
  Parameters:
  
  pet - 欲移除的寵物
- getSummonedPets
  
  public final List<MaplePet> getSummonedPets()
  
  取得角色目前已召喚（出戰）的寵物，依召喚槽位順序排列。
  掃描角色全部寵物，將已召喚者依其槽位值（getSummonedValue() - 1，0–2）放入對應位置，再剔除未填滿的空槽，因此回傳清單的長度等於實際已召喚的寵物數（最多 3 隻）。
  
  Returns:
  
  已召喚寵物清單（依槽位排序；無已召喚寵物時為空清單，不為 null）
- getSummonedPet
  
  public final MaplePet getSummonedPet(int index)
  
  依召喚槽位索引取得對應的已召喚寵物。
  
  Parameters:
  
  index - 召喚槽位索引（0–2，對應 getSummonedValue() - 1）
  
  Returns:
  
  該槽位的已召喚寵物；若該槽位沒有已召喚寵物則回傳 null
- getPetSlotNext
  public final int getPetSlotNext()
  
  計算下一隻寵物應使用的召喚槽位索引，必要時騰出空間。
  具有副作用：
  
  若三個召喚槽位皆已佔滿，會卸下索引 0 的寵物（unequipPet(MaplePet, boolean) with hunger=false）並回傳 0。
  
  否則找出第一個未被佔用的槽位（最大為 2）；若該槽位仍被某寵物佔用，則先卸下該寵物再回傳此索引。
  
  卸下動作會觸發封包推送（見 unequipPet(MaplePet, boolean)）。
  
  Returns:
  
  可供新寵物使用的召喚槽位索引（0–2）
- getPetIndex
  
  public final byte getPetIndex(MaplePet petz)
  
  取得指定寵物實例的召喚槽位索引。
  本多載直接由傳入寵物的召喚值換算（getSummonedValue() - 1），不檢查該寵物是否屬於本角色；另有以寵物唯一 ID 查詢的多載 getPetIndex(int)。
  
  Parameters:
  
  petz - 欲查詢的寵物實例
  
  Returns:
  
  召喚槽位索引（0–2）；若寵物未召喚則為 -1
- getPetIndex
  
  public final byte getPetIndex(int petId)
  
  依寵物唯一 ID（uniqueId）查詢其召喚槽位索引。
  僅在已召喚寵物中比對 getUniqueId()；另有以寵物實例查詢的多載 getPetIndex(MaplePet)，以及以道具 ID 查詢的 getPetIndexById(int)。
  
  Parameters:
  
  petId - 寵物唯一 ID
  
  Returns:
  
  召喚槽位索引（0–2）；若找不到相符的已召喚寵物則為 -1
- getPetIndexById
  
  public final byte getPetIndexById(int petId)
  
  依寵物道具 ID（petItemId）查詢其召喚槽位索引。
  僅在已召喚寵物中比對 getPetItemId()；與以唯一 ID 查詢的 getPetIndex(int) 不同，此處比對的是道具 ID（同一道具 ID 可能對應多隻寵物，回傳第一隻相符者）。
  
  Parameters:
  
  petId - 寵物道具 ID
  
  Returns:
  
  召喚槽位索引（0–2）；若找不到相符的已召喚寵物則為 -1
- unequipAllPets
  
  public final void unequipAllPets()
  
  卸下角色目前所有已召喚的寵物。
  逐一對每隻已召喚寵物呼叫 unequipPet(MaplePet, boolean)（hunger=false），因此會連帶觸發各寵物的存檔與封包推送等副作用（見 unequipPet(MaplePet, boolean)）。
- unequipPet
  public void unequipPet(MaplePet pet, boolean hunger)
  
  卸下單一已召喚的寵物。
  僅當該寵物目前為已召喚狀態時才動作，具有多項副作用：
  
  將寵物存檔至資料庫（saveToDb()）。
  
  重設寵物召喚狀態為未召喚（setSummoned(0)）。
  
  向角色本身推送 PetPacket.updatePet 封包。
  
  若角色所在地圖不為 null，向全地圖廣播 PetPacket.removePet。
  
  最後送出 CWvsContext.enableActions() 解除動作鎖定。
  
  Parameters:
  
  pet - 欲卸下的寵物
  
  hunger - 飢餓旗標；目前僅保留參數（對應已註解掉的 showPet 廣播），實際未影響卸下流程
- spawnPet
  
  public void spawnPet(byte slot)
  
  召喚指定 CASH 欄位槽位的寵物（便利多載）。
  等同呼叫 spawnPet(byte, boolean, boolean)，且 lead=false、broadcast=true。
  
  Parameters:
  
  slot - CASH 物品欄中的寵物槽位
- spawnPet
  
  public void spawnPet(byte slot, boolean lead)
  
  召喚指定 CASH 欄位槽位的寵物，可指定領隊旗標（便利多載）。
  等同呼叫 spawnPet(byte, boolean, boolean)，且 broadcast=true。
  
  Parameters:
  
  slot - CASH 物品欄中的寵物槽位
  
  lead - 領隊旗標，透傳給完整多載
- spawnPet
  public void spawnPet(byte slot, boolean lead, boolean broadcast)
  
  召喚指定 CASH 欄位槽位的寵物（完整實作）。
  先取出該槽位的 CASH 道具並驗證為合法寵物道具（道具 ID 介於 5000000–5009999），否則直接返回。其後依道具 ID 分流，具有多項副作用：
  
  進化型寵物（道具 ID 5000047／5000028）：建立進化後寵物、以 MapleInventoryManipulator.addById(MapleClient, int, short, String) 加入進化後道具並移除原道具（不直接召喚）。
  
  一般寵物：在寵物存在且未過期（含道具 5000054 須剩餘秒數 > 0、以及到期時間檢查）時，若已召喚則改為卸下（unequipPet(MaplePet, boolean)）；否則設定座標／落點／姿勢、指派召喚槽位（getPetSlotNext()）並加入寵物清單（addPet(MaplePet)）。當 broadcast 為真且地圖存在時，向角色推送 PetPacket.updatePet、向全地圖廣播 PetPacket.showPet、推送 PetPacket.showPetUpdate，並呼叫 updatePetAuto()。
  
  不論分流結果如何，最後都會送出 CWvsContext.enableActions() 解除動作鎖定。
  
  Parameters:
  
  slot - CASH 物品欄中的寵物槽位
  
  lead - 領隊旗標；目前保留但未於本方法內使用
  
  broadcast - 是否推送／廣播召喚相關封包並套用寵物自動設定；spawnSavedPets 以 false 靜默召喚
- spawnSavedPets
  
  public final void spawnSavedPets()
  
  召喚登入時保存的待召喚寵物。
  逐一掃描 petStore 槽位快照，對每個有效槽位（值 > -1）以 broadcast=false 靜默召喚（spawnPet(byte, boolean, boolean)）。召喚完成後將 petStore 重設為 {-1, -1, -1}，因此本方法只生效一次。直接讀寫所屬角色的 petStore 欄位。
- getPetStores
  
  public final byte[] getPetStores()
  
  取得角色登入時保存的待召喚寵物槽位快照。
  直接回傳所屬角色底層的 petStore 陣列（非複本），長度為 3，每個元素為對應槽位的 CASH 寵物位置，值 -1 表示該槽位無寵物。
  
  Returns:
  
  petStore 槽位陣列（長度 3）
- updatePetAuto
  
  public void updatePetAuto()
  
  向角色推送寵物自動補 HP／MP／解毒（自動藥水）的設定封包。
  分別檢查角色的自動 HP／MP／解毒設定（GameConstants.HP_ITEM／MP_ITEM／ POT_ITEM），凡設定值大於 0 即送出對應的 CField.petAutoHP／petAutoMP／ petAutoCure 封包。
  注意：HP／MP 兩項以 getIntNoRecord 作為判斷條件、卻以 getIntRecord 取值送出，解毒項則前後皆用 getIntNoRecord；此既有的取值不對稱行為依搬移前原樣保留。

Class CharacterPetManager

Method Summary

Methods inherited from class Object

Method Details

getPets

addPet

removePet

getSummonedPets

getSummonedPet

getPetSlotNext

getPetIndex

getPetIndex

getPetIndexById

unequipAllPets

unequipPet

spawnPet

spawnPet

spawnPet

spawnSavedPets

getPetStores

updatePetAuto