HarryHello/ba-click-mac

适用于 MacOS 的 BA Click

碧蓝档案点击特效 + 鼠标光迹的原生 macOS 版本，使用 Swift + Metal 编写，基于 ba-click-fx 网页特效。

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

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

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

功能 / Features

| | 英文 | 中文 |
|---|---|---|
| 覆盖层 | 在所有已连接屏幕上创建透明可点击穿透覆盖层；从不抢占焦点 | 所有屏幕透明可穿透覆盖层；从不抢占焦点 |
| 点击特效 | 中心圆盘 → 随机两侧弧光相向扩散/汇聚 → 圆盘淡出 → 弧光收缩；飞散碎片 | 中心圆盘 → 随机两侧弧光相向扩散/汇聚 → 圆盘消失 → 弧光收缩；飞散碎片 |
| 光迹 | 鼠标光迹带宽度渐缩（尾部变细，颜色保持不变） | 鼠标光迹，尾部收细（颜色不变） |
| 辉光 | 移植原版 MXFinalBloom（多级金字塔：预过滤 → 降采样 → 升采样 → 叠加） | 移植原版 MXFinalBloom（多级金字塔：预过滤 → 降采样 → 升采样 → 叠加） |
| 全屏 | NSPanel（fullScreenAuxiliary）会自动进入全屏应用的 Space —— 可在 QQ / Chrome 全屏视频上正常工作 | NSPanel（fullScreenAuxiliary）自动进入全屏应用的 Space —— QQ / Chrome 全屏视频下均正常 |
| 实时调参 | 面板会实时应用更改（持久化到 settings.json）；文件本身在启动时读取，允许部分文件 | 面板实时调参（防抖写入 settings.json）；配置文件本身在启动时读取，允许只写要改的键 |
| 省电 | 空闲时停止渲染；隐藏全屏后方无 GPU 工作（showInFullscreen=false） | 闲置时停止渲染；隐藏全屏时不产生 GPU 开销（showInFullscreen=false） |
| 管理面板 | 通过菜单栏图标打开 Apple 原生面板：特效开关、开机自启、仅接通电源时启用、强制置顶、光迹模式/粗细/辉光、点击大小/亮度/透明度、刷新率、右键/中键开关、点击统计、自动检查更新、检查更新 + GitHub 仓库（状态栏常显当前版本号）、恢复默认设置、语言选择 | 菜单栏图标打开的 Apple 原生管理面板：效果开关、开机自启、仅接通电源时启用、强制置顶、尾迹模式/粗细/辉光、点击大小/亮度/透明度、刷新率、右键/中键开关、点击统计、自动检测更新、检查更新 + GitHub 仓库（状态栏常显当前版本号）、恢复默认设置、语言选择 |
| 国际化 | 中文/英文/日文 UI，面板内置语言选择器（默认自动检测） | 中/英/日三语界面，面板内置语言选择器（默认跟随系统） |
| 无 Dock 图标 | 以 .accessory 应用运行（仅菜单栏），因此 Dock 保持干净 | .accessory 模式运行（仅菜单栏），Dock 干净 |

状态 / Status

- ✅ 透明可点击穿透覆盖层

透明可穿透覆盖层

- ✅ 全局点击 + 鼠标移动追踪

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

- ✅ 带收细的鼠标光迹

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

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

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

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

- ✅ 闲置省电（无内容时停止渲染；无活动粒子的显示器整条渲染管线跳过）

- ✅ 单元测试 + CI

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

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

- ✅ 检查更新 + 自动更新（失败时跳转 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）。需要装有 /Applications/Icon Composer.app。

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

环境要求

- macOS 14+（./build.sh 构建；macOS 14 起启用 vsync 渲染驱动，macOS 26+ 启用原生液态玻璃面板）
- x64（Intel）DMG 仅在 macOS 仍自带 Rosetta 2 时可运行——macOS 27 是最后一个支持 Intel 应用的大版本，因此 x64 构建将随 macOS 28 一同终止支持。Apple Silicon 用户应使用 arm64 DMG。
-
x64（Intel）DMG 依赖 macOS 自带的 Rosetta 2：macOS 27 是最后支持 Intel 应用的大版本，macOS 28 起 x64 构建将无法运行。Apple Silicon 用户请使用 arm64 DMG。

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

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

- 支持 Metal 的 Mac（任意 Apple Silicon、大多数 Intel Mac）

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

- build.sh 是唯一的构建入口（二进制，或使用 --app 构建 .app 包）；没有 SPM 的 Package.swift——test.sh 直接构建单元测试。

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

构建、运行与测试 / 构建、运行与测试

./build.sh            # 编译 → .build/ba-click-mac
./run.sh              # 如需要则构建，然后运行
./test.sh             # 单元测试：BAEval / ParticleSystem / FXSettings / UpdateManager

或构建可双击的 .app 包 / 或构建可双击的 .app 包：

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

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

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

单独测试点击特效 / 单独测试点击特效

BA_CLICK_LOOP=1 ./run.sh   # 每 0.9 秒自动点击屏幕中心

环境变量 / 环境变量

| 变量 | 效果 | 说明 |
|---|---|---|
| BA_CLICK_LOOP=1 | 每 0.9 秒在屏幕中心自动点击（单独测试点击特效） | 每 0.9 秒在屏幕中心自动点击（单独测试点击特效） |
| BA_SHOW_HUD=1 | 在左上角显示调试 HUD（渲染速率、跳过计数、降级标志、drawAge） | 在左上角显示调试 HUD（渲染速率、跳过计数、降级标志、drawAge） |
| BA_DISABLE_BLOOM=1 | 完全禁用辉光（仅核心特效） | 完全关闭辉光（只画核心特效） |
| BA_BLOOM_DEBUG_VIEW=1 | 仅显示辉光金字塔（无核心）——用于验证辉光本身 | 只显示辉光金字塔（无核心）—— 用于验证辉光本身 |

settings.json（实时调参 / 实时调参）

应用在启动时从当前工作目录、可执行文件所在文件夹或 ~/.ba-click-mac-settings.json 读取 settings.json（以最先找到的为准）。该文件是可选的：以下默认值即为调优后的“最佳”值，因此你可以在没有任何设置文件的情况下运行——而管理面板就是实时调参界面：其更改会立即生效，并（防抖后）写回此文件。完整模板见 settings.example.json。
应用会从当前工作目录、可执行文件所在目录或 ~/.ba-click-mac-settings.json（按顺序取第一个存在的）在启动时读取 settings.json。该文件是可选的：下表默认值就是调好的“最佳”参数，不提供文件也能直接跑——而管理面板才是实时调参的入口：改动即时生效并（防抖）写回此文件。完整模板见 settings.example.json。

| Key | Default | Meaning / 含义 |
|---|---|---|
| diskScale | 0.8 | Center disk size multiplier / 中心圆盘尺寸倍率 |
| ringScale | 0.8 | Arc (弧光) radius multiplier / 弧光半径倍率 |
| shardScale | 0.8 | Shard size/speed multiplier / 碎片大小与速度倍率 |
| trailScale | 2.2 | Trail width multiplier / 光迹宽度倍率 |
| showInFullscreen | true | Keep overlay over fullscreen apps; false = hide + stop rendering | 在全屏应用上显示覆盖层；false = 隐藏并停止渲染 |
| clickBloomStrength | 0.1 | Click glow-source energy / 点击辉光源能量 |
| trailBloomStrength | 3.5 | Trail glow-source energy / 光迹辉光源能量 |
| bloomStrength | 1.7 | MXFinalBloom exposure (2^(strength/10)-1 in composite) / 辉光曝光 |
| bloomLevels | 16 | Max pyramid levels (actual count follows the diffusion formula) / 金字塔最大层数（实际层数由扩散公式决定） |
| bloomDiffusion | 7.0 | MXFinalBloom diffusion — drives iteration count + sample scale / 扩散度——决定迭代次数与采样尺度 |
| bloomThreshold | 1.0 | Brightness threshold (gamma space) for bloom prefilter / 辉光预过滤亮度阈值（伽马空间） |
| bloomFalloff | 0.35 | Rational falloff knee a = lum/(lum+k) / 有理式衰减拐点 |
| bloomBoost | 1.2 | Extra glow overlay brightness / 辉光叠加额外亮度 |
| enabled | true | Master effect switch / 效果总开关 |
| trailAlwaysVisible | true | Trail on any mouse move; false = only while dragging any button / 尾迹始终显示；false = 仅按住任意鼠标键拖动时 |
| rightClickEnabled | true | Spawn the click effect on right-click (button 2) / 右键点击触发效果 |
| middleClickEnabled | true | Spawn the click effect on middle-click (button 3) / 中键点击触发效果 |
| clickBrightness | 1.0 | Click effect brightness / 点击效果亮度 |
| clickDiskOpacity | 1.0 | Click disk opacity (higher = more opaque) / 点击圆盘不透明度（越高越实） |
| triangleOpacity | 1.0 | Triangle particle opacity (higher = more opaque) / 三角粒子不透明度（越高越实） |
| refreshRate | 60 | Render refresh rate (30/60/120/240) / 渲染刷新率 |

Launch at login is not persisted in settings.json — it's system state (SMAppService / LaunchAgent) toggled by the panel's launch-at-login switch.

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

Lenient parsing: a settings.json may contain only the keys you want to override — missing keys keep the defaults. Unknown keys print a warning to stderr (ignored); invalid JSON prints a warning and falls back to defaults. This is intentional, so a partial edit never silently wipes your other settings.

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

settings.json is git-ignored (personal tuning stays local); commit changes to settings.example.json instead.

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

Adding a setting / 新增一个设置项
每个运行时设置都涉及同样的几处——让它们保持同步：

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——断言新的默认值 +（如相关）持久化
往返。

How it works / 工作原理

- Persistent per-screen NSPanels — each attached display gets a borderless, non-activating overlay panel with level = .floating, collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary, .ignoresCycle], and ignoresMouseEvents = true. Per-screen panels avoid macOS/Spaces edge cases where one giant transparent window does not render on every display.

每屏常驻 NSPanel——每个已连接显示器都有一个无边框、非激活覆盖层，level = .floating、collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary, .ignoresCycle]、ignoresMouseEvents = true。每屏独立面板可避开 macOS/Spaces 下单个超大透明窗口无法在所有显示器渲染的边缘情况。

- Manual vsync-synced render loop — the MTKView's internal display link randomly stalls after Space/fullscreen transitions (the effect appeared "sometimes dead"), so we keep isPaused = true and drive MTKView.draw() ourselves via a CADisplayLink (vsync-synced). The trail samples the live mouse position every frame, so it stays smooth even when the OS coalesces mouse-moved events. An App Nap activity (beginActivity(.userInitiated)) keeps the background app's driver alive, and a watchdog rebuilds the driver if the tick loop goes silent.

手动 vsync 同步渲染循环——MTKView 内部 display link 在 Space/全屏切换后会随机停滞（表现为特效"时有时无"），所以我们保持 isPaused = true，用自建 CADisplayLink（vsync 同步）驱动 MTKView.draw()。尾迹每帧直接采样鼠标实时位置，即使系统合并了 mouse-moved 事件也保持顺滑。beginActivity(.userInitiated) 防止 App Nap 节流后台应用，看门狗会在 tick 循环沉默时重建它。

- Idle power saving — the render loop stops itself as soon as nothing is on screen; clicks / mouse moves / the click-loop wake it. With showInFullscreen=false, the overlay hides and rendering fully stops over fullscreen apps.

闲置省电——屏幕上没有内容时渲染循环自动停止；点击 / 移动鼠标 / 自动点击循环会唤醒它。showInFullscreen=false 时，全屏应用之上会隐藏覆盖层并完全停止渲染。
- 事件——NSEvent.addGlobalMonitorForEvents 全局监听点击/移动。应用绝不能变成前台，否则全局监听会收不到事件（我们只用 orderFrontRegardless()，绝不 activate）。

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

- 管理面板——SwiftUI 面板，放在带标题栏、非激活 NSPanel 里，主体为原生液态玻璃（NSGlassEffectView，macOS 26+；用 NSClassFromString 运行时查找，旧 SDK 也能编译）。老系统自动回退经典 NSVisualEffectView（.menu 材质）玻璃。titlebarAppearsTransparent + fullSizeContentView 保留原生红绿灯与标题栏拖动，同时窗口透明让玻璃透出。控件可用但不激活应用，所以调参时全局鼠标监听仍在工作。点击菜单栏图标弹出菜单（快捷启停特效 / 打开管理面板 / 退出 BA Click）。所有改动即时生效并（防抖）持久化到 settings.json。

- 尾迹模式——开启"始终显示尾迹"：尾迹跟随任意鼠标移动；关闭：仅在按住任意鼠标键并拖动时显示尾迹（左键 / 右键 / 中键均可）。
- 鼠标按键——左键、右键、中键点击都会触发点击特效；右键 / 中键可在面板中独立开关（rightClickEnabled / middleClickEnabled）。
- Updates / 更新 — 面板的检查更新 (Check for Updates) 会查询 GitHub 最新 release API 并比较版本；自动检测更新 (Check Automatically)（默认开启）在启动时（3 秒后）以及每次打开面板时各检查一次，节流为每 60 秒一次，失败时静默——手动按钮则始终真实检查。状态栏在空闲时始终显示当前运行版本（例如 v0.3.3），检查后显示“已是最新”/“有可用更新”。立即更新 (Update Now) 会下载与当前运行架构匹配的 DMG，验证其签名与当前运行应用使用同一证书（指定要求匹配——被篡改的代理提供的下载会被拒绝），挂载它，通过一个分离的辅助程序原子替换应用包（~/Library/Logs/BA Click/update.log，失败时回滚）并重新启动。当无法自动更新时（裸二进制 / 不可写位置 / 失败），它会打开 GitHub Releases 页面。GitHub 仓库 (GitHub Repo) 按钮会打开仓库主页。

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

- Battery saver / 仅接通电源时启用 — 当该开关打开时，所有效果在使用电池供电时暂停，并在接通交流电源的瞬间恢复（IOKit 电源通知）。没有电池的台式机视为始终接通电源，因此该开关在那里不起作用。

省电——开关打开后，使用电池时自动暂停全部特效，插回电源立即恢复（IOKit 电源源通知）。没有电池的台式机视为始终接通电源，此开关无副作用。

- GitHub proxies / 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（仅下载）。

- Launch at login / 开机自启 — 捆绑应用通过 SMAppService 注册，因此该条目会出现在 系统设置 → 通用 → 登录项 中；注册绝不会当场启动应用。裸二进制（run.sh）无法在那里自行注册，会回退到用户 LaunchAgent plist，并以休眠方式注册（禁用 → 引导 → 启用）。旧版 plist 注册（≤0.2.1）会在下次切换时迁移。flock 单实例锁（~/.ba-click-mac.lock）会让任何双重启动立即退出。

开机自启——捆绑版通过 SMAppService 注册，条目出现在 系统设置 → 通用 → 登录项，注册绝不当场启动；裸二进制（run.sh）回退为用户 LaunchAgent plist，以"禁用→注册→启用"方式休眠注册。旧版（≤0.2.1）的 plist 注册在下次切换开关时自动迁移。另有 flock 单实例锁（~/.ba-click-mac.lock），双开时第二个实例立即退出。
- 强制置顶——可选功能（私有 API）：把覆盖层窗口移入钉在锁屏层级之上的专属 SkyLight Space，特效显示在菜单、Dock、启动器乃至锁屏之上。关闭时通过重建覆盖层窗口退出该 Space；所有私有调用均有守卫，失败时保持普通层级。

- GPU 压力自适应——采样永远不被饿死：tick 持续超预算时自动隔帧绘制；上一帧未完成时跳帧而非阻塞等待；压力下只有辉光降分辨率（0.5× → 0.25× 原生），核心永远锐利。全部状态可在 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 loading / defaults (lenient decode)
PowerMonitor.swift         AC/battery detection + power-state notifications
SingleInstance.swift       flock-based single-instance guard
DrawPacer.swift            Adaptive draw pacing (GPU contention → skip draws)
SkyLightSpace.swift        Private-framework interop for force-topmost mode
BAEffectData.swift         Unity keyframes / game-derived values
DebugLog.swift             stderr logging + bail() helper
ResourceLocator.swift      Shared bundled-resource lookup
SettingsStore.swift        ObservableObject settings store + launch-at-login
SettingsPanel.swift        SwiftUI management panel + non-activating NSPanel
UpdateManager.swift        GitHub update check + self-update (helper script)
AppInfo.swift              App version + GitHub links
L10n.swift                 Chinese/English/Japanese strings + language override
Resources/
AppIcon.icns               macOS app icon (used by the .app bundle)
icon.png                   App icon bitmap (Dock icon for the raw binary)
bar_icon_22/44.png         Menu bar icon (1x / 2x template)
circle/ring/trail/triangle  Game-derived effect textures
dmg-background.jpg         DMG installer background (generated, committed)
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        可选运行时调优的模板

权限

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

排障

- 特效随机出现：这曾是 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 数据。