metin2-client/docs/AVA2-DISPLAY.md

AVA2 显示开关适配进度（v1）

2026-10-15。只改了 metin2-client，服务端不需要改动。参考了 AVA2 的 ENABLE_GRAPHIC_ON_OFF（InstanceBase.cpp 中 __CanRender 的 effect_level 0–4）和 HIDE_OBJECTS（background.SetVisiblePart）。

与 AVA2 的差异

项目	AVA2	本实现
特效等级	0–4，在渲染判断里跳过	相同的 5 档；在 CInstanceBase::Update 中对角色挂载的特效调用 Active/Deactive，不改渲染路径
摆摊、宠物、坐骑的显示范围	有	不移植：经典版没有离线摆摊和宠物
树木、云	background.SetVisiblePart	相同，使用原有接口
名字、伤害数字	原有选项	窗口内加了快捷开关，仍然写原来的 systemSetting，退出时由原配置保存

特效等级

等级	显示的特效
0 全部特效	全部
1 只看怪物特效	自己、怪物、灵石
2 只看玩家特效	自己、其他玩家
3 只看自己特效	只有自己
4 关闭全部特效	无，包括自己

客户端

• C++：
  • CEffectManager::ActiveEffectInstance。
  • CActorInstance::SetAttachingEffectShown：对已挂载的特效调用 Active/Deactive；关闭期间新挂载的特效也会立即 Deactive。使用 Deactive 而不是 Hide，避免和刺客隐身的 Show/Hide 冲突。
  • CPythonSystem::Get/SetEffectLevel，越界值按 0 处理；不写入 metin2.cfg。
  • systemSetting.SetEffectLevel/GetEffectLevel。
  • CInstanceBase::__UpdateEffectShown，每帧在 Update 开头按上表判断。
  • CMapOutdoor::RenderPCBlocker：离镜头近、挡住角色的树会作为遮挡物（PC blocker）单独绘制，不经过 RenderTree，所以原来关闭树木后这类树仍然显示。现在隐藏树木时跳过遮挡物中的树。AVA2 有同样的问题。
• 模块 mt_display（src/platform/ScriptLib/DisplayScript.inc），在 PythonBoot.cpp 中安装：
  • 入口是小地图旁“拾取”下方的“显示”按钮。
  • 窗口“显示设置”包含 5 个特效等级、显示树木、显示云、总是显示名字、显示伤害数字，【】 表示当前选中。
  • 设置保存在客户端目录的 mt_display.cfg，格式为“特效等级 树木 云”，默认 0 1 1，损坏时回到默认值。
  • 特效等级在启动时生效；树木和云在进入游戏（GameWindow.Open）时生效。

证据

• tests/wiki/test_display.py（CTest：port.display）共 3 项通过，覆盖：
  • 默认值、配置文件读写、损坏的配置；
  • 进入游戏时生效，窗口按钮、配置保存、名字和伤害开关；
  • 5 档和 C++ 规则一致。
• test_pickup.py（7 项）和 test_switchbot.py（6 项）仍然通过。
• 2026-10-15 联机测试（203 测试核心 channel5，macOS 原生客户端，账号 admin）：
  • 切到等级 4 并关闭树木后，配置为 4 0 1；恢复后为 0 1 1。
  • 截图确认窗口布局正常。
  • 用 /goto 646 798 走到离树约 7 米的位置截图对比：等级 4 时 GM 标志和武器光效消失；关闭树木后树消失（修复遮挡物问题之前，这棵树仍然显示）；恢复后都回来。

限制和未完成

• 只控制挂载在角色上的特效（装备光效、buff、种族特效）。单独播放的特效和飞行特效（技能弹道、命中特效）不受影响。
• macOS 桌面客户端没有中文字体，窗口文字显示为 ?（原版界面同样乱码）；Android 使用 CFF FreeType，不受影响。
• 树的影子烘焙在地形阴影图里，关闭树木后地面上仍有树影（与 AVA2 相同）。
• Android 真机测试未做。