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

Install FVM. The repository .fvmrc tracks the latest stable Flutter channel, and all Dart and Flutter commands are run through FVM.

fvm flutter pub get

Verify the configured SDK with fvm flutter --version.

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:

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

Development

Run the component catalog from its standalone workspace:

cd widgetbook
fvm dart run build_runner build
fvm flutter run -d windows

See docs/widgetbook.md for the required use-case naming, knobs, callback, asset, and coverage conventions.

Regenerate dependency injection after changing injectable services:

fvm dart run build_runner build --delete-conflicting-outputs

Run static analysis:

fvm flutter analyze

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

Build the Windows launcher:

fvm 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. Presentation-only design-system components live in lib/app/design_system and are catalogued by the standalone widgetbook/ workspace before they are integrated into production screens. 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
• docs/widgetbook.md: Widgetbook use-case generation and catalog conventions