BAMCLaunch：跨平台栈自研的 Minecraft 启动器

一、核心架构设计：统一接口 + 完全模块化

采用分层架构 + 接口抽象 + 插件化模块设计，彻底解耦业务与平台、功能与视图，保证高内聚低耦合，为后续扩展和维护打下基础。

1. 整体分层架构

┌─────────────────────────────────────────────────┐
│  UI层（自研BAMC UI Kit）                        │
├─────────────────────────────────────────────────┤
│  业务层（模块化功能单元）                        │
├─────────────────────────────────────────────────┤
│  核心适配层（统一接口抽象）                      │
├─────────────────────────────────────────────────┤
│  原生桥接层（平台专属实现）                      │
└─────────────────────────────────────────────────┘

2. 核心模块拆分与统一接口规范

所有模块均通过统一抽象接口对外提供能力，上层业务完全不感知底层实现与平台差异，新增功能/平台仅需实现对应接口，无需修改上层代码。

3. 模块间通信规范

• 采用事件驱动模式，使用全局事件总线实现模块间解耦通信，避免直接依赖

• 状态管理采用Bloc模式，严格分离UI与业务逻辑，保证状态可追踪、可测试，杜绝黑盒逻辑

• 所有耗时操作（下载、解压、安装）均放入独立Isolate执行，完全不阻塞UI线程

二、技术选型：全栈自研 + 桌面优先 + 高鲁棒性

严格遵循核心能力全自研，必要依赖仅选成熟稳定的底层库原则，杜绝过度依赖第三方包，保证代码完全可控、鲁棒性拉满。

1. 基础环境

• Flutter 稳定版（3.22+）：桌面端支持已完全成熟，对Win/Mac/Linux的窗口、文件、进程API支持完善

• Dart SDK 3.0+：利用空安全、模式匹配等特性，从语法层面降低崩溃风险

• 桌面端专属工具链：

  • window_manager：唯一引入的UI底层依赖，用于全平台窗口管理、托盘、标题栏自定义，成熟稳定无替代必要

  • flutter_distributor：全平台打包工具，一键生成Win安装包、Mac dmg、Linux deb/rpm/AppImage

2. 必须全自研的核心能力

1. 统一接口与跨平台适配层

2. 微软OAuth2完整登录链路（含Xbox/XSTS/Minecraft全流程认证）

3. 多线程分块下载引擎（含断点续传、镜像源容错、哈希校验）

4. 全版本MC与模组加载器安装逻辑

5. 游戏启动核心流程与进程管理

6. BAMC UI Kit 全自研组件库

7. 全局异常捕获与容错系统

8. 自动更新与回滚系统

9. 账户信息加密存储模块

3. 可引入的底层依赖（无业务侵入，仅做底层能力支撑）

4. 绝对禁用的依赖

• 任何移动端优先的UI组件库（Material Design/Cupertino/各类安卓风格组件库）

• GetX等黑盒状态管理框架（不利于自研与问题定位）

• 第三方MC启动相关SDK/封装库（保证核心逻辑全自研）

• 非官方维护的、小众的第三方包（降低依赖风险）

三、UI设计：Minecraft × 蔚蓝档案 清新桌面风

完全规避安卓移动端交互，纯桌面端原生交互逻辑，融合两个IP的核心风格，打造辨识度拉满的专属设计语言。

1. 核心设计规范：方块清新风

配色系统

• 主色调：蔚蓝档案经典清新蓝 #64B5F6，搭配MC草方块绿 #7CB342 作为辅助色

• 中性色：柔和米白、低饱和浅灰/深灰，杜绝纯黑纯白，降低视觉疲劳

• 强调色：MC红石红 #E53935（警告/错误）、金块黄 #FDD835（成功/高亮），饱和度调低适配清新风格

• 质感：大面积使用低透明度毛玻璃（BackdropFilter）、柔和线性渐变、轻微阴影，贴合蔚蓝档案的通透感；细节处加入像素线条、方块化点缀，呼应MC风格

布局结构（纯桌面端逻辑）

• 采用左侧固定侧边栏 + 右侧主内容区的经典桌面布局，完全摒弃移动端底部导航、滑动返回等交互

• 侧边栏：固定宽度，放置核心功能入口（主页、版本管理、模组管理、整合包、服务器、账户、设置），选中态有方块化高亮与渐变效果，悬浮时有微动效

• 主内容区：面包屑导航 + 标签页切换 + 卡片式布局，符合桌面端操作习惯；内容区留白充足，卡片圆角8px，边缘加入1px像素线条点缀，兼顾清新感与MC元素

• 标题栏：全自定义，适配不同平台习惯（Mac红绿灯在左，Win窗口控制在右），按钮采用像素风图标，悬浮时有渐变效果，完全替代系统默认标题栏

自研组件库规范

所有组件均为桌面端交互设计，完全规避安卓风格，核心组件设计如下：

1. 按钮：方块化圆角，主按钮采用主色渐变，悬浮时有轻微放大与亮度提升，点击有按压反馈；图标采用线性+像素点缀的自研图标，杜绝Material Design图标

2. 输入框：圆角矩形描边，聚焦时有主色柔和发光效果，前缀图标为像素风，摒弃安卓下划线输入框

3. 列表：卡片式列表项，悬浮有背景色变化，选中有主色边框，全量支持右键菜单（桌面端核心交互），支持键盘方向键导航

4. 进度条：融合MC经验条的方块化填充设计，整体为圆角清新风格，同时支持像素化进度动画，兼顾两个IP的风格

5. 弹窗：毛玻璃背景居中弹窗，标题栏带像素风关闭按钮，内容区留白充足，摒弃安卓底部弹窗、侧边抽屉等移动端交互

6. 字体：正文采用Inter/思源黑体无衬线字体，清晰易读；标题、按钮采用MC像素字体点缀，不通篇使用，避免视觉疲劳

动效设计

• 整体动效柔和流畅，符合蔚蓝档案的清新感，页面切换采用淡入淡出+轻微位移，卡片悬浮有轻微上浮与阴影加深

• MC风格动效仅做点缀：启动时的像素加载动画、下载完成的方块弹出动效、按钮点击的像素颗粒反馈，不喧宾夺主

• 完全适配桌面端鼠标交互：所有可交互元素均有悬浮态、点击态、聚焦态，支持滚轮缩放、键盘快捷键、右键菜单

四、跨平台适配：Win/Mac/Linux 优先全覆盖

针对三大桌面平台做深度适配，保证每个平台的体验符合系统原生习惯，同时上层业务完全无感知。

1. 路径规范适配

严格遵循各平台的系统规范，统一通过IPlatformAdapter暴露给上层，支持用户自定义路径：

• Windows：默认目录 %APPDATA%/.bamclauncher，Java路径自动检测注册表与常规安装目录

• MacOS：默认目录 ~/Library/Application Support/BAMCLauncher，适配沙盒权限，Java路径自动检测/Library/Java与Homebrew安装目录

• Linux：默认目录 ~/.config/bamclauncher，遵循XDG规范，适配Debian/Ubuntu/Fedora/Arch等主流发行版，兼容X11与Wayland

2. 系统能力适配

3. 打包与分发适配

• Windows：生成msi安装包 + 便携版zip，支持一键安装、桌面快捷方式、开始菜单条目

• MacOS：生成dmg安装包，支持Intel/Apple Silicon通用二进制、签名与公证，规避Gatekeeper拦截

• Linux：生成deb/rpm/AppImage/flatpak，覆盖所有主流发行版，AppImage提供便携版

五、鲁棒性与全功能对标方案

1. 高鲁棒性保障体系

全局容错与异常处理

• 采用Zone.runZonedGuarded捕获全量Dart层同步/异步异常，原生层异常通过MethodChannel统一捕获，所有异常均写入日志，绝对杜绝无理由闪退

• 分级错误处理：每个模块独立处理自身异常，下载失败、启动出错等局部问题不会影响整个启动器运行，同时给出明确的错误提示与解决方案

• 自动容错机制：配置文件损坏自动备份并恢复默认配置、下载文件校验失败自动重下、版本损坏自动检测并提示修复、更新失败自动回滚

测试与性能优化

• 核心模块100%单元测试覆盖，核心流程（登录-下载-安装-启动）全量集成测试，跨平台全量兼容性测试

• 内存管理：所有资源严格生命周期管理，大文件采用流处理，图片懒加载与缓存回收，杜绝内存泄漏

• 性能优化：UI层全量使用const构造函数，列表采用懒加载，耗时操作全量放入独立Isolate，保证UI全程60fps流畅运行

安全与隐私

• 账户令牌、敏感信息采用AES-256加密存储，密钥与设备硬件信息绑定，杜绝明文存储

• 全量HTTPS请求证书校验，防止中间人攻击，微软OAuth2采用PKCE流程，保证认证安全

• 权限最小化：仅申请必要的系统权限，无多余隐私数据采集

2. 全功能对标：PCL/HMCL/BakaXL/LaunchX 能力全覆盖