# ba-click-fx β Blue Archive Click Effect and Cursor Trail for Web
[](LICENSE)
[](https://github.com/CialloKing/ba-click-fx/actions)
[](https://www.npmjs.com/package/ba-click-fx)
[](https://www.npmjs.com/package/ba-click-fx)
[](https://chromewebstore.google.com/detail/clphaaacolnifhgmeblfeofapccgoami) [](https://microsoftedge.microsoft.com/addons/detail/ba-click-fx/gocfepocmghimclocjafcihcplnpjpkc) [](https://addons.mozilla.org/zh-CN/firefox/addon/ba-click-fx/)
> π [δΈζη](./README.md)
**A parameter-level port of the Blue Archive Unity UI/FX_Touch click effect and cursor trail for the web.**
`ba-click-fx` faithfully reproduces the ParticleSystem and TrailRenderer from the game's `FX_Touch.prefab` β colour curves, size curves, rotation speed, dissolve thresholds, HDR intensity, and TrailRenderer timing/width. **Full WebGL2** owns the complete Scene, Coverage, and MXFinalBloom output by default. Optional WebGPU modes provide a guaranteed standard SDR Canvas or, when the browser and display chain support it, real highlights above SDR white. WebGL2, Canvas 2D, Software Bloom, and Native Glow remain automatic fallbacks. Zero external runtime dependencies.
**Live Demo:** [ba-click-fx.cialloking.top](https://ba-click-fx.cialloking.top)
> π± Click, drag, or move your mouse on the demo page to preview.
ba-click-fx demo (left) Β· In-game reference (right)
> π₯ **Desktop (Windows test build):** [ba-click-fx-desktop](https://github.com/CialloKing/ba-click-fx-desktop) reimplements the same effect from scratch in C++ / Win32 API / Direct3D 11. See the [Desktop Edition](#desktop-edition-windows-test-build) section.
---
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Desktop Edition (Windows Test Build)](#desktop-edition-windows-test-build)
- [Common Usage](#common-usage)
- [API Reference](#api-reference)
- [Effects](#effects)
- [FAQ](#faq)
- [How It Differs](#how-it-differs)
- [Project Structure](#project-structure)
- [Development](#development)
- [Credits](#credits)
- [License](#license)
---
## Features
- Parameter-level port from the Unity FX_Touch.prefab β not a "lookalike"
- Dissolve rings (MeshTri), centre disk (ring), click shards (Ring 3/4), drag trail (TrailRenderer)
- All particle parameters locked to the game's original values: colour curves, size curves, rotation speed, dissolve thresholds, HDR intensity
- Canvas 2D, Full WebGL2, and WebGPU share the reviewed effect geometry with zero external runtime dependencies
- Six demo rendering choices: WebGPU, WebGPU HDR (experimental), Full WebGL2 (default), WebGL2 Bloom, Software Bloom, and Native Glow
- WebGPU uses an `rgba16float` linear Scene and multi-level Bloom; the ordinary mode forces a standard SDR Canvas, while the HDR mode may request `extended` output that preserves highlights above SDR white
- An unavailable or lost WebGPU device falls back to Full WebGL2, then through Canvas 2D, Software Bloom, and Native Glow
- Advanced hosts can place the core in a Worker with direct `OffscreenCanvas`, Full WebGL2, manual input, and explicit sizing
- Browser extension, npm, CDN, and direct download
- Theme colours support compatible HSL hue shifting and recommended relative-OKLCH full-colour mapping
- Runtime-tweakable FX parameters via `setFxParam()`
- Particle sizes keep scaling with canvas height to preserve the Unity UI proportions
---
## Installation
### 1. Browser Extension
Install the browser extension for any of the supported stores:
| Store | Link |
|-------|------|
| **Chrome** | [Chrome Web Store](https://chromewebstore.google.com/detail/clphaaacolnifhgmeblfeofapccgoami) |
| **Edge** | [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/ba-click-fx/gocfepocmghimclocjafcihcplnpjpkc) |
| **Firefox** | [Firefox Add-ons](https://addons.mozilla.org/zh-CN/firefox/addon/ba-click-fx/) |
Source: [ba-click-fx-extension](https://github.com/CialloKing/ba-click-fx-extension).
### 2. npm
```bash
npm install ba-click-fx
```
```js
import { BAClickFX } from 'ba-click-fx';
const fx = new BAClickFX();
```
### 3. CDN
```html
```
### 4. Direct Download
Download the ESM builds from [GitHub Releases](https://github.com/CialloKing/ba-click-fx/releases) (`ba-click-fx.js`, `config.js`, `worker.js`, and their `.d.ts` declarations):
```html
```
---
## Desktop Edition (Windows Test Build)
[ba-click-fx-desktop](https://github.com/CialloKing/ba-click-fx-desktop) is an independently implemented Windows-native desktop edition. It does not reuse this project's JavaScript / WebGL / WebGPU code; instead it reimplements the same Blue Archive click effect and cursor trail from scratch with **C++20, Win32 API, Direct3D 11, HLSL, and DirectComposition**. Unity/game assets remain the visual ground truth, while the web version only serves as the behavioural and parameter-semantics reference.
The current release is the **first test build (Alpha)**, and its support contract covers the single-primary-monitor FX-only / SDR path only:
- Single-file runtime: the Visual C++ runtime is statically linked, and only Windows system components such as D3D11, DirectComposition, WIC, and D3DCompiler are used
- The overlay is click-through and never steals focus; quit via the notification-area icon's right-click menu, or press `Ctrl+Alt+F12`
- Ships with a standalone Control Center (`BAFX.ControlCenter.exe`, pure Win32 Common Controls, no Windows App SDK): it connects to the Host over a local Named Pipe and can pause/resume effects as well as tweak effect size, trail length/width, Bloom strength/quality, and more
- Build and tests are driven by CMake presets (Visual Studio 2026 + Windows SDK); architecture and decision documents live in `ARCHITECTURE.md` and `docs/adr` of the desktop repository
---
## Common Usage
```js
const fx = new BAClickFX({ target: '#myCanvas' });
fx.boom(window.innerWidth / 2, window.innerHeight / 2);
fx.destroy();
```
---
## API Reference
### Constructor
```ts
new BAClickFX(options?: {
target?: string | HTMLElement | OffscreenCanvas,
scale?: number, // default 1
opacity?: number, // default 1
themeColor?: string, // six-digit hex, default #4ca7ff
themeColorMode?: 'hue-only' | 'relative-oklch', // public-library default: relative-oklch
outputCompositing?: 'scene' | 'browser-overlay', // default scene
overlayAlphaPolicy?: 'coverage' | 'visual-max', // default coverage
overlayColorCompensation?: 'none' | 'bright-core', // default none
overlayAlphaLimit?: number, // overlay alpha limit, default 250/255
hostCompositing?: 'source-over' | 'screen' | 'plus-lighter', // default source-over
clickEnabled?: boolean, // default true
trailEnabled?: boolean, // default true
trailAlways?: boolean, // default false
inputSource?: 'dom' | 'manual', // default dom
inputSamplingRate?: number, // move-input rate limit; 0 unlimited, 1..1000 Hz, default 0
clickTimeScale?: number, // minimum 0.01, default 1
trailTimeScale?: number, // minimum 0.01, default 1
effectBackend?: 'canvas2d' | 'webgl2' | 'webgpu' | 'auto', // default webgl2
webgpuPreferHdr?: boolean, // true prefers HDR; false forces standard SDR; default true
webgpuHdrPeak?: number, // Extended linear peak 2..4, default 3
webgpuHdrBrightness?: number, // Extended effect brightness multiplier 0..32, default 1
webgpuHdrColorPreservation?: number, // Extended highlight hue preservation 0..1, default 0
webgpuHdrWhiteCore?: number, // Extended white-core strength 0..1, default 0.6
webgpuHdrWhiteStart?: number, // Extended white-core start 0..15.99, default 1
webgpuHdrWhiteEnd?: number, // Extended white-core end 0.01..16, default 5
bloomBackend?: 'auto' | 'software' | 'webgl2' | 'native', // default webgl2
softwareBloomEnabled?: boolean, // compatibility alias: true = software, false = native
isolatedCompositing?: boolean, // default false; true enables non-game white-background compatibility
lightBackgroundContrastAlpha?: number, // light-background compatibility strength, default 0
maxDpr?: number, // default 1; raise explicitly for capable devices
touchAction?: string, // DOM touch-gesture policy; default 'auto'
inputFilter?: (e: PointerEvent) => boolean,
})
```
`touchAction` accepts CSS `touch-action` keywords and space-separated combinations, including `none`, `pan-x`, `pan-y`, `pan-left`, `pan-right`, `pan-up`, `pan-down`, and `pinch-zoom`. DOM input installs capture Touch arbitration only when the policy must block a direction or pinch; `auto`, `manipulation`, and combinations that explicitly allow every axis and pinch retain the browser's compositor-friendly scrolling. When an overlay Canvas is not hit-testable, the library locks the gesture direction at its first meaningful move and applies `inputFilter` to exclude host controls; `inputSource: 'manual'` does not install these DOM listeners.
`effectBackend` decides whether WebGPU or WebGL2 owns the complete crisp scene and Bloom. `webgpuPreferHdr` only controls whether the final WebGPU Canvas attempts Extended HDR; `false` forces Standard SDR. The Canvas 2D path then uses `bloomBackend` to select its Bloom implementation. The demo exposes six direct combinations:
| Demo choice | API configuration | Behaviour |
|---|---|---|
| WebGPU | `{ effectBackend: 'webgpu', webgpuPreferHdr: false, bloomBackend: 'webgl2' }` | Formal ordinary WebGPU mode. It configures only the browser-preferred Standard SDR Canvas and never requests `toneMapping: extended`, while retaining the Unity-aligned linear Scene and MXFinalBloom |
| WebGPU HDR (experimental) | `{ effectBackend: 'webgpu', webgpuPreferHdr: true, bloomBackend: 'webgl2' }` | Requests WebGPU asynchronously and prefers `rgba16float + toneMapping: extended`; if HDR Canvas configuration is unavailable it keeps WebGPU with standard SDR output, while an unavailable or lost device falls back to Full WebGL2 |
| Full WebGL2 | `{ effectBackend: 'webgl2', bloomBackend: 'webgl2' }` | Default; builds the complete Scene, Coverage, and MXFinalBloom output in one WebGL2 HDR pipeline; falls back to the Canvas 2D chain on failure |
| WebGL2 Bloom | `{ effectBackend: 'canvas2d', bloomBackend: 'webgl2' }` | Compatibility selector; when the GPU is available it reuses the same complete HDR Scene as Full WebGL2, then falls back through the Canvas 2D Software / Native chain on failure |
| Software Bloom | `{ effectBackend: 'canvas2d', bloomBackend: 'software' }` | Compatibility implementation using an 8-bit Canvas mask, pixel readback, and full-viewport Float32 Bloom buffers |
| Native Glow | `{ effectBackend: 'canvas2d', bloomBackend: 'native' }` | Uses Canvas 2D `shadowBlur`; cheaper, but visually different from post-process Bloom |
The demo exposes Isolated Compositing as a separate switch beside the six rendering choices. It is disabled by default and orthogonal to the rendering backend: it changes only the final CSS compositing boundary for the canvases, not Bloom thresholds, filtering, colour calculations, or Bloom compute cost.
WebGPU availability does not imply HDR display output. Only `getConfig().resolvedWebGPUOutputMode === 'extended'` means that the Canvas negotiated extended dynamic range, encodes the linear HDR result as extended sRGB, and preserves highlights above SDR white. `'standard'` means the WebGPU Scene and Bloom are running but the final Canvas remains SDR, `'pending'` means device or first-frame work is in progress, and `'unavailable'` means no WebGPU output is active. Visible super-white highlights additionally require an HDR display, system HDR enabled, browser support for WebGPU HDR Canvas, and successful `rgba16float + toneMapping: extended` configuration.
Setting `webgpuPreferHdr: false` skips Extended configuration on every browser and uses the browser-preferred Standard SDR Canvas directly; this is the fixed contract of the demo's ordinary βWebGPUβ mode. The internal `rgba16float` Scene remains necessary to retain emission energy before prefiltering and preserve Unity MXFinalBloom precision. It is not HDR display output; `resolvedWebGPUOutputMode` remains the only output verdict.
Below the HDR summary, the demo provides a collapsed WebGPU Diagnostics section. It reports the secure context, WebGPU API, Canvas context, adapter, device, Extended Canvas, Standard SDR, first-frame pipeline, graphics/video dynamic range, and CSS HDR syntax support, while retaining stable failure-stage codes and browser exception text. `(video-dynamic-range: high)` is only a video-output environment hint and does not participate in the WebGPU HDR success verdict. `CSS.supports()` likewise proves only that the browser accepts the relevant syntax, not that the current display is producing HDR output. A webpage cannot reliably read the operating-system HDR switch or display luminance in nits; the final browser-side criterion remains `resolvedWebGPUOutputMode === 'extended'`.
The demo's UI HDR controls are demo-only. In addition to an effect that actually resolves to WebGPU Extended, the browser must support extended `color(srgb-linear ...)` values and `dynamic-range-limit: no-limit`; otherwise the controls are disabled. The demo applies CSS HDR outlines and glows directly to the title, status area, panel edges, and interactive controls, without creating a second full-screen Canvas or using `mix-blend-mode`. The `1..16` UI HDR Brightness multiplier is not part of the `BAClickFX` public API and does not change `webgpuHdrBrightness`, Unity FX parameters, or click-effect pixels.
`webgpuHdrPeak`, `webgpuHdrBrightness`, `webgpuHdrColorPreservation`, `webgpuHdrWhiteCore`, `webgpuHdrWhiteStart`, and `webgpuHdrWhiteEnd` calibrate only the final HDR presentation mapping of a WebGPU Extended Canvas. WebGPU Standard, WebGL2, and Canvas 2D output are unaffected, and these options do not change Unity FX parameters, particle counts, geometry, or the Bloom algorithm. `webgpuHdrBrightness` is a linear multiplier in the `0..32` range. When a matching compositing reference is present, it amplifies only the effect increment above that background and does not brighten the reference itself. High values let advanced users target more display highlight headroom, but the browser, operating system, or display may clip, compress, or tone-map them, so the value is not a fixed nit target.
`webgpuHdrColorPreservation` controls how strongly the highlight increment is restored towards the original linear RGB chromatic direction. Its range is `0..1`; the default `0` preserves the existing gradual white-core presentation. At `1`, the HDR shoulder still determines the peak, while high brightness multipliers no longer amplify white-core colour drift introduced by the renderer. The demo's Preserve Original Hue preset sets this option to `1` and `webgpuHdrWhiteCore` to `0`. This removes renderer-induced whitening, but it cannot prevent the browser, operating system, or display from reducing saturation when the requested output exceeds its actual HDR colour volume.
Explicit `effectBackend: 'webgpu'` and `'auto'` both resolve the complete-effect backend in WebGPU β WebGL2 β Canvas 2D order. The default remains the stable `'webgl2'`, so upgrading does not silently switch existing pages to WebGPU.
`bloomBackend: 'auto'` tries WebGL2 first, then Software Bloom, then Native Glow. The default `'webgl2'` uses the same fallback chain; explicit `'software'` falls back to Native Glow when pixel readback is unavailable. For compatibility with 1.2.13 and earlier, constructor options or `createConfig()` that explicitly provide `bloomBackend` / `softwareBloomEnabled` without `effectBackend` retain the `effectBackend: 'canvas2d'` configuration and fallback-state contract; an explicit `effectBackend` always wins. If both `bloomBackend` and the old `softwareBloomEnabled` field are provided, `bloomBackend` wins. The compatibility field still maps `true` to `'software'` and `false` to `'native'`.
To preserve the already reviewed colour, transparency, and edge sampling, a successful WebGL2 Bloom frame intentionally reuses the complete `WebGL2EffectRenderer` Scene instead of uploading an 8-bit Canvas Scene. It therefore uses the same shaders and pixel pipeline as Full WebGL2 and does not pre-rasterise a Canvas that will be hidden. The distinction is the compatibility contract: WebGL2 Bloom retains the `effectBackend: 'canvas2d'` request and its Software / Native fallback chain, while Full WebGL2 is owned directly by the complete-effect backend.
`outputCompositing: 'scene'` is the default and preserves Unity's direct additive RGB semantics for a Scene render target. The demo and integrations that require strict game reproduction should use it together with a `setCompositingReference()` image that pixel-matches the displayed background; this is the contract under which the complete GPU paths evaluate Scene RGB precisely. `'browser-overlay'` is selected explicitly by transparent desktop hosts such as BASpark, WebView2, and Electron. HDR emission and Bloom energy remain independent, while final alpha is no longer inferred from the largest final RGB channel.
Four orthogonal options further define transparent output over an unknown background. Alpha allocation and colour compensation never switch one another implicitly:
| Configuration | Contract |
|---|---|
| `overlayAlphaPolicy: 'coverage'` | Default transparent contract. Requested alpha sums crisp Scene Coverage and independent Bloom transport alpha before lifetime, `opacity`, and the final limit are applied. Use it when stable occlusion and cross-backend continuity matter most |
| `overlayAlphaPolicy: 'visual-max'` | A v1.2.15-style visual approximation. Requested alpha takes the larger of crisp Scene Coverage and Bloom transport alpha, preserving lower occlusion where they overlap. Alpha still comes only from those independent transport quantities and is never generated from final `maxRGB` |
| `overlayColorCompensation: 'none'` | Default; preserves the transparent payload's colour relationships without compensation |
| `overlayColorCompensation: 'bright-core'` | A visibility approximation for unknown light backgrounds. It compensates only high-energy cores, gated independently by crisp emission and Bloom energy. It neither mixes all RGB towards white nor turns low-energy trail tips grey-white. The premultiplied `RGB <= Alpha` constraint is preserved, but pixel equivalence with Unity is not claimed |
| `overlayAlphaLimit` | Final alpha capacity for `browser-overlay + source-over`, default `250 / 255`, with finite values clamped to `0..1`. Premultiplied RGB contracts proportionally when capacity is insufficient. The option does not change effect `opacity`, HDR emission strength, or Bloom strength |
| `hostCompositing: 'source-over'` | Default host contract; uses the alpha policy, colour compensation, and alpha limit above |
| `hostCompositing: 'screen'` | Independent full-payload contract for unknown mid-tone and light backgrounds. A library-owned layer group uses CSS `screen` once, so the increment contracts as the backdrop gets brighter; alpha policy, colour compensation, and alpha limit are ignored |
| `hostCompositing: 'plus-lighter'` | Independent Add-payload contract for unknown backgrounds. The renderer emits the complete additive payload for the host to composite once with `plus-lighter`, so `overlayAlphaPolicy`, `overlayColorCompensation`, and `overlayAlphaLimit` are ignored |
The old `unknownBackgroundAppearance` field has been removed from constructor options, `updateConfig()`, `getConfig()`, and the type declarations. Colour compensation is controlled only by `overlayColorCompensation`, while alpha allocation is controlled only by `overlayAlphaPolicy`; no compatibility mirror links the two settings.
Both `screen` and `plus-lighter` are SDR DOM-compositing approximations and vary with browser colour management and implementation details. Unity composites the backdrop and effect together in linear HDR before one final encoding step. An unknown desktop is outside the overlay process, so no single transparent payload can be pixel-equivalent over every backdrop. `screen` preserves the full payload over black and automatically reduces its increment towards white; it is used by the demo's βDOM Add (Approximate)β option and is recommended for unknown mid-tone or light backdrops. `plus-lighter` remains available for known black or dark hosts, but directly adds the sRGB payload and saturates early over light content.
For a library-owned overlay, the selected host blend is applied once to the complete layer group. With a caller-owned `