# EZPPLauncher **EZPPLauncher** is a modern, feature-rich custom launcher for the private osu! server [EZPPFarm](https://ez-pp.farm), built with **Rust** and **Svelte 5** using the [Tauri](https://tauri.app) framework. It enhances the osu! experience with quality-of-life features, advanced launcher theming, customized Discord Rich Presence, and seamless server integration. Windows and macOS are supported, with partial support for Linux. --- ## 🖼️ Preview ![EZPPLauncher Preview](./assets/EZPPLauncher-preview.png) --- ## 🚀 Features ### Game & Server Integration - [x] **Direct Server Launch**: Launches osu! directly with `-devserver ez-pp.farm`, bypassing osu! updater loops and preserving launch parameters. - [x] **Automatic In-Game Login**: Automatically signs into your EZPPFarm account upon game boot. - [x] **In-Game Relax & Autopilot Miss Patcher**: Injects a hook into the osu! client to display misses in Relax and Autopilot modes (Windows, macOS via Wine, and partially on Linux via osu-winello). - [x] **Live Player Stats**: Displays rank, PP, accuracy, playcount, and server latency directly on the launcher dashboard. - [x] **Library Indexing**: Automatically counts imported beatmapsets and skins. - [x] **OpenTabletDriver Integration**: Automatically starts and stops the OpenTabletDriver daemon on launch/exit (Windows only). - [x] **Performance Display Overlay**: In-game HUD overlay (available in the experimental patcher stream). ### Visual Theme Engine v2 & In-App Studio - [x] **Declarative Theme API 2.0**: Modern JSON schema supporting background videos, audio, Lottie animations, and layered widgets without custom compilation. - [x] **Dedicated Visual Theme Editor**: Standalone resizable window with a full-featured visual canvas, live preview, and multi-element selection. - [x] **Custom Svelte 5 Component Layers**: Embed custom reactive Svelte 5 components with an integrated **Monaco code editor** and live compiler diagnostics. - [x] **Canvas Transform Tooling**: Multi-selection, snapping, freeform rotation, X/Y scale, skew, and group breadcrumb navigation. - [x] **Logic & Scripting System**: Visual WHEN/IF/THEN rule builder and sandboxed rule scripting (expressions, branches, loops, visibility toggles) without `eval`. - [x] **Dynamic Placeholders & Clock Expressions**: Real-time variables (`{username}`, `{rank}`, `{pp}`) and second-accurate clock variables (`{time}`, `{hour}`, `{minute}`). - [x] **Typography & Icon Families**: Gradient fills, outlines, drop shadows, custom `@fontsource` webfonts, and bundled Lucide, Phosphor, and Tabler icon catalogs. - [x] **Backup & Rollback System**: Automatic versioned theme snapshots with one-click restoration, plus security trust prompts for executable components. ### Discord Rich Presence Studio - [x] **Dedicated Presence Editor Window**: In-app studio to customize your Discord presence. - [x] **Interactive Discord Embed Preview**: Real-time visual mockup mirroring Discord's user profile popout card. - [x] **Dynamic Placeholders**: Interpolate live stats (`{username}`, `{rank}`, `{pp}`, `{accuracy}`, `{playcount}`, `{version}`) into details, state, and asset tooltips. - [x] **Custom Action Buttons & Presets**: Configurable buttons linking to player profiles, leaderboards, or custom URLs, plus quick presets (Default, Grinding, Competitive, Relax, AFK). ### Diagnostics, Logging & System Tools - [x] **In-App Diagnostics Panel**: Validates osu! folder integrity, write permissions, Wine runtimes, .NET 8 desktop runtime, FFmpeg, and patcher status. - [x] **Multi-Stream Log Viewer**: Dedicated rotating logs (`launcher.log`, `osu.log`, `patcher.log`) with session bundling, zip archive export, and an in-app viewer. - [x] **macOS Wine Automation**: Automatic font registry sanitization (eliminating GDI+ `AccessViolationException` crashes), Wine prefix management, and automated in-place patcher bytecode patching for .NET 4.0 runtimes under Wine. - [x] **Hardware-Accelerated Media Server**: Local HTTP range streaming server on macOS and Linux for smooth, low-memory WebM and MP4 video playback. --- ## 💻 Supported Platforms | Platform | Status | Runtime / Environment | | -------- | ---------------------- | ---------------------------------------------------------- | | Windows | ✅ Supported | Native Win32 | | macOS | ✅ Supported | Wine wrapper (Wineskin, Whisky, CrossOver, or system Wine) | | Linux | 🕧 Partially Supported | Wine / Proton (via osu-winello / wmctrl) | > **Windows** and **macOS** are fully supported. **Linux is partially supported**: osu! must be managed through external community tooling ([`osu-winello`](https://github.com/NelloKudo/osu-winello)), window tracking requires `wmctrl`, OpenTabletDriver automation is unavailable, and the launcher is restricted to the stable patcher stream. --- ### 🍎 macOS Integration Details osu! stable is a 32-bit Windows application, so on macOS it runs inside a Wine-based wrapper. EZPPLauncher natively supports **Wineskin wrappers** (the standard `osu!.app` bundle), **Whisky bottles**, and **CrossOver bottles**. - **Automatic Wrapper Detection**: The setup wizard automatically searches `/Applications` and `~/Applications` for existing Wineskin bundles and Wine prefixes. If choosing **Browse**, selecting the `osu!.app` bundle directly resolves the underlying prefix without needing to navigate inside "Show Package Contents". - **Wine Prefix Font Fix**: macOS system font enumeration under Wine GDI+ can crash osu! on cold start with an `AccessViolationException` when reading Apple Braille fonts. EZPPLauncher automatically detects and cleans incompatible font entries from the prefix registry (`user.reg` / `system.reg`). - **Updater Loop Prevention**: Abnormal game exits can leave behind `.require_update`, `help.txt`, or `_pending` folders that cause `osu!.exe` to boot into the Bancho updater and lose command-line parameters. The launcher purges these markers before launch to ensure the `-devserver ez-pp.farm` flag is always preserved. - **Automated Patcher Bytecode Patching**: The Windows patcher (`osu!.patcher.exe`) targets .NET 4.5+ and embeds `ManagedInjector.Lib`. In Wine prefixes using the .NET Framework 4.0 runtime, generic `Marshal.SizeOf()` and `Marshal.PtrToStructure()` methods do not exist, and redirected standard I/O causes `Console.ReadKey()` crashes. EZPPLauncher automatically inspects and patches the patcher binary and its embedded Costura assemblies in-place, enabling seamless injection into the running game process under Wine. - **Hardware-Accelerated Theme Media**: Large VP8/VP9/AV1 theme videos are automatically transcoded to hardware-decoded H.264/AAC. The launcher manages a sandboxed static FFmpeg build in `~/.ezpplauncher/bin` (with fallback to system FFmpeg). Theme assets are served over an internal loopback server supporting HTTP range requests to minimize memory consumption. - **Native macOS Window Rounding**: Native Cocoa window clipping applies rounded corners and transparent borders to the Tauri window. --- ### 🐧 Linux (Partially Supported) Linux support is functional but partial, relying on external community tools rather than built-in prefix management: - **External Tooling Requirements**: - **[`osu-winello`](https://github.com/NelloKudo/osu-winello)**: osu! must be installed and managed through osu-winello. EZPPLauncher detects the `osu-wine` binary in standard search locations (`/usr/bin`, `/usr/local/bin`, and `~/.local/bin`). - **`wmctrl`**: Required for game process discovery and active window title detection under X11 and XWayland (`sudo pacman -S wmctrl` on Arch or `sudo apt install wmctrl` on Debian/Ubuntu). - **Feature Limitations**: - **OpenTabletDriver**: Automated daemon start/stop is Windows-only. On Linux, run OpenTabletDriver as a user systemd service (`systemctl --user enable --now opentabletdriver.service`). - **Patcher Stream**: Linux is constrained to the **stable** patcher stream. The experimental stream (.NET 8 runtime) is not supported on Linux. - **Theme Streaming via Loopback**: Tauri uses WebKit2GTK on Linux, which does not support byte-range streaming over custom application URI schemes. EZPPLauncher automatically spins up an internal loopback HTTP server to stream large video/audio theme assets with low memory overhead. --- ## 🎮 Discord Rich Presence Studio The launcher features an interactive Discord Rich Presence editor accessible from **Settings → Discord Presence**: - **Live Profile Mockup**: Visualizes your presence card exactly as it appears inside Discord. - **Stat Placeholders**: Insert live interpolated values: - `{username}`: Player display name - `{rank}`: Current global rank - `{pp}`: Total performance points - `{accuracy}`: Overall hit accuracy percentage - `{playcount}`: Account playcount - `{version}`: Active launcher version - **Custom Buttons**: Add interactive links (e.g. your EZPPFarm profile or twitch stream). - **Presence Presets**: One-click presets for default launcher idle, grinding, competitive matches, and relax sessions. --- ## 🎨 Launcher Theming The launcher supports two theme generations: - **Theme API 2.0 (Recommended)**: A declarative format described in `theme.json` with assets, audio, Lottie animations, and layered elements. - Can be built and edited visually with the **in-app Theme Editor**. - Supports custom **Svelte 5 component layers** with Monaco editor integration for rich interactive widgets. - Features visual WHEN/IF/THEN rule building or sandboxed JavaScript scripting. - Exported as shareable `.ezpplauncher-theme` zip archives. - **Theme API 1.0**: Standalone bundled Svelte themes compiled via the CLI. For detailed documentation, schemas, and packaging guides, refer to [THEME_API_V2.md](THEME_API_V2.md). --- ## 🪵 Logs & Diagnostics Output from the launcher, osu!, and the patcher is organized under `.ezpplauncher/logs` in your user home directory (`%USERPROFILE%\.ezpplauncher\logs` on Windows, `~/.ezpplauncher/logs` on macOS and Linux): | File | Source | | -------------- | ------------------------------------------------------------------------- | | `launcher.log` | Launcher lifecycle, backend commands, webview console and uncaught errors | | `osu.log` | osu! game client and updater stdout/stderr | | `patcher.log` | Patcher stdout/stderr and injection diagnostic messages | - **Session Archiving**: When a new session begins or when any active log file reaches 5 MiB, the active logs are bundled into a compressed `logs__