From 81a62402ef6f8900ff092366121a9b7a4263ba52 Mon Sep 17 00:00:00 2001 From: Natsuu Date: Fri, 27 Feb 2026 17:18:25 +0800 Subject: Restructure docs into manual/development and add implementation docs (#94) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary by Sourcery Restructure documentation into separate manual and development sections, introduce detailed internal implementation docs for auth/Java/mod loaders, and update site navigation, landing page links, and MDX tooling (Mermaid, card styling) to match the new structure and tech stack. Enhancements: - Enable Mermaid rendering support in the docs app and add a reusable Mermaid React component. - Refine Docs page rendering by customizing Card styling and removing redundant in-page titles/descriptions rendered by the layout. - Align docs source configuration and routing comments with the new manual-based default paths. Documentation: - Split user-facing docs under a new manual section and move contributor content into a dedicated development section for both English and Chinese. - Add comprehensive internal implementation documentation covering authentication, Java management, mod loader/version merging, event bus, and architecture patterns in both English and Chinese. - Update existing feature docs (mod loaders, Java, authentication) and getting-started/troubleshooting pages to be more conceptual, pointing to implementation docs for technical details. - Refresh architecture docs to reflect the React/Zustand frontend stack and add Mermaid-based architecture diagrams. - Adjust navigation labels, home-page CTAs, and doc links to target the new manual/development structure and routes. --------- Co-authored-by: 简律纯 --- packages/docs/content/en/architecture.mdx | 281 ------------------------------ 1 file changed, 281 deletions(-) delete mode 100644 packages/docs/content/en/architecture.mdx (limited to 'packages/docs/content/en/architecture.mdx') diff --git a/packages/docs/content/en/architecture.mdx b/packages/docs/content/en/architecture.mdx deleted file mode 100644 index 5f55c5e..0000000 --- a/packages/docs/content/en/architecture.mdx +++ /dev/null @@ -1,281 +0,0 @@ ---- -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(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 { - 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/ -│ └── / -│ ├── .json -│ ├── .jar -│ └── natives/ -├── libraries/ -│ └── / -├── assets/ -│ ├── indexes/ -│ └── objects/ -├── instances/ -│ └── / -│ ├── mods/ -│ ├── config/ -│ └── saves/ -├── java/ -│ └── / -├── 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 -- cgit v1.2.3-70-g09d2