LimbHealthServerAPI

服务端入口类，继承自 LimbHealthCommonAPI，所有方法均为 @staticmethod。

from LimbHealthScripts.server.LimbHealthServerAPI import LimbHealthServerAPI

---

肢体血量操作

setLimbHealth(playerId, posTypeEnum, newHealth, isFromHurt)

直接设置玩家某部位的当前血量。

@staticmethod
def setLimbHealth(playerId, posTypeEnum, newHealth, isFromHurt):

参数

名称	类型	必填	说明
playerId	str	✅	玩家 ID
posTypeEnum	LimbHealthPosTypeEnum.PosTypeValue	✅	目标部位
newHealth	float | int	✅	新血量值（内部会 float() 转换）
isFromHurt	bool	✅	是否由「受伤」流程触发，影响事件语义与下游逻辑

返回

None

异常

• TypeError —— posTypeEnum 不是 LimbHealthPosTypeEnum.PosTypeValue 实例时抛出。
• TypeError —— isFromHurt 不是 bool 时抛出。

---

getLimbHealth(playerId, posTypeEnum)

获取玩家某部位的当前血量。

@staticmethod
def getLimbHealth(playerId, posTypeEnum):

参数

名称	类型	必填	说明
playerId	str	✅	玩家 ID
posTypeEnum	LimbHealthPosTypeEnum.PosTypeValue	✅	目标部位

返回

float | int —— 当前血量值。

异常

• TypeError —— posTypeEnum 类型错误时抛出。

---

syncLimbHealthToAttr(playerId, isFromHurt)

将玩家所有部位的血量按当前内部状态同步到原版血量属性。

@staticmethod
def syncLimbHealthToAttr(playerId, isFromHurt):

参数

名称	类型	必填	说明
playerId	str	✅	玩家 ID
isFromHurt	bool	✅	是否由「受伤」流程触发

返回

None

用途

在你直接通过 setLimbHealth 改写多个部位之后调用一次，确保下游对原版血量的展示与逻辑保持一致。

---

命中预设与拦截

setNextDamageHitPart(playerId, posTypeEnumOrAll)

预设指定玩家下一次受伤的命中部位，由外部模组在 Hurt() 之前调用。

@staticmethod
def setNextDamageHitPart(playerId, posTypeEnumOrAll):
    # type: (str, LimbHealthPosTypeEnum.PosTypeValue | str) -> None
    """
    预设指定玩家下一次受伤的命中部位。外部模组在调用 Hurt() 之前调用此方法，
    LimbHealth 将优先使用该预设值进行护甲耐久抵消和肢体伤害分配，跳过自动判定。
    仅消费一次（pop 语义），若伤害未实际触发则残留到下次消费。
    """

参数

名称	类型	必填	说明
playerId	str	✅	被攻击的玩家 ID
posTypeEnumOrAll	LimbHealthPosTypeEnum.PosTypeValue | str	✅	部位枚举值，或字符串 "all" 表示平均分配到所有部位

返回

None

异常

• TypeError —— 当传入既不是合法的 PosTypeValue 也不是字符串 "all" 时抛出。

pop 语义与残留风险

预设值以 dict[playerId -> hitPart] 形式存储，在 ActuallyHurtServerEvent 中受到真实伤害非0/无敌帧伤害时被 pop 出来消费。

会被消费：玩家受到 damage_f > 0、非摔落、非倒地状态下的任意一次实际伤害。

不会被消费的情况（留在内部映射里，等下一次满足条件的伤害）：

场景	原因
Hurt() 实际未造成伤害（damage_f <= 0，例如被无敌帧拦截、被护盾抵消）	在消费前直接跳出
摔落伤害（cause == ActorDamageCause.Fall）	跳过护甲耐久抵消整条路径
玩家处于 PlayerRevive 倒地状态	LimbHealth 把伤害处理让位给 PlayerRevive，整条路径被跳过
被攻击实体不是玩家	不走玩家肢体逻辑

残留特征：

• 永久残留——不会过期
• 再次 set 会直接覆盖前一次的预设

最佳实践：

• 紧贴 Hurt() 调用 setNextDamageHitPart，避免被中间事件错位消费
• 若你的逻辑可能导致 Hurt() 不实际触发伤害（例如不确定无敌帧），在调用 Hurt() 之后立刻覆盖 set 一个无关的"哨兵值"或在下一次正常伤害前重新 set，确保不会作用到无关伤害上
• 若玩家可能正处于 PlayerRevive 倒地状态，先用 PlayerReviveServerAPI.getIsNeedRevive(playerId) 判断后再 set，避免无效预设积压

---

setIsStopAttrMaxValuePatch(isStop)

控制是否暂停「原版属性最大值补丁」。

@staticmethod
def setIsStopAttrMaxValuePatch(isStop):

参数

名称	类型	必填	说明
isStop	bool	✅	True 暂停补丁，False 恢复（默认）

返回

None

Info

LimbHealth 会拦截所有外部模组通过 SetAttrMaxValue() 对玩家血量属性最大值（MAX_HEALTH 等属性）的修改以维持自身一致性。当你需要短暂放行第三方模组的修改时，传入 True，完成后务必再恢复为 False。

---

配置查询

getIsDisplayVanillaHealthBar()

查询当前是否显示原版血条。

@staticmethod
def getIsDisplayVanillaHealthBar():

参数

无。

返回

bool —— True 表示显示原版血条，False 表示隐藏。

---

事件系统

getApiEvents()

返回可注册事件的枚举类。

@staticmethod
def getApiEvents():
    # type: () -> type[LimbHealthServerAPI.ApiEvents]

返回

type[LimbHealthServerAPI.ApiEvents] —— 包含三个事件枚举项：LimbHealthUpdateEvent、LimbHealthMaxUpdateEvent、LimbHealthConfigMaxHealthUpdateEvent。

---

getLimbHealthEventPriorityEnum()

返回事件优先级枚举类。

@staticmethod
def getLimbHealthEventPriorityEnum():
    # type: () -> type[LimbHealthEventPriorityEnum]

返回

type[LimbHealthEventPriorityEnum] —— 5 个等级。

---

registerEventHandler(event, func, priority=None, *presetArgs)

注册事件处理器（通用）。

@staticmethod
def registerEventHandler(event, func, priority=None, *presetArgs):
    # type: (LimbHealthServerAPI.ApiEvents.EnumObject | type, callable, LimbHealthEventPriorityEnum.EnumObject | None, *any) -> None

参数

名称	类型	必填	说明
event	ApiEvents.EnumObject | type	✅	通过 getApiEvents() 取得
func	callable	✅	处理器，签名为 (*presetArgs, event) -> None
priority	LimbHealthEventPriorityEnum.EnumObject | None	❌（默认 NORMAL）	触发优先级
*presetArgs	any	❌	预置参数

返回

None

异常

• TypeError —— event / func / priority 类型错误时抛出。

---

unregisterEventHandler(event, func)

取消事件处理器注册（通用）。

@staticmethod
def unregisterEventHandler(event, func):
    # type: (LimbHealthServerAPI.ApiEvents.EnumObject | type, callable) -> None

参数

名称	类型	必填	说明
event	ApiEvents.EnumObject | type	✅	与注册时相同
func	callable	✅	与注册时相同的函数对象

返回

None

异常

• TypeError —— event / func 类型错误时抛出。

---

registerLimbHealthUpdateEventHandler(func, priority=None, *presetArgs)

注册 LimbHealthUpdateEvent 处理器的便捷方法（最常用的事件）。

@staticmethod
def registerLimbHealthUpdateEventHandler(func, priority=None, *presetArgs):
    # type: (callable, LimbHealthEventPriorityEnum.EnumObject | None, *any) -> None

参数

与 registerEventHandler 一致，但省略 event 参数（隐式为 LimbHealthUpdateEvent）。

返回

None

---

unregisterLimbHealthUpdateEventHandler(func)

取消 LimbHealthUpdateEvent 处理器注册的便捷方法。

@staticmethod
def unregisterLimbHealthUpdateEventHandler(func):
    # type: (callable) -> None

参数

名称	类型	必填	说明
func	callable	✅	与注册时相同的函数对象

返回

None

---

LimbHealthCommonAPI 继承

LimbHealthServerAPI 继承自 LimbHealthCommonAPI，自动包含以下两个方法。

getPosTypeEnum()

返回部位枚举类。

@staticmethod
def getPosTypeEnum():
    # type: () -> type[LimbHealthPosTypeEnum]

返回

type[LimbHealthPosTypeEnum] —— 8 个部位常量。

---

getCustomEffectEnum()

返回自定义药水效果标识枚举类。

@staticmethod
def getCustomEffectEnum():
    # type: () -> type[CustomEffectIdentifierEnum]

返回

type[CustomEffectIdentifierEnum] —— 3 个药水效果标识常量。