sindoring
7799b33239
Include the prepared cleanup of both client roots while preserving manifest-listed files and unrelated user state. Verified on Windows through FVM: full formatting and analysis, all 76 tests, production dry run, x64 build and DSA signature verification.
199 lines
7.7 KiB
Markdown
199 lines
7.7 KiB
Markdown
# MoonWell Launcher
|
|
|
|
MoonWell Launcher is the desktop launcher for MoonWell, a private World of
|
|
Warcraft 1.12.1 server on vMaNGOS, focused on a player-friendly experience
|
|
without excessive grind and with stronger social play.
|
|
|
|
The Windows executable requests administrator privileges on startup so it can
|
|
synchronize game clients installed under protected directories such as
|
|
`Program Files`.
|
|
|
|
Launcher version labels are read from the packaged application metadata. Change
|
|
only the `version: X.Y.Z+N` value in `pubspec.yaml`; login, launcher status,
|
|
Windows metadata, installer packaging, and AppCast are synchronized from it.
|
|
|
|
The launcher is responsible for:
|
|
|
|
- logging in to a player's MoonWell account
|
|
- registering new MoonWell game accounts
|
|
- downloading and synchronizing client files
|
|
- displaying launcher news
|
|
- displaying the live status of the first configured realm
|
|
- requesting a single-use game ticket and launching the game client without
|
|
putting credentials in command-line arguments
|
|
- starting the Rust MoonWell client on Windows and macOS
|
|
|
|
During synchronization, the manifest is authoritative for `Data/` and
|
|
`WoW/Data/`: files absent from it and unused subdirectories are removed.
|
|
Legacy `WoW.exe` and DLLs in the installation root or `WoW/` are also removed
|
|
when absent from the manifest. Required DLLs stay; player settings, addons,
|
|
logs, screenshots, and other files outside these cleanup areas are preserved.
|
|
The obsolete `Extentions/` directory in either client root is cleaned the same
|
|
way and removed when no manifest files require it.
|
|
Cleanup runs even when all manifest files are already up to date.
|
|
|
|
## 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.
|
|
|
|
```powershell
|
|
fvm flutter pub get
|
|
```
|
|
|
|
Verify the configured SDK with `flutter --version`.
|
|
|
|
## Configuration
|
|
|
|
Set the launcher Web API base URL at compile time:
|
|
|
|
```powershell
|
|
--dart-define=MOONWELL_API_BASE_URL=https://moon-well.online
|
|
```
|
|
|
|
Set the public AppCast feed URL to enable Windows launcher self-updates:
|
|
|
|
```powershell
|
|
--dart-define=MOONWELL_APPCAST_URL=https://moon-well.online/appcast.xml
|
|
```
|
|
|
|
The updater is disabled when `MOONWELL_APPCAST_URL` is omitted. Production
|
|
feeds must use HTTPS.
|
|
|
|
The game's auth endpoint is read from `realmlist.wtf` in the selected client
|
|
folder. For builds that pin an endpoint, set
|
|
`--dart-define=MOONWELL_AUTH_ADDRESS=login.example:3724` instead. This endpoint is
|
|
the vMaNGOS auth server, separate from the realm's world port and the Web API.
|
|
|
|
Russian 1.12.1 language archives are regular manifest files under `Data/ruRU`
|
|
(or `WoW/Data/ruRU` for a nested install). They are downloaded and verified with
|
|
the same size and SHA-256 checks as the base client. The launcher passes
|
|
`WOW_LOCALE=auto` to the game: an installed pack selects Russian, and a base-only
|
|
install selects English, regardless of the launcher's inherited environment.
|
|
|
|
Example run command:
|
|
|
|
```powershell
|
|
flutter run -d windows --dart-define=MOONWELL_API_BASE_URL=https://moon-well.online --dart-define=MOONWELL_APPCAST_URL=https://moon-well.online/appcast.xml
|
|
```
|
|
|
|
## Development
|
|
|
|
Run the component catalog from its standalone workspace:
|
|
|
|
```powershell
|
|
cd widgetbook
|
|
dart run build_runner build
|
|
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:
|
|
|
|
```powershell
|
|
dart run build_runner build --delete-conflicting-outputs
|
|
```
|
|
|
|
Run static analysis:
|
|
|
|
```powershell
|
|
flutter analyze
|
|
```
|
|
|
|
See `docs/linting.md` for the full format, analyze, test, and Lefthook
|
|
pre-commit workflow.
|
|
|
|
Build the Windows launcher:
|
|
|
|
```powershell
|
|
flutter build windows --dart-define=MOONWELL_API_BASE_URL=https://moon-well.online --dart-define=MOONWELL_APPCAST_URL=https://moon-well.online/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.
|
|
|
|
Run a safe local production-release rehearsal:
|
|
|
|
```powershell
|
|
.\tool\deploy_launcher.ps1 `
|
|
-DryRun `
|
|
-ExpectedVersion 1.0.2 `
|
|
-ReleaseNotes "Исправления и улучшения MoonWell Launcher."
|
|
```
|
|
|
|
Remove `-DryRun` only after reviewing the generated installer and AppCast.
|
|
See `docs/production_deploy.md` for required environment variables, production
|
|
defaults, safety checks, and failure recovery.
|
|
|
|
Local deploy credentials are read from the ignored root `.env`; use
|
|
`.env.example` as the safe template. Process and CI environment variables
|
|
override values from the file.
|
|
|
|
## 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 and automatically synchronize a saved client
|
|
installation
|
|
3. refresh the manifest every five minutes while the launcher is open and
|
|
automatically synchronize when the server build changes
|
|
4. scan the selected installation directory
|
|
5. compare local files to the manifest
|
|
6. remove stale files outside ignored directories
|
|
7. download missing or changed files to temporary part files
|
|
8. verify size and SHA-256 before replacing client files
|
|
9. request a short-lived game ticket for build 5875 and launch MoonWell from the
|
|
selected client directory with authorization in its child environment
|
|
|
|
The selected folder must contain `MoonWell.exe` on Windows, or `MoonWell.app`
|
|
on macOS, and your own 1.12.1 data in `Data/` or `WoW/Data/`. macOS launches the
|
|
bundle's `Contents/MacOS/launch` directly so the launcher keeps a handle to the
|
|
game process. `benilla-config/` stays beside the EXE or `.app`.
|
|
|
|
The ticket's account and temporary password become `WOW_USER` and `WOW_PASS`;
|
|
the launcher also sets `WOW_HOST`, `WOW_DATA`, and `BENILLA_HOME` for that child
|
|
only. Launching does not clear the WoW cache or modify `WTF/Config.wtf`.
|
|
The ticket is consumed by `realmd` after a successful proof; a new login attempt
|
|
requires a fresh ticket from the launcher.
|
|
|
|
In the local WSL deployment, Web API traffic uses the web service's published
|
|
port 8080, while game authorization and the world use ports 3724 and 8085.
|
|
The web application writes ticket SRP data to `realmd.launcher_ticket`; the
|
|
modified auth server consumes it. No additional web/core endpoint is required.
|
|
Distribute the MoonWell executable and the 1.12.1 data in the client manifest
|
|
before enabling automatic synchronization for that distribution.
|
|
|
|
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/production_deploy.md`: automated production launcher deployment
|
|
- `docs/widgetbook.md`: Widgetbook use-case generation and catalog conventions
|