12 KiB
AVA2 功能迁移计划
日期：2026-10-14。本文是计划，不代表功能已实现或授权部署。
范围与原则
- 目标客户端：metin2-client；目标服务端：metin2-server，来自 203 的源码快照。
- AVA2 原始源码与 ava2-client 作为只读参考；不迁移整个 AVA2 root、协议或数据库。
- 以 AVA2 的活动实现为功能依据；面向当前服务器的数据和物品规则适配，移动端布局沿用现有单层最多六技能方案。
- 生物学家系统保持现有实现；百科可提供其材料查询入口。
- 每阶段分别提交客户端、服务端改动；契约注明对应版本。数据库变更提供升级、验证及回退方案。
- 不默认迁移 AVA2 的 8 sockets、15 attrs、64 位货币、征服者等级、装备槽或新副本内容。
- 开发先用隔离测试运行目录与测试账号；上线前备份相关二进制、配置与新增数据，避免恢复整个数据库覆盖玩家后续进度。
阶段 0：共同基础与活动代码确认
- 为每项建立 AVA2 入口、启用宏、Python/C++ 方法、网络请求、服务器处理、数据配置、数据库字段的追踪清单，记录源码哈希。
- 识别 old/copia/ex 等多版本实现，依据实际 import、调用、编译路径确定基准。日历与战令尤其不能按文件名任选一套。
- 定义版本化功能能力和扩展消息契约。检查当前包头占用，统一固定宽度字段、长度上限、分页、错误码、请求标识；不直接复制 AVA2 的包头编号。
- 查询与写操作分离。服务器确认道具消耗、奖励、任务进度、冷却和洗练结果；客户端只展示和发送请求。
- 资料使用当前服务器配置导出，包含版本/哈希与中文名；客户端打包和 Android 增量同步都纳入新资源。
- 公用分页、物品提示、搜索、空态、错误提示、触屏滚动、关闭与重连处理。小地图旁使用收纳入口，避免七个窗口入口长期遮挡画面。
验收：不支持功能的服务端不会触发客户端解析错误；未知/越界消息被拒绝；查询不阻塞游戏主循环；旧功能基本流程回归通过。
阶段 1：游戏百科
参考：uiwiki.py、wikiui.py、PythonWiki；模型预览另参考 RenderTarget。
客户端：物品/怪物分类、中文及 ID 搜索、详情、升级材料链、关联跳转；材料详情可进入掉落来源，生物学家材料可进入百科。 服务端/工具：由当前 item_proto、mob_proto、refine 配置及实际可用物品清单生成目录；缺少或禁用内容不伪装可获取。 数据：静态版本化资料包优先，服务端只补实时/受权限影响的数据；分页索引避免一次创建全部 UI。 首批交付：2D 图标与文字查询；第二子批移植 Vulkan 离屏模型预览、独立相机、对象生命周期及尺寸适配，完成后才称 AVA2 对应预览已迁移。 验收：升级链无错链、搜索可定位现有物品、缺失图标可回退、重复开关无资源泄漏；模型预览不污染主场景状态。
阶段 2：怪物掉落查询
参考：uitarget.py 的 InfoBoard、PythonDropItem、目标信息及掉落消息路径。
客户端：目标栏信息按钮、怪物详情掉落列表、按物品反查来源、与百科互跳。 服务端：复用实际加载的掉落配置/解析结果，区分怪物组掉落、等级/任务/活动条件和特殊代码发奖；不只读取一份文本便声称覆盖所有来源。 数据：区分数量、候选权重、基础概率、附加条件；未解析的来源明确标为未覆盖。动态倍率影响的最终概率不按静态权重伪造百分比。 验收：按实际掉落分支选样本，对照等级/活动/任务条件；仅查询不改变掉落 RNG 或消耗状态；生物学家材料来源可反查。
阶段 3：宝箱预览
参考：uiChestDrop.py、uichestdropinfo.py 与服务器 special item group / 开箱路径。
客户端：物品提示进入预览、分页展示奖励与数量，绑定当前物品 ID 和实时背包位置；先交付只读预览。 服务端：从真实开箱奖励组构建预览，标注“全部获得”“随机其一”“多次抽取”等真实规则；不能将权重直接当独立中奖率。 完整交互子批：若 AVA2 活动入口包含数量选择/批量开箱，跟随其限制移植；校验背包容量、绑定、钥匙、金币及失败消费顺序。 验收：预览与实际奖励候选集一致；预览无消耗；物品移动后旧请求不作用于另一件物品；批量不足、背包满、重复点击不会超额扣除。
阶段 4：角色详细属性面板
参考：uicharacterdetails.py / uicharacterdetails2.py，先核实实际入口与属性枚举。
客户端：按攻击、防御、职业/种族加成、抗性、速度、恢复等分类；中文搜索、单位、说明和已支持值展示。 服务端：返回同一角色状态版本的有效属性快照，补充当前协议未同步的对石、对 Boss、半人抗性等值。 边界：当前生物学家怪物加成对 Boss 的特殊处理必须在说明中体现；展示累计属性不等于承诺所有目标上的最终伤害百分比。首批不虚构“装备/任务/活动”分项来源。 验收：穿脱装备、切换增益、生物学家领奖与重选后更新一致；死亡/复活、重登、切线不残留旧快照；显示值对应实际战斗计算使用值。
阶段 5：副本信息与冷却提示
参考：uidungeoninfo.py、uidungeontimer.py、PythonDungeonInfo、dungeon_info 与任务 Lua 接口。
客户端：副本列表、等级/组队要求、门票提示、冷却、入口按钮和完成提醒；仅列当前服已安装并有真实入口的副本。 服务端：为每个副本建立任务标识、入口处理、冷却字段与写入时机映射；首次加载读取真实任务状态，禁止另建一套互不相通的客户端计时器。 计时：服务器下发时间基准与到期时间，客户端只渲染倒计时；休眠恢复/重连重新同步。明确角色/账号、队伍成员及频道间的冷却作用域。 持久化：优先复用现有 quest flags；确需新表时按角色/账号与副本键设计。通关次数、最快时间、排名分后续子批，不能用零占位声称已接入。 验收：提前进入被服务器拒绝；门票消耗与传送顺序正确；重复请求不重复扣票；重登、重启与跨频道后冷却一致。
阶段 6：自动洗练与属性锁定
参考：uiswitchbot.py、PythonSwitchbot、new_switchbot，以及 ENABLE_LOCK_ATTR 对应的 item_attribute / char_item / item_addon。
前置核查：明确 AVA2 活动版本的工作槽数、候选组合数、普通/稀有属性适用范围、停止条件、材料与锁定上限。原版锁信息存于扩展属性区域，当前七属性布局不能直接容纳。 存储决策：先编写字段映射与兼容测试。优先评估独立锁定元数据/表是否能完整承载其语义；若不能，必须单独规划物品结构、DB 缓存与网络格式升级，不能直接写入现有属性或 socket。 客户端：放入装备、目标属性及阈值、候选组合、锁定状态、开始/停止、剩余材料与停止原因；触屏可选列表代替细小输入控件。 服务端：在权威物品对象上执行受限频率任务；按物品唯一 ID 绑定，阻止运行中交易、出售、仓库转移和替换目标；统一所有手动/自动洗练路径的锁定行为。 执行规则：每次洗练原子检查状态、消耗、生成、保存；同一组合内条件如何组合、多个候选如何匹配，严格按已确认 AVA2 规则。客户端不决定随机值或自行发批量循环洗练。 断线策略：核实 AVA2 行为并明确恢复规则；不默认承诺离线洗练。断线/重启后的消耗和任务状态必须可核对。 验收：满足目标即停止；材料耗尽、非法属性、锁定上限、平均/技能伤害特殊属性、物品转移、重复开始和重启恢复都不复制物品、不重复扣费、不覆盖其他装备。
阶段 7A：活动日历
参考：interfacemodule.py 中实际 uiEventCalendarNew 入口、uieventcalendarnew.py、char_event_calendar；旧 uicalendar 有入口被注释，不默认全部移植。
客户端：月历/列表、活动详情、进行中状态、开始/结束提醒；显示服务器时区及当前活动作用频道/阵营。 服务端：唯一活动配置与调度器，同一配置驱动日历和真实倍率/掉落效果；仅支持当前服已实现的活动类型，不因日历有图标就导入对应玩法。 运维：配置校验、重新加载、重启后的活动恢复和结束清理，避免每个 game core 重复发奖。 验收：月末、跨日、服务器时间调整、断线恢复与进出活动区间正确；界面“进行中”与实际效果一致；重复调度不会重复开启/叠加奖励。
阶段 7B：战令任务
参考：uibattlepass.py 的实际 UiBattlePass 入口、PythonBattlePass、battlepass.cpp、questlua_battlepass；其余 ex 版本先做活动路径核实。
客户端：赛季、任务分类、进度、任务奖励/阶段奖励和领取状态；未适配的任务类型不展示成可完成。 服务端：在击杀、开箱、通关、采集等真实完成事件挂钩计数，区分击杀归属、组队和重复回调；客户端不能上报任意增加进度。 数据库：从 AVA2 实际 SQL 读写还原语义，使用新建迁移脚本；角色/账号归属、赛季 ID、任务 ID、完成量及领奖记录具有明确唯一键。禁止导入整个 AVA2 MySQL 数据目录。 奖励：领奖校验、持久化记录与发奖采取能抵御重试和崩溃的幂等流程；背包满、断线和切线不能丢奖或重复领。高级战令如活动实现需要解锁道具，另建明确的资格与消费流程。 验收：真实行为推进正确任务；任务/赛季边界、重启恢复、重复事件、并发领奖、赛季切换和背包满均可恢复；活动倍率不能意外放大战令计数。
交付顺序与阶段门槛
建议顺序：0 → 1 → 2 → 3 → 4 → 5 → 6 → 7A → 7B。
1/2/3 共用目录与查询层，先形成“生物学家材料 → 百科 → 怪物/宝箱来源”的完整闭环。 4 作为后续战斗加成验证工具；5 的通关事件可复用于 7B；3 的开箱事件也可复用于 7B。 活动日历与战令共用时间/通知基础，但进度、调度和领奖分别管理。
每阶段交付：客户端提交、服务端提交（如需）、协议与字段文档、资料生成脚本、资源清单、自动测试、macOS 联机记录、Android 真机交互记录、部署/回退说明。 完成条件：隔离环境通过后再安排 203 部署，实际任务闭环通过方可标记完成；编译、模拟包和静态比较不能替代联机验收。 2026-10-15 进度：阶段 0 的资料/界面基础与阶段 1 的静态查询子批已实现并完成本机回归；详情见 AVA2-WIKI-IMPLEMENTATION.md。服务端握手/查询协议、模型预览、阶段 2 以后均未完成，未部署上述新功能到 203。
2026-10-15 后续批次：阶段 0 的只读能力协商、阶段 2/3 的掉落/来源/宝箱查询、阶段 4 属性面板已实现并在隔离环境测试；未部署 203，待联机与真机验收。范围和缺口见 AVA2-READONLY-FEATURES.md。
2026-10-15 再续：龙穴/周任务信息与提醒、共享真实掉落开关的活动日历已实现并在隔离环境验证。副本仅首批龙穴；活动仅月光宝箱/圣诞袜，生产未部署，无生产排期。自动洗练/锁定、战令、模型预览、批量开箱仍待实现。见 AVA2-DUNGEON-CALENDAR.md。