# 礼包、兑换码与游戏邮件

礼包保存奖励脚本，12位游戏码负责核销并发邮件，玩家领取邮件附件执行奖励。16位商品码保持原流程。

通过 AI 创建礼包并编辑名称、说明和脚本，保存立即生效，无草稿、版本、试领或发布步骤。礼包没有参数，奖励数量直接写入脚本，例如 player.addPro('金币', 100)。空脚本可以保存，但不能发放；作者可在礼包管理中启停礼包。停用礼包阻止后续兑换及邮件未领取附件的领取；启用后恢复，已领取奖励不受影响。

脚本只支持同步属性和对象操作：player.getPro/setPro/addPro、objects.newObject/getObjects。不支持联网、异步、定时器、UI、事件或存档。使用已有实体不需要发布游戏；新增游戏实体或运行时能力仍需更新游戏。

“兑换码管理”只选择礼包ID，核销时读取当前启用礼包并把脚本和描述复制到邮件附件。以后编辑礼包不会改变已发邮件。邮件管理中，超管可以撤销未领附件，或显式改绑到礼包当前内容；已领取奖励不能重置。

作者只能管理自己的礼包和兑换码。超管在“礼包、兑换码与邮件”管理全站数据，支持邮件筛选、详情、发信和软删除。邮件有未领附件时须先撤销才能删除。批量发信最多1000人、每封10附件；全体成功或失败，不跳过无效收件人。同请求重试不会重复发信。

AI 工具是 query_gift_packs/upsert_gift_packs。脚本路径 gift_pack/<礼包ID>/script 使用统一脚本工具；需要执行时用 debug_script 在现有测试服运行，会修改测试状态，不发送正式邮件。请求去重标识内部生成，不用填写。

玩家兑换和领取都携带当前会话最近保存/读档的DataID，后端匹配当前账号当前游戏任意非空云存档。脚本失败整封回滚并恢复资格，保存失败只重试保存、不重跑奖励。批量最多20封/100附件，逐封保存；结果不确定不自动补发。

旧码继续兼容，迁移会把已发布旧脚本及固定name分支值生成兼容礼包。至少并行七天，所有有效旧码处理后才显式关闭旧直接兑换；历史核销永不补发。