path: root/packages/docs/content/zh/development/implementation.mdx

---
title: 内部实现
description: DropOut 核心功能的详细实现和技术规范
---

# 内部实现

本页详细介绍了启动器各个核心模块的技术实现细节、数据结构和处理流程。

## 1. 身份验证系统 (Authentication)

身份验证链包含多个异步步骤，任何一步失败都会中断整个流程。DropOut 采用 Microsoft Device Code Flow 实现免重定向的安全登录。

### 1.1 详细流程
1.  **设备代码请求**: 
    - 调用 `https://login.microsoftonline.com/consumers/oauth2/v2.0/devicecode`
    - 获取用户验证码及验证 URL。
2.  **令牌交换**: 轮询 `/oauth2/v2.0/token` 获取主访问令牌 (Access Token) 和刷新令牌 (Refresh Token)。
3.  **Xbox Live 认证**: 获取 `Token` 和 `uhs` (User Hash)。
4.  **XSTS 授权**: 重定向至 `rp://api.minecraftservices.com/`。
5.  **Minecraft 登录**: 使用 `XBL3.0 x=<uhs>;<xsts_token>` 格式令牌换取最终的游戏 Access Token。

### 1.2 账户存储与安全
账户数据持久化在 `accounts.json` 中，包含账户类型及加密后的令牌信息：
```json
{
  "active_account_uuid": "...",
  "accounts": [
    {
      "type": "Microsoft",
      "username": "...",
      "uuid": "...",
      "access_token": "...",
      "refresh_token": "...",
      "expires_at": 1234567890
    },
    { "type": "Offline", "username": "Player", "uuid": "..." }
  ]
}
```
**离线 UUID**: 使用基于用户名的确定性 UUID v3，确保本地存档和配置的一致性。

```rust
// core/auth.rs 实现详情
pub fn generate_offline_uuid(username: &str) -> String {
    let namespace = Uuid::NAMESPACE_OID;
    Uuid::new_v3(&namespace, username.as_bytes()).to_string()
}
```

### 1.3 身份验证相关接口
| 命令 / 事件 | 类型 | 说明 |
| :--- | :--- | :--- |
| `start_microsoft_login` | Invoke | 启动设备流并返回验证码 |
| `complete_microsoft_login` | Invoke | 轮询并完成全套身份验证链 |
| `login_offline` | Invoke | 创建并切换至离线账户 |
| `auth-progress` | Event | 实时上报认证进度（如 "Xbox Live Auth..."） |

---

## 2. Java 运行环境管理 (Java Runtime)

### 2.1 目录与元数据
Java 目录 (Catalog) 缓存了来自 Adoptium 的可用版本及其平台特定链接。
-   **存储**: `java_catalog.json` 记录了各个版本的 SHA256 校验和及文件大小。

```json
// java_catalog.json 结构示例
{
  "releases": [
    {
      "major_version": 17,
      "image_type": "jdk",
      "version": "17.0.9+9",
      "download_url": "...",
      "checksum": "...",
      "file_size": 123456789
    }
  ],
  "cached_at": 1700000000
}
```

-   **检测**: 通过对候选路径执行 `java -version` 命令，解析其 `stderr` 输出中的版本字符串和 64-Bit 标识。

```rust
// core/java.rs 检测逻辑
fn check_java_installation(path: &PathBuf) -> Option<JavaInstallation> {
    let mut cmd = Command::new(path);
    cmd.arg("-version");
    // 解析 stderr 输出中的 "version" 关键字信息
}
```

### 2.2 自动安装逻辑
1.  **下载**: 支持断点续传，大型文件通过分片并行下载。
2.  **解压**: 针对不同操作系统处理压缩包（macOS 处理 .tar.gz 内部的 .app 结构，Windows 处理 .zip）。
3.  **验证**: 下载后强制进行哈希校验，确保运行时环境的完整性。

### 2.3 Java 管理相关接口
| 命令 / 事件 | 类型 | 说明 |
| :--- | :--- | :--- |
| `detect_java` | Invoke | 扫描系统已安装的 Java 环境 |
| `download_adoptium_java` | Invoke | 启动异步下载并自动解压配置 |
| `cancel_java_download` | Invoke | 通过原子标志位取消当前的下载任务 |
| `java-download-progress` | Event | 报告文件大小、速度、百分比和 ETA |

---

## 3. 游戏启动逻辑与 JVM 优化

### 3.1 内存分配方案
-   **Xmx & Xms**: 建议将初始内存与最大内存设为一致。
-   **策略**: 启动器会自动根据系统总内存和 Java 架构提示用户最优分配，且启动器生成的参数具有最高优先级。

### 3.2 G1GC 优化策略
针对 1.17+ 版本及高负载模组环境，DropOut 默认注入精简的 G1GC 参数链：
```bash
-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 
-XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC 
```

---

## 4. 模组加载机制 (Mod Loaders)

### 4.1 版本合并 (Inheritance)
模组加载器通过 `inheritsFrom` 字段链接原版 Minecraft 版本 JSON。

```json
// 典型的 Fabric 版本配置 (部分)
{
  "id": "fabric-loader-0.15.0-1.20.4",
  "inheritsFrom": "1.20.4",
  "mainClass": "net.fabricmc.loader.impl.launch.knot.KnotClient",
  "libraries": [
    {
      "name": "net.fabricmc:fabric-loader:0.15.0",
      "url": "https://maven.fabricmc.net/"
    }
  ]
}
```

启动阶段执行以下合并：
1.  **库优先级**: 加载器自身的库（如 Fabric Loader）排在原版库之前。
2.  **主类覆盖**: `mainClass` 始终取自子级定义（即模组加载器的入口，如 Fabric 的 `KnotClient`）。
3.  **参数链**: 合并 `jvm` 和 `game` 参数数组，自动剔除不适用的系统规则。

```rust
// core/version_merge.rs 合并核心实现
pub fn merge_versions(child: GameVersion, parent: GameVersion) -> GameVersion {
    let mut merged_libraries = child.libraries;
    merged_libraries.extend(parent.libraries);
    // 合并参数逻辑并返回新的 GameVersion 实例
}
```

### 4.2 库路径解析 (Maven)
启动器实现了完整的 Maven 路径转换逻辑：
`group:artifact:version` → `group_path/artifact/version/artifact-version.jar`

```rust
// core/maven.rs 坐标转换路径逻辑
pub fn to_path(&self) -> String {
    let group_path = self.group.replace('.', "/");
    format!("{}/{}/{}/{}-{}.{}", 
        group_path, self.artifact, self.version, 
        self.artifact, self.version, self.extension
    )
}
```

### 4.3 模组安装接口
启动器根据不同加载器的特性采用差异化安装策略。

#### Forge 安装逻辑
对于 Forge，DropOut 会下载官方 Installer 并通过子进程调用 Java 运行标准安装程序，确保这一过程与官方流程完全一致（包括字节码补丁生成）。

```rust
// core/forge.rs 调用官方安装器 (简化示例)
Command::new(java_path)
    .args(&[
        "-jar", 
        installer_path.to_str().unwrap(), 
        "--installClient", 
        game_dir.to_str().unwrap()
    ])
    .output()?;
```

| 命令 / 事件 | 类型 | 说明 |
| :--- | :--- | :--- |
| `install_fabric` | Invoke | 下载 Fabric 库并生成继承 JSON |
| `install_forge` | Invoke | 运行 Forge Installer 并执行字节码打桩 |
| `mod-loader-progress` | Event | 报告安装阶段（如 "processing", "complete"） |

---

## 5. 通讯与监控系统

### 5.1 事件总线 (Event Bus)
后端通过 Tauri 的 `Window` 实例向上层发送异步脉冲。

```rust
// 后端 emit_log! 宏简化日志外发
macro_rules! emit_log {
    ($window:expr, $msg:expr) => {
        let _ = $window.emit("launcher-log", $msg);
        println!("[Launcher] {}", $msg);
    };
}
```

-   **`launcher-log`**: 通用的控制台输出流，用于全局操作轨迹记录。
-   **`game-stdout` / `game-stderr`**: 捕获游戏子进程的标准输出与错误，通过独立线程实时回传前端。

```typescript
// 前端监听示例 (Svelte 5)
import { listen } from "@tauri-apps/api/event";

const unlisten = await listen("launcher-log", (event) => {
    logStore.addLine(event.payload);
});
```

-   **`version-installed`**: 异步任务完成后通知 UI 更新版本列表状态。

### 5.2 启动日志脱敏
为防止敏感信息泄露至第三方日志平台，启动器在记录启动指令前会对令牌进行遮蔽。

```rust
// 基于 main.rs 的参数遮蔽逻辑 (部分)
let masked_args: Vec<String> = args.iter().enumerate().map(|(i, arg)| {
    if i > 0 && (args[i-1] == "--accessToken" || args[i-1] == "--uuid") {
        "***".to_string()
    } else {
        arg.clone()
    }
}).collect();
```

---

## 6. 架构与开发规范

### 6.1 核心架构模式

#### 后端命令模式 (Tauri)
所有后端功能均封装为异步 Command，并通过 `State` 注入全局状态。

1. **定义命令**:
```rust
#[tauri::command]
async fn start_game(
    window: Window,
    auth_state: State<'_, AccountState>,
    config_state: State<'_, ConfigState>
) -> Result<String, String> {
    emit_log!(window, "Starting game launch...");
    // 业务逻辑...
    Ok("Success".into())
}
```

2. **注册命令 (main.rs)**:
```rust
tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![start_game, ...])
```

3. **前端调用**:
```typescript
import { invoke } from "@tauri-apps/api/core";
// 参数名需与 Rust 函数参数保持蛇形/驼峰对应
const result = await invoke("start_game", { versionId: "1.20.4" });
```

#### 错误处理模式
所有 Tauri 命令统一返回 `Result<T, String>`，其中 Err 类型固定为 String，以便前端直接展示错误信息。

```rust
// 统一使用 map_err 将错误转换为 String
.await
.map_err(|e| e.to_string())?;

// 前端捕获
try {
    await invoke("...")
} catch (e) {
    // e 即为 Rust 返回的错误字符串
    console.error(e); 
}
```

#### 前端状态管理 (Svelte 5 Runes)
前端全线采用 Svelte 5 的 `Runes` 系统 (`$state`, `$effect`) 替代旧版的 `writable` stores。

```typescript
// ui/src/stores/auth.svelte.ts
export class AuthState {
  // 使用 $state 定义响应式数据
  currentAccount = $state<Account | null>(null);
  isLoginModalOpen = $state(false);

  constructor() {
    // 初始化逻辑
  }
}

// 导出单例用于全局访问
export const authState = new AuthState();
```

#### 前端视图路由 (Manual Routing)
DropOut 不使用常规的 URL 路由，而是通过全局状态管理当前激活的视图组件。

```typescript
// ui/src/stores/ui.svelte.ts
export class UIState {
    activeView = $state("home"); // "home" | "versions" | "settings"
    
    setView(view: string) {
        this.activeView = view;
    }
}
```

```svelte
<!-- App.svelte -->
<script>
    import { uiState } from "./stores/ui.svelte";
</script>

{#if uiState.activeView === "home"}
    <HomeView />
{:else if uiState.activeView === "settings"}
    <SettingsView />
{/if}
```

### 6.2 开发最佳实践
1.  **静默刷新**: 在调用 `start_game` 前检查 `expires_at`，若过期则调用 `refresh_full_auth`。
2.  **UA 伪装**: 微软认证 WAF 会拦截空 UA 请求，务必在 `reqwest` 客户端中模拟真实 UA。
3.  **日志脱敏**: 启动日志中需屏蔽 `--accessToken` 和 `--uuid` 等敏感参数值。

### 6.3 未来路线图 (Roadmap)
-   **账户多端同步**: 探索 OS 级加密存储方案以替代现有明文 `accounts.json`。
-   **自动依赖解析**: 安装模组时自动解析并下载 Modrinth/CurseForge 上的前置库。
-   **智能冲突检测**: 启动前扫描 `mods/` 文件夹，识别潜在的类冲突或版本不匹配。
-   **配置文件共享**: 支持一键导出/导入完整的实例配置包（Modpack）。