原创 【XMRole🌟角色库】 1.0.0

API 方法​

1. CheckPlayerRole - 检查玩家是否拥有指定角色​

方法名: CheckPlayerRole
参数:

• BasePlayer player - 玩家对象
• int roleID - 角色ID

返回值:

• 如果玩家拥有该角色，返回 Dictionary<string, object>，包含以下键值：
  • Player (BasePlayer) - 玩家对象
  • RoleID (int) - 角色ID
  • Level (int) - 角色等级
  • TotalExp (int) - 角色总经验值（包括已升级消耗的经验）
  • Constellation (int) - 角色命格
  • DaysSinceUnlock (int) - 玩家解锁此角色的天数
• 如果玩家未拥有该角色，返回 null

2. GetPlayerCurrentRoleID - 获取玩家当前角色ID​

方法名: GetPlayerCurrentRoleID
参数:

• BasePlayer player - 玩家对象

返回值:

• int - 玩家当前角色ID
• 如果玩家没有选择角色，返回 0

3. AddPlayerRoleExp - 增加玩家角色经验值​

方法名: AddPlayerRoleExp
参数:

• BasePlayer player - 玩家对象
• int roleID - 角色ID（可选，0表示使用玩家当前角色）
• int exp - 要增加的经验值（正数）

返回值:

• bool - 成功返回 true，失败返回 false

4. RemovePlayerRoleExp - 扣除玩家角色经验值​

方法名: RemovePlayerRoleExp
参数:

• BasePlayer player - 玩家对象
• int roleID - 角色ID（可选，0表示使用玩家当前角色）
• int exp - 要扣除的经验值（正数）

返回值:

• bool - 成功返回 true，失败返回 false

5. UnlockPlayerRole - 为玩家解锁角色​

方法名: UnlockPlayerRole
参数:

• BasePlayer player - 玩家对象
• int roleID - 角色ID
• int durationSeconds - 解锁时长（秒，可选，0或省略表示永久解锁）

返回值:

• bool - 成功返回 true，失败返回 false

说明:

• 如果玩家已拥有该角色，会根据配置文件的"重复解锁角色提升命格概率"来决定是否提升命格
• 如果指定了 durationSeconds，角色将在到期后根据配置文件的"转职后"模式自动清理数据

6. GetRoleConfiguration - 获取角色配置信息​

方法名: GetRoleConfiguration
参数:

• int roleID - 角色ID

返回值:

• Dictionary<string, object> - 角色配置信息，包含：
  • RoleName (string) - 角色名称
  • RoleDescription (string) - 角色描述
  • RoleImage (string) - 角色图像
  • MainSkillImage (string) - 主技能图像
  • SecondarySkillImage (string) - 次技能图像
  • AuxiliarySkillImage (string) - 辅技能图像
  • MainSkillDescription (string) - 主技能介绍
  • SecondarySkillDescription (string) - 次技能介绍
  • AuxiliarySkillDescription (string) - 辅技能介绍
  • Tags (List<RoleTag>) - 角色标签
  • Attributes (RoleAttributes) - 角色属性
  • Abilities (RoleAbilitySettings) - 角色能力设置
• 如果角色不存在，返回 null

7. GetPlayerEnergy - 查询玩家当前角色指定编号能量​

方法名: GetPlayerEnergy
参数:

• string userid - 玩家的UserIDString
• string channelID - 能量渠道编号（如"1"、"2"、"3"等）

返回值:

• 成功返回 int - 能量数量
• 失败返回 null - 玩家不存在、没有当前角色、参数错误等
• 如果该能量渠道不存在，返回 0

说明:

• 查询玩家当前角色的指定能量渠道余额
• 能量渠道编号对应配置文件中"角色专属能量收集渠道"的键

8. AddPlayerEnergy - 添加玩家当前角色指定编号能量​

方法名: AddPlayerEnergy
参数:

• string userid - 玩家的UserIDString
• string channelID - 能量渠道编号（如"1"、"2"、"3"等）
• int amount - 要添加的能量数量（必须大于0）

返回值:

• bool - 成功返回 true，失败返回 false

说明:

• 为玩家当前角色的指定能量渠道添加能量
• 如果能量渠道不存在会自动创建
• 自动保存数据

9. RemovePlayerEnergy - 扣除玩家当前角色指定编号能量​

方法名: RemovePlayerEnergy
参数:

• string userid - 玩家的UserIDString
• string channelID - 能量渠道编号（如"1"、"2"、"3"等）
• int amount - 要扣除的能量数量（必须大于0）

返回值:

• bool - 成功返回 true（能量足够并成功扣除），失败返回 false（能量不足或其他错误）

说明:

• 扣除玩家当前角色的指定能量渠道能量
• 会检查能量是否足够，不足则返回false且不扣除
• 自动保存数据

---

HOOK 接口​

1. OnPlayerSwitchRole - 玩家切换角色时触发​

HOOK名: OnPlayerSwitchRole
参数:

• BasePlayer player - 玩家对象
• int roleID - 切换后的角色ID（不是切换前的）

返回值:

• 无返回值要求

说明:

• 当玩家成功切换角色后触发
• roleID 是玩家切换后的当前角色ID

2. OnPlayerRoleLevelUp - 玩家角色升级时触发​

HOOK名: OnPlayerRoleLevelUp
参数:

• BasePlayer player - 玩家对象
• int roleID - 角色ID
• int newLevel - 新的等级

返回值:

• 无返回值要求

说明:

• 当玩家角色等级提升时触发
• 可能一次升级多级，但每次升级都会触发一次

3. OnPlayerRoleLevelDown - 玩家角色降级时触发​

HOOK名: OnPlayerRoleLevelDown
参数:

• BasePlayer player - 玩家对象
• int roleID - 角色ID
• int newLevel - 新的等级

返回值:

• 无返回值要求

说明:

• 当玩家角色等级下降时触发（例如扣除经验导致降级）

4. OnPlayerUnlockRole - 玩家解锁角色时触发​

HOOK名: OnPlayerUnlockRole
参数:

• BasePlayer player - 玩家对象
• int roleID - 角色ID
• string durationText - 解锁时长文本（"永久" 或 "X秒"）

返回值:

• 无返回值要求

说明:

• 当玩家解锁角色时触发
• 如果玩家已拥有该角色，根据概率提升命格时也会触发（此时 durationText 为 "永久"）

5. OnPlayerUseRoleSkill - 玩家使用角色技能时触发（已存在）​

HOOK名: OnPlayerUseRoleSkill
参数:

• string playerName - 玩家名称
• int roleID - 角色ID
• string skillType - 技能类型（"main", "secondary", "auxiliary"）

返回值:

• 无返回值要求

说明:

• 当玩家使用角色技能时触发

6. OnPlayerCollectEnergy - 玩家获取能量时触发​

HOOK名: OnPlayerCollectEnergy
参数:

• string playerName - 玩家名称
• int roleID - 角色ID
• string channelID - 能量渠道编号

返回值:

• 无返回值要求

说明:

• 当玩家成功收集能量时触发
• 在能量已添加到玩家余额后触发

7. OnPlayerCraftExclusiveItem - 玩家制作专属物品时触发​

HOOK名: OnPlayerCraftExclusiveItem
参数:

• string playerName - 玩家名称
• int roleID - 角色ID
• string itemName - 物品名称
• int craftAmount - 制作数量

返回值:

• 无返回值要求

说明:

• 当玩家成功制作专属物品时触发
• 在物品已发放到玩家背包后触发
• itemName 是配置文件中设置的物品名称（不是shortname）
• 可用于任务系统、统计系统等监听玩家制作行为