Class MapleItemInformationProvider

java.lang.Object
server.MapleItemInformationProvider
public class MapleItemInformationProvider extends Object
全伺服器道具與裝備靜態資料的權威來源，採單例（instance）。

自 Character.wz／Etc.wz／Item.wz（透過 MapleDataProviderFactory 取得 MapleDataProvider）與啟動時匯入的 wz_itemdata SQL 快取讀取道具屬性， 並以一系列記憶體 Map 快取（dataCache／itemEffects／potentialCache／ socketCache／setItems／familiars／androids 等）提供查詢。

關鍵職責與協作者：

  • Field Details

    • chrData

      protected final MapleDataProvider chrData
      Character.wz 資料供應者，用於讀取裝備外觀與角色相關資料。

    • etcData

      protected final MapleDataProvider etcData
      Etc.wz 資料供應者，用於讀取套裝、潛能等雜項道具資料。

    • itemData

      protected final MapleDataProvider itemData
      Item.wz 資料供應者，用於讀取消耗品、安裝、其它類道具效果資料。

    • dataCache

      protected final Map<Integer, ItemInformation> dataCache
      道具基本資訊（ItemInformation）快取，以道具 ID 為鍵；由 SQL 的 wz_itemdata 載入。

    • petFlagInfo

      protected final Map<Integer,Short> petFlagInfo
      寵物旗標快取，以道具 ID 對應其寵物旗標（flag）。

    • afterImage

      protected final Map<String, List<Triple<String,Point,Point>>> afterImage
      殘像（after image）攻擊範圍快取，以殘像名稱對應一組 (動作, 左上, 右下) 範圍。

    • potentialCache

      protected final Map<Integer, List<StructItemOption>> potentialCache
      潛能選項快取，以潛能 ID 對應其各等級的 StructItemOption 清單。

    • socketCache

      protected final Map<Integer, Map<Integer, StructItemOption>> socketCache
      星岩（socket／nebulite）選項快取，外層以星岩等級為鍵、內層以星岩 ID 對應 StructItemOption。

    • itemEffects

      protected final Map<Integer, MapleStatEffect> itemEffects
      道具效果快取，以道具 ID 對應其 MapleStatEffect（消耗品／使用效果）。

    • itemEffectsEx

      protected final Map<Integer, MapleStatEffect> itemEffectsEx
      道具額外效果快取（EX 版本），以道具 ID 對應其 MapleStatEffect。

    • mobIds

      protected final Map<Integer,Integer> mobIds
      怪物圖鑑卡片快取，以怪物 ID 對應其卡片道具 ID（反查亦由此提供）。

    • potLife

      protected final Map<Integer, Pair<Integer,Integer>> potLife
      潛能生命（pot life）快取，以道具 ID 對應其 (生命 ID, 等級)。

    • familiars

      protected final Map<Integer, StructFamiliar> familiars
      怪物夥伴（familiar）快取，以夥伴 ID（familiarID）為鍵。

    • familiars_Item

      protected final Map<Integer, StructFamiliar> familiars_Item
      怪物夥伴快取，以卡片道具 ID（cardID）為鍵。

    • familiars_Mob

      protected final Map<Integer, StructFamiliar> familiars_Mob
      怪物夥伴快取，以怪物 ID（mobID）為鍵。

    • androids

      protected final Map<Integer, Pair<List<Integer>, List<Integer>>> androids
      機器人（android）零件快取，以道具 ID 對應其 (頭部清單, 身體清單)。

    • monsterBookSets

      protected final Map<Integer, Triple<Integer, List<Integer>, List<Integer>>> monsterBookSets
      怪物圖鑑套組快取，以套組 ID 對應 (獎勵, 怪物 ID 清單, ...)。

    • setItems

      protected final Map<Integer, StructSetItem> setItems
      套裝（set item）資訊快取，以套裝 ID 對應其 StructSetItem。

    • expCardTimes

      protected Map<Integer, Map<String,String>> expCardTimes
      經驗卡時段快取，以道具 ID 對應其可用時段設定（星期 → 時段字串）。

    • expPotionLev

      protected final Map<Integer,int[]> expPotionLev
      經驗藥水等級區間快取，以道具 ID 對應其可用等級陣列。

  • Constructor Details

    • MapleItemInformationProvider

      public MapleItemInformationProvider()

  • Method Details

    • runEtc

      public void runEtc()
      自 Etc.wz／Item.wz 載入套裝、潛能與星岩資料並填入對應快取。

      讀取 SetItemInfo.img 建立 setItems、ItemOption.img 建立 potentialCache（依潛能類型分流）與 socketCache（依星岩等級）。若三者任一已非空 則直接返回（具冪等性，重複呼叫不會重載）。屬啟動期載入動作。

    • runItems

      public void runItems()
      自 SQL 道具快取資料表載入全部道具與裝備資訊並填入 dataCache。

      依序查詢 wz_itemdata（基本資訊）、wz_itemequipdata（裝備數值）、 wz_itemadddata（附加效果）、wz_itemrewarddata（獎勵內容），再對所有裝備類道具 呼叫 finalizeEquipData 完成最終化。讀取失敗僅記錄錯誤不中斷；完成後記錄已讀取道具數 （日誌行 已讀取N 個道具.）。屬啟動期載入動作；不拋出例外。

    • getPotentialInfo

      public final List<StructItemOption> getPotentialInfo(int potId)
      取得指定潛能 ID 的各等級選項清單。
      Parameters:
      potId - 潛能 ID
      Returns:
      潛能選項清單；未知潛能回傳 null

    • getAllPotentialInfo

      public final Map<Integer, List<StructItemOption>> getAllPotentialInfo()
      取得全部潛能選項快取。
      Returns:
      以潛能 ID 為鍵的潛能選項對應表（內部快取，請勿修改）

    • getSocketInfo

      public final StructItemOption getSocketInfo(int potId)
      取得指定星岩（nebulite）ID 的選項資料。

      先以 GameConstants.getNebuliteGrade(int) 推得其等級再查表。

      Parameters:
      potId - 星岩 ID
      Returns:
      星岩選項；等級無法判定（-1）時回傳 null

    • getAllSocketInfo

      public final Map<Integer, StructItemOption> getAllSocketInfo(int grade)
      取得指定等級的全部星岩選項。
      Parameters:
      grade - 星岩等級
      Returns:
      該等級的星岩選項對應表（星岩 ID → 選項）；未知等級可能回傳 null

    • getMonsterBookList

      public final Collection<Integer> getMonsterBookList()
      取得所有怪物圖鑑卡片道具 ID 的集合。
      Returns:
      卡片道具 ID 集合（為 mobIds 的值視圖）

    • getMonsterBook

      public final Map<Integer,Integer> getMonsterBook()
      取得怪物 ID 對卡片道具 ID 的完整對應表。
      Returns:
      怪物圖鑑對應表（內部快取，請勿修改）

    • getPot

      public final Pair<Integer,Integer> getPot(int f)
      取得指定道具的潛能生命資料。
      Parameters:
      f - 道具 ID
      Returns:
      (生命 ID, 等級)；無對應資料時回傳 null

    • getFamiliar

      public final StructFamiliar getFamiliar(int f)
      依夥伴 ID 取得怪物夥伴資料。
      Parameters:
      f - 夥伴 ID（familiarID）
      Returns:
      對應的 StructFamiliar；不存在時回傳 null

    • getFamiliars

      public final Map<Integer, StructFamiliar> getFamiliars()
      取得以夥伴 ID 為鍵的全部怪物夥伴對應表。
      Returns:
      怪物夥伴對應表（內部快取，請勿修改）

    • getFamiliarByItem

      public final StructFamiliar getFamiliarByItem(int f)
      依卡片道具 ID 取得怪物夥伴資料。
      Parameters:
      f - 卡片道具 ID（cardID）
      Returns:
      對應的 StructFamiliar；不存在時回傳 null

    • getFamiliarByMob

      public final StructFamiliar getFamiliarByMob(int f)
      依怪物 ID 取得怪物夥伴資料。
      Parameters:
      f - 怪物 ID（mobID）
      Returns:
      對應的 StructFamiliar；不存在時回傳 null

    • getInstance

      public static final MapleItemInformationProvider getInstance()
      取得本類別的單例實例。
      Returns:
      全域唯一的 MapleItemInformationProvider 實例

    • getAllItems

      public final Collection<ItemInformation> getAllItems()
      取得已載入的全部道具資訊。
      Returns:
      dataCache 的值集合（內部快取的視圖，請勿修改）

    • getAndroidInfo

      public final Pair<List<Integer>, List<Integer>> getAndroidInfo(int i)
      取得指定機器人（android）道具的零件資訊。
      Parameters:
      i - 道具 ID
      Returns:
      (頭部清單, 身體清單)；無對應資料時回傳 null

    • getMonsterBookInfo

      public final Triple<Integer, List<Integer>, List<Integer>> getMonsterBookInfo(int i)
      取得指定怪物圖鑑套組的資訊。
      Parameters:
      i - 套組 ID
      Returns:
      套組資訊三元組；無對應資料時回傳 null

    • getAllMonsterBookInfo

      public final Map<Integer, Triple<Integer, List<Integer>, List<Integer>>> getAllMonsterBookInfo()
      取得全部怪物圖鑑套組的對應表。
      Returns:
      以套組 ID 為鍵的套組資訊對應表（內部快取，請勿修改）

    • getItemData

      protected final MapleData getItemData(int itemId)
      直接自 Item.wz 目錄樹搜尋並取得指定道具的原始 MapleData 節點。

      掃描各子目錄下以道具 ID 前四碼命名的 .img 檔（消耗品等聚合檔）或以完整 ID 命名的 .img 檔（個別檔）。裝備類道具沒有道具效果，故通常找不到對應節點。

      Parameters:
      itemId - 道具 ID
      Returns:
      道具的 WZ 資料節點；找不到時回傳 null

    • getItemIdByMob

      public Integer getItemIdByMob(int mobId)
      依怪物 ID 取得其對應的怪物圖鑑卡片道具 ID。
      Parameters:
      mobId - 怪物 ID
      Returns:
      卡片道具 ID；無對應卡片時回傳 null

    • getSetId

      public Integer getSetId(int itemId)
      取得指定道具所屬的卡片套組 ID。
      Parameters:
      itemId - 道具 ID
      Returns:
      卡片套組 ID；未知道具時回傳 null

    • getSlotMax

      public final short getSlotMax(int itemId)
      returns the maximum of items in one slot

    • getWholePrice

      public final int getWholePrice(int itemId)
      取得指定道具的整批（whole）價格。
      Parameters:
      itemId - 道具 ID
      Returns:
      整批價格；未知道具時回傳 0

    • getOption

      public final int getOption(int itemId, int line)
      取得指定道具指定行（1～3）的潛能選項值。
      Parameters:
      itemId - 道具 ID
      line - 潛能行號（1、2 或 3）
      Returns:
      該行的潛能選項值；未知道具或無效行號時回傳 0

    • getPrice

      public final double getPrice(int itemId)
      取得指定道具的單價。
      Parameters:
      itemId - 道具 ID
      Returns:
      道具單價；未知道具時回傳 -1.0

    • rand

      protected int rand(int min, int max)
      取得 [min, max] 區間內的非負隨機整數。

      以 Randomizer 產生，結果非確定性。

      Parameters:
      min - 區間下界
      max - 區間上界
      Returns:
      區間內隨機整數的絕對值

    • levelUpEquip

      public Equip levelUpEquip(Equip equip, Map<String,Integer> sta)
      依給定的能力值區間表，對裝備的副本逐項隨機加成後回傳。

      不修改傳入的 equip，而是先 複製再於副本上累加。每個 XxxMin／XxxMax 鍵對對應一項能力值，加成量由 rand(int, int) 於該區間隨機決定， 故結果非確定性。若資料表存在缺漏導致 NullPointerException，會記錄錯誤並回傳當前已加成的副本。

      Parameters:
      equip - 來源裝備（不會被修改）
      sta - 能力值區間表（STRMin/STRMax/PADMin/PADMax 等）
      Returns:
      加成後的新裝備副本

    • getEquipAdditions

      public final EnumMap<EquipAdditions, Pair<Integer,Integer>> getEquipAdditions(int itemId)
      取得指定裝備的附加效果（EquipAdditions）對應表。
      Parameters:
      itemId - 裝備道具 ID
      Returns:
      附加效果對應表；未知道具時回傳 null

    • getEquipIncrements

      public final Map<Integer, Map<String,Integer>> getEquipIncrements(int itemId)
      取得指定裝備的能力值增量（依等級）對應表。
      Parameters:
      itemId - 裝備道具 ID
      Returns:
      等級 → 能力值增量的對應表；未知道具時回傳 null

    • getEquipSkills

      public final List<Integer> getEquipSkills(int itemId)
      取得指定裝備附帶的技能 ID 清單。
      Parameters:
      itemId - 裝備道具 ID
      Returns:
      附帶技能 ID 清單；未知道具時回傳 null

    • getEquipStats

      public final Map<String,Integer> getEquipStats(int itemId)
      取得指定裝備的能力值對應表（reqLevel／reqSTR／tuc 等鍵）。
      Parameters:
      itemId - 裝備道具 ID
      Returns:
      能力值對應表；未知道具時回傳 null

    • canEquip

      public final boolean canEquip(Map<String,Integer> stats, int itemid, int level, int job, int fame, int str, int dex, int luk, int int_, int supremacy)
      判斷角色是否符合配戴指定裝備的需求。

      檢查等級（含 supremacy 加值）、四維（STR／DEX／LUK／INT）與名聲（reqPOP）需求； 各需求若不存在於 stats 則視為 0。

      Parameters:
      stats - 裝備需求對應表
      itemid - 裝備道具 ID
      level - 角色等級
      job - 角色職業
      fame - 角色名聲
      str - 角色力量
      dex - 角色敏捷
      luk - 角色幸運
      int_ - 角色智力
      supremacy - 等級加值（額外可滿足的等級需求）
      Returns:
      符合所有需求時為 true，否則為 false

    • getReqLevel

      public final int getReqLevel(int itemId)
      取得配戴指定裝備所需的等級。
      Parameters:
      itemId - 裝備道具 ID
      Returns:
      需求等級；未知道具或無 reqLevel 時回傳 0

    • getSlots

      public final int getSlots(int itemId)
      取得指定裝備的可升級孔數（tuc，total upgrade count）。
      Parameters:
      itemId - 裝備道具 ID
      Returns:
      升級孔數；未知道具或無 tuc 時回傳 0

    • getSetItemID

      public final Integer getSetItemID(int itemId)
      取得指定裝備所屬的套裝 ID（setItemID）。
      Parameters:
      itemId - 裝備道具 ID
      Returns:
      套裝 ID；未知道具或無 setItemID 時回傳 0

    • getSetItem

      public final StructSetItem getSetItem(int setItemId)
      取得指定套裝 ID 的套裝資訊。
      Parameters:
      setItemId - 套裝 ID
      Returns:
      套裝資訊 StructSetItem；不存在時回傳 null

    • getScrollReqs

      public final List<Integer> getScrollReqs(int itemId)
      取得使用指定卷軸（捲軸）的前置需求道具清單。
      Parameters:
      itemId - 卷軸道具 ID
      Returns:
      需求道具 ID 清單；未知道具時回傳 null

    • scrollEquipWithId

      public final Item scrollEquipWithId(Item equip, Item scrollId, boolean ws, MapleCharacter chr, int vegas)
      對裝備套用卷軸效果，依卷軸類型計算成功／詛咒並改寫該裝備的能力值與旗標。

      本方法以 Randomizer 進行隨機判定，故結果非確定性；會直接「就地」修改傳入的 equip（增益能力值、加減升級次數、設定 ItemFlag 等）， 並依持有者特性（MapleTrait.MapleTraitType.craft）與幸運卷軸旗標調整成功率。 涵蓋一般卷軸、混沌卷軸、強化（裝備）卷軸、潛能卷軸、白卷／特殊卷軸與多種特殊功能卷軸 （防滑、防寒、保護升級次數、幸運鑰匙、盾守護等）。

      失敗時若卷軸具詛咒可能銷毀裝備（回傳 null）；對非裝備物品（type != 1）則原樣回傳。 失敗且未受保護時可能扣減升級次數，並對持有者送出聊天訊息。

      Parameters:
      equip - 受卷裝備（會被就地修改）
      scrollId - 卷軸物品（決定效果與類型）
      ws - 是否為白卷效果（影響失敗時是否扣減升級次數）
      chr - 進行卷軸的角色（用於特性加成與訊息提示）
      vegas - 拉斯維加斯活動卷軸 id（5610000／5610001 提供額外成功率），無則傳 0
      Returns:
      套用後的裝備；若卷軸銷毀裝備則回傳 null

    • getEquipById

      public final Item getEquipById(int equipId)
      依裝備 id 建立一個全新的 Equip 實例（無戒指唯一 id）。

      委派至 getEquipById(int, int)，ringId 傳入 -1。

      Parameters:
      equipId - 裝備物品 id
      Returns:
      對應的裝備實例；未知 id 仍回傳一個能力值為 0 的空裝備（不為 null）

    • getEquipById

      public final Item getEquipById(int equipId, int ringId)
      依裝備 id 與戒指唯一 id 建立一個全新的 Equip 實例。

      自快取的範本 ItemInformation.eq 複製一份，並套用其固定潛能 （option1／option2／option3），最後設定唯一 id。 若該裝備不在快取中，仍回傳一個能力值為 0 的空裝備（不為 null）。

      Parameters:
      equipId - 裝備物品 id
      ringId - 戒指／物品唯一 id（無則傳 -1）
      Returns:
      對應的裝備實例（不為 null）

    • getRandStatFusion

      protected final short getRandStatFusion(short defaultValue, int value1, int value2)
      計算融合（fuse(Equip, Equip)）後某一能力值的隨機結果，落於基準值與兩來源平均值之間。

      以 Randomizer 隨機，故結果非確定性；defaultValue 為 0 時直接回傳 0。

      Parameters:
      defaultValue - 該能力值的基準值（範本裝備值）
      value1 - 來源裝備一的該能力值
      value2 - 來源裝備二的該能力值
      Returns:
      融合後的能力值

    • getRandStat

      protected final short getRandStat(short defaultValue, int maxRange)
      在基準值上下浮動產生隨機能力值，浮動幅度不超過基準值 10%（向上取整）且不超過 maxRange。

      以 Randomizer 隨機，故結果非確定性；defaultValue 為 0 時直接回傳 0。

      Parameters:
      defaultValue - 該能力值的基準值
      maxRange - 浮動幅度上限
      Returns:
      浮動後的能力值（可能高於或低於基準值）

    • getRandStatAbove

      protected final short getRandStatAbove(short defaultValue, int maxRange)
      僅向上浮動產生隨機能力值（結果不低於基準值），增量不超過基準值 10%（向上取整）且不超過 maxRange。

      以 Randomizer 隨機，故結果非確定性；defaultValue 小於等於 0 時直接回傳 0。

      Parameters:
      defaultValue - 該能力值的基準值
      maxRange - 增量上限
      Returns:
      浮動後的能力值（大於等於基準值）

    • randomizeStats

      public final Equip randomizeStats(Equip equip)
      將裝備的各項能力值就地隨機化（上下浮動），用於產生帶隨機屬性的掉落或獎勵裝備。

      對每項能力值套用 getRandStat(short, int)（主屬性／攻擊／命中等上限 5，防禦與 HP／MP 上限 10）。 結果非確定性（Randomizer），且直接修改傳入的 equip。

      Parameters:
      equip - 待隨機化的裝備（會被就地修改）
      Returns:
      同一個傳入的 equip 實例

    • randomizeStats_Above

      public final Equip randomizeStats_Above(Equip equip)
      將裝備的各項能力值就地向上隨機化（結果不低於原值），用於只增不減的隨機屬性產生。

      對每項能力值套用 getRandStatAbove(short, int)（主屬性／攻擊／命中等上限 5，防禦與 HP／MP 上限 10）。 結果非確定性（Randomizer），且直接修改傳入的 equip。

      Parameters:
      equip - 待隨機化的裝備（會被就地修改）
      Returns:
      同一個傳入的 equip 實例

    • fuse

      public final Equip fuse(Equip equip1, Equip equip2)
      融合兩件相同 id 的裝備，產生一件能力值介於兩者之間的全新裝備。

      以 getEquipById(int) 取範本後，逐項套用 getRandStatFusion(short, int, int)。 結果非確定性（Randomizer）。若兩裝備 id 不同則不融合，直接回傳 equip1。

      Parameters:
      equip1 - 來源裝備一（id 不同時原樣回傳）
      equip2 - 來源裝備二
      Returns:
      融合後的全新裝備；id 不符時為 equip1

    • getTotalStat

      public final int getTotalStat(Equip equip)
      計算裝備所有能力值的總和（STR/DEX/INT/LUK、攻擊、命中迴避、跳躍、製作、移速、HP/MP、防禦等）。
      Parameters:
      equip - 目標裝備
      Returns:
      各項能力值的算術總和

    • getItemEffect

      public final MapleStatEffect getItemEffect(int itemId)
      取得消耗品的道具效果 MapleStatEffect，結果快取於 itemEffects。

      首次查詢時自 WZ 的 spec 節點以 MapleStatEffect.loadItemEffectFromData(MapleData, int) 解析並快取。

      Parameters:
      itemId - 道具 id
      Returns:
      對應的道具效果；若該道具無 spec 資料則回傳 null

    • getItemEffectEX

      public final MapleStatEffect getItemEffectEX(int itemId)
      取得道具的延伸效果 MapleStatEffect（specEx 節點），結果快取於 itemEffectsEx。

      首次查詢時自 WZ 的 specEx 節點以 MapleStatEffect.loadItemEffectFromData(MapleData, int) 解析並快取。

      Parameters:
      itemId - 道具 id
      Returns:
      對應的延伸效果；若該道具無 specEx 資料則回傳 null

    • getCreateId

      public final int getCreateId(int id)
      取得道具的製作（合成）來源 id（create 欄位）。
      Parameters:
      id - 道具 id
      Returns:
      製作來源 id；未知道具回傳 0

    • getCardMobId

      public final int getCardMobId(int id)
      取得怪物卡片對應的怪物書 id（monsterBook 欄位）。
      Parameters:
      id - 卡片道具 id
      Returns:
      對應的怪物書 id；未知道具回傳 0

    • getBagType

      public final int getBagType(int id)
      取得道具袋（消耗品分頁）的類型，取 flag 旗標的低 4 位元。
      Parameters:
      id - 道具 id
      Returns:
      道具袋類型（flag & 0xF）；未知道具回傳 0

    • getWatkForProjectile

      public final int getWatkForProjectile(int itemId)
      取得投擲道具（飛鏢／子彈等）的物攻加成（裝備能力值 incPAD）。
      Parameters:
      itemId - 投擲道具 id
      Returns:
      物攻加成；無對應資料時回傳 0

    • canScroll

      public final boolean canScroll(int scrollid, int itemid)
      判斷卷軸是否可用於指定裝備，依兩者 id 中的裝備部位代碼比對。
      Parameters:
      scrollid - 卷軸物品 id
      itemid - 目標裝備 id
      Returns:
      兩者部位代碼相符時為 true

    • getName

      public final String getName(int itemId)
      取得道具名稱。
      Parameters:
      itemId - 道具 id
      Returns:
      道具名稱；未知道具回傳 null

    • getDesc

      public final String getDesc(int itemId)
      取得道具說明文字。
      Parameters:
      itemId - 道具 id
      Returns:
      道具說明；未知道具回傳 null

    • getMsg

      public final String getMsg(int itemId)
      取得道具使用時的提示訊息（msg 欄位）。
      Parameters:
      itemId - 道具 id
      Returns:
      道具訊息；未知道具回傳 null

    • getItemMakeLevel

      public final short getItemMakeLevel(int itemId)
      取得製作該道具所需的技能等級（itemMakeLevel 欄位）。
      Parameters:
      itemId - 道具 id
      Returns:
      製作所需等級；未知道具回傳 0

    • isDropRestricted

      public final boolean isDropRestricted(int itemId)
      判斷道具是否禁止掉落，綜合 flag 旗標、GameConstants.isDropRestricted(int) 與一串例外白名單 id。
      Parameters:
      itemId - 道具 id
      Returns:
      禁止掉落時為 true；未知道具回傳 false

    • isPickupRestricted

      public final boolean isPickupRestricted(int itemId)
      判斷道具是否禁止拾取，綜合 flag 旗標、GameConstants.isPickupRestricted(int) 與少數例外 id。
      Parameters:
      itemId - 道具 id
      Returns:
      禁止拾取時為 true；未知道具回傳 false

    • isAccountShared

      public final boolean isAccountShared(int itemId)
      判斷道具是否可在同帳號角色間共享（flag 的 0x100 位元）。
      Parameters:
      itemId - 道具 id
      Returns:
      可帳號共享時為 true；未知道具回傳 false

    • getStateChangeItem

      public final int getStateChangeItem(int itemId)
      取得使用後觸發狀態變化所連動的道具 id（stateChange 欄位）。
      Parameters:
      itemId - 道具 id
      Returns:
      連動道具 id；未知道具回傳 0

    • getMeso

      public final int getMeso(int itemId)
      取得道具使用後給予的楓幣數（meso 欄位，如錢袋類道具）。
      Parameters:
      itemId - 道具 id
      Returns:
      楓幣數；未知道具回傳 0

    • isShareTagEnabled

      public final boolean isShareTagEnabled(int itemId)
      判斷道具是否支援共享標籤（flag 的 0x800 位元）。
      Parameters:
      itemId - 道具 id
      Returns:
      支援共享標籤時為 true；未知道具回傳 false

    • isKarmaEnabled

      public final boolean isKarmaEnabled(int itemId)
      判斷道具是否可使用剪刀（白銀剪刀，karmaEnabled == 1）解除交易限制。
      Parameters:
      itemId - 道具 id
      Returns:
      可用剪刀時為 true；未知道具回傳 false

    • isPKarmaEnabled

      public final boolean isPKarmaEnabled(int itemId)
      判斷道具是否可使用白金剪刀（karmaEnabled == 2）解除交易限制。
      Parameters:
      itemId - 道具 id
      Returns:
      可用白金剪刀時為 true；未知道具回傳 false

    • isPickupBlocked

      public final boolean isPickupBlocked(int itemId)
      判斷道具是否被封鎖拾取（flag 的 0x40 位元）。
      Parameters:
      itemId - 道具 id
      Returns:
      封鎖拾取時為 true；未知道具回傳 false

    • isLogoutExpire

      public final boolean isLogoutExpire(int itemId)
      判斷道具是否於登出時失效／消失（flag 的 0x20 位元）。
      Parameters:
      itemId - 道具 id
      Returns:
      登出即失效時為 true；未知道具回傳 false

    • cantSell

      public final boolean cantSell(int itemId)
      判斷道具是否禁止販售給商店（flag 的 0x10 位元）。
      Parameters:
      itemId - 道具 id
      Returns:
      不可販售時為 true、可販售為 false；未知道具回傳 false

    • getRewardItem

      public final Pair<Integer, List<StructRewardItem>> getRewardItem(int itemid)
      取得隨機獎勵箱道具的開箱資訊：總機率與可能獎勵清單。
      Parameters:
      itemid - 獎勵箱道具 id
      Returns:
      Pair（總機率, 獎勵 StructRewardItem 清單）；未知道具回傳 null

    • isMobHP

      public final boolean isMobHP(int itemId)
      判斷道具是否依怪物 HP 連動（flag 的 0x1000 位元）。
      Parameters:
      itemId - 道具 id
      Returns:
      與怪物 HP 連動時為 true；未知道具回傳 false

    • isQuestItem

      public final boolean isQuestItem(int itemId)
      判斷道具是否為任務道具（flag 的 0x200 位元，且非 301 類）。
      Parameters:
      itemId - 道具 id
      Returns:
      為任務道具時為 true；未知道具回傳 false

    • questItemInfo

      public final Pair<Integer, List<Integer>> questItemInfo(int itemId)
      取得道具關聯的任務資訊：所屬任務 id 與相關道具清單。
      Parameters:
      itemId - 道具 id
      Returns:
      Pair（任務 id, 相關道具 id 清單）；未知道具回傳 null

    • replaceItemInfo

      public final Pair<Integer,String> replaceItemInfo(int itemId)
      取得道具到期或轉換後的替換資訊：替換道具 id 與替換訊息。
      Parameters:
      itemId - 道具 id
      Returns:
      Pair（替換道具 id, 替換訊息）；未知道具回傳 null

    • getAfterImage

      public final List<Triple<String,Point,Point>> getAfterImage(String after)
      依殘像（攻擊範圍）名稱取得其攻擊判定範圍清單。
      Parameters:
      after - 殘像名稱
      Returns:
      該殘像各動作的判定範圍 Triple（名稱, 左上點, 右下點）清單；不存在時回傳 null

    • getAfterImage

      public final String getAfterImage(int itemId)
      取得武器道具的殘像（攻擊範圍）名稱。
      Parameters:
      itemId - 武器道具 id
      Returns:
      殘像名稱；未知道具回傳 null

    • itemExists

      public final boolean itemExists(int itemId)
      判斷道具 id 是否確實存在（具有合法物品分頁且已載入快取）。

      先以 GameConstants.getInventoryType(int) 排除分頁為 MapleInventoryType.UNDEFINED 者， 再確認其存在於 SQL 載入的 dataCache。此方法是道具載入的閘門：載入時未通過者會被略過， 故 wz_itemdata 為空會導致所有道具都「不存在」（角色裸體）。

      Parameters:
      itemId - 道具 id
      Returns:
      道具存在時為 true

    • isCash

      public final boolean isCash(int itemId)
      判斷道具是否為商城（現金）道具，依物品分頁為 MapleInventoryType.CASH 或裝備能力值含 cash 標記。
      Parameters:
      itemId - 道具 id
      Returns:
      為商城道具時為 true

    • isOnlyTradeBlock

      public final boolean isOnlyTradeBlock(int itemId)
      判斷道具是否僅有交易封鎖（WZ info/tradeBlock 為 1）。
      Parameters:
      itemId - 道具 id
      Returns:
      設有交易封鎖時為 true

    • getItemInformation

      public final ItemInformation getItemInformation(int itemId)
      取得道具的快取資料物件 ItemInformation（多數查詢方法的共同入口）。

      直接讀取 SQL 載入的 dataCache；itemId 小於等於 0 或未載入時回傳 null。

      Parameters:
      itemId - 道具 id
      Returns:
      道具快取資料；不存在時回傳 null

    • initItemRewardData

      public void initItemRewardData(ResultSet sqlRewardData) throws SQLException
      由 wz_itemrewarddata 的一列填入對應道具的隨機獎勵清單（rewardItems）。

      啟動時由 loadItems(boolean) 逐列呼叫；對目標 ItemInformation 累加一筆 StructRewardItem。 若該道具不在 dataCache 中則記錄並略過。非執行緒安全，僅供載入階段使用。

      Parameters:
      sqlRewardData - 指向 wz_itemrewarddata 當前列的結果集
      Throws:
      SQLException - 讀取結果集欄位失敗時

    • initItemAddData

      public void initItemAddData(ResultSet sqlAddData) throws SQLException
      由 wz_itemadddata 的一列填入對應道具的附加屬性（equipAdditions）。

      啟動時由 loadItems(boolean) 逐列呼叫；以 EquipAdditions.fromString(String) 解析 key 後存入。 若該道具不在 dataCache 中則記錄並略過。非執行緒安全，僅供載入階段使用。

      Parameters:
      sqlAddData - 指向 wz_itemadddata 當前列的結果集
      Throws:
      SQLException - 讀取結果集欄位失敗時

    • initItemEquipData

      public void initItemEquipData(ResultSet sqlEquipData) throws SQLException
      由 wz_itemequipdata 的一列填入對應裝備的能力值（equipStats）或分等加成（equipIncs）。

      啟動時由 loadItems(boolean) 逐列呼叫；itemLevel == -1 者存入基本能力值，否則依等級存入加成表。 若該道具不在 dataCache 中則記錄並略過。非執行緒安全，僅供載入階段使用。

      Parameters:
      sqlEquipData - 指向 wz_itemequipdata 當前列的結果集
      Throws:
      SQLException - 讀取結果集欄位失敗時

    • finalizeEquipData

      public void finalizeEquipData(ItemInformation item)
      為單一裝備資料完成最終初始化：依 equipStats 建立其範本 Equip（eq）。

      啟動時由 loadItems(boolean) 對所有裝備類道具呼叫。透過 GameConstants 將原始能力值換算為實際值 （STR/DEX/INT/LUK、攻擊、HP/MP、防禦、升級次數、製作、耐久、魅力經驗、PVP 傷害等）； 若裝備無能力資料仍會建立空 equipStats。對現金裝備在魅力經驗未設時依部位給定預設值。 非執行緒安全，僅供載入階段使用。

      Parameters:
      item - 待完成初始化的道具資料（會被就地修改）

    • initItemInformation

      public void initItemInformation(ResultSet sqlItemData) throws SQLException
      由 wz_itemdata 的一列建立一個 ItemInformation 並放入 dataCache。

      啟動時由 loadItems(boolean) 逐列呼叫，是道具快取的主要填充來源。解析名稱／說明／價格／旗標／ 楓幣／怪物書／製作／替換／卷軸需求等欄位，並逗號展開 scrollReqs／consumeItem／incSkill； 怪物卡片（238 類）另建立怪物書與卡片組對應。非執行緒安全，僅供載入階段使用。

      Parameters:
      sqlItemData - 指向 wz_itemdata 當前列的結果集
      Throws:
      SQLException - 讀取結果集欄位失敗時

    • getPetFlagInfo

      public short getPetFlagInfo(int itemId)
      取得寵物的行為旗標位元組合（撿取、遠距、全撿、掃地、消耗 HP／MP、自動施放等），結果快取於 petFlagInfo。

      首次查詢時自 WZ 的 info 節點逐項解析並組成位元旗標後快取；非寵物道具（非 500 類）或無資料時回傳 0。

      Parameters:
      itemId - 寵物道具 id
      Returns:
      寵物行為旗標位元組合

    • getItemIncMHPr

      public int getItemIncMHPr(int itemId)
      取得裝備的最大 HP 百分比加成（裝備能力值 MHPr）。
      Parameters:
      itemId - 裝備道具 id
      Returns:
      最大 HP 百分比加成；無對應資料時回傳 0

    • getItemIncMMPr

      public int getItemIncMMPr(int itemId)
      取得裝備的最大 MP 百分比加成（裝備能力值 MMPr）。
      Parameters:
      itemId - 裝備道具 id
      Returns:
      最大 MP 百分比加成；無對應資料時回傳 0

    • getExpPotionLev

      public int[] getExpPotionLev(int itemId)
      取得經驗藥水的適用等級範圍 [最低等級, 最高等級]，結果快取於 expPotionLev。

      首次查詢時自 WZ 的 info/exp/minLev／maxLev 讀取（預設皆為 1）並快取。

      Parameters:
      itemId - 經驗藥水道具 id
      Returns:
      長度 2 的陣列：最低與最高適用等級

    • getExpCardRate

      public final double getExpCardRate(int itemId)
      取得經驗卡的經驗倍率（WZ info/rate 除以 100，預設 1.0）。
      Parameters:
      itemId - 經驗卡道具 id
      Returns:
      經驗倍率（如 2.0 表示雙倍）

    • getExpCardMaxLevel

      public final int getExpCardMaxLevel(int itemId)
      取得經驗卡的適用最高等級（WZ info/maxLevel，預設 249）。
      Parameters:
      itemId - 經驗卡道具 id
      Returns:
      適用最高等級

    • isExpOrDropCardTime

      public boolean isExpOrDropCardTime(int itemId)
      判斷經驗／掉落加成卡此刻是否處於其生效時段（依星期與時段設定）。

      依現在時間取得星期與小時，比對 WZ info/time 的各星期時段設定（首次解析後快取於 expCardTimes）。 結果隨呼叫時間而異。

      Parameters:
      itemId - 加成卡道具 id
      Returns:
      當前時間落於生效時段內時為 true

    • getScrollSuccess

      public int getScrollSuccess(int itemId)
      取得卷軸（204 類）的基礎成功率（裝備能力值 success）。
      Parameters:
      itemId - 卷軸道具 id
      Returns:
      成功率百分比；非卷軸或無對應資料時回傳 0

    • loadEtc

      public final void loadEtc(boolean reload)
      載入套裝資料（Etc.wz 的 SetItemInfo.img）至 setItems 快取。

      啟動時由 ItemLoader 呼叫。解析每組套裝的成員道具與各件數的套裝效果（防禦、四維、命中、攻擊、移速、HP/MP 等）。 若快取已有資料且 reload 為 false 則直接返回；reload 為 true 時先清空 setItems 與 potentialCache 再重新載入。

      Parameters:
      reload - 是否強制清空快取後重新載入

    • loadItems

      public void loadItems(boolean reload)
      自 SQL 載入全部道具資料至 dataCache，是道具快取的主要載入入口。

      啟動時由 ItemLoader 呼叫。依序查詢 wz_itemdata、wz_itemequipdata、 wz_itemadddata、wz_itemrewarddata，分別委派 initItemInformation(ResultSet)／ initItemEquipData(ResultSet)／initItemAddData(ResultSet)／initItemRewardData(ResultSet)，最後對所有裝備類道具 呼叫 finalizeEquipData(ItemInformation)。使用 DatabaseConnection 取得連線（不關閉共用連線）。 若快取已有資料且 reload 為 false 則直接返回；reload 為 true 時先清空 dataCache。 SQL 例外會被記錄並吞下。

      Parameters:
      reload - 是否強制清空快取後重新載入