QmClient v3.3

QmClient v3.3 · 正式版（Stable）

通道：正式发布 · 建议日常使用
Tag：v3.3
范围：v2.79.33..v3.3

---

1. 🎨 界面与视觉

1.1 名牌、文字与图标

• 扩展名字板文本效果范围，并加入名字特效渐变渲染。
• 重构铭牌文字渲染链路，加入 MSDF 字体支持、门控、回退诊断及设备重置恢复。
• 调整图标图集的字重与颜色。
• 统一图标字体回退与 MSDF 图标尺寸行为。
• 修复铭牌容器失效后的重建问题。
• 修复表情基线、字体度量及字重回写。
• 修复字体输入器索引越界、按键及粘贴绑定。
• 完善 CJK 字体与字体商店相关翻译。

1.2 卡片化 UI

• 全面推进设置页与功能页卡片化。
• 建立统一卡片 Frame、布局解析、排序模型及公共卡片 Deck。
• 新增全局卡片组件注册表，目前包含 69 个默认 Placement。
• 支持卡片折叠、拖拽排序及布局持久化。
• Tclient 卡片拖拽从 Ctrl+drag 调整为长按 0.3s，统一栖梦交互范式。
• 支持拖拽过程中实时让位，并采用连续环绕式布局。
• 持久化卡片排序至 qm_settings_card_order。
• 统一卡片背景、圆角、间距、字号、边框及动画。
• 修复卡片重排、动态高度、入场动画导致的重叠、闪烁及布局异常。
• 修复卡片跨列拖拽、排序迁移及默认页面归属。
• 修复卡片测量回调悬空引用。
• 修复动态卡片、下拉框及折叠交互回归。

1.3 滚动与弹窗

• 昵称区域改为卡片内部滚动。
• 统一设置页、功能页、列表及浏览器的滚动手感。
• 使用统一滚动条与缓动逻辑。
• 修复横向内容拖拽滚动轴向。
• 修复整页滚动、列表高度及滚动边界问题。
• 弹窗支持视口居中、缩放动画及卡片化下拉层。
• 下拉弹层支持锚点对齐、键盘选择及键盘焦点显示。
• 修复下拉框尺寸、字号、禁用状态及 Popup 几何同步问题。

1.4 计分板与顶部/底部 UI

• 计分板标题栏增加服务器人数。

• 支持 128 人服务器滚动模式及名字/战队过滤。

• 增加标题栏滚动模式开关。

• 计分板底部重构为整宽横栏：

  • 上方显示 SMTC 歌曲标题与艺术家；
  • 下方显示围观者列表；
  • 无人时不绘制且不占用高度；
  • 保留 qm_smtc_enable 配置。

• 删除旧计分板中的三个媒体控制按钮。

• 修复计分板锁鼠、上游同步及布局问题。

1.5 其他视觉体验

• 更新媒体岛布局及底部内容宽度计算。
• 重构灵动岛状态呈现及动画。
• 加入灵动岛弹簧动画。
• 新增全局 UI 缩放。
• 新增电影镜头。
• 新增截图水印。
• 支持禅模式恢复。
• 修复圆角渲染、取色器、输入光标、卡片闪烁及 macOS 图形回退问题。
• 修复 Linux 菜单主题加载失败导致背景变黑的问题。

---

2. ⚙️ 设置系统

2.1 设置架构

• 建立全新的设置页卡片化架构。
• 设置卡片迁移至：

src/game/client/QmUi/cards/

• 新增 QmCardCatalog。

• 设置卡片划分为：

  • Visual
  • Function
  • Hud
  • Skin

• 通过 QmCardRenderHook 连接菜单内容函数。

• menus_qmclient.cpp 简化为页面骨架及 RenderQm*Content 内容函数，不再直接承载卡片实现。

• 建立运行时主题链。

• 建立统一布局解析与唯一设置卡片 Frame。

• 支持设置卡片搜索定位。

• 建立统一卡片注册、搜索跳转、排序及迁移机制。

2.2 外观与皮肤

• 设置页皮肤队列支持：

  • 默认预设；
  • 服务器预设；
  • 保存；
  • 另存。

• 皮肤设置拆分为两张全局卡片：

  • Tee 外观
  • 皮肤切换动画

• Tee 外观卡片支持：

  • 本体/分身；
  • 他人描边；
  • 颜色；
  • 粗细；
  • 不透明度；
  • 循环色调；
  • 分身同步；
  • 表情阴影。

• 皮肤动画卡片支持：

  • 锤中偷皮；
  • 7 种动画；
  • 3 种范围；
  • 时长；
  • 4 种缓动；
  • 强度。

• 新增 stableId：

qm:skin_appearance

• 保留原动画卡 stableId、折叠 key 及用户布局兼容性。
• 修复皮肤列表刷新、皮肤搜索网格、收藏点击及双击应用。
• 修复皮肤 PNG 泄漏、皮肤度量及皮肤隔离问题。
• 删除内建皮肤被误认为下载皮肤导致无法加载的问题。
• 删除皮肤后保持相邻项目选中。

2.3 设置交互与布局

• 支持卡片折叠及标题操作。

• 支持全局卡片排序。

• 扩大全局卡片排序配置容量。

• 修复设置页：

  • 卡片闪烁；
  • 动态高度；
  • 列表高度；
  • 卡片间距；
  • 控制器内容重叠；
  • 输入框布局；
  • 下拉框布局；
  • 字体尺寸；
  • 滚动条；
  • 动画；
  • 响应式布局。

• 新增数值输入纯逻辑。

• 固化输入框布局 Helper。

• 支持搜索定位图形设置卡片。

• 修复延迟滑条释放提交。

• 修复设置卡片跨列拖拽。

• 修复配置迁移与排序迁移。

• 修复启动预热与公共控件回归。

• 修复设置页预热 sanitizer。

• 修复文本预热 sanitizer。

• 优化设置页文本缓存及稳定帧性能。

---

3. 🧩 客户端核心架构

3.1 调度与模块化

• 完成 Phase A 调度器 Service 化重构及验收。
• 新增 QmAnimationBackend，分离 UI 动画状态与提交逻辑。
• 清理死字段、死代码及旧模块。
• 移除栖梦侧栏残留的 NameplateText 死模块。
• 优化客户端启动、状态生命周期及模块初始化。

3.2 CModel 与布局系统

• CModel 增加 Tab 维度与 Page-aware 查询。

• 新增 stableId → index 的 O(1) 注册表。

• 建立全局卡片组件注册表。

• 建立栖梦旧 key → stableId 迁移映射。

• 建立栖梦布局适配层：

  • Parse；
  • Serialize；
  • Load；
  • Move。

• 修复适配层 Review 问题。

• 修复配置迁移、排序迁移及状态隔离问题。

3.3 输入与客户端状态

• 输入处理提前至网络泵之后。
• 修复输入与设置界面回归。
• 修复网络与客户端状态生命周期。
• 修复地图上传输入崩溃。
• 修复快速练习与翻译交互。
• 修复回放、皮肤及客户端状态回归。

---

4. 🎮 游戏功能

4.1 地图与服务器

• 地图上传卡片显示目标服务器。

• 地图选择弹窗支持递归搜索：

  • maps
  • downloadedmaps

• 搜索忽略英文大小写。

• 同名地图显示完整来源路径。

• 清空搜索关键字后恢复原浏览位置。

• 选择地图文件后不自动上传。

• 支持下载地图 Rank 1 回放。

• 新增地图难度筛选。

• 新增落水榜。

• 新增响应式地图历史工作区。

• 支持多地图标签。

• 修复地图图层数据长度校验。

• 修复地图编辑器无法加载地图。

• 修复多地图保存与设置状态隔离。

4.2 HUD 与游戏内提示

• 新增自定义 Bind 状态 HUD。
• 曾加入 DDRace HUD Pro 卡片，后续已回退移除自定义 Bind 状态列表。
• 新增水域卡锤高亮指示。
• 修复 HUD、表情及单图资源的空白回退。
• 修复旁观/死亡状态下练习与锁队图标缓存。
• 优化练习/锁队图标随行字号等比缩放。

4.3 表情与称号

• 新增匿名表情实时功能。

• 通过匿名 WebSocket 同步表情。

• 新增 shot_emote <ID> 控制台命令。

• shot_emote 支持：

  • 指定表情 ID；
  • 朝瞄准方向发射；
  • bind 绑定；
  • 与 emote 共用参数解析及发送路径。

• 新增称号系统。

• 新增五套独立形态拖尾。

• 重构弹射表情轮廓碰撞。

• 修复不同地址格式下匿名表情同步。

---

5. 💬 聊天与社交

• 扩展地图及 Tab 候选补全。
• 提取地图类别并优化候选项逻辑。
• 恢复斜杠指令用法提示。
• 新增聊天参数补全。
• 修复聊天合并及自动登录误判。
• 修复带引号 victim 参数校验。
• 修复传送点查找面板编译问题。
• 浏览器好友列表按数据版本重建。
• 修复好友进服默认文案 Localize 问题。
• 完善社区收藏、好友命令注册。
• 支持赞助作者横排及专属皮肤。

---

6. 🎵 媒体与音乐

6.1 歌词系统

• 重写歌词模块并完成翻译收口。

• 支持多音乐客户端歌词获取：

  • 汽水音乐；
  • 酷狗；
  • QQ 音乐。

• 新增 Lyrics 模块。

• 优化歌词同步缓存。

• 缓存歌词文本宽度。

• 默认关闭歌词并补齐相关卡片翻译。

6.2 网易云与媒体客户端

• 集成网易云音乐 Hook。
• 新增网易云注入自检脚本：

qmclient_scripts/support/check_netease_inject.py

• 脚本生成与文档一致的排查批处理。
• 优化媒体岛状态提示及动画。
• 修复无设备音频及样本状态。
• 兼容 WavPack 本地采样率转换。

---

7. 🌐 网络与实时链路

7.1 网络处理

• 客户端单次 Recv 最多处理 64 个数据报。
• 剩余数据延迟到下一帧处理。
• 避免控制包、STUN 包及无效包长期占用主线程。
• UDP Socket 不再主动丢弃未读数据。
• 修复网络与客户端状态生命周期。
• 修复 Chunk 解包边界检查。
• 完善网络攒批诊断。
• 增加实时链路诊断日志。
• 完善实时链路 USERS 全局广播标记及诊断注释。

7.2 服务器列表

• 将服务器列表 HTTP 解析抽离为纯函数。
• 解析过程不再访问客户端状态。
• 先构建完整结果，失败时保留调用方旧列表。
• 修复服务器列表滚动、列布局及伪性能优化回退。
• 使用服务器广播提供的队伍人数上限。

7.3 自有服务

• 自有服务迁移至 WebSocket。
• Anonymous Emote 改由匿名 WebSocket 同步。
• 修复 Axiom 自动登录及相关状态。

---

8. 🖥️ 图形与渲染

8.1 渲染后端

• 新增 QmVulkan 增强渲染合成。
• 优化屏幕外实体裁剪。
• Ghost 渲染增加屏外裁剪。
• 修复 OpenGL 后端客户端数组未关闭导致的 Intel 驱动越界读取崩溃。
• 保留 BACKEND_GL_MODERN_API 条件保护。
• 修复图形恢复及图形后端野指针。
• 修复 envelope 区域背景裁剪。
• 修复图形歌词及设置相关回归。

8.2 文本与资源

• 优化 MSDF 名牌字体渲染。
• 优化字形图集、轮廓及字形查找缓存。
• 优化字号查询。
• 优化文本布局。
• 优化逐词光标推进，减少重复解析。
• 增加空白材质回退语义。
• 优化资源预览及文本渲染。
• 修复资源预览 key 非有限尺寸问题。
• 修复图形回退及资源加载问题。

8.3 图形配置

• 补齐虚化及双色调 Alpha 配置。
• 修复旧用户图形模式偏好迁移。
• 修复图像设置行布局及翻译。
• 移除线性缩放与设置页字体独立缩放。
• 修复 tc_allow_any_resolution 配置链导致的启动断言崩溃。

---

9. 🚀 性能优化

9.1 UI 性能

• 设置页性能优化正式落地。
• 建立全局调度层。
• 稳定 UI 帧预算。
• 优化文本缓存。
• 修复文本缓存 key 不匹配导致的卡顿。
• 建立非卡片菜单性能证据。
• 减少动态卡片布局的首帧及稳定帧重复工作。
• DrawCall 合批。
• 优化卡片拖拽数据层。

9.2 渲染性能

• 分帧构建地图进度距离场。
• 缺口遥测每帧最多保留一个样本。
• 皮肤素材复用已有解码任务后台准备。
• 按 1ms 预算分步上传皮肤素材。
• 名牌文字、四边形旋转、圆角方向、轨迹带几何等加入缓存或预计算。
• 路线访问位图、快照实体加入缓存。
• Hook 提示线采用共享位置索引及相交/可见性预筛。
• collision_hitbox 改用预计算方向表与栈上定长缓冲，去除每帧 std::vector 分配。
• 优化文本与退出收尾时机。

9.3 帧率与主循环

• 撤回自动限帧及主循环等待机制。

• 恢复原有手动渲染限帧。

• 修复疑似锁刷新率导致的：

  • 操作延迟；
  • 拖影；
  • 卡顿。

• 恢复菜单空闲刷新率下限。

• 加载进度条恢复原版绘制。

---

10. 🌍 翻译与国际化

• 重建翻译维护脚本链。
• 补充多语言维护源。
• 完善多语言维护与通知栏文案。
• 完善 i18n 系统。
• 配置说明统一使用英文 source key。
• 统一翻译提取及门禁流程。
• 补齐服务端中文提示的 HUD 本地化。
• 补齐新增 QmClient 文案。
• 接入裸英文界面文案。
• 修复 TOML 回填块空行。
• 修复多语言工具链审查问题。
• 清零人工审查字符串 backlog。
• 完善简中术语维护检查。
• 审校 Dummy copy、Hook、team-lock 等术语。
• 修复百分比占位假阳性。
• 补齐中文缺译及非中文缺口。
• 补齐 tc_execute_on_join_delay 新文案。
• 补齐字体商店及 CJK 字体相关缺译。
• 统一 Unicode 与国家/地区代码处理。
• 翻译源重新提取、生成并校验 12 种语言产物。

---

11. 🧱 平台与构建

• 修复 macOS 26 构建及开发环境。
• 补齐 OpenGL ES 字符串常量声明。
• 兼容旧 Vulkan 头文件，并补定义 VK_API_VERSION_1_4。
• 补齐 Emscripten Fetch API HTTP 后端。
• 修复 CI 实现回归。
• 修复 CMake 链接签名问题。
• 新增 QmAnimationBackend 及 QmUi/cards/* 源文件。
• 新增对应测试源。
• 建立 MSL 构建与打包探针。
• 修复 clang-tidy 存量缺陷。
• 清理无效 sanitizer suppressions。
• 修复遗留编译、链接、格式及同步问题。

---

12. 🌐 官网与工程基础设施

• 官网 1.0.0 正式上线。
• 官网采用语义化静态页面。
• 样式与动画模块独立。
• 支持平台识别与下载入口。
• 增加原子切换部署脚本。
• 旧 /docs、/changelog 及子路径重定向至首页。
• 建立 Nightly 发布说明自动润色流程。
• 完善编辑器保存任务日志依赖。
• 清理批量合并、PreInput、Demo Seek 等同步残留。
• 清理命令列表重复声明。
• 清理网络头文件格式问题。
• 收口上游同步构建及格式问题。

---

13. 🔄 上游同步与兼容性

• 持续吸收上游客户端稳定性修复。
• 修复上游同步切片构建问题。
• 修复上游同步 include 适配。
• 修复上游同步审查问题。
• 修复上游合并后的滚动边界。
• 适配保留本地结构的上游残留。
• 修复兼容门碰撞调用签名。
• 修复 Snapshot Rust 同步构建。
• 修复网络、配置、图形、输入及客户端状态方面的上游兼容问题。

---

14. 🧹 删除与回退

删除

• 删除 qm_respawn_default_weapon 配置及 CControls 中对应逻辑。
• 删除 QmRespawnDefaultWantedWeapon。
• 删除 qm_present_align 配置。
• 删除 RenderGateRate 分支。
• 删除主循环渲染限速等待代码。
• 删除计分板旧媒体控制按钮。
• 删除栖梦侧栏残留 NameplateText 模块。
• 删除无引用内部函数。
• 删除冗余 constexpr inline。
• 删除设置页与卡片目录死代码及未使用捕获。

回退

• 回退旁观 Solo 硬隐藏。
• 回退加载进度条的新绘制方式。
• 移除 DDRace HUD Pro 自定义 Bind 状态列表。
• 移除旁观幽灵显示。
• 撤回自动限帧及主循环等待。
• 移除线性缩放与设置页字体独立缩放。
• 撤销旧 UI 顶栏圆角相关改动。

---

15. 🧪 测试与质量保障

• 增加卡片 Deck 测试。
• 增加设置页布局测试。
• 增加 Dropdown 测试。
• 增加预热/迁移门禁测试。
• 修复监控结构断言，使其覆盖新的 Frame Runtime。
• 增加图形后端、配置迁移、客户端状态等相关回归验证。
• 加强构建、格式、CI、sanitizer 与 clang-tidy 检查。
• 完善上游同步及本地适配层 Review。

---

16. 📦 版本汇总

QmClient v3.3 本轮主要完成以下方向：

1. UI 架构重构

   • 全局卡片目录；
   • 卡片注册表；
   • 卡片排序与持久化；
   • 统一布局、动画及滚动系统。

2. 设置系统重构

   • 设置页全面卡片化；
   • 外观、皮肤、HUD、功能模块重新组织；
   • 支持搜索、折叠、拖拽和迁移。

3. 客户端基础设施升级

   • Phase A 调度器 Service 化；
   • CModel Page-aware 查询；
   • stableId O(1) 注册表；
   • 布局适配层及迁移机制。

4. 渲染与性能优化

   • MSDF；
   • QmVulkan；
   • DrawCall 合批；
   • 文本/资源缓存；
   • 屏外裁剪；
   • 网络读取及主线程负载优化。

5. 媒体与社交能力扩展

   • 多音乐平台歌词；
   • 网易云 Hook；
   • Anonymous Emote；
   • shot_emote；
   • 称号及拖尾系统。

6. 地图与游戏功能扩展

   • 地图搜索；
   • Rank 1 回放；
   • 地图难度筛选；
   • 落水榜；
   • 多地图标签；
   • 水域卡锤提示。

7. 国际化与平台支持

   • 12 种语言产物；
   • CJK 字体；
   • macOS 26；
   • Vulkan/OpenGL/Emscripten 兼容。

8. 稳定性与工程质量

   • 大量上游同步；
   • 网络生命周期修复；
   • 图形后端崩溃修复；
   • CI、sanitizer、clang-tidy 与测试门禁完善。

完整变更范围： v2.79.33...v3.3。原始记录注明另有约 220 条未在摘要中列出，可通过 GitHub Compare / git log 查看完整历史。