蔚蓝点击特效 HarryHello/ba-click-mac

BA Click for MacOS

碧蓝档案点击特效 + 鼠标光迹的原生 macOS 版本，用 Swift + Metal 实现，特效来自 ba-click-fx 网页版。

A native macOS version of the Blue Archive click effect + cursor trail, written in Swift + Metal, based on the ba-click-fx web effect.

它为所有已连接屏幕创建透明、无边框、可点击穿透的覆盖层。全局鼠标事件通过 AppKit 的全局事件监听器收集，按光标所在显示器分发给对应覆盖层；Metal 用从 ba-click-fx 解包出的原始游戏贴图（Circle_01 / Ring3 / Triangle_02_1 / Trail_03）渲染粒子与光迹，并移植了 MXFinalBloom 辉光。

It creates transparent, borderless, click-through overlays covering all attached screens. Global mouse events are observed with AppKit's global event monitor and routed to the overlay for the display under the cursor; Metal renders particles/trail with the original game textures (Circle_01 / Ring3 / Triangle_02_1 / Trail_03) extracted from ba-click-fx, plus a ported MXFinalBloom glow.

Features / 功能

| | English | 中文 |
| Overlay | Transparent click-through overlays on all attached screens; never steals focus | 所有屏幕透明可穿透覆盖层；从不抢占焦点 |
| Click effect | Center disk → two arcs (弧光) from random sides spread/converge → disk fades → arcs shrink; flying shards | 中心圆盘 → 随机两侧弧光相向扩散/汇聚 → 圆盘消失 → 弧光收缩；飞散碎片 |
| Trail | Cursor trail with width taper (tail thins, color stays constant) | 鼠标光迹，尾部收细（颜色不变） |
| Glow | Ported original MXFinalBloom (multi-level pyramid, prefilter → downsample → upsample → additive) | 移植原版 MXFinalBloom（多级金字塔：预过滤 → 降采样 → 升采样 → 叠加） |
| Fullscreen | NSPanel (fullScreenAuxiliary) is carried into fullscreen apps' Spaces automatically — works over QQ / Chrome fullscreen video | NSPanel（fullScreenAuxiliary）自动进入全屏应用的 Space —— QQ / Chrome 全屏视频下均正常 |
| Live tuning | The panel applies changes live (persisted to settings.json); the file itself is read at launch, partial files allowed | 面板实时调参（防抖写入 settings.json）；配置文件本身在启动时读取，允许只写要改的键 |
| Power saving | Stops rendering when idle; no GPU work behind hidden fullscreen (showInFullscreen=false) | 闲置时停止渲染；隐藏全屏时不产生 GPU 开销（showInFullscreen=false） |
| Management panel | Apple-native panel via the menu bar icon: effect on/off, launch at login, trail mode/thickness/glow, click size/brightness/opacity, refresh rate, right/middle-click toggles, power-saver toggle, force topmost, click statistics, auto update check, update status with the running version, reset to defaults, language selector | 菜单栏图标打开的 Apple 原生管理面板：效果开关、开机自启、仅接通电源时启用、强制置顶、尾迹模式/粗细/辉光、点击大小/亮度/透明度、刷新率、右键/中键开关、点击统计、自动检测更新、检查更新 + GitHub 仓库（状态栏常显当前版本号）、恢复默认设置、语言选择 |
| i18n | Chinese/English/Japanese UI with a language selector in the panel (auto-detect by default) | 中/英/日三语界面，面板内置语言选择器（默认跟随系统） |
| No Dock icon | Runs as an .accessory app (menu bar only), so the Dock stays clean | .accessory 模式运行（仅菜单栏），Dock 干净 |

Status / 状态

- ✅ Transparent click-through overlay

透明可穿透覆盖层

- ✅ Global click + mouse-move tracking

全局点击 + 鼠标移动追踪
- ✅ 点击特效：中心圆盘、旋转溶解弧光、飞散碎片

- ✅ 鼠标光迹，带收细效果

- ✅ 原始游戏贴图 + Unity 粒子曲线

- ✅ 多级 MXFinalBloom 辉光（HDR 场景 → 金字塔 → 叠加辉光）

- ✅ 全屏应用之上正常显示（每屏常驻 NSPanel）

- ✅ 手动垂直同步渲染循环，24–240 fps（修复 display link 停滞）

- ✅ 闲置省电（屏幕上没内容就停止渲染；没有活动内容的显示器整条渲染管线跳过）

- ✅ 单元测试（./test.sh）+ CI（GitHub Actions）

- ✅ 菜单栏图标 + 管理面板（无 Dock 图标）

- ✅ 右键 + 中键点击效果（可独立开关）

- ✅ 检查更新 + 自动更新（失败时回退到 GitHub Releases）

- ✅ 可选自动检测更新（启动时 + 打开面板时，节流且静默）

- ✅ 省电模式：仅在接通电源时运行特效

- ✅ 强制置顶（可选，私有 SkyLight API）：显示在 Dock、菜单、启动器甚至锁屏之上

- ✅ 开机自启

- ✅ 多显示器覆盖层，每个接入的显示器一个

应用图标：用新版 Icon Composer（macOS 26+ / Xcode 26）制作，源文件为 icons/icon.icon（icon.json 清单 + 分层 Assets/*.svg）。该格式是满幅的——macOS 会在 Dock/Launchpad 自动套上自家的 squircle mask（连续曲线，不是普通圆角，且随系统版本不同），所以不要在素材里自己烘焙圆角或边距。在 Icon Composer 里改完用 ./tools/build-icon.sh 重新生成（内部调用自带的 ictool CLI，产出 Resources/icon.png + Resources/AppIcon.icns）。需要装有 /Applications/Icon Composer.app。

菜单栏图标：以 22 pt 渲染，源文件为 icons/bar_icon.svg。改完 SVG 后用 ./tools/svg2png.sh icons/bar_icon.svg Resources/bar_icon_22.png 22 和 ./tools/svg2png.sh icons/bar_icon.svg Resources/bar_icon_44.png 44 重新生成。

菜单栏图标：以 22pt 渲染，源文件为 icons/bar_icon.svg。改完 SVG 后用上面的命令重新生成 PNG。

Install / 安装

Homebrew（推荐）——用一条命令从我们的 tap 安装和升级：

brew install --cask harryhello/tap/ba-click
升级走 brew upgrade --cask ba-click；应用内更新检测到 Homebrew 安装（Caskroom 路径）时会提示改用 brew 升级，而不是就地替换应用包。

Homebrew（推荐）——一条命令从我们的 tap 安装与升级：

brew install --cask harryhello/tap/ba-click

升级走 brew upgrade --cask ba-click；应用内更新检测到 Homebrew 安装（Caskroom 路径）时会提示改用 brew 升级，而不是就地替换应用包。

手动安装——从 GitHub Releases 下载对应架构的 DMG（arm64 = Apple Silicon，x64 = Intel），打开后把 BA Click 拖进 Applications。构建为自签名、未公证：首次启动请右键 → 打开（macOS 15+ 需在 系统设置 → 隐私与安全性 中点仍要打开）。

环境要求

- macOS 14+（./build.sh 构建；macOS 14 起启用 vsync 渲染驱动，macOS 26+ 启用原生液态玻璃面板）

- x64（Intel）DMG 依赖 macOS 自带的 Rosetta 2：macOS 27 是最后支持 Intel 应用的大版本，macOS 28 起 x64 构建将无法运行。Apple Silicon 用户请使用 arm64 DMG。

- Xcode Command Line Tools 或 Xcode（Swift 工具链）

- 需要 Metal 支持的 Mac（Apple Silicon 或大部分 Intel Mac）

- build.sh 是唯一构建入口（二进制，或 --app 构建可双击 .app 包）；无 SPM Package.swift——test.sh 直接构建单元测试。

构建、运行与测试

./build.sh # compile → .build/ba-click-mac
./run.sh # build (if needed) then run
./test.sh # unit tests: BAEval / ParticleSystem / FXSettings / UpdateManager

或构建可双击的 .app 包:

./build-app.sh # == ./build.sh --app → build/BaClickMac.app
open build/BaClickMac.app

应用以 .accessory 模式运行（无 Dock 图标、无菜单栏），只有菜单栏图标。点击图标弹出菜单：启用/停用特效（快捷开关）、打开管理面板与退出 BA Click。也可用面板里的退出 BA Click 按钮或 pkill BaClickMac 退出。

单独测试点击特效

bash
BA_CLICK_LOOP=1 ./run.sh # auto-clicks screen center every 0.9 s

环境变量

| 变量 | 作用 | 说明 |
| BA_CLICK_LOOP=1 | Auto-click at screen center every 0.9 s (isolated click-effect testing) | 每 0.9 秒在屏幕中心自动点击（单独测试点击特效） |
| BA_SHOW_HUD=1 | Show the debug HUD (render rates, skip counters, degraded flags, drawAge) in the top-left corner | 在左上角显示调试 HUD（渲染速率、跳过计数、降级标志、drawAge） |
| BA_DISABLE_BLOOM=1 | Disable bloom entirely (core effect only) | 完全关闭辉光（只画核心特效） |
| BA_BLOOM_DEBUG_VIEW=1 | Show only the bloom pyramid (no core) — for verifying the glow itself | 只显示辉光金字塔（无核心）—— 用于验证辉光本身 |

settings.json（实时调参）

应用会在启动时读取 settings.json，查找顺序是当前工作目录、可执行文件所在目录、~/.ba-click-mac-settings.json，取第一个存在的。该文件可选：下表默认值就是调好的「最佳」参数，不提供文件也能直接跑——而管理面板才是实时调参的入口：改动即时生效，并（防抖）写回此文件。完整模板见 settings.example.json。

| 键 | 默认值 | 含义 |
| diskScale | 0.8 | 中心圆盘尺寸倍率 |
| ringScale | 0.8 | 弧光半径倍率 |
| shardScale | 0.8 | 碎片大小与速度倍率 |
| trailScale | 2.2 | 光迹宽度倍率 |
| showInFullscreen | true | 在全屏应用上显示覆盖层；false = 隐藏并停止渲染 |
| clickBloomStrength | 0.1 | 点击辉光源能量 |
| trailBloomStrength | 3.5 | 光迹辉光源能量 |
| bloomStrength | 1.7 | MXFinalBloom 曝光（合成时 2^(strength/10)-1） |
| bloomLevels | 16 | 金字塔最大层数（实际层数由扩散公式决定） |
| bloomDiffusion | 7.0 | MXFinalBloom 扩散度——决定迭代次数与采样尺度 |
| bloomThreshold | 1.0 | 辉光预过滤亮度阈值（伽马空间） |
| bloomFalloff | 0.35 | 有理式衰减拐点 a = lum/(lum+k) |
| bloomBoost | 1.2 | 辉光叠加额外亮度 |
| enabled | true | 效果总开关 |
| trailAlwaysVisible | true | 尾迹始终显示；false = 仅按住任意鼠标键拖动时 |
| rightClickEnabled | true | 右键点击触发效果 |
| middleClickEnabled | true | 中键点击触发效果 |
| clickBrightness | 1.0 | 点击效果亮度 |
| clickDiskOpacity | 1.0 | 点击圆盘不透明度（越高越实） |
| triangleOpacity | 1.0 | 三角粒子不透明度（越高越实） |
| refreshRate | 60 | 渲染刷新率（30/60/120/240） |

开机自启不保存在 settings.json 里——它是系统状态（SMAppService / LaunchAgent），由面板的开机自启开关控制。

解析规则：settings.json 可以只写你要改的键——缺失的键沿用默认值。未知键会在 stderr 打印告警（忽略）；JSON 非法会打印告警并回退默认值。这是刻意设计：部分修改不会悄悄丢掉其它设置。

settings.json 已被 git 忽略（个人调参留在本地）；如需提交参数，请改 settings.example.json。

新增一个设置项

每个运行时设置都要动同一批地方——记得保持同步：

1. FXSettings（Sources/BaClickMac/FXSettings.swift）：加属性、加 defaultXxx 常量，在 init() 和 init(from:) 里接上。CodingKeys 是 CaseIterable，所以「已知键」告警列表会自动同步——不用手动改列表。
2. 面板控件（Sources/BaClickMac/SettingsPanel.swift）：用 store.binding(\\.field) 绑定（统一尺寸滑块则用 clickScaleBinding()）。
3. 应用它：渲染器读取 settings.field（由 Renderer.applySettings 同步）；面板开关逻辑（比如拖尾模式）放在 AppDelegate。
4. L10n（Sources/BaClickMac/L10n.swift）：如果标签面向用户，加一条 "key": (zh, en)，再到 ja 表里补上日文翻译——缺键会让完整性测试失败。
5. 文档：settings.example.json + 本 README 的表格。
6. 测试：Tests/main.swift——断言新默认值 +（如果相关）持久化往返。

工作原理

- 每屏常驻 NSPanel——每个已连接显示器都有一个无边框、非激活覆盖层，level = .floating、collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary, .ignoresCycle]、ignoresMouseEvents = true。每屏独立面板可避开 macOS/Spaces 下单个超大透明窗口无法在所有显示器渲染的边缘情况。
- 手动 vsync 同步渲染循环——MTKView 内部 display link 在 Space/全屏切换后会随机停滞（表现为特效「时有时无」），所以我们保持 isPaused = true，用自建 CADisplayLink（vsync 同步）驱动 MTKView.draw()。尾迹每帧直接采样鼠标实时位置，即使系统合并了 mouse-moved 事件也保持顺滑。beginActivity(.userInitiated) 防止 App Nap 节流后台应用，看门狗会在 tick 循环沉默时重建它。

- 闲置省电——屏幕上没有内容时渲染循环自动停止；点击 / 移动鼠标 / 自动点击循环会唤醒它。showInFullscreen=false 时，全屏应用之上会隐藏覆盖层并完全停止渲染。

- 事件——NSEvent.addGlobalMonitorForEvents 全局监听点击/移动。应用绝不能变成前台，否则全局监听会收不到事件（我们只用 orderFrontRegardless()，绝不 activate）。

- 渲染——离屏 HDR 场景（rgba16Float）→ MXFinalBloom 金字塔（预过滤 → 降采样 → 升采样）→ 在锐利核心之上做叠加。屏幕无内容时完全跳过辉光。

- 管理面板——SwiftUI 面板放在带标题栏、不激活应用的 NSPanel 里，主体是原生 Liquid Glass（NSGlassEffectView，macOS 26+；通过 NSClassFromString 解析，代码仍能对旧 SDK 编译）。旧系统上回退到经典 NSVisualEffectView（.menu 材质）玻璃。titlebarAppearsTransparent + fullSizeContentView 保留原生红绿灯按钮和标题栏拖拽，同时窗口保持透明，让玻璃透出来。它能为控件成为 key window，但绝不激活应用，所以你调参时全局鼠标监听仍在给覆盖层喂事件。它能为控件成为 key window，但绝不激活应用，所以你调参时全局鼠标监听仍在给覆盖层喂事件。点击菜单栏图标会弹出菜单（快捷启停特效 / 打开管理面板 / 退出 BA Click）。所有改动立即作用于渲染器，并（防抖后）持久化到 settings.json。
管理面板——SwiftUI 面板，放在带标题栏、非激活 NSPanel 里，主体为原生液态玻璃（NSGlassEffectView，macOS 26+；用 NSClassFromString 运行时查找，旧 SDK 也能编译）。老系统自动回退经典 NSVisualEffectView（.menu 材质）玻璃。titlebarAppearsTransparent + fullSizeContentView 保留原生红绿灯与标题栏拖动，同时窗口透明让玻璃透出。控件可用但不激活应用，所以调参时全局鼠标监听仍在工作。点击菜单栏图标弹出菜单（快捷启停特效 / 打开管理面板 / 退出 BA Click）。所有改动即时生效并（防抖）持久化到 settings.json。

- Trail mode — the "always show trail" toggle (始终显示尾迹) on: trail follows any mouse move. Off: trail only appears while a mouse button is held and dragging (left / right / middle all work).

尾迹模式——开启"始终显示尾迹"：尾迹跟随任意鼠标移动；关闭：仅在按住任意鼠标键并拖动时显示尾迹（左键 / 右键 / 中键均可）。
- Mouse buttons / 鼠标按键 — left, right and middle clicks all spawn the click effect; right/middle are independently toggleable in the panel (rightClickEnabled / middleClickEnabled).

鼠标按键——左键、右键、中键点击都会触发点击特效；右键 / 中键可在面板中独立开关（rightClickEnabled / middleClickEnabled）。

- Updates / 更新 — panel's 检查更新 (Check for Updates) queries the GitHub latest release API and compares versions; 自动检测更新 (Check Automatically) (on by default) checks once at launch (3s in) and each time the panel opens, throttled to once per 60s and silent on failure — the manual button always checks for real. The status line always shows the running version (e.g. v1.0.0) when idle, then "up to date" / "update available" after a check. 立即更新 (Update Now) downloads the DMG for the running architecture, verifies it is signed with the SAME certificate as the running app (designated-requirement match — a tampered proxy-served download is refused), mounts it, atomically replaces the app bundle via a detached helper (~/Library/Logs/BA Click/update.log, rollback on failure) and relaunches. When auto-update isn't possible (raw binary / unwritable location / failure) it opens the GitHub Releases page; Homebrew installs (Caskroom path) get a hint to run brew upgrade --cask ba-click instead. The GitHub 仓库 (GitHub Repo) button opens the repo home.

更新——面板检查更新查询 GitHub 最新 release 并与当前版本对比；自动检测更新（默认开）在启动 3 秒后和每次打开面板时各检查一次，60 秒节流、失败静默——手动点按钮则始终真实检查。状态栏空闲时常显当前版本号（如 v1.0.0），检查后显示 v1.0.0 已是最新版本 / 发现新版本 vX.Y.Z。立即更新下载对应架构 DMG，先校验其签名与当前应用是同一张证书（设计需求匹配，代理投递的篡改包会被拒绝）→ 挂载 → 通过分离助手脚本原子替换应用包（日志在 ~/Library/Logs/BA Click/update.log，失败自动回滚）→ 自动重启。无法自动更新（裸二进制 / 目录不可写 / 失败）时跳转 GitHub Releases 页面；Homebrew 安装（Caskroom 路径）则提示改用 brew upgrade --cask ba-click；GitHub 仓库按钮打开仓库主页。

- Battery saver / 仅接通电源时启用 — when the toggle is on, all effects pause on battery power and resume the moment AC power returns (IOKit power-source notification). Desktops without a battery count as always plugged in, so the toggle is a no-op there.

省电——开关打开后，使用电池时自动暂停全部特效，插回电源立即恢复（IOKit 电源源通知）。没有电池的台式机视为始终接通电源，此开关无副作用。
- GitHub 代理——直连 api.github.com / github.com 被墙或失败时，检查更新与 DMG 下载会按序回退到配置的代理（AppInfo.swift 里的 GitHubProxy）。实测可用：gh-proxy.org、gh-proxy.com（API + 下载）、ghproxy.net、ghfast.top（仅下载）。

GitHub 代理——直连 api.github.com / github.com 被墙或失败时，检查更新与 DMG 下载会按序回退到配置的代理（AppInfo.swift 里的 GitHubProxy）。实测可用：gh-proxy.org、gh-proxy.com（API + 下载）、ghproxy.net、ghfast.top（仅下载）。

- 开机自启——捆绑版通过 SMAppService 注册，条目出现在 系统设置 → 通用 → 登录项，注册绝不当场启动；裸二进制（run.sh）无法在那里自注册，回退为用户 LaunchAgent plist，以「禁用 → 注册 → 启用」方式休眠注册。旧版（≤0.2.1）的 plist 注册在下次切换开关时自动迁移。另有 flock 单实例锁（~/.ba-click-mac.lock），双开时第二个实例立即退出。

开机自启——捆绑版通过 SMAppService 注册，条目出现在 系统设置 → 通用 → 登录项，注册绝不当场启动；裸二进制（run.sh）无法在那里自注册，回退为用户 LaunchAgent plist，以「禁用 → 注册 → 启用」方式休眠注册。旧版（≤0.2.1）的 plist 注册在下次切换开关时自动迁移。另有 flock 单实例锁（~/.ba-click-mac.lock），双开时第二个实例立即退出。

- 强制置顶——可选功能（私有 API）：覆盖层窗口加入专属 SkyLight Space，钉在锁屏层级之上，特效显示在菜单、Dock、启动器乃至锁屏之上。关闭时重建覆盖层窗口（否则窗口无法离开该 Space）；所有私有调用均有守卫，失败时回退到普通层级。

强制置顶——可选功能（私有 API）：覆盖层窗口加入专属 SkyLight Space，钉在锁屏层级之上，特效显示在菜单、Dock、启动器乃至锁屏之上。关闭时重建覆盖层窗口（否则窗口无法离开该 Space）；所有私有调用均有守卫，失败时回退到普通层级。

- GPU 压力自适应——采样永远不被饿死：帧完成得慢时（其他应用抢占 GPU），绘制节拍器每隔一次 DRAW 跳过一次，上一帧仍在执行时跳帧而非阻塞等待，压力下只有辉光降分辨率（0.5x → 0.25x 原生），核心永远渲染得锐利。压力信号与状态可在 HUD 中查看。

GPU 压力自适应——采样永远不被饿死：帧完成得慢时（其他应用抢占 GPU），绘制节拍器每隔一次 DRAW 跳过一次，上一帧仍在执行时跳帧而非阻塞等待，压力下只有辉光降分辨率（0.5x → 0.25x 原生），核心永远渲染得锐利。压力信号与状态可在 HUD 中查看。

工程结构

Sources/BaClickMac/
main.swift App entry, NSApplication + delegate
AppDelegate.swift Per-display NSPanel overlays, vsync render loop,
mouse-event routing, fullscreen handling, watchdog, HUD
TransparentMTKView.swift Non-opaque MTKView
MouseMonitor.swift Global mouse event observation (raw global points)
ScreenGeometry.swift Global→overlay coordinate conversion + display routing
ParticleSystem.swift Click particles + trail simulation
Renderer.swift Metal pipelines, geometry building, bloom pyramid
Shaders.swift Metal Shader Language source (runtime compiled)
FXSettings.swift 加载 settings.json / 默认值（宽松解码） PowerMonitor.swift 检测 AC/电池 + 电源状态通知 SingleInstance.swift 基于 flock 的单实例保护 DrawPacer.swift 自适应绘制节流（GPU 争用 → 跳过绘制） SkyLightSpace.swift 私有框架互操作，用于强制置顶模式 BAEffectData.swift Unity 关键帧 / 游戏内提取的数值 DebugLog.swift stderr 日志 + bail() 辅助函数 ResourceLocator.swift 共享的打包资源查找 SettingsStore.swift ObservableObject 设置存储 + 开机自启 SettingsPanel.swift SwiftUI 管理面板 + 不抢焦点的 NSPanel UpdateManager.swift 检查 GitHub 更新 + 自更新（辅助脚本） AppInfo.swift 应用版本 + GitHub 链接 L10n.swift 中/英/日字符串 + 语言覆盖 Resources/ AppIcon.icns macOS 应用图标（供 .app 包使用） icon.png 应用图标位图（裸二进制文件的 Dock 图标） bar_icon_22/44.png 菜单栏图标（1x / 2x 模板） circle/ring/trail/triangle 游戏内提取的特效贴图 dmg-background.jpg DMG 安装器背景（已生成，已提交） icons/ icon.icon / bar_icon.svg 图标源文件（Icon Composer 包 / 菜单栏 SVG） tools/ svg2png.sh / svg2png.swift SVG → PNG 转换器（重新生成菜单栏图标） build-icon.sh 从 icons/icon.icon 重新生成 icon.png + AppIcon.icns make-dmg-background.sh 重新生成 DMG 背景（取自 ../room_night.png） Tests/ main.swift 单元测试：BAEval / ParticleSystem / FXSettings / L10n / ScreenGeometry / DrawPacer / UpdateManager / SingleInstance .github/workflows/build.yml CI：在 macOS 上构建 + 跑单元测试 build.sh 构建二进制文件，--app 构建 .app 包，--release 构建 DMG build-app.sh ./build.sh --app 的包装脚本 test.sh 构建并运行单元测试 settings.example.json 可选运行时调优的模板

Permissions / 权限

通过 NSEvent.addGlobalMonitorForEvents 做全局鼠标监听，在 macOS 上一般无需额外权限。（未来若改用 CGEventTap 则需要「辅助功能」权限。）

通过 NSEvent.addGlobalMonitorForEvents 的全局鼠标监听在 macOS 上一般无需额外权限。（未来若改用 CGEventTap 则需要"辅助功能"权限。）

Troubleshooting / 排障

- 特效随机出现：这曾是 MTKView display link 在 Space/全屏切换后停滞所致——现已通过手动 vsync 渲染循环修复。若再次看起来「死了」，看门狗会自行重建沉默的 tick 循环；HUD 的 tick/s / drawAge 能显示它是否恢复。

特效随机消失或时有时无：这曾是 MTKView display link 在 Space/全屏切换后停滞所致——现已通过手动 vsync 渲染循环修复。若再次看起来"死了"，看门狗会重建沉默的 tick 循环；HUD 的 tick/s 与 drawAge 能显示它是否恢复。
- 启动即退出并打印 FATAL:：Metal 设备 / Shader 编译 / 纹理加载失败——请从终端运行查看具体原因（Resources/ 下资源必须存在且尺寸匹配）。

- 点击完全无反应：请确认应用不是前台（绝不 activate）；全局鼠标监听只在其他应用为前台时才能收到事件。

- HUD 不显示：默认关闭——用 BA_SHOW_HUD=1 运行。

- 设置没生效：配置文件在启动时读取——应用运行中改文件需重启生效；实时调参请用面板。留意 stderr 的 [settings] WARNING:（JSON 非法 → 回退默认值；未知键 → 忽略）。

备注

- 覆盖层从不抢占焦点；点击穿透到下层应用。

- 坐标基于 AppKit 屏幕点，按屏幕高度缩放（对齐网页版的 1080p 参考高度）。

- 原生从零实现；视觉参数移植自 ba-click-fx 网页项目解包出的 Unity 数据。