forked from nikita/muzika-gromche
70 lines
5.1 KiB
Markdown
70 lines
5.1 KiB
Markdown
|
# 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/src/assets/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.
|