Add configurable procedural sounds

README.md

@@ -3,6 +3,7 @@
 Physilinks is a browser-based physics linking game built with Matter.js. Match and chain same-colored falling balls; link enough to clear them and rack up points.
 
 ## Play instructions
+
 - Open `index.html` in a modern browser (desktop or mobile touch).
 - Choose a scene from the selector (changes gravity, obstacles, spawn rate, palette, ball size). Switching scenes restarts the run.
 - Click/touch a ball to start a chain; drag through balls of the same color to add them. Drag back to the previous ball to undo the last link.
@@ -11,21 +12,26 @@ Physilinks is a browser-based physics linking game built with Matter.js. Match a
 - Pause/resume with the button or `Esc`. HUD shows spawn rate, min link, chain length, score, per-scene high score, and palette legend.
 
 ## Tech notes
+
 - **Engine**: Matter.js (via CDN). Canvas rendering with custom overlays for HUD, pause, game over, and score popups.
 - **Scenes**: Defined in `src/scenes/*.js` as presets (config + `createBodies` factory). Applying a scene updates gravity, spawn rate, ball radius, palette, link constraints (stiffness/stretch/damping/width), and static bodies, then restarts the game.
 - **Physics entities**: Falling balls (`Bodies.circle`) with gentle restitution/friction; static boundaries/obstacles per scene. The top is open; sides and floor are static bodies.
 - **Input**: Pointer/touch events mapped to scene coords; chain state tracks bodies and a dashed preview line to the pointer. Undo by dragging back to the previous node.
+- **Sound**: Procedural Web Audio by default with optional sample playback per channel (buzz/click/pop). Configure via `config.sounds` and per-scene overrides.
 - **Scoring**: `10 × length²` per cleared chain. Score popup rendered as DOM element near release point (via UI module).
 - **Persistence**: Per-scene high score stored in `localStorage` under `physilinks-highscore-<sceneId>`; loaded on scene change; HUD shows current scene's best.
 - **Game loop**: Single Matter runner controlled in `main.js`, with spawning handled by `src/spawn.js` and goal messaging handled by `src/goals.js`. Pause/game over stop the runner and spawner and zero `engine.timing.timeScale` so physics and rotating obstacles freeze; resume restarts the runner and spawner.
 - **Lose detection**: Spawned balls monitor entry; if they remain near the spawn zone with negligible velocity after a short delay, the run is over.
 
 ## File structure
+
 - `index.html`: Shell layout and HUD overlays; loads Matter.js plus game scripts.
 - `styles.css`: Styling for canvas, HUD, overlays, and score popups.
 - `src/scenes/`: Scene presets split per file (`scene-*.js`) plus `index.js` that registers them to `window.PhysilinksScenes` (e.g., zero-G grid, balanced, low-G, fast drop, lava drift).
 - `src/scenes/scene-template.js`: Reference-only template documenting every scene config option; not loaded by default.
 - `src/config.js`: Base game config defaults (gravity, spawn timing, link settings, palettes, message defaults).
+- `src/sounds.js`: Audio system (procedural + sample playback) with per-channel config and scene overrides.
+- `assets/sfx/`: Optional sample audio files plus `SOURCES.txt` with source URLs.
 - `src/engine.js`: Matter engine/render/runner setup helpers (create, start/stop runner, resize render).
 - `src/decomp-setup.js`: Registers `poly-decomp` with Matter to allow concave shapes (stars, blobs) built via `Bodies.fromVertices`.
 - `src/ui.js`: DOM access, HUD updates, overlays, popups, and control/selector wiring.
@@ -35,11 +41,13 @@ Physilinks is a browser-based physics linking game built with Matter.js. Match a
 - `src/main.js`: Physics setup, state machine, chain interaction, scene application, and pause/restart logic; delegates spawn duties to `src/spawn.js`, goal handling to `src/goals.js`, and input/chain interactions to `src/input.js`.
 
 ## Development quick start
+
 - No build step. Open `index.html` directly in the browser.
 - Key files: `index.html` (layout), `styles.css` (styling), `src/ui.js` (DOM/HUD), `src/main.js` (physics/game logic), `src/scenes/index.js` (scene registration).
 - Adjust or add scenes by extending the files in `src/scenes/` with config and a `createBodies(width, height)` function.
 
 ## Adding a new scene
+
 - Create `src/scenes/scene-<your-id>.js` based on `src/scenes/scene-template.js` or an existing scene, and keep the `id` aligned to the filename suffix.
 - Add the script tag to `index.html` with the other scene files so it loads in the browser.
 - Register the scene id in `src/scenes/index.js` (append to `desiredOrder` or rely on the unordered fallback).