|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +VRC OSC Manager is a Rust desktop application for managing multiple VRChat OSC plugins. It runs as a system tray application on Linux and Windows, with a Slint-based GUI for configuration. |
| 8 | + |
| 9 | +## Build & Development Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Build (requires system libs on Linux: libdbus-1-dev libssl-dev libxdo-dev) |
| 13 | +cargo build |
| 14 | + |
| 15 | +# Run |
| 16 | +cargo run |
| 17 | + |
| 18 | +# Check without building |
| 19 | +cargo check |
| 20 | + |
| 21 | +# Lint |
| 22 | +cargo clippy -- -D warnings |
| 23 | + |
| 24 | +# Format check |
| 25 | +cargo fmt --all -- --check |
| 26 | + |
| 27 | +# Format fix |
| 28 | +cargo fmt --all |
| 29 | + |
| 30 | +# Cross-compile for Windows from Linux |
| 31 | +cross build --target x86_64-pc-windows-gnu --release |
| 32 | +``` |
| 33 | + |
| 34 | +There are no tests in this project. |
| 35 | + |
| 36 | +## Architecture |
| 37 | + |
| 38 | +The application has two main threads: |
| 39 | +1. **UI thread** — runs the Slint event loop (`src/ui.rs`, `src/main.rs`) |
| 40 | +2. **Tokio runtime** — runs all background tasks (`src/background.rs`) |
| 41 | + |
| 42 | +Communication between UI and background uses `tokio::sync::mpsc` channels (`UiEvent` for UI→background, `AppEvent` for background→UI). |
| 43 | + |
| 44 | +### Background Task System |
| 45 | + |
| 46 | +Background tasks are managed via `tokio-graceful-shutdown` subsystems, all started in `src/background.rs`: |
| 47 | + |
| 48 | +- **OrchestrateTask** — central coordinator handling app/UI events and routing commands |
| 49 | +- **VrchatMonitorTask** — detects VRChat process start/stop via `sysinfo` |
| 50 | +- **PluginManagerTask** — starts/stops plugins based on VRChat activity and user config |
| 51 | +- **OscReceiverTask** / **OscSenderTask** — UDP OSC message I/O |
| 52 | +- **OscQueryTask** — HTTP server for VRChat's OSCQuery protocol |
| 53 | +- **TrayTask** — system tray icon management |
| 54 | +- **ConfigWriterTask** — debounced config file persistence |
| 55 | + |
| 56 | +### Plugin System |
| 57 | + |
| 58 | +Plugins implement the `Plugin` trait (`src/plugins/mod.rs`). The `define_plugins!` macro registers all plugins. Each plugin: |
| 59 | +- Has its own config managed via `ConfigManager::with_plugin_id()` |
| 60 | +- Receives/sends OSC messages through `ChannelManager` (broadcast receiver + mpsc sender) |
| 61 | +- Registers OSCQuery endpoints |
| 62 | +- Can optionally provide a settings UI panel |
| 63 | + |
| 64 | +Current plugins: `media_control`, `watch`, `pishock`. |
| 65 | + |
| 66 | +### UI Layer |
| 67 | + |
| 68 | +- UI is defined in Slint (`.slint` files in `ui/`) |
| 69 | +- `build.rs` compiles Slint files and converts tray icons (RGBA pixel reorder for Linux, `.rc` embedding for Windows) |
| 70 | +- `slint::include_modules!()` in `main.rs` generates Rust bindings from Slint |
| 71 | + |
| 72 | +### Config System |
| 73 | + |
| 74 | +`src/utils/config.rs` provides `ConfigManager` and `ConfigHandle<T>`. Configs are TOML files stored in the OS config directory under `vrc-osc-manager/`. `ConfigHandle` wraps `Arc<RwLock<T>>` and triggers async writes through the `ConfigWriterTask`. |
| 75 | + |
| 76 | +### Platform Abstraction |
| 77 | + |
| 78 | +`src/platform/` contains `linux.rs` and `windows.rs` behind `cfg` gates, implementing the `Platform` trait for auto-start and folder-open functionality. |
| 79 | + |
| 80 | +### mDNS/Service Discovery |
| 81 | + |
| 82 | +The app broadcasts OSCQuery and OSC services via mDNS (`searchlight` crate) so VRChat can discover it automatically. |
0 commit comments