metin2-client/docs/AVA2-DUNGEON-CALENDAR.md

AVA2 副本与活动日历适配进度

2026-10-15。修改 metin2-client 和 metin2-server；AVA2 只读参考。

已实现

百科顶部增加“副本信息”“活动日历”入口，沿用触屏按钮与可移动窗口，缩放时重新排版。

副本首批接入当前服实际安装的 dragon_lair_access 和 dragon_lair_weekly。服务端直接调用已加载任务的只读 settings 函数，读取当前冷却、加入窗口、门票及动态需求数量；读取当前角色 quest flags 和全服 event flags。保持 Lua 栈和当前任务/角色上下文，不调用 CHARACTER::GetQuestFlag（其内部 GetPC 会切换任务上下文），不设置任务状态、不创建物品、不传送、不消耗门票。

龙穴按任务原规则显示共享场次：加入窗口为闭区间，申请新场次要求冷却严格小于零，因此到期秒仍在等待。个人周任务冷却从接取任务开始，与共享龙穴计时分别显示；当前收集阶段从原任务状态读取。界面提供入口说明和登录期间的单个到期提醒，提醒必须经过一次新的服务端快照确认；场次延期不会按旧到期时间误报。休眠或时间跳变使旧快照失效，重连/换角色销毁提醒。

活动列表按 UTC 展示排期、频道/阵营范围、当前状态及开始/结束提醒。只适配当前服已有的月光宝箱和圣诞袜掉落；同一份 port_events.tsv 同时驱动查询和原始 CreateQuestDropItem 分支的启用条件。原概率、怪物等级/种类限制、随机数调用、生成物品流程沿用原实现；重叠排期取布尔并集，不叠加概率。原管理员 event flags 仍可独立启用这些活动，日历展示的是计划时段。

调度按服务器当前 Unix 时间计算 [start,end)，没有开服补发/定时发奖，也不向 DB 写全局开关。服务重启后从文件恢复，所有共享 locale 的 core 在五秒内发现原子替换的新配置。删除/非法配置使计划效果关闭，并返回 schedule_unavailable；不伪造空日历。有效空文件表示明确无计划活动。

配置

服务端示例：metin2-server/tools/calendar/port_events.tsv.example。复制到 LocaleService_GetBasePath() / port_events.tsv；不是客户端资源或 quest/object。部署时必须让所有 core 读取同一个文件，先验证再用原子 rename 发布。未部署任何生产排期，本批不会自动开启活动。

格式与运维/验证说明见 metin2-server/docs/FEATURE-DUNGEON-CALENDAR.md。协议在既有 MTF1 上增量扩展 capability 16/32，旧服降级为未启用；未知能力位忽略，未知协议版本拒绝。所有页面带 request ID 和服务器时间；缺行/重复行/非法时间和范围不提交界面。

证据与边界

• tests/wiki/test_service.py：新增副本完整性、日历范围和未来能力位兼容测试；与目录/提醒测试合计 22 项通过。
• tests/wiki/test_timers.py：验证副本原始到期边界、延期、休眠后查询、日历频道范围、一次提醒及配置删除取消。
• 服务端 tests/features/test_calendar.py：编译实际解析/调度/查询主体，验证区间边界、频道/阵营、重叠不叠加、重启、同秒同大小文件原子替换、非法配置关闭；查询与掉落开关一致。
• 服务端 tests/features/dungeon_lua_probe.cpp：在 203 独立进程中使用实际 Lua 5.0.3 库和现网编译 quest state 文件验证 settings、动态门票、共享/个人时间、状态、上下文及栈保持；不连接游戏/数据库，不修改运行状态。
• build/wiki-source/dungeon-calendar-integration.log：隔离加密登录、查询、分页/提醒开关，以及原有触控背包、装备、商店、仓库、战斗回归通过。
• macOS dungeon-calendar-mac-build.log、Android dungeon-calendar-android-build.log 构建通过；Android 未进行真机验收。
• dungeon-info.png、event-calendar.png（另有短屏 event-calendar-small.png）为实际原生宿主渲染，使用隔离协议 fixture，不代表生产活动安排。
• FreeBSD 输出仅在 /root/metin2-features-dev/bin/game，没有替换 /usr/metin2 程序或重启服务。

没有承诺所有副本已迁移：其他副本、NPC 导航/传送、通关次数、最快时间与排名仍待接入。龙穴入口最终资格和门票检查仍由原 NPC 任务负责，查询就绪不等于保证入场。自动洗练/属性锁定、战令任务及领奖持久化、百科模型预览、批量开箱仍未实现，不能标记整体迁移完成。