92 lines
4.9 KiB
Markdown
92 lines
4.9 KiB
Markdown
# WoW Backup
|
||
|
||
A lightweight, native-feeling desktop application built with Kotlin and Compose Multiplatform to automatically backup and restore World of Warcraft configuration data (WTF and Interface directories) on macOS and Windows.
|
||
|
||
## Overview
|
||
|
||
World of Warcraft stores all UI configurations, macros, keybindings, and addon saved variables in the `WTF/` and `Interface/` folders. Losing this data due to game corruption, accidental deletion, or addon errors can mean losing years of customized setups. **WoW Backup** runs discreetly in the system tray, automatically creates scheduled, timestamped backups (optionally compressed as ZIP archives), and will provide seamless one-click restoration.
|
||
|
||
## Key Features
|
||
|
||
- 🛡️ **System Tray Native Life Cycle**: Lives in the menu bar / system tray with custom template icons matching light/dark OS appearances. Closing the window hides to tray; quitting is explicit.
|
||
- ⚙️ **Smart Auto-Configuration**: Automatically detects standard WoW install locations (supporting retail and classic directories) and validates folder permissions.
|
||
- ⏰ **Automated & Scheduled Backups**: Background scheduler powered by Cardiologist ensures dependable daily backups at a user-defined time.
|
||
- 📦 **Compression & History Management**: Supports both folder replication and ZIP compression, with automatic pruning of backups beyond the configured retention limit (1–30 backups).
|
||
- 🎮 **Game State Detection**: Checks for active WoW processes before running backups to prevent file-locking conflicts, with optional "force backup" override and safety confirmation.
|
||
- 🔔 **Native OS Notifications**: Notifies the user when backups start, succeed, fail, or are skipped due to game execution.
|
||
- 🚀 **Launch at Startup**: Integrated with macOS LaunchAgents (`~/Library/LaunchAgents/`) and Windows Registry (`HKCU\...\Run`).
|
||
- 🎨 **Modern Theming & Customization**: Dynamic Material 3 theming supporting System/Light/Dark modes and configurable accent colors (via MaterialKolor).
|
||
- 🔄 **Restore System (In Progress)**: Interactive restore interface to safely roll back WTF and Interface configurations.
|
||
|
||
---
|
||
|
||
## Tech Stack & Architecture
|
||
|
||
- **Language & Runtime**: Kotlin Multiplatform targeting Desktop (JVM, Java 17+)
|
||
- **UI Framework**: JetBrains Compose Multiplatform with Material 3 Design
|
||
- **Architecture**: MVI / MVVM with Kotlin Coroutines and StateFlow
|
||
- **Scheduling**: `io.github.kevincianfarini.cardiologist` for drift-free daily execution
|
||
- **Logging**: `logback-classic` + `kotlin-logging-jvm` with daily rotation and size archiving in app data directories
|
||
- **Serialization**: `kotlinx-serialization-json` for typed JSON configuration persistence
|
||
- **Theming**: `com.materialkolor:material-kolor` for dynamic palette generation
|
||
|
||
---
|
||
|
||
## Installation & Download
|
||
|
||
Pre-built binaries for macOS, Windows, and Linux are automatically packaged and published on each release.
|
||
|
||
👉 **See [INSTALL.md](INSTALL.md)** for download links, step-by-step installation instructions, Gatekeeper/SmartScreen bypass guidance, and initial setup notes.
|
||
|
||
---
|
||
|
||
## Build & Run
|
||
|
||
### Prerequisites
|
||
- JDK 17 or higher installed
|
||
|
||
### Development Run
|
||
- **macOS / Linux**:
|
||
```shell
|
||
./gradlew :composeApp:run
|
||
```
|
||
- **Windows**:
|
||
```shell
|
||
.\gradlew.bat :composeApp:run
|
||
```
|
||
|
||
### Package Application Distributions
|
||
- **macOS DMG**:
|
||
```shell
|
||
./gradlew :composeApp:packageDmg
|
||
```
|
||
- **Windows MSI**:
|
||
```shell
|
||
.\gradlew.bat :composeApp:packageMsi
|
||
```
|
||
- **Linux DEB**:
|
||
```shell
|
||
./gradlew :composeApp:packageDeb
|
||
```
|
||
|
||
---
|
||
|
||
## Feature Implementation Status
|
||
|
||
| Feature | Plan Document | Status | Description |
|
||
|---|---|---|---|
|
||
| **0. Foundation** | `docs/plans/feature-0-foundation.md` | ✅ **Completed** | Architecture, config persistence, logging, platform abstractions |
|
||
| **1. System Tray** | `docs/plans/feature-1-system-tray.md` | ✅ **Completed** | Tray icon, menu, tray-first lifecycle, window alignment |
|
||
| **2. Configuration** | `docs/plans/feature-2-configuration.md` | ✅ **Completed** | Full settings UI, path validation, native file dialogs, startup manager |
|
||
| **3. Backup Engine** | `docs/plans/feature-3-backup.md` | ✅ **Completed** | Parallel copy, ZIP compression, scheduler, history pruning, notifications |
|
||
| **4. Status Screen** | `docs/plans/feature-4-status.md` | ✅ **Completed** | Live status dashboard, progress indicator, manual backup trigger, shortcuts |
|
||
| **5. Restore Screen** | `docs/plans/feature-5-restore.md` | 🚧 **Pending** | Backup list browser, ZIP extraction, confirmation flow, safety checks |
|
||
| **6. Release Pipeline** | `docs/plans/feature-6-release-pipeline.md` | ✅ **Completed** | GitHub Actions multi-platform release pipeline & packaging automation |
|
||
|
||
---
|
||
|
||
## Application Data Locations
|
||
|
||
- **macOS**: `~/Library/Application Support/WoWBackup/` (Logs: `.../logs/wowbackup.log`)
|
||
- **Windows**: `%APPDATA%\WoWBackup\` (Logs: `...\logs\wowbackup.log`)
|
||
- **Linux**: `~/.config/WoWBackup/` (Logs: `.../logs/wowbackup.log`)
|