PRD-037 采集与生活技能

文档编号：PRD-037
版本：v1.0
状态：已通过
适用端：服务端 / 客户端
脚本挂载：lua/life/gather.lua

1. 背景与目标

采集是制造与经济的原料入口。资源点、刷新、技能等级、稀有产出适合用 Lua 配置，C++ 负责资源实体与交互。

目标

• 采集节点按地图/等级分布，定时刷新。
• 采集成功率受生活技能等级、工具、BUFF 影响。
• 支持稀有掉落、采集日志、脚本扩展节日资源。

2. 核心规则

• 玩家 15 级以上可学习采集，生活技能 1–10 级。
• 采集消耗体力，每次 1 点，体力每 5 分钟恢复 1 点。
• 节点分草药/矿石/木材/特殊，等级不足无法采集。
• 采集读条 2 秒，移动/受击打断。
• 成功获得 1–3 个材料，稀有材料概率受技能等级加成。
• 节点采集 3–5 次后枯竭，按 respawn 时间刷新。

3. 服务端设计

3.1 Lua 脚本设计

-- lua/life/gather.lua
Gather = {
    nodes = {
        [7001] = { level=1, type="herb", items={ {id=5011,w=900}, {id=5012,w=100} } },
    },
    stamina_cost = 1,
    cast_time = 2,
}

function OnGatherStart(ctx, role, node_id)
    local node = Gather.nodes[node_id]
    if not node then return ctx:Fail(role, "无效资源点") end
    if ctx:GetLifeLevel(role, node.type) < node.level then
        return ctx:Fail(role, "生活技能等级不足")
    end
    if ctx:GetStamina(role) < Gather.stamina_cost then
        return ctx:Fail(role, "体力不足")
    end
    ctx:StartCast(role, Gather.cast_time, "gather", node_id)
end

function OnGatherFinish(ctx, role, node_id)
    local node = Gather.nodes[node_id]
    ctx:ConsumeStamina(role, Gather.stamina_cost)
    local item = ctx:PickWeighted(node.items, ctx:GetLifeLevel(role, node.type))
    ctx:GrantItem(role, item.id, ctx:RandomInt(1,3))
    ctx:ConsumeNode(node_id, 1)
end

• 节点剩余次数、刷新时间由 C++ 资源管理器维护，脚本读取/扣减。
• 采集读条由 C++ 统一处理，完成时回调 Lua 结算。
• 节日资源通过新增 node 配置与脚本条件扩展，不改主流程。

3.2 协议

方向	协议	说明
C→S	CS_GatherStart	开始采集
C→S	CS_GatherCancel	取消
S→C	SC_GatherProgress	读条进度
S→C	SC_GatherResult	产出/失败原因

3.3 资源点刷新

• 节点由 scenesinfo.xml 配置坐标、类型、等级、刷新时间。
• 枯竭后进入 depleted 状态，客户端显示灰色。
• 刷新由场景服定时器统一处理，脚本可注册 OnNodeRespawn 做额外逻辑。

4. 客户端设计

• 资源点高亮：可采集绿色、等级不足灰色、枯竭灰色。
• 采集读条、打断提示、体力不足提示。
• 生活技能面板：等级、经验、可采集类型。
• 产出飘字与背包提示，稀有材料特殊光效。
• 地图资源分布筛选。

5. 配置与 Lua 接口

配置	说明
node_id / map_id	资源点
type / level	类型与等级
items	产出权重
respawn	刷新时间
stamina_cost	体力消耗

Lua 接口：GetLifeLevel、GetStamina、ConsumeStamina、StartCast、GrantItem、ConsumeNode、PickWeighted。

6. 边界与异常

场景	处理
采集读条中移动	打断，不扣体力
节点被他人采完	返回枯竭，不扣体力
背包满	产出转邮件
生活技能升级	脚本回调 OnLifeLevelUp
脚本异常	停止该次采集，记录日志

7. 验收标准

• 采集读条/打断/体力/产出/枯竭/刷新正确。
• 生活技能等级与成功率/稀有率生效。
• 节日资源可通过脚本配置扩展。
• 背包满/并发采集处理正确。
• 节点状态在客户端显示一致。