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, custom Svelte 5 component layers with Monaco editing and inline compiler diagnostics, gradient/outline/shadow text effects, multi-select and snapping, a drag-and-drop layer tree with moves into and out of nested groups, layer/group transforms with independent X/Y scale and skew, hover group breadcrumbs, on-canvas layer/group rotate handles plus group move and scale handles, layer/group-linked WHEN/IF/THEN logic with quick navigation, safe advanced rule scripts with expressions, branches and loops, draft recovery, validation and export
Theme update backups with one-click rollback, plus a trust prompt before running executable API 1.0 themes or API 2.0 themes with custom Svelte layers
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, custom Svelte 5 components with a Monaco editor, rich text effects (gradient fills, outlines, shadows, decoration and case), WebM support, @fontsource fonts and custom font imports. Themes can switch the launcher chrome between the bundled Lucide, Phosphor and Tabler icon families. Hover a layer and click a crumb in its group path (or double-click it), then use the on-canvas frame or the inspector to move, rotate, scale or skew the group. Logic rules can be linked to layers or groups and edited from their inspectors. Any rule can switch from the visual builder to a sandboxed JavaScript script with variables, expressions, if/else, for/while, visibility actions and navigation; scripts open in a Monaco editor with syntax highlighting, completion, hover docs and inline errors, and can expand to fullscreen. Text layers can display live variables with {name} placeholders and theme-defined starting values, plus read-only clock values such as {time} and {hour} that refresh every second. Scripts are compiled into a safe instruction set and run by the launcher without eval. It creates API 2.0 themes and can export them as shareable .ezpplauncher-theme files.
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.

7.9 KiB Raw Blame History Unescape Escape