muzika-gromche/AGENTS.md

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.