MoonWell Launcher

MoonWell Launcher is the desktop launcher for MoonWell, a private World of Warcraft: Wrath of the Lich King server focused on a player-friendly experience without excessive grind and with stronger social play.

The launcher is responsible for:

• logging in to a player's MoonWell account
• downloading and synchronizing client files
• displaying launcher news
• launching the game client

Stack

• Flutter desktop
• Dart
• flutter_bloc for launcher UI state
• get_it and injectable for dependency injection
• dio for Web API and file download requests
• flutter_secure_storage for launcher sessions
• shared_preferences for non-sensitive launcher preferences

Prerequisites

Use the latest stable Flutter SDK available from the official Flutter release channel. This project does not support FVM-pinned SDK workflows.

flutter pub get

If flutter is unavailable, restart the shell after installing Flutter or fix PATH so flutter --version works.

Configuration

Set the launcher Web API base URL at compile time:

--dart-define=MOONWELL_API_BASE_URL=https://host

Set the public AppCast feed URL to enable Windows launcher self-updates:

--dart-define=MOONWELL_APPCAST_URL=https://host/launcher/updates/appcast.xml

The updater is disabled when MOONWELL_APPCAST_URL is omitted. Production feeds must use HTTPS.

Example run command:

flutter run -d windows --dart-define=MOONWELL_API_BASE_URL=https://host --dart-define=MOONWELL_APPCAST_URL=https://host/launcher/updates/appcast.xml

Development

Regenerate dependency injection after changing injectable services:

dart run build_runner build --delete-conflicting-outputs

Run static analysis:

flutter analyze

See docs/linting.md for the full format, analyze, test, and Lefthook pre-commit workflow.

Build the Windows launcher:

flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://host --dart-define=MOONWELL_APPCAST_URL=https://host/launcher/updates/appcast.xml

The Inno Setup installer script lives at installer/moonwell_launcher.iss. See docs/launcher_self_update.md for the AppCast format, signing keys, and manual release procedure.

Architecture

The UI lives in lib/app, with shared UI widgets under lib/app/widgets. Launcher domain models, sync use cases, API clients, installation services, and preferences live under lib/features.

The launcher sync flow is manifest-based:

1. authenticate against the MoonWell Web API
2. fetch the client manifest
3. scan the selected installation directory
4. compare local files to the manifest
5. remove stale files outside ignored directories
6. download missing or changed files to temporary part files
7. verify size and SHA-256 before replacing client files
8. launch Wow.exe from the selected client directory

See docs/launcher_web_api_spec.md for the API and sync contract.

Documentation

• AGENTS.md: architecture, commands, and repository rules for contributors
• TODO.md: remaining verification and maintenance tasks
• docs/linting.md: format, analyze, test, and Lefthook workflow
• docs/project_review.md: project review with strengths, weaknesses, and upgrade feasibility notes
• docs/launcher_web_api_spec.md: current launcher Web API and sync behavior
• docs/launcher_self_update.md: Windows self-update and release operations