diff options
Diffstat (limited to 'packages/docs/content/en/architecture.mdx')
| -rw-r--r-- | packages/docs/content/en/architecture.mdx | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/packages/docs/content/en/architecture.mdx b/packages/docs/content/en/architecture.mdx new file mode 100644 index 0000000..5f55c5e --- /dev/null +++ b/packages/docs/content/en/architecture.mdx @@ -0,0 +1,281 @@ +--- +title: Architecture +description: Technical architecture and design of DropOut Minecraft Launcher +--- + +# Architecture + +DropOut is built with a modern tech stack designed for performance, security, and cross-platform compatibility. + +## Technology Stack + +### Backend (Rust) +- **Framework**: Tauri v2 +- **Language**: Rust (Edition 2021) +- **Async Runtime**: Tokio +- **HTTP Client**: reqwest with native-tls + +### Frontend (Svelte) +- **Framework**: Svelte 5 (with runes) +- **Styling**: Tailwind CSS 4 +- **Build Tool**: Vite with Rolldown +- **Package Manager**: pnpm + +### Documentation +- **Framework**: Fumadocs with React Router v7 +- **Content**: MDX files +- **Styling**: Tailwind CSS 4 + +## System Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ Frontend (Svelte 5) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ +│ │ Stores │ │Components│ │ UI Views │ │Particles│ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ │ +│ │ │ │ │ │ +│ └─────────────┴─────────────┴──────────────┘ │ +│ │ │ +│ Tauri Commands │ +│ Events/Emitters │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────┴──────────────────────────────┐ +│ Backend (Rust/Tauri) │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ main.rs (Commands) │ │ +│ └──────────────┬──────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────┴───────────────────────────────┐ │ +│ │ Core Modules │ │ +│ │ ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │ │ +│ │ │ Auth │ │Download│ │ Java │ │ Instance │ │ │ +│ │ └──────┘ └────────┘ └──────┘ └──────────┘ │ │ +│ │ ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │ │ +│ │ │Fabric│ │ Forge │ │Config│ │Manifest │ │ │ +│ │ └──────┘ └────────┘ └──────┘ └──────────┘ │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ Utils & Helpers │ │ +│ │ • ZIP extraction • Path utilities │ │ +│ └─────────────────────────────────────────────────┘ │ +└──────────────────────────┬──────────────────────────────┘ + │ + External APIs + │ + ┌──────────────────┼──────────────────┐ + │ │ │ + ┌─────┴────┐ ┌──────┴─────┐ ┌──────┴─────┐ + │ Mojang │ │ Fabric │ │ Forge │ + │ APIs │ │ Meta │ │ Maven │ + └──────────┘ └────────────┘ └────────────┘ +``` + +## Core Components + +### Frontend State Management + +DropOut uses **Svelte 5 runes** for reactive state management: + +```typescript +// stores/auth.svelte.ts +export class AuthState { + currentAccount = $state<Account | null>(null); // Reactive + isLoginModalOpen = $state(false); + + $effect(() => { // Side effects + // Auto-runs when dependencies change + }); +} +``` + +**Key Stores:** +- `auth.svelte.ts`: Authentication state and login flow +- `settings.svelte.ts`: Launcher settings and Java detection +- `game.svelte.ts`: Game running state and logs +- `instances.svelte.ts`: Instance management +- `ui.svelte.ts`: UI state (toasts, modals, active view) + +### Backend Architecture + +#### Command Pattern +All Tauri commands follow this structure: + +```rust +#[tauri::command] +async fn command_name( + window: Window, + state: State<'_, SomeState>, + param: Type, +) -> Result<ReturnType, String> { + emit_log!(window, "Status message"); + // Async logic + Ok(result) +} +``` + +#### Event Communication + +**Rust → Frontend (Progress Updates):** +```rust +window.emit("launcher-log", "Downloading...")?; +window.emit("download-progress", progress_struct)?; +``` + +**Frontend → Rust (Commands):** +```typescript +import { invoke } from "@tauri-apps/api/core"; +const result = await invoke("start_game", { versionId: "1.20.4" }); +``` + +### Core Modules + +#### Authentication (`core/auth.rs`) +- **Microsoft OAuth 2.0**: Device Code Flow +- **Offline Authentication**: Local UUID generation +- **Token Management**: Refresh token storage and auto-refresh +- **Xbox Live Integration**: Full authentication chain + +**Authentication Flow:** +1. Device Code Request → MS Token +2. Xbox Live Authentication +3. XSTS Authorization +4. Minecraft Token Exchange +5. Profile Fetching + +#### Downloader (`core/downloader.rs`) +- **Concurrent Downloads**: Configurable thread pool +- **Resume Support**: `.part` and `.part.meta` files +- **Multi-segment Downloads**: Large files split into chunks +- **Checksum Verification**: SHA1/SHA256 validation +- **Progress Tracking**: Real-time events to frontend + +#### Java Management (`core/java.rs`) +- **Auto-detection**: Scans system paths +- **Adoptium Integration**: Download JDK/JRE on-demand +- **Catalog Caching**: 24-hour cache for version lists +- **Installation**: Extracts to app data directory +- **Cancellation**: Atomic flag for download cancellation + +#### Fabric Support (`core/fabric.rs`) +- **Meta API Integration**: Fetch loader versions +- **Profile Generation**: Creates version JSON +- **Library Resolution**: Maven artifact handling + +#### Forge Support (`core/forge.rs`) +- **Installer Execution**: Runs Forge installer +- **Profile Parsing**: Extracts install profile +- **Library Management**: Handles Forge-specific libraries + +#### Instance System (`core/instance.rs`) +- **Isolation**: Separate directories per instance +- **Configuration**: Per-instance settings +- **Mod Management**: Instance-specific mods +- **Version Locking**: Reproducible environments + +#### Version Management +- **Manifest Parsing** (`manifest.rs`): Mojang version manifest +- **Inheritance System** (`version_merge.rs`): Parent version merging +- **Game Version** (`game_version.rs`): JSON parsing and validation +- **Rules Engine** (`rules.rs`): OS/feature conditional logic + +### File Structure + +``` +~/.local/share/com.dropout.launcher/ (Linux) +~/Library/Application Support/com.dropout.launcher/ (macOS) +%APPDATA%/com.dropout.launcher/ (Windows) +├── versions/ +│ └── <version_id>/ +│ ├── <version_id>.json +│ ├── <version_id>.jar +│ └── natives/ +├── libraries/ +│ └── <maven-path>/ +├── assets/ +│ ├── indexes/ +│ └── objects/ +├── instances/ +│ └── <instance_name>/ +│ ├── mods/ +│ ├── config/ +│ └── saves/ +├── java/ +│ └── <version>/ +├── config.json +└── accounts.json +``` + +## Data Flow + +### Game Launch Sequence + +1. **Frontend**: User clicks "Launch Game" +2. **Command**: `start_game(version_id)` invoked +3. **Backend Processing**: + - Load version JSON (with inheritance) + - Resolve all libraries + - Download missing assets + - Extract native libraries + - Build classpath + - Construct JVM arguments + - Replace placeholders +4. **Process Spawn**: Launch Java with arguments +5. **Stream Logs**: Emit stdout/stderr to frontend +6. **Monitor**: Track game process status + +### Download Flow + +1. **Queue Creation**: List of files to download +2. **Concurrent Processing**: Semaphore-limited threads +3. **Resume Check**: Verify existing `.part` files +4. **Download**: Multi-segment for large files +5. **Verification**: Checksum validation +6. **Progress Events**: Real-time updates to UI +7. **Completion**: Move from `.part` to final location + +### Authentication Flow + +1. **Device Code Request**: Get user code + device code +2. **User Authorization**: User visits URL and enters code +3. **Token Polling**: Frontend polls for completion +4. **Token Exchange**: MS token → Xbox → XSTS → Minecraft +5. **Profile Fetch**: Get username and UUID +6. **Storage**: Save account with refresh token +7. **Auto-refresh**: Background token refresh on expiry + +## Platform-Specific Considerations + +### Linux +- Uses GTK WebView (`webkit2gtk`) +- System Java detection from `/usr/lib/jvm` +- Desktop file integration + +### macOS +- Uses system WebKit +- App bundle structure +- Keychain integration for secure storage + +### Windows +- Uses WebView2 runtime +- Registry Java detection +- MSI installer support +- No console window in release builds + +## Performance Optimizations + +- **Concurrent Downloads**: Parallel asset/library downloads +- **Lazy Loading**: Load version manifests on-demand +- **Caching**: Java catalog, version manifests +- **Native Code**: Rust for CPU-intensive operations +- **Async I/O**: Tokio for non-blocking operations + +## Security Features + +- **Token Encryption**: Secure storage of auth tokens +- **HTTPS Only**: All external API calls +- **Checksum Validation**: File integrity verification +- **Sandboxed Execution**: Tauri security model +- **No Arbitrary Code**: No eval or dynamic code execution |