client.CharacterSocialManager

public final class CharacterSocialManager extends Object

角色「社交（social）」子系統的協作者，由 P5 God class 拆分自 MapleCharacter。

本類別封裝對角色社交關係狀態的存取，涵蓋五個彼此相關的面向：

組隊（party）——getParty()/setParty(MapleParty)，以及隊員血量同步廣播 updatePartyMemberHP()/receivePartyMemberHP()（party 欄位）；
家族／公會（guild）——識別碼、職級、貢獻度與聯盟職級的讀寫 getGuildId()/setGuildId(int)/getGuildRank()/setGuildRank(byte)/ getGuildContribution()/setGuildContribution(int)/getMGC()/ getAllianceRank()/setAllianceRank(byte)/getGuild()，以及線上／離線狀態同步 guildUpdate()/saveGuildStatus()（guildid/guildrank/ guildContribution/allianceRank/mgc 欄位）；
家庭（family）——成員資訊與聲望 getFamilyId()/getSeniorId()/getJunior1()/getJunior2()/ getCurrentRep()/setCurrentRep(int)/getTotalRep()/setTotalRep(int)/ getNoJuniors()/getMFC()/makeMFC(int, int, int, int)/setFamily(int, int, int, int)，以及狀態同步與聲望結算 familyUpdate()/saveFamilyStatus()/familyRep(int, int, boolean)（mfc/currentrep/ totalrep 欄位）；
好友（buddy）——好友列表與容量 getBuddylist()/getBuddyCapacity()/setBuddyCapacity(byte)（buddylist 欄位）；
密語頻道（messenger）——getMessenger()/setMessenger(MapleMessenger)（messenger 欄位）。

MapleCharacter 以**逐字搬移**的方式把這些方法移入此處，並對每個方法保留**簽名完全相同**的委派（delegate），因此所有 Java 呼叫端與透過 cm／pi 等腳本 API 轉呼的腳本完全不受影響。協作者僅持有對所屬角色的回參考，透過同 package 存取其社交狀態欄位（party／buddylist／ messenger／mgc／mfc／guildid／guildrank／guildContribution／ allianceRank／currentrep／totalrep）以及供 guildUpdate／familyRep 讀取的核心欄位（level／job／name）。這些欄位本身仍宣告並初始化於 MapleCharacter（載入／存檔／跨頻道搬移會直接存取），僅放寬為 package-private 供本協作者存取。協作者內部方法之間以**裸名稱**互相呼叫（如 getGuild 內呼叫 getGuildId、setFamily 內呼叫 makeMFC），與搬移前在 MapleCharacter 內的裸呼叫逐位元組一致。

Method Summary

Modifier and Type

Method

Description

void

familyRep(int prevexp, int needed, boolean leveled)

依本次取得的經驗值，換算並向家庭上線（senior）發放家庭聲望。

void

familyUpdate()

將角色目前的家庭成員狀態同步至所屬家庭。

byte

getAllianceRank()

取得角色在公會聯盟中的職級。

byte

getBuddyCapacity()

取得角色好友列表的容量上限。

BuddyList

getBuddylist()

取得角色的好友列表。

int

getCurrentRep()

取得角色目前的家庭聲望值。

int

getFamilyId()

取得角色所屬家庭的識別碼。

MapleGuild

getGuild()

取得角色所屬的公會實體。

int

getGuildContribution()

取得角色對所屬公會的貢獻度。

int

getGuildId()

取得角色所屬公會的識別碼。

byte

getGuildRank()

取得角色在所屬公會中的職級。

int

getJunior1()

取得角色在家庭中的第一位「徒弟／下線」成員識別碼。

int

getJunior2()

取得角色在家庭中的第二位「徒弟／下線」成員識別碼。

MapleMessenger

getMessenger()

取得角色目前所在的密語頻道。

MapleFamilyCharacter

getMFC()

取得角色的家庭成員物件。

MapleGuildCharacter

getMGC()

取得角色的公會成員物件。

int

getNoJuniors()

取得角色在家庭中目前的下線（junior）人數。

MapleParty

getParty()

取得角色目前所屬的隊伍。

int

getSeniorId()

取得角色在家庭中的「師父／上線」成員識別碼。

int

getTotalRep()

取得角色累計的家庭總聲望值。

void

guildUpdate()

將角色目前的等級與職業同步至所屬公會（線上狀態更新）。

void

makeMFC(int familyid, int seniorid, int junior1, int junior2)

依指定的家庭關係建立或更新角色的家庭成員物件（mfc）。

void

receivePartyMemberHP()

向本角色同步同地圖、同頻道每位隊友的目前血量。

void

saveFamilyStatus()

將角色的家庭成員關係持久化至資料庫。

void

saveGuildStatus()

將角色的公會狀態持久化為離線狀態。

void

setAllianceRank(byte rank)

設定角色在公會聯盟中的職級。

void

setBuddyCapacity(byte capacity)

設定角色好友列表的容量上限，並通知用戶端。

void

setCurrentRep(int _rank)

設定角色目前的家庭聲望值。

void

setFamily(int newf, int news, int newj1, int newj2)

在家庭關係有實際變動時，才重建角色的家庭成員物件。

void

setGuildContribution(int _c)

設定角色對所屬公會的貢獻度。

void

setGuildId(int _id)

設定角色所屬公會的識別碼，並同步維護其公會成員物件。

void

setGuildRank(byte _rank)

設定角色在所屬公會中的職級。

void

setMessenger(MapleMessenger messenger)

設定角色目前所在的密語頻道。

void

setParty(MapleParty party)

設定角色目前所屬的隊伍。

void

setTotalRep(int _rank)

設定角色累計的家庭總聲望值。

void

updatePartyMemberHP()

把本角色目前的血量同步廣播給同地圖、同頻道的隊友。

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

Method Details
- getParty
  
  public MapleParty getParty()
  
  取得角色目前所屬的隊伍。
  具有惰性清理的副作用：若已快取的隊伍處於已解散（MapleParty.isDisbanded()）狀態，會將 party 欄位重設為 null 後再回傳。
  
  Returns:
  
  角色目前所屬的隊伍；若未組隊或隊伍已解散則為 null
- setParty
  
  public void setParty(MapleParty party)
  
  設定角色目前所屬的隊伍。
  
  Parameters:
  
  party - 要綁定的隊伍；可為 null 以表示離開隊伍
- updatePartyMemberHP
  
  public void updatePartyMemberHP()
  
  把本角色目前的血量同步廣播給同地圖、同頻道的隊友。
  具有封包傳送副作用：對每位處於相同地圖與頻道的隊員傳送 CField.updatePartyMemberHP(int, int, int) 封包，內容為本角色的目前血量與目前最大血量。若角色未組隊或所在頻道伺服器不存在則不進行任何動作。
- receivePartyMemberHP
  
  public void receivePartyMemberHP()
  
  向本角色同步同地圖、同頻道每位隊友的目前血量。
  updatePartyMemberHP() 的反向操作：具有封包傳送副作用，對每位處於相同地圖與頻道的隊員，向「本角色」的連線傳送該隊員血量的 CField.updatePartyMemberHP(int, int, int) 封包。若角色未組隊則不進行任何動作。
- getGuildId
  
  public int getGuildId()
  
  取得角色所屬公會的識別碼。
  
  Returns:
  
  公會識別碼；未加入任何公會時為 0（或非正值）
- setGuildId
  public void setGuildId(int _id)
  
  設定角色所屬公會的識別碼，並同步維護其公會成員物件。
  具有狀態變更副作用：
  
  當識別碼為正值時，若尚無公會成員物件（mgc）則新建一個 MapleGuildCharacter，否則更新既有物件的公會識別碼；
  
  當識別碼非正值時，清除公會成員物件並將公會貢獻度（guildContribution）歸零。
  
  Parameters:
  
  _id - 目標公會識別碼；非正值表示離開公會
- getGuildRank
  
  public byte getGuildRank()
  
  取得角色在所屬公會中的職級。
  
  Returns:
  
  公會職級
- setGuildRank
  
  public void setGuildRank(byte _rank)
  
  設定角色在所屬公會中的職級。
  若已有公會成員物件（mgc），會一併更新該物件的職級。
  
  Parameters:
  
  _rank - 目標公會職級
- getGuildContribution
  
  public int getGuildContribution()
  
  取得角色對所屬公會的貢獻度。
  
  Returns:
  
  公會貢獻度
- setGuildContribution
  
  public void setGuildContribution(int _c)
  
  設定角色對所屬公會的貢獻度。
  若已有公會成員物件（mgc），會一併更新該物件的貢獻度。
  
  Parameters:
  
  _c - 目標公會貢獻度
- getMGC
  
  public MapleGuildCharacter getMGC()
  
  取得角色的公會成員物件。
  
  Returns:
  
  公會成員物件 MapleGuildCharacter；未加入公會時為 null
- getAllianceRank
  
  public byte getAllianceRank()
  
  取得角色在公會聯盟中的職級。
  
  Returns:
  
  聯盟職級
- setAllianceRank
  
  public void setAllianceRank(byte rank)
  
  設定角色在公會聯盟中的職級。
  若已有公會成員物件（mgc），會一併更新該物件的聯盟職級。
  
  Parameters:
  
  rank - 目標聯盟職級
- getGuild
  
  public MapleGuild getGuild()
  
  取得角色所屬的公會實體。
  透過 World.Guild.getGuild(int) 以公會識別碼向全域公會儲存層查詢。
  
  Returns:
  
  角色所屬的公會 MapleGuild；未加入公會（識別碼非正值）時為 null
- guildUpdate
  
  public void guildUpdate()
  
  將角色目前的等級與職業同步至所屬公會（線上狀態更新）。
  具有跨伺服器廣播副作用：先把角色目前的等級與職業寫入公會成員物件（mgc），再呼叫 World.Guild.memberLevelJobUpdate(MapleGuildCharacter) 將變更廣播給公會。若角色未加入公會（識別碼非正值）則不進行任何動作。
- saveGuildStatus
  
  public void saveGuildStatus()
  
  將角色的公會狀態持久化為離線狀態。
  具有持久化副作用：透過 MapleGuild.setOfflineGuildStatus(int, byte, int, byte, int) 把公會識別碼、公會職級、公會貢獻度與聯盟職級寫回，供角色離線後仍能維持公會資訊。
- getFamilyId
  
  public int getFamilyId()
  
  取得角色所屬家庭的識別碼。
  
  Returns:
  
  家庭識別碼；無家庭成員資訊（mfc 為 null）時為 0
- getSeniorId
  
  public int getSeniorId()
  
  取得角色在家庭中的「師父／上線」成員識別碼。
  
  Returns:
  
  上線（senior）成員識別碼；無家庭成員資訊（mfc 為 null）時為 0
- getJunior1
  
  public int getJunior1()
  
  取得角色在家庭中的第一位「徒弟／下線」成員識別碼。
  
  Returns:
  
  第一位下線（junior）成員識別碼；無家庭成員資訊（mfc 為 null）時為 0
- getJunior2
  
  public int getJunior2()
  
  取得角色在家庭中的第二位「徒弟／下線」成員識別碼。
  
  Returns:
  
  第二位下線（junior）成員識別碼；無家庭成員資訊（mfc 為 null）時為 0
- getCurrentRep
  
  public int getCurrentRep()
  
  取得角色目前的家庭聲望值。
  
  Returns:
  
  目前家庭聲望值
- setCurrentRep
  
  public void setCurrentRep(int _rank)
  
  設定角色目前的家庭聲望值。
  若已有家庭成員物件（mfc），會一併更新該物件的目前聲望值。
  
  Parameters:
  
  _rank - 目標家庭聲望值
- getTotalRep
  
  public int getTotalRep()
  
  取得角色累計的家庭總聲望值。
  
  Returns:
  
  累計家庭總聲望值
- setTotalRep
  
  public void setTotalRep(int _rank)
  
  設定角色累計的家庭總聲望值。
  若已有家庭成員物件（mfc），會一併更新該物件的總聲望值。
  
  Parameters:
  
  _rank - 目標家庭總聲望值
- familyUpdate
  
  public void familyUpdate()
  
  將角色目前的家庭成員狀態同步至所屬家庭。
  具有跨伺服器廣播副作用：透過 World.Family.memberFamilyUpdate(MapleFamilyCharacter, MapleCharacter) 把家庭成員物件（mfc）與角色本體的最新狀態廣播給家庭。若角色無家庭成員資訊（mfc 為 null）則不進行任何動作。
- saveFamilyStatus
  
  public void saveFamilyStatus()
  
  將角色的家庭成員關係持久化至資料庫。
  具有資料庫寫入副作用：對 characters 資料表執行 UPDATE，寫入家庭識別碼、上線（senior）與兩位下線（junior1／junior2）的成員識別碼。若角色無家庭成員資訊（mfc 為 null），上述四欄一律寫為 0。
  使用共用的 DatabaseConnection ThreadLocal 連線，僅以 try-with-resources 關閉 PreparedStatement（絕不關閉共用連線）。任何 SQLException 都會被攔截並記錄，不對外拋出。
- familyRep
  
  public void familyRep(int prevexp, int needed, boolean leveled)
  
  依本次取得的經驗值，換算並向家庭上線（senior）發放家庭聲望。
  具有跨伺服器副作用：透過 World.Family.setRep(int, int, int, int, String) 把聲望加到上線（一倍 ×10）以及上線的上線（半額 ×5，僅當第一階回傳值為正時繼續往上），藉此在家庭樹上向上傳遞聲望。
  計算邏輯（逐位元組保留搬移前行為）：以「目標經驗值的百分之一」為刻度，取本次經驗成長跨越的百分比段數（目前經驗/onepercent - prevexp/onepercent）作為基礎聲望；若本次有升級（leveled 為真），則改以 100 - 基礎段數 + 等級/2 計算。當每百分之一刻度為 0（needed 過小導致整數除法為零）或最終聲望非正時，不發放任何聲望。角色無家庭成員資訊（mfc 為 null）時亦不進行任何動作。
  
  Parameters:
  
  prevexp - 本次獲得經驗前的累積經驗值
  
  needed - 當前等級升級所需的經驗值（作為百分比刻度的基準）
  
  leveled - 本次經驗變動是否造成升級
- getNoJuniors
  
  public int getNoJuniors()
  
  取得角色在家庭中目前的下線（junior）人數。
  
  Returns:
  
  下線人數；無家庭成員資訊（mfc 為 null）時為 0
- getMFC
  
  public MapleFamilyCharacter getMFC()
  
  取得角色的家庭成員物件。
  
  Returns:
  
  家庭成員物件 MapleFamilyCharacter；無家庭時為 null
- makeMFC
  public void makeMFC(int familyid, int seniorid, int junior1, int junior2)
  
  依指定的家庭關係建立或更新角色的家庭成員物件（mfc）。
  具有狀態變更副作用：
  
  當 familyid 為正值時，向 World.Family.getFamily(int) 取得家庭實體：找不到家庭則把 mfc 設為 null；否則取得（或以 MapleFamily.addFamilyMemberInfo(MapleCharacter, int, int, int) 新增）本角色的成員物件，並在上線／下線識別碼與傳入值不符時逐一更新；
  
  當 familyid 非正值時，把 mfc 設為 null（脫離家庭）。
  
  Parameters:
  
  familyid - 目標家庭識別碼；非正值表示脫離家庭
  
  seniorid - 上線（senior）成員識別碼
  
  junior1 - 第一位下線（junior）成員識別碼
  
  junior2 - 第二位下線（junior）成員識別碼
- setFamily
  
  public void setFamily(int newf, int news, int newj1, int newj2)
  
  在家庭關係有實際變動時，才重建角色的家庭成員物件。
  僅當目前無家庭成員資訊（mfc 為 null），或傳入的家庭／上線／兩位下線識別碼與現況任一不符時，才委派 makeMFC(int, int, int, int) 重建；否則不進行任何動作（避免無謂重建）。
  
  Parameters:
  
  newf - 目標家庭識別碼
  
  news - 目標上線（senior）成員識別碼
  
  newj1 - 目標第一位下線（junior）成員識別碼
  
  newj2 - 目標第二位下線（junior）成員識別碼
- getBuddylist
  
  public BuddyList getBuddylist()
  
  取得角色的好友列表。
  
  Returns:
  
  好友列表 BuddyList
- getBuddyCapacity
  
  public byte getBuddyCapacity()
  
  取得角色好友列表的容量上限。
  
  Returns:
  
  好友列表容量
- setBuddyCapacity
  
  public void setBuddyCapacity(byte capacity)
  
  設定角色好友列表的容量上限，並通知用戶端。
  具有封包傳送副作用：更新好友列表容量後，向角色連線傳送 BuddylistPacket.updateBuddyCapacity(int) 封包以同步用戶端顯示。
  
  Parameters:
  
  capacity - 目標好友列表容量
- getMessenger
  
  public MapleMessenger getMessenger()
  
  取得角色目前所在的密語頻道。
  
  Returns:
  
  密語頻道 MapleMessenger；未加入任何密語頻道時為 null
- setMessenger
  
  public void setMessenger(MapleMessenger messenger)
  
  設定角色目前所在的密語頻道。
  
  Parameters:
  
  messenger - 要綁定的密語頻道；可為 null 以表示離開密語頻道

Class CharacterSocialManager

Method Summary

Methods inherited from class Object

Method Details

getParty

setParty

updatePartyMemberHP

receivePartyMemberHP

getGuildId

setGuildId

getGuildRank

setGuildRank

getGuildContribution

setGuildContribution

getMGC

getAllianceRank

setAllianceRank

getGuild

guildUpdate

saveGuildStatus

getFamilyId

getSeniorId

getJunior1

getJunior2

getCurrentRep

setCurrentRep

getTotalRep

setTotalRep

familyUpdate

saveFamilyStatus

familyRep

getNoJuniors

getMFC

makeMFC

setFamily

getBuddylist

getBuddyCapacity

setBuddyCapacity

getMessenger

setMessenger