角色与生物系统技术手册 (Characters & Creatures Manual)¶

本手册系统性讲解 Cataclysm: Cleanwater Bomb (CCB) 中的角色（Character）、玩家（avatar）、非玩家角色（NPC）与怪物（Monster）实体系统、底层运作机制以及供 Mod 调用的核心 API。

1. 实体体系与生命周期¶

CCB 的所有生物实体均继承自 Creature 核心基类：

Creature（生物基类）：提供三维网格坐标（tripoint）、基础移动速度（moves）、每回合生命恢复、视野感知（sees）与伤害结算接口。
Character（人形角色）：管理分部位肢体解剖结构（body_part）、痛觉、耐力、背包库存与武术技能。
avatar（玩家实体）：绑定全局输入管理器与任务日志。
monster（怪物实体）：挂载攻击 AI、仇恨度（Aggression）、士气（Morale）与特殊攻击行为树。

2. 身体部位与生命健康模型 (Body Anatomy)¶

人形角色（Character）的生命值并非单一数值，而是划分为 12 个独立的身体部位：

部位标识符 (`body_part`)	部位名称	关键影响
`"head"`	头部	致命部位，HP 归零直接死亡；受创可能引发脑震荡
`"torso"`	躯干	致命部位，HP 归零直接死亡；影响绝大多数装备的穿戴与负重
`"eyes"` / `"mouth"`	眼部 / 嘴部	影响视野清晰度、感知范围与防毒面具过滤效率
`"arm_l"` / `"arm_r"`	左臂 / 右臂	影响近战武器挥舞速度、持枪瞄准稳定性与格挡效果
`"hand_l"` / `"hand_r"`	左手 / 右手	影响精细手工制作、握持物品能力与敏捷判定
`"leg_l"` / `"leg_r"`	左腿 / 右腿	影响基础移动速度；腿部骨折将大幅增加移动 AP 消耗
`"foot_l"` / `"foot_r"`	左脚 / 右脚	影响复杂地形翻越与奔跑体力消耗

3. 核心 API 参考 (Core APIs)¶

`character:get_hp(part) -> integer`¶

查询指定身体部位的当前生命值。

参数 (Parameters): * part (string, 必填): 目标身体部位标识符（如 "head", "torso", "arm_l"）。

返回值 (Returns): * integer: 该部位当前的生命值（HP）。

实战示例 (Example):

-- 检查玩家躯干是否处于重伤状态
local torso_hp = player:get_hp("torso")
if torso_hp < 20 then
    game.add_msg("danger", "你的躯干受到致命重创，急需包扎！")
end

`character:mod_pain(amount)`¶

增减角色的疼痛指数。疼痛会直接削减角色的属性与移动速度。

参数 (Parameters): * amount (integer, 必填): 疼痛变动值。正数为增加疼痛，负数为减轻疼痛（镇痛）。

[!TIP] 疼痛阈值提示：当疼痛值超过 40 时，角色将出现间歇性失神；超过 80 时可能因剧痛休克昏迷。

`character:add_effect(effect_id, duration)`¶

为角色附加一个状态效果（Buff / Debuff）。

参数 (Parameters): * effect_id (string, 必填): 效果标识符（例如 "adrenaline", "bleed", "poison"）。 * duration (integer, 必填): 持续时间，单位：回合数 (turns)。

实战示例 (Example):

-- 注入兴奋剂，获得 60 回合的肾上腺素激增效果
player:add_effect("adrenaline", 60)
game.add_msg("info", "肾上腺素在血管中奔涌！")

4. 关键事件监听 (Event Hooks)¶

通过订阅以下原生事件，Mod 可以精确感知角色的生存动态：

-- 监听角色受到伤害事件
events.on("character_takes_damage", function(event)
    local victim = event.character
    local damage = event.damage
    -- 自定义防具充能或护盾吸收逻辑
end)

-- 监听角色从睡眠中苏醒
events.on("character_wakes_up", function(event)
    game.add_msg("info", "天亮了，你揉了揉惺忪的睡眼。")
end)