跳到主要内容

背包与任务:定义、实例和奖励事务

物品编号与物品实例不是一回事​

物品定义描述名称、图标、堆叠上限和用途,物品实例描述某一件装备的等级、耐久、随机属性或绑定状态。普通材料可以按定义编号堆叠,具有独特状态的装备需要独立实例编号。若把显示名称当标识,改名或本地化就会破坏存档;若把数组下标当实例身份,排序和删除会让装备引用错位。

任务也有定义和玩家进度。定义包含目标类型、数量、前置条件和奖励;玩家状态包含当前进度、是否解锁、是否完成与是否领取。完成和领取需要区分,因为玩家可能已经满足目标但尚未查看界面。任务的生命周期应有明确终止态和重复周期身份,不能只保存一个 completed 布尔值应付所有日常与主线任务。

后端的库存和交易经验非常适用,但需要注意本地表现与持久状态的分离。点击领取发出命令,领域规则确认状态并一次提交奖励和领取标志,HUD 再播放飞入动画。动画中途关闭面板不应该丢奖励,动画重复也不应再发一次。对可信资产,客户端只展示服务端确认结果;本地背包不能自行成为支付和跨设备库存的权威。

背包操作要返回完整结果​

type Wallet = { coins: number };
type Quest = { id: string; progress: number; target: number; claimed: boolean };
type ClaimResult =
| { ok: true; reward: number }
| { ok: false; reason: 'incomplete' | 'claimed' };
function claim(q: Quest, wallet: Wallet, reward: number): ClaimResult {
if (q.claimed) return { ok: false, reason: 'claimed' };
if (q.progress < q.target) return { ok: false, reason: 'incomplete' };
q.claimed = true;
wallet.coins += reward;
return { ok: true, reward };
}

示例只展示内存中的原子步骤,正式入口仍需校验奖励配置和整数范围,持久化时把两个对象放进同一快照。网络版要在服务端事务中完成,并用任务实例或领取操作编号去重。不能因为 JavaScript 单线程,就忽略异步保存、重试请求和多设备并发带来的重复提交。

向背包加入物品时,先判断可用格数和可堆叠空间,再确定全部成功、部分成功还是进入邮件或临时仓库。结果应包含实际加入与剩余数量,调用方不能假设成功。消耗物品也要先验证总量,再统一扣除;跨多个堆叠时采用稳定顺序。升级或合成同时消费材料并生成物品,应作为一个事务,失败不能只扣材料不发结果。

任务进度消费领域事实​

击败敌人任务应该消费“合法击杀”事实,而不是敌人节点被销毁事件。节点可能因离屏、场景退出或对象池回收而消失,并不代表击杀。收集任务要区分累计获得、当前持有与消耗指定材料,这三种含义的进度逻辑不同。装备任务也要明确是曾经装备过,还是当前仍装备,不能只靠相同字段名猜测。

领域事件可包含唯一编号、发生时刻、来源和数量。重复投递时,消费者需要按合理范围去重;无限保存所有历史事件编号会增长无界,可以按会话、任务实例或服务端序列水位管理。对可重放任务,要规定是否追溯解锁前的历史。主线任务可能统计历史累计,活动任务可能只统计活动期间,两者都要有数据来源支持。

日常任务必须有周期身份,如服务端日期或固定时区日期。重置时创建新任务实例,不要只把 progress 清零后继续使用同一领取键,否则旧请求可能影响新周期。离线期间跨多个周期是否补发、过期奖励如何处理,属于产品规则,需要清楚说明。客户端本地日期不适合独自决定有价值的奖励资格。

列表显示与选择状态​

Cocos Creator 3.8.8 的 ScrollView 和 Layout 可以组成背包或任务列表。每个视图绑定稳定编号,选中状态保存在模型或界面状态中,不能只用节点颜色表示。列表刷新后按编号恢复选择;物品被消耗时,详情页收到明确失效状态。大量条目需要视口复用时,异步图标加载必须检查当前绑定编号,防止旧图片覆盖新格子。

排序不应影响规则。按稀有度排序只改变展示顺序,不改变装备栏引用和任务引用。筛选为空时显示明确空态,配置缺失时记录错误并保留可恢复信息,不要静默丢弃玩家物品。图标和颜色可以提示稀有度,但名称、等级和数量也应可读,避免色觉差异使关键信息丢失。

常见错误与排查​

“领取按钮点两次多发”检查提交守卫与幂等键;“换语言装备消失”检查是否用名称做主键;“杀怪任务随返回菜单增长”检查是否把销毁当击杀;“整理背包装备变了”检查是否引用数组下标;“满背包奖励丢失”检查容量策略与领取事务;“任务完成但界面不亮”检查 HUD 初始快照与订阅。

配置更新还可能删除任务或修改目标。已领取任务不能因目标调整重新领取,进行中任务是沿用旧定义还是迁移到新定义也需要明确。保留定义版本或迁移规则,避免在线内容更新悄悄重写玩家权益。付费道具和活动奖励的变更尤其需要可追溯记录,不能只改当前表格然后期待旧存档自然兼容。

奖励预览与实际发放共用定义​

任务面板的奖励图标和领取逻辑应读取同一份已固定版本的奖励定义。预览若自行写一份数量,配置更新后很容易显示十个却只发八个。领取结果返回实际发放清单,表现层按结果播放,容量不足或替代补偿也如实显示。对于多种奖励组合,先验证整体是否可提交,再统一修改状态,避免玩家只收到其中一部分却被标记为全部领取。

给 AI 的任务与验收​

任务示例:“实现可堆叠材料与独立装备实例,稳定编号,背包容量固定。任务监听合法击杀和累计获得事件,完成与领取分离;领取原子更新奖励和 claimed,满背包时拒绝且不改变任务。列表按编号绑定,不接真实支付或云资产。”要求写明部分加入是否允许以及重复事件的去重范围。

验收覆盖跨多个堆叠扣料、容量刚好不足、同一奖励重复领取、重复击杀事件、排序后装备引用、图标异步返回和旧任务迁移。模拟领取后立即关闭并重启,奖励与领取状态应一致;保存失败有明确恢复行为。将配置、领域事件、存档和 HUD 串起来后,才能算完成一条可靠的任务奖励链。

来源与核查范围​

  • Cocos 3.8 动态列表,核查日期:2026-11-17。参考数据驱动列表思路,页面含历史示例写法,本文目标代码采用 3.8.8 TypeScript。
  • Cocos 3.8 事件监听与派发,核查日期:2026-11-17。仅用于事件机制核对,库存事务与任务身份由项目自行实现。