beatsaber-overlay/AGENTS.md

AGENTS.md

OBS/browser overlay that reads Beat Saber Plus Song Overlay events over WebSocket (ws://localhost:2947/socket). Serve the folder with deno task serve (see serve.ts) so the request-queue JSON loads from the same origin; configure the BS+ database path via CHAT_REQUEST_DATABASE or chat-request-database.path.

Preference: HTTP only, no file://

Do not add or maintain code paths for opening the overlay as file://. The client assumes http: / https: for fetching JSON (cache-busted fetch). Do not reintroduce XHR/file: fallbacks or docs that suggest local file URLs—one supported way: serve with Deno (or another HTTP server) per README.md.

Files of interest

• index.html — Page shell: markup for map info, time bar, score, settings dialog; pulls index.css and index.js.
• index.js — Connects to BS+ WebSocket, parses JSON events (gameState, mapInfo, pause, resume, score), updates DOM; optional BeatSaver API fetch for custom maps; reads/writes settings from URL hash.
• index.css — Layout, theming, visibility toggles driven by body classes and CSS variables from settings.
• serve.ts — Deno static server + optional mapping of ChatRequest.json / database.json to the real BS+ Database.json path.
• types.d.ts — JSDoc typedefs for BS+ payloads and events (editor/IDE hints only).
• jsconfig.json — JS project roots/path so editors resolve modules and types.d.ts.
• images/ — Cover fallback (unknown.svg), characteristic icons under images/characteristic/ (filenames match BS+ characteristic strings).
• README.md — User-facing usage (Deno, OBS URL, BS+ module).
• dprint.json — Formatter config for the repo.
• .editorconfig — Basic indent/charset rules for editors.

Out of scope here

Beat Saber Plus itself (game mod) exposes the socket; this repo is only the HTML/CSS/JS client.