# Muzika Gromche — AI Agent Guide

## Overview

- **Purpose**: This repository builds a BepInEx plugin (C#) that adds synchronized party music + light effects to Lethal Company, plus a small frontend playground for track metadata and browsing.
- **Two main parts**: the core plugin in `MuzikaGromche/` (targets `netstandard2.1`) and the frontend in `Frontend/` (Vite 3 + Vue + Vitest).
- **Tools and helpers**: there are some helpful Python scripts in the `playground` directory.

## What to edit / hotspots

- `MuzikaGromche/Plugin.cs`: plugin entry and initial configuration registration.
- `MuzikaGromche/*.cs` (e.g. `PoweredLights.cs`, `DiscoBallManager.cs`, `SpawnRateManager.cs`, `ScreenFiltersManager.cs`): main game integration and effect logic.
- `UnityAssets/` and `MuzikaGromche/bin/...`: Unity assets and compiled outputs used for packaging.
- Frontend audio/metadata: `Frontend/src/audio/AudioEngine.ts` and `Frontend/public/*` (track lists and audio bundles).
- Sources of audio tracks are edited and mixed outside of this repo, and only final deliveries are checked in here.

## Build & run (developer workflow)

- Primary helper: `Justfile` (root) and `MuzikaGromche.just.user` (root, not checked into the repo, so some commands may be unavailable). Common recipes:
  - `just build` — runs both `build-debug` and `build-release` (calls `dotnet build`).
  - `just build-release` — `dotnet build --configuration Release`.
  - `just build-debug` — `dotnet build --configuration Debug`.
  - `just build-debug run` — build & run the game for testing, most commonly used combination.
  - `just install-imperium` — installs `dist/MuzikaGromche-Debug.zip` into an r2modman/Imperium profile path (see `Justfile` for `plugin_dir`). Not needed, as it is a post-build step anyway.
  - `just ogg <track_name>` and `just ogg1 <track_name>` — custom msbuild targets that convert wav→ogg via `dotnet msbuild /t:wav2ogg` (used when adding tracks from outside of this repo).
  - `just loud <track_name>` — runs a Python script that measures loudness of an audio track in LUFS, useful to calculate volume adjustments for normalization to a consistent desirable level.
  - `just oggloud1 <track_name>` and `just oggloud <track_name>` — convert and measure loudness in one command invocation (single track, and intro+loop pair of tracks respectively).

- Frontend: in `Frontend/`:
  - Use `pnpm` (lockfile `pnpm-lock.yaml` present). Run `pnpm install`.
  - Dev: `pnpm run dev` (Vite). Build: `pnpm run build`.
  - Test: `pnpm run test:browser` or `pnpm run coverage`. Uses Vitest with unified config in `vite.config.ts`.

- Python scripts in `playground`:
  - Use `uv` tool to run Python code, or corresponding `just` targets if available.

## Packaging and outputs

- Plugin target: `netstandard2.1` — compiled DLLs appear under `MuzikaGromche/bin/<Configuration>/netstandard2.1/`.
- The repo expects a `dist/` zip for quick install (see `Justfile` `install-imperium` target). Look for `dist/MuzikaGromche-Debug.zip` when installing into a profile.

## Conventions & patterns

- BepInEx plugin pattern: follow `Plugin.cs` for how features are registered and how configuration entries are declared.
- Prefer small localized changes: keep public APIs stable and avoid broad refactors across many `*.cs` files without tests. The game integration is timing-sensitive.
- Manual testing is done by running the game (see `Justfile` `run` target).
- Track assets: audio tracks and timings are curated; if you add tracks, use the `just ogg` or `dotnet msbuild` tasks to convert. Run the game once, so that it dumps a new JSON metadata under the frontend `public/` directory to ensure that data stays in sync.

## Integration points & external dependencies

- Game modding: integrates with Lethal Company via BepInEx. The repo assumes you understand how to drop plugin DLLs into r2modman profiles (see `Justfile` `plugin_dir`).
- External tools: `dotnet` (SDK for building and custom msbuild targets), `just` (task runner) — commands are invoked from repository root; `pnpm`/`node` (frontend) — commands are invoked from `Frontend` directory.

## Examples to reference

- Change visual effects: edit `MuzikaGromche/PoweredLights.cs` or `MuzikaGromche/ScreenFiltersManager.cs` and test by running `just build-debug run`.
- Add frontend metadata: update `Frontend/public/MuzikaGromcheTracks.json` and run `pnpm run build`.

## What NOT to assume

- There are no automated unit tests in the C# mod; it is unreasonably hard to run mod's code outside of Unity runtime, so don't bother with it. Validate changes with local builds and by installing into an r2modman profile.
- Packaging and profile paths are user-specific — `Justfile` contains a template `plugin_dir` that uses `$HOME` and `imperium_profile` fields; do not hardcode absolute paths in commits.

## Where to look next (quick links)

- `Justfile` and `MuzikaGromche.just.user` — primary developer recipes and packaging helpers.
- `MuzikaGromche/` — all plugin source code.
- `UnityAssets/` — art/animator resources, treat them as opaque binary blobs.
- `Frontend/` — frontend app, `src/audio/AudioEngine.ts` for audio logic.