How overlayplugin/cactbot works
Project Type and Purpose
• Cactbot is an open-source plugin overlay system for the Advanced Combat Tracker (ACT) tool, built to provide real-time raid assistance for Final Fantasy XIV.
• It is a mixed-environment project with a C#/.NET “EventSource” backend that parses network logs (via OverlayPlugin), a Node/npm‐based build pipeline (TypeScript, webpack, util scripts) that generates and bundles resources, and a collection of HTML/TypeScript “overlay” front ends loaded by OverlayPlugin via a local WebSocket server.
Top-Level Components
A. Backend Plugin Layer (“plugin/”)
• CactbotEventSource (.NET 4.6.1+) – reads FFXIV combat logs from the FFXIV_ACT_Plugin, filters and normalizes events, exposes a JSON event stream to OverlayPlugin.
• CactbotOverlay – minimal C# loader that registers on ACT’s plugin chain and hands off to the EventSource.
B. Overlay Host (OverlayPlugin)
• Hosts and serves a WebSocket API (OverlayPlugin.dll), acting as the bridge between CactbotEventSource and any number of browser‐based overlay clients.
C. WebSocket API
• A standardized JSON message protocol over a local ws://127.0.0.1:10501/ws interface, through which UI overlays subscribe to combat events, config changes, and user triggers.
D. Front-End Overlays (“ui/” directory)
• A set of independent HTML+CSS+TypeScript applications (“raidboss”, “oopsyraidsy”, “jobs”, “eureka”, “radar”, “dps”, “pullcounter”, “test”).
• Each overlay implements its own Data → View binding, event handling, styling, and user configuration.
• The “raidboss emulator” mimics the live WebSocket feed using dropped network logs.
E. Build & Tooling
• Node/npm + webpack configurations (webpack/, tsconfig*.json, package.json) compile TypeScript overlays and util scripts.
• “util/” scripts generate JSON/TypeScript data (zone IDs, effect IDs, timeline files) and automate version bumps, translation coverage, and release packaging.
• Test harnesses (test/, ui/raidboss/test/, ui/test/) validate triggers, regexes, timeline parsing, and UI components.
Run-Time Data Flow
1. FFXIV game writes network log → FFXIV_ACT_Plugin (ACT)
2. CactbotEventSource reads raw log entries → parses into structured events.
3. OverlayPlugin WebSocket server forwards events over WS.
4. Each UI overlay subscribes to the WS feed → processes events through its own triggers/timelines → renders visual and audio alerts in the browser overlay.
5. User interactions (config panel, user scripts) send commands back to EventSource via the same WS or via updateable JSON config files under %APPDATA%\...OverlayPlugin.config.json.
Architectural Patterns & Principles
• Plugin‐Architecture: CactbotEventSource and CactbotOverlay plug into ACT’s extension points.
• Event‐Driven: All communication uses publish/subscribe over WebSocket.
• Separation of Concerns:
• Backend (.NET) exclusively handles log ingest and event normalization.
• Front-end (HTML/TS) exclusively handles rendering and user interaction.
• Build scripts (Node) exclusively handle code generation, packaging, and resource management.
• Modular Overlays: Each overlay resides in its own directory and can be added/removed independently in the OverlayPlugin UI.
• Detail Balance: Capture all essential pieces (C# plugin, WS API, each overlay, build scripts) without cluttering minor utilities.