Ely Prism Launcher组件系统:ComponentUpdateTask如何实现实例文件增量更新
Ely Prism Launcher组件系统:ComponentUpdateTask如何实现实例文件增量更新
Ely Prism Launcher 是基于 Prism Launcher 的 Minecraft 启动器分支,在保留多实例管理能力的基础上,集成了 Ely.by 账号登录支持。它的组件系统(Component System)负责管理每个实例的 Minecraft 版本、模组加载器和依赖库,而核心类 ComponentUpdateTask 正是实现"实例文件增量更新"的关键——它只在组件元数据缺失或版本变化时下载新数据,避免整包重复下载,让更新实例变得快速而省流量。
一、组件系统:实例配置的基本单元
在 Ely Prism Launcher 中,一个实例(Instance)并不是几个散落的配置文件,而是一张组件清单(Component List),由 PackProfile 统一管理。每个组件对应一个 uid(唯一标识,如 net.minecraft、net.fabricmc.intermediary)和一个版本号,例如:
- 游戏本体:
net.minecraft 1.20.4 - 模组加载器:Fabric、Forge 等,作为独立组件挂载
- 依赖项:如
org.lwjgl图形库,被自动注入清单
组件的元数据(名称、版本、依赖声明 requires、冲突声明 conflicts)以 JSON 版本文件描述,数据结构定义在 Component.h。组件列表按顺序加载并生效,顺序决定了依赖注入的位置——这一点在后面的更新流程中很重要。
💡 组件机制的妙处在于"声明式":你不需要手动管理 jar 文件,只需声明"要什么版本",启动器负责把文件补齐。
二、增量更新的总调度:ComponentUpdateTask 四步流水线
ComponentUpdateTask 继承自 Task,是整个更新过程的总调度。它的实现位于 ComponentUpdateTask.cpp,私有状态存放在 ComponentUpdateTask_p.h。执行入口 executeTask() 只有一行核心逻辑——加载所有组件,随后进入四步流水线:
| 阶段 | 方法 | 作用 |
|---|---|---|
| 1️⃣ 加载元数据 | loadComponents() |
本地优先,缺失才远程拉取 |
| 2️⃣ 执行更新动作 | performUpdateActions() |
处理版本变更、移除等动作 |
| 3️⃣ 解析依赖 | resolveDependencies() |
自动补齐/清理/改版本 |
| 4️⃣ 最终校验 | finalizeComponents() |
生成问题报告 |
它支持两种运行模式(Mode::Launch / Mode::Resolution)和两种网络模式(Online / Offline),由 PackProfile::resolve() 创建并启动,成功后通过 updateSucceeded 信号通知 UI 刷新。
第一步:本地优先,缺失才下载——增量更新的起点
loadComponents() 遍历组件清单,对每个组件调用内部的 loadComponent() 函数,判定结果分为三类:
LoadedLocal(本地可用):组件已加载,或本地存在自定义 JSON 覆盖文件(getFilename()存在),直接解析本地文件,零网络请求;RequiresRemote(需要远程):本地元数据索引(metadataIndex)中没有该 uid + 版本组合,才发起下载任务,并连接succeeded/failed/aborted信号等待回调;Failed(失败):离线模式下拿不到数据,直接终止。
多路下载通过 remoteLoadStatusList(定义见 ComponentUpdateTask_p.h)并发管理,所有子任务完成后由 checkIfAllFinished() 汇合,再进入后续阶段。这就是"增量"的第一层含义:元数据层面只补缺失的部分。
第二步:执行 UpdateAction,最小化变更
元数据就绪后,performUpdateActions() 检查每个组件上挂着的 UpdateAction(一个 std::variant,定义于 Component.h),通过 std::visit 分派处理(实现位置):
UpdateActionChangeVersion:精确切换到目标版本;UpdateActionLatestRecommendedCompatible:向元数据索引查询"推荐版本"或"兼容的最新版本",找不到时报错并记录组件问题;UpdateActionRemove:将组件从清单移除;UpdateActionImportantChanged:当"重要组件"(如游戏本体)换版本时,联动更新collectTreeLinked()收集到的关联组件版本,并移除旧版本专属的依赖。
处理采用 do-while (addedActions) 循环:ImportantChanged 会派生新的更新动作,因此要反复执行直到没有新动作——这是一种定点收敛策略,保证联动更新彻底且不遗漏。
第三步:依赖解析,自动补齐与清理
resolveDependencies()(实现位置)执行朴素但可靠的依赖算法:
- 收集全部需求:
gatherRequirementsFromComponents()汇总所有组件的requires声明,相同 uid 的需求两两合成;版本精确值冲突则报"依赖冲突"错误; - 清理无用项:
getTrivialRemovals()找出"仅作为依赖安装、volatile 且已无人引用"的组件,直接从清单移除——卸载旧版游戏后,旧依赖会被自动清走,这是"增量"在反向的体现; - 补齐缺失项:
getTrivialComponentChanges()将需求分类为toAdd(缺失需新增)和toChange(版本需调整),其中"锁定版本不可改"的情况会直接失败并提示用户; - 递归收敛:新增/改版本会触发
loadComponents()重新走一遍加载流程,直到依赖图稳定。
在 Launch 模式下若检测到未解决的依赖(checkOnly = true),任务会以"实例依赖未解决"失败退出,避免带病启动游戏。
第四步:最终校验,生成可读的问题报告
finalizeComponents()(实现位置)遍历清单做最后把关:缺失的需求、版本不符(精确值为 Error、建议值为 Warning)、已知冲突组件并存(如两个互斥的模组加载器)都会转化为 addComponentProblem() 记录,最终以 UI 中醒目的问题列表呈现,而不是一句模糊的"启动失败"。
三、从元数据到真实文件:下载环节的接力
ComponentUpdateTask 管到"清单和元数据一致"为止,真实文件的增量下载由后续任务接力完成。MinecraftInstance::createUpdateTask() 组装了文件级更新流水线:
- LibrariesTask:下载/校验组件声明的 Java 库文件,已存在且校验通过的文件跳过;
- AssetUpdateTask:按 assets 索引比对哈希,只补下缺失或损坏的贴图、声音资源;
- LegacyFMLLibrariesTask:兼容老版本 Forge 的库文件处理。
对于 Ely.by 用户,流水线上还插入了 ElyPatchTask:它从组件声明的库中查找 com.mojang:authlib,通过元数据索引解析并落地对应版本的 Authlib 组件,使实例支持 Ely.by 第三方账号认证——这本身就是一次典型的"组件驱动增量更新",与主流程共享同一套元数据机制。
四、在线/离线双模式:断网也能增量
ComponentUpdateTask 构造时接收 Net::Mode(Online / Offline)。离线模式下:
- 所有组件都必须能从本地元数据或自定义 JSON 加载,否则立即失败并提示;
- 依赖解析进入
checkOnly行为,只报告不修改; - 文件下载任务跳过,仅做本地完整性检查。
这意味着你可以离线修改组件版本配置,等联网后再一次性增量补齐,更新过程对用户透明且可随时取消(canAbort() 会检查所有进行中的远程子任务)。
五、核心源码索引
| 文件 | 说明 |
|---|---|
| launcher/minecraft/ComponentUpdateTask.cpp | 更新总调度实现(约 820 行) |
| launcher/minecraft/ComponentUpdateTask.h | 类定义与双模式枚举 |
| launcher/minecraft/ComponentUpdateTask_p.h | 私有状态:远程任务状态列表 |
| launcher/minecraft/Component.h | 组件与 UpdateAction 数据结构 |
| launcher/minecraft/PackProfile.cpp | 任务创建入口 resolve() |
| launcher/minecraft/MinecraftInstance.cpp | 文件级更新流水线组装 |
| launcher/minecraft/update/ElyPatchTask.cpp | Ely.by Authlib 补丁解析 |
总结
ComponentUpdateTask 的增量更新哲学可以概括为三句话:元数据本地优先、缺失才拉取;变更通过类型化的 UpdateAction 定点收敛;文件下载按索引哈希比对只补缺口。配合 Ely.by 账号支持的 ElyPatchTask,Ely Prism Launcher 让"更新一个加了十几个模组的实例"不再意味着重复下载几个 GB 的数据。理解了这条流水线,你就掌握了 Ely Prism Launcher 组件系统的核心脉络。