EZPPLauncher
EZPPLauncher is a custom launcher for the private osu! server EZPPFarm, built with Rust and Svelte using the Tauri framework.
It enhances the osu! experience with quality-of-life features and integration specifically designed for the EZPPFarm community.
🖼️ Preview
🚀 Features
- Automatically updates osu! before launching
- Automatically start/stop the OpenTabletDriver Daemon (Windows)
- Automatic ingame login
- Patches the osu! client to show misses in Relax and Autopilot (Windows, Linux and macOS via Wine)
- Displays your EZPPFarm stats in the launcher
- Shows the number of imported beatmapsets
- Shows the number of imported skins
- Displays ping to the EZPPFarm server
- Discord Rich Presence
- Performance Display Overlay (currently in experimental patcher release stream)
- Launcher Theming (API 1.0 bundles and API 2.0 declarative themes)
- Advanced theme editor in its own window with freeform text/image/video/shape layers, multi-select and snapping, layer locks, draft recovery, validation and export
- Theme update backups with one-click rollback, plus a trust prompt before running executable API 1.0 themes
- In-app diagnostics for osu!, Wine, the patcher, and the experimental stream's .NET 8 runtime, plus a log-bundle viewer
💻 Supported Platforms
| Platform | Status |
|---|---|
| Windows | ✅ Supported |
| macOS | 🕧 Partially supported (via Wineskin/Whisky/CrossOver) |
| Linux | 🕧 Partially supported (via osu-winello) |
Windows remains the fully supported platform. OpenTabletDriver is Windows-only. On macOS, in-game patching runs the Windows patcher through the same Wine prefix as osu!. The stable patcher stream needs no extra runtime; the experimental stream needs the .NET 8 Desktop Runtime installed in that prefix.
macOS
osu! stable is a Windows build, so on macOS it runs inside a Wine wrapper. EZPPLauncher
supports Wineskin wrappers (the usual osu!.app wine skin), Whisky bottles and CrossOver
bottles.
The setup wizard automatically looks for Wineskins in /Applications and ~/Applications.
If detection fails, choose Browse and pick the osu!.app wrapper itself (or a Wine prefix
folder); the launcher resolves the osu! installation inside it, so there is no need to open the
bundle's package contents.
Large VP8/VP9/AV1 theme videos are transcoded once to a cached 720p H.264/AAC file so WebKit
can use the Mac's hardware decoder. The first large video triggers a one-time (~63 MB) download
of a signed static FFmpeg 9.0.2 build from ffmpeg.martin-riedl.de into ~/.ezpplauncher/bin;
the launcher verifies its pinned SHA-256 and makes it executable. The managed build requires
macOS 12 or newer. If the download fails, a system FFmpeg (Homebrew or MacPorts) is used; without
either, themes still load but large WebM videos remain on WebKit's software decoder and may
stutter. Theme authors can also ship an H.264/MP4 version alongside the WebM.
🪵 Logs
Launcher, osu! and patcher output is written to .ezpplauncher/logs in your home folder:
| File | Contents |
|---|---|
launcher.log |
Launcher lifecycle, webview console output and uncaught errors |
osu.log |
osu! and osu! updater output, including stdout/stderr |
patcher.log |
Patcher output, including stdout/stderr |
A file is only created when that stream actually writes a line. On each new session, or when
any file reaches 5 MiB, all three active files are bundled into a single
logs_<date>_<time>.zip; the five most recent bundles are kept. You can turn file logging off,
open the folder, or browse and filter a bundle in the built-in viewer from Settings → Logging.
On Windows the folder is %USERPROFILE%\.ezpplauncher\logs.
Settings → Diagnostics checks the selected osu! install and write access, the macOS Wine prefix/runtime/version and (for the experimental patcher stream) its .NET 8 runtime, the FFmpeg theme-video transcoder, osu-winello/wmctrl on Linux, and whether the patcher is present. It can copy a plain-text support report or reopen the setup wizard for a guided repair.
🛠 Build From Source
Requirements
- Rust (installed via rustup – recommended for Windows)
- Cargo (comes with rustup)
- CMake
- Bun (JavaScript runtime)
- On macOS: Xcode Command Line Tools (
xcode-select --install)
Steps
# Install all dependencies
bun i
# Build the project
bun run build
After building, the launcher executable will be located at:
# Windows
src-tauri/target/release/ezpplauncher.exe
# macOS
src-tauri/target/release/bundle/macos/EZPPLauncher.app
src-tauri/target/release/bundle/dmg/EZPPLauncher_*.dmg
📁 Project Structure (Simplified)
├── src/ # Frontend (Svelte)
├── src-tauri/ # Backend (Rust)
│ ├── src/macos.rs # Wine/Wineskin support for macOS
│ ├── tauri.conf.json # Tauri configuration
│ └── tauri.macos.conf.json # macOS bundle targets (app + dmg)
├── package.json # Bun project config
└── README.md
🎨 Launcher Themes
By default, the launcher includes several downloadable themes. Themes can be created in two ways:
- Use the built-in advanced editor on the Themes screen. It opens in its own
resizable window with a full launcher home canvas, freeform text/image/video/shape
layers, WebM support,
@fontsourcefonts and custom font imports. It creates API 2.0 themes and can export them as shareable.ezpplauncher-themefiles. - Use the create-ezpplauncher-theme CLI. It supports both API 1.0 Svelte themes and API 2.0 declarative themes.
See THEME_API_V2.md for the full API 2.0 schema, limits and packaging layout. API 1.0 themes continue to load unchanged.