metin2-client/docs/MAC-UI-CLARITY.md

macOS UI 清晰度

原生客户端按 macOS 窗口的逻辑尺寸布局，在 Retina 的物理像素尺寸上绘制 UI。 本轮保持 40250 的窗口尺寸、格子、图标位置和点击逻辑，通过更细的纹理和字形改善显示。

• hd_ui.pak 提供 2× UI 图片；原版 EPK 继续负责逻辑尺寸和 UV。高清纹理不改变道具数据。
• 加载顺序为显式 MT_HD_UI_PAK、应用资源目录、客户端工作目录。缺失或无效时记录一次日志并使用原图。
• mac 打包必须包含通过索引/PNG 检查的高清包，同时包含 SDL3、Vulkan loader 和 MoltenVK。
• 轴对齐图片的起点对齐物理像素；宽高、UV 和旋转保持不变。一比一显示使用 point 采样，其余缩放保留 linear。
• 字体按物理像素/逻辑像素比向上取整生成 1–4× 字形。Retina 字形保留 8 位覆盖率，1× 路径保持原版阈值。
• 窗口尺寸、显示器和显示倍率变化时，在脚本帧之间重建字体页。字符信息节点地址和原字号/字距保留。

构建高清包使用现有 Real-ESRGAN 管线：先放大 4×，再缩到 2×，恢复原图低频残差与纹理， 对透明边缘填色和可平铺背景补边。模型不会恢复原图中不存在的真实细节，因此保留原版素材开关便于对照。 工具来源：Real-ESRGAN 官方发布。

python3 scripts/build_hd_ui.py --esrgan build/tools/realesrgan \
  --client build/zh-locale/Client --locale zh --out build/hd-ui/hd_ui.pak
python3 scripts/verify_hd_ui.py build/hd-ui/hd_ui.pak
cmake --build build/release --target mt_native_render -j8
scripts/package_mac_app.sh build/release build/zh-locale/Client dist/Metin2.app build/hd-ui/hd_ui.pak

临时关闭高清图片：MT_HD_UI=0 dist/Metin2.app/Contents/MacOS/Metin2。 字体强制倍率：MT_FONT_OVERSAMPLE=1（用于原版对照）或 2 等；默认自动适应显示器。 启动日志应显示 [hd_ui] loaded ... textures 和 UI glyph raster: 2x ...（普通 Retina 屏）。

验证：host.ui_quality 检查物理像素对齐、采样选择和无效高清索引回退；port.text 在 1→2→3→1→2× 中检查字符指针、字号、字距、页面尺寸和 8 位透明度。旧字体实现不能通过这些新增检查。 实际应用用本地测试服务器打开背包、填入武器/防具/消耗品并截取原尺寸画面，检查背包与工具栏； 截图仅用于清晰度验收，不是 Windows 像素完全等价声明。应用为本地 ad-hoc 签名构建。