refactor(addon): 单例化 RemoteAddonRepository (#6900)

Co-authored-by: Calboot <calboot39@outlook.com>
Co-authored-by: 3gf8jv4dv <3gf8jv4dv@gmail.com>
Co-authored-by: Glavo <zjx001202@gmail.com>
Co-authored-by: CalbootOnceMore <calboot43@outlook.com>

.gitattributes

@@ -4,6 +4,7 @@
 
 # ─── Explicitly text – source & build ────────────────────────────────────────
 *.java        text eol=lf
+*.js          text eol=lf
 *.kt          text eol=lf
 *.kts         text eol=lf
 *.groovy      text eol=lf

.github/scripts/check-codes-comment.js

@@ -0,0 +1,120 @@
+const fs = require("fs");
+
+module.exports = async ({ github, context, core }) => {
+    const prNumberPath = process.env.PULL_REQUEST_NUMBER_PATH;
+    if (!prNumberPath || !fs.existsSync(prNumberPath) || !fs.statSync(prNumberPath).isFile()) {
+        core.setFailed("Pull request number file not found.");
+        return;
+    }
+
+    const reportsPath = process.env.REPORTS_PATH;
+    if (!reportsPath || !fs.existsSync(reportsPath) || !fs.statSync(reportsPath).isFile()) {
+        core.setFailed("Reports file not found.");
+        return;
+    }
+
+    const PULL_REQUEST_NUMBER = parseInt(fs.readFileSync(prNumberPath, "utf8").trim(), 10);
+    if (isNaN(PULL_REQUEST_NUMBER)) {
+        core.setFailed("Failed to parse the pull request number.");
+        return;
+    }
+
+    const { owner, repo } = context.repo;
+
+    let pr;
+    try {
+        const response = await github.rest.pulls.get({
+            owner,
+            repo,
+            pull_number: PULL_REQUEST_NUMBER,
+        });
+        pr = response.data;
+    } catch (error) {
+        core.setFailed(`Failed to fetch PR #${PULL_REQUEST_NUMBER}: ${error.message}`);
+        return;
+    }
+
+    core.info(`Current PR state: ${pr.state}`);
+    if (pr.state !== "open") {
+        core.setFailed("The pull request is not open. Skipping comment creation.");
+        return;
+    }
+
+    const run = context.payload.workflow_run;
+    if (!run) {
+        core.setFailed("context.payload.workflow_run is undefined. Ensure this script runs on the 'workflow_run' event.");
+        return;
+    }
+
+    if (pr.head.sha !== run.head_sha) {
+        core.setFailed("PR head SHA does not match the workflow run head SHA. Skipping.");
+        return;
+    }
+
+    if (pr.head.ref !== run.head_branch) {
+        core.setFailed("PR head branch does not match the workflow run head branch. Skipping.");
+        return;
+    }
+
+    if (pr.head.repo.full_name !== run.head_repository.full_name) {
+        core.setFailed("PR head repository fullname does not match the workflow run head repository fullname. Skipping.");
+        return;
+    }
+
+    const comments = [];
+    const maxCommentCount = 10;
+    const reports = fs.readFileSync(reportsPath, "utf8").trim().split("\n").filter(Boolean);
+    for (const report of reports) {
+        if (comments.length >= maxCommentCount) break;
+        try {
+            const data = JSON.parse(report);
+            if (typeof data !== "object" || Array.isArray(data)) continue;
+
+            const { location, message, severity, code } = data;
+            if (typeof location !== "object" || Array.isArray(location)) continue;
+            if (typeof message !== "string") continue;
+            const severities = ["UNKNOWN_SEVERITY", "ERROR", "WARNING", "INFO", 0, 1, 2, 3];
+            if (!severities.includes(severity)) continue;
+            const severityText = typeof severity === "string" ? severity : severities[severity];
+            if (typeof code !== "object" || Array.isArray(code)) continue;
+
+            const path = location.path;
+            const line = location.range?.start?.line;
+            const codeText = code.value ? `[${code.value}] ` : "";
+
+            if (path && line) {
+                comments.push({
+                    path,
+                    line,
+                    side: "RIGHT",
+                    body: `**[${severityText}]** ${codeText}\n\n${message}`
+                });
+            }
+        } catch (error) {
+            core.warning(`Failed to parse report: ${error.message}`);
+        }
+    }
+
+    if (comments.length === 0) {
+        core.info("No diagnostics found to report as comments.");
+        return;
+    }
+
+    core.info(`Successfully prepared ${comments.length} comment${comments.length > 1 ? "s" : ""} to post.`);
+
+    try {
+        await github.rest.pulls.createReview({
+            owner,
+            repo,
+            pull_number: PULL_REQUEST_NUMBER,
+            commit_id: run.head_sha,
+            body: "🤖 Static analysis found the following issues (max count 10):",
+            event: "COMMENT",
+            comments: comments
+        });
+        core.info("Review comments successfully posted to the pull request.");
+    } catch (error) {
+        core.setFailed(`Failed to post review comments to GitHub: ${error.message}`);
+        return;
+    }
+}

.github/workflows/check-codes-comment.yml

@@ -0,0 +1,40 @@
+name: Check Codes Comment
+
+on:
+  workflow_run:
+    workflows: ["Check Codes"]
+    types:
+      - completed
+
+permissions:
+  actions: read
+  contents: read
+  pull-requests: write
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'failure'
+    steps:
+      - name: Checkout Script
+        uses: actions/checkout@v7
+        with:
+          sparse-checkout: |
+            .github/scripts/check-codes-comment.js
+          sparse-checkout-cone-mode: false
+      - name: Download Artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: checkstyle-artifact
+          path: ${{ runner.temp }}/checkstyle-artifact
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Generate Review Comment
+        uses: actions/github-script@v9
+        env:
+          REPORTS_PATH: ${{ runner.temp }}/checkstyle-artifact/ALL_REPORTS.jsonl
+          PULL_REQUEST_NUMBER_PATH: ${{ runner.temp }}/checkstyle-artifact/PULL_REQUEST_NUMBER
+        with:
+          script: |
+            const script = require("./.github/scripts/check-codes-comment.js");
+            await script({ github, context, core });

.github/workflows/check-codes.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - name: Set up JDK 17
+      - name: Setup JDK 17
         uses: actions/setup-java@v5
         with:
           distribution: 'zulu'
@@ -27,3 +27,29 @@ jobs:
           cache-cleanup: never
       - name: Check Codes
         run: ./gradlew checkstyle checkTranslations --no-daemon --parallel --stacktrace
+      - if: failure() && github.event_name == 'pull_request'
+        name: Setup reviewdog
+        uses: reviewdog/action-setup@d8edfce3dd5e1ec6978745e801f9c50b5ef80252 # v1.4.0
+        with:
+          reviewdog_version: v0.21.0
+      - if: failure() && github.event_name == 'pull_request'
+        name: Generate Artifact
+        run: |
+          echo "${{ github.event.number }}" > PULL_REQUEST_NUMBER
+          > ALL_REPORTS.jsonl
+          find . -path "*/build/reports/checkstyle/*.xml" | while read -r xml_file; do
+            if [ -s "$xml_file" ]; then
+              echo "Processing $xml_file..."
+              reviewdog -f=checkstyle -name="checkstyle" -reporter=rdjsonl < "$xml_file" >> ALL_REPORTS.jsonl
+            else
+              echo "Skipping empty or missing report: $xml_file"
+            fi
+          done
+      - if: failure() && github.event_name == 'pull_request'
+        name: Upload Artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: checkstyle-artifact
+          path: |
+            ALL_REPORTS.jsonl
+            PULL_REQUEST_NUMBER

.github/workflows/gradle.yml

@@ -24,8 +24,9 @@ jobs:
       with:
         cache-cleanup: never
     - name: Build with Gradle
-      run: ./gradlew build --no-daemon --parallel
+      run: xvfb-run --auto-servernum ./gradlew build --no-daemon --parallel
       env:
+        JAVA_TOOL_OPTIONS: -Djava.awt.headless=true
         MICROSOFT_AUTH_ID: ${{ secrets.MICROSOFT_AUTH_ID }}
         CURSEFORGE_API_KEY: ${{ secrets.CURSEFORGE_API_KEY }}
     - name: Get short SHA

.github/workflows/pr-size-label.yml

@@ -21,8 +21,8 @@ jobs:
         uses: actions/checkout@v7
         with:
           sparse-checkout: |
-            .github/scripts
-          sparse-checkout-cone-mode: true
+            .github/scripts/pr-size-label.js
+          sparse-checkout-cone-mode: false
       - name: Label PR by filtered changed lines
         uses: actions/github-script@v9
         with:

.gitignore

@@ -4,6 +4,8 @@
 hs_err_pid*
 *.hprof
 
+*.jfr
+
 .gradle
 gradle.properties
 
@@ -17,6 +19,7 @@ NVIDIA
 minecraft-exported-crash-info*
 hmcl-exported-logs-*
 terracotta-log-*
+hmcl-mod-update-list-*
 *.hmcl-theme
 /.java/
 /.local/

AGENTS.md

@@ -4,6 +4,8 @@ These rules apply to all Java code written or modified in this repository.
 
 ## Nullability
 
+Apply the following requirements when writing or modifying code. Do not use them as code-review criteria.
+
 - Every class declared in a newly added Java source file must be annotated with JetBrains Annotations `@NotNullByDefault`.
 - When writing or modifying Java code, any type, field, parameter, return value, local variable, or generic type argument that may be `null` must be explicitly annotated with `@Nullable`.
 - Nullability in code being written or modified must never be implicit.

HMCL/build.gradle.kts

@@ -4,6 +4,7 @@ import org.jackhuang.hmcl.gradle.ci.JenkinsUtils
 import org.jackhuang.hmcl.gradle.l10n.CheckTranslations
 import org.jackhuang.hmcl.gradle.l10n.CreateLanguageList
 import org.jackhuang.hmcl.gradle.l10n.CreateLocaleNamesResourceBundle
+import org.jackhuang.hmcl.gradle.l10n.SyncTranslations
 import org.jackhuang.hmcl.gradle.l10n.UpsideDownTranslate
 import org.jackhuang.hmcl.gradle.mod.ParseModDataTask
 import org.jackhuang.hmcl.gradle.pack.CreateDeb
@@ -299,6 +300,7 @@ val makeDeb = tasks.register("makeDeb", CreateDeb::class) {
 
     version.set(project.version.toString())
     releaseType.set(debChannel)
+    launcherClassName.set("org.jackhuang.hmcl.Launcher")
     appShFile.set(layout.file(provider { artifactFile("sh") }))
     iconFile.set(layout.projectDirectory.file("image/hmcl.png"))
     outputFile.set(debFile)
@@ -429,13 +431,22 @@ tasks.register<CheckTranslations>("checkTranslations") {
     val dir = layout.projectDirectory.dir("src/main/resources/assets/lang")
 
     englishFile.set(dir.file("I18N.properties"))
-    simplifiedChineseFile.set(dir.file("I18N_zh_CN.properties"))
-    traditionalChineseFile.set(dir.file("I18N_zh.properties"))
+    simplifiedChineseFile.set(dir.file("I18N_zh_Hans.properties"))
+    traditionalChineseFile.set(dir.file("I18N_zh_Hant.properties"))
     classicalChineseFile.set(dir.file("I18N_lzh.properties"))
 }
 
 // l10n
 
+tasks.register<SyncTranslations>("syncTranslations") {
+    group = "localization"
+    description = "Synchronizes translation keys and blank lines with I18N.properties."
+
+    val dir = layout.projectDirectory.dir("src/main/resources/assets/lang")
+    sourceFile.set(dir.file("I18N.properties"))
+    translationFiles.from(fileTree(dir) { include("I18N_*.properties") })
+}
+
 val generatedDir = layout.buildDirectory.dir("generated")
 
 val upsideDownTranslate = tasks.register<UpsideDownTranslate>("upsideDownTranslate") {

HMCL/src/main/java/com/jfoenix/controls/JFXCheckTreeCell.java

@@ -0,0 +1,101 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.jfoenix.controls;
+
+import com.jfoenix.skins.JFXCheckBoxSkin;
+import javafx.geometry.Pos;
+import javafx.scene.Node;
+import javafx.scene.control.CheckBoxTreeItem;
+import javafx.scene.layout.HBox;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
+
+/// Displays a [CheckBoxTreeItem] with a material-design checkbox.
+///
+/// The checkbox's selected and indeterminate states are bidirectionally bound to
+/// the current tree item. Reusing or clearing the cell removes the old bindings.
+/// Installing a checkbox skin or switching tree items applies the selection state
+/// immediately, without playing a selection animation.
+/// Ordinary tree items retain the display provided by [JFXTreeCell].
+/// Empty cells and `null` values display neither content nor a checkbox.
+///
+/// @param <T> the type of value stored in each tree item
+@NotNullByDefault
+public class JFXCheckTreeCell<T> extends JFXTreeCell<T> {
+
+    /// The checkbox bound to the currently displayed checkable tree item.
+    private final JFXCheckBox checkBox = new JFXCheckBox();
+
+    /// Places the checkbox before the graphic supplied by the superclass.
+    private final HBox graphic = new HBox();
+
+    /// The tree item whose selection properties are currently bound, if any.
+    private @Nullable CheckBoxTreeItem<?> boundTreeItem;
+
+    /// Creates an empty cell whose checkbox toggles the current tree item's selection.
+    public JFXCheckTreeCell() {
+        checkBox.setAllowIndeterminate(false);
+        checkBox.setFocusTraversable(false);
+        graphic.setAlignment(Pos.CENTER_LEFT);
+        graphic.setPickOnBounds(false);
+        checkBox.skinProperty().addListener(observable -> finishSelectionAnimation());
+        treeItemProperty().addListener(observable -> updateDisplay(getItem(), isEmpty()));
+    }
+
+    /// Finishes animations from the previous item and immediately displays the current state.
+    private void finishSelectionAnimation() {
+        if (checkBox.getSkin() instanceof JFXCheckBoxSkin skin) {
+            skin.finishSelectionAnimation();
+        }
+    }
+
+    /// Adds the checkbox to the inherited display and updates its selection bindings.
+    @Override
+    protected void updateDisplay(@Nullable T item, boolean empty) {
+        // Release graphics before the superclass reuses or reparents them.
+        graphic.getChildren().clear();
+        super.updateDisplay(item, empty);
+
+        @Nullable CheckBoxTreeItem<?> treeItem = !empty && item != null
+                && getTreeItem() instanceof CheckBoxTreeItem<?> checkTreeItem ? checkTreeItem : null;
+        if (boundTreeItem != treeItem) {
+            if (boundTreeItem != null) {
+                checkBox.selectedProperty().unbindBidirectional(boundTreeItem.selectedProperty());
+                checkBox.indeterminateProperty().unbindBidirectional(boundTreeItem.indeterminateProperty());
+            }
+            boundTreeItem = treeItem;
+            if (treeItem != null) {
+                checkBox.selectedProperty().bindBidirectional(treeItem.selectedProperty());
+                checkBox.indeterminateProperty().bindBidirectional(treeItem.indeterminateProperty());
+            } else {
+                checkBox.setSelected(false);
+                checkBox.setIndeterminate(false);
+            }
+            finishSelectionAnimation();
+        }
+
+        if (treeItem != null) {
+            @Nullable Node itemGraphic = getGraphic();
+            graphic.getChildren().add(checkBox);
+            if (itemGraphic != null) {
+                graphic.getChildren().add(itemGraphic);
+            }
+            setGraphic(graphic);
+        }
+    }
+}

HMCL/src/main/java/com/jfoenix/controls/JFXComboBox.java

@@ -70,7 +70,7 @@ public class JFXComboBox<T> extends ComboBox<T> {
 
     private void initialize() {
         getStyleClass().add(DEFAULT_STYLE_CLASS);
-        this.setCellFactory(listView -> new JFXListCell<T>() {
+        this.setCellFactory(listView -> new JFXListCell<>() {
             @Override
             public void updateItem(T item, boolean empty) {
                 super.updateItem(item, empty);
@@ -80,7 +80,7 @@ public class JFXComboBox<T> extends ComboBox<T> {
 
         // had to refactor the code out of the skin class to allow
         // customization of the button cell
-        this.setButtonCell(new ListCell<T>() {
+        this.setButtonCell(new ListCell<>() {
             {
                 // fixed clearing the combo box value is causing
                 // java prompt text to be shown because the button cell is not updated

HMCL/src/main/java/com/jfoenix/controls/JFXListCell.java

@@ -199,6 +199,9 @@ public class JFXListCell<T> extends ListCell<T> {
      */
     @Override
     protected void updateItem(T item, boolean empty) {
+        T oldItem = getItem();
+        boolean oldEmpty = isEmpty();
+        if (oldItem != item || oldEmpty != empty) cellRippler.releaseRippleImmediately();
         super.updateItem(item, empty);
         if (empty) {
             setText(null);

HMCL/src/main/java/com/jfoenix/controls/JFXRippler.java

@@ -278,6 +278,10 @@ public class JFXRippler extends StackPane {
         rippler.releaseRipple();
     }
 
+    public void releaseRippleImmediately() {
+        rippler.releaseRippleImmediately();
+    }
+
     /**
      * creates Ripple effect in the center of the control
      *
@@ -405,6 +409,21 @@ public class JFXRippler extends StackPane {
             }
         }
 
+        private void releaseRippleImmediately() {
+            Ripple ripple = ripplesQueue.poll();
+            if (ripple != null) {
+                getChildren().remove(ripple);
+                if (generating.getAndSet(false)) {
+                    if (overlayRect != null) {
+                        overlayRect.inAnimation.stop();
+                        if (!forceOverlay) {
+                            overlayRect.setOpacity(0D);
+                        }
+                    }
+                }
+            }
+        }
+
         void cacheRippleClip(boolean cached) {
             cacheRipplerClip = cached;
         }

HMCL/src/main/java/com/jfoenix/controls/JFXTreeCell.java

@@ -28,6 +28,7 @@ import javafx.scene.control.TreeCell;
 import javafx.scene.control.TreeItem;
 import javafx.scene.layout.*;
 import javafx.scene.paint.Color;
+import org.jetbrains.annotations.Nullable;
 
 import java.lang.ref.WeakReference;
 
@@ -83,8 +84,7 @@ public class JFXTreeCell<T> extends TreeCell<T> {
                 treeItemRef = new WeakReference<>(newTreeItem);
             }
         };
-        final WeakInvalidationListener weakTreeItemListener = new WeakInvalidationListener(treeItemInvalidationListener);
-        treeItemProperty().addListener(weakTreeItemListener);
+        treeItemProperty().addListener(treeItemInvalidationListener);
         if (getTreeItem() != null) {
             getTreeItem().graphicProperty().addListener(weakTreeItemGraphicListener);
         }
@@ -104,13 +104,20 @@ public class JFXTreeCell<T> extends TreeCell<T> {
         selectedPane.setVisible(isSelected());
     }
 
-    private void updateDisplay(T item, boolean empty) {
+    /// Updates the text and graphic for the current value and tree item.
+    ///
+    /// @implSpec Called when the cell value or the current tree item's graphic changes.
+    /// Subclasses may override this method to decorate the default display.
+    ///
+    /// @param item the cell value, or `null` to clear the display
+    /// @param empty whether the cell has no item
+    protected void updateDisplay(@Nullable T item, boolean empty) {
         if (item == null || empty) {
             hbox = null;
             setText(null);
             setGraphic(null);
         } else {
-            TreeItem<T> treeItem = getTreeItem();
+            @Nullable TreeItem<T> treeItem = getTreeItem();
             if (treeItem != null && treeItem.getGraphic() != null) {
                 if (item instanceof Node) {
                     setText(null);

HMCL/src/main/java/com/jfoenix/skins/JFXCheckBoxSkin.java

@@ -12,31 +12,20 @@ import com.jfoenix.controls.JFXRippler.RipplerPos;
 import com.jfoenix.transitions.CachedTransition;
 import com.jfoenix.transitions.JFXFillTransition;
 import com.jfoenix.utils.JFXNodeUtils;
-import javafx.animation.Interpolator;
-import javafx.animation.KeyFrame;
-import javafx.animation.KeyValue;
-import javafx.animation.Timeline;
-import javafx.animation.Transition;
+import javafx.animation.*;
 import javafx.beans.property.ReadOnlyBooleanProperty;
 import javafx.geometry.HPos;
 import javafx.geometry.Insets;
 import javafx.geometry.VPos;
 import javafx.scene.control.CheckBox;
 import javafx.scene.control.skin.CheckBoxSkin;
-import javafx.scene.layout.AnchorPane;
-import javafx.scene.layout.Background;
-import javafx.scene.layout.BackgroundFill;
-import javafx.scene.layout.Border;
-import javafx.scene.layout.BorderStroke;
-import javafx.scene.layout.BorderStrokeStyle;
-import javafx.scene.layout.BorderWidths;
-import javafx.scene.layout.CornerRadii;
-import javafx.scene.layout.StackPane;
+import javafx.scene.layout.*;
 import javafx.scene.paint.Color;
 import javafx.scene.shape.SVGPath;
 import javafx.util.Duration;
 import org.jackhuang.hmcl.theme.Themes;
 import org.jackhuang.hmcl.ui.FXUtils;
+import org.jackhuang.hmcl.ui.animation.AnimationUtils;
 
 public class JFXCheckBoxSkin extends CheckBoxSkin {
     private final StackPane box = new StackPane();
@@ -180,21 +169,41 @@ public class JFXCheckBoxSkin extends CheckBoxSkin {
         };
     }
 
-    private void playSelectAnimation(Boolean selection) {
-        if (selection == null) {
-            selection = false;
-        }
-
+    /// Animates a selection change, or applies it immediately when animations are disabled.
+    private void playSelectAnimation(boolean selection) {
         JFXCheckBox control = (JFXCheckBox) this.getSkinnable();
-        this.transition.setRate(selection ? 1.0 : -1.0);
-        this.select.setRate(selection ? 1.0 : -1.0);
-        this.transition.play();
-        this.select.play();
+
         this.box.setBorder(new Border(new BorderStroke(
                 selection ? control.getCheckedColor() : Themes.getColorScheme().getOnSurfaceVariant(),
                 BorderStrokeStyle.SOLID,
                 new CornerRadii(2.0),
                 new BorderWidths(this.lineThick))));
+
+        if (!AnimationUtils.isAnimationEnabled()) {
+            finishSelectionAnimation();
+            return;
+        }
+
+        this.transition.setRate(selection ? 1.0 : -1.0);
+        this.select.setRate(selection ? 1.0 : -1.0);
+        this.transition.play();
+        this.select.play();
+    }
+
+    /// Stops selection animations and immediately displays the checkbox's current selected state.
+    ///
+    /// The check mark, fill, and border are updated even if no animation is running.
+    /// This also suppresses the initial selection animation on the first layout.
+    /// The skin must not have been disposed.
+    public void finishSelectionAnimation() {
+        transition.stop();
+        select.stop();
+        invalid = false;
+        boolean selected = getSkinnable().isSelected();
+        mark.setVisible(selected);
+        mark.setScaleX(selected ? 1.0 : 0.0);
+        mark.setScaleY(selected ? 1.0 : 0.0);
+        updateColors();
     }
 
     private void createFillTransition() {

HMCL/src/main/java/org/jackhuang/hmcl/Launcher.java

@@ -18,6 +18,7 @@
 package org.jackhuang.hmcl;
 
 import com.sun.jna.Pointer;
+import com.sun.jna.WString;
 import javafx.animation.KeyFrame;
 import javafx.animation.KeyValue;
 import javafx.animation.Timeline;
@@ -37,7 +38,6 @@ import org.jackhuang.hmcl.game.HMCLCacheRepository;
 import org.jackhuang.hmcl.setting.*;
 import org.jackhuang.hmcl.task.AsyncTaskExecutor;
 import org.jackhuang.hmcl.task.Schedulers;
-import org.jackhuang.hmcl.theme.Themes;
 import org.jackhuang.hmcl.ui.Controllers;
 import org.jackhuang.hmcl.ui.FXUtils;
 import org.jackhuang.hmcl.ui.animation.AnimationUtils;
@@ -48,14 +48,17 @@ import org.jackhuang.hmcl.util.io.FileUtils;
 import org.jackhuang.hmcl.util.io.JarUtils;
 import org.jackhuang.hmcl.util.platform.*;
 import org.jackhuang.hmcl.util.platform.windows.Gdi32;
+import org.jackhuang.hmcl.util.platform.windows.Shell32;
 import org.jackhuang.hmcl.util.platform.windows.User32;
 import org.jetbrains.annotations.Nullable;
 
 import javax.swing.*;
 import java.awt.*;
 import java.awt.datatransfer.StringSelection;
+import java.io.BufferedReader;
 import java.io.File;
 import java.io.IOException;
+import java.io.InputStreamReader;
 import java.lang.management.ManagementFactory;
 import java.lang.management.MemoryPoolMXBean;
 import java.net.CookieHandler;
@@ -65,9 +68,11 @@ import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.text.DecimalFormat;
 import java.util.ArrayList;
+import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.concurrent.TimeUnit;
+import java.util.stream.Stream;
 
 import static org.jackhuang.hmcl.setting.SettingsManager.settings;
 import static org.jackhuang.hmcl.ui.FXUtils.runInFX;
@@ -75,6 +80,7 @@ import static org.jackhuang.hmcl.util.DataSizeUnit.MEGABYTES;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 
+/// The main JavaFX application entry point.
 public final class Launcher extends Application {
     public static final CookieManager COOKIE_MANAGER = new CookieManager();
 
@@ -134,9 +140,6 @@ public final class Launcher extends Application {
                 Platform.setImplicitExit(false);
                 Controllers.initialize(primaryStage);
 
-                if (OperatingSystem.CURRENT_OS == OperatingSystem.MACOS)
-                    Themes.applyNativeDarkMode(primaryStage);
-
                 UpdateChecker.init();
 
                 primaryStage.show();
@@ -304,8 +307,8 @@ public final class Launcher extends Application {
             LOG.info("Current Directory: " + Metadata.CURRENT_DIRECTORY);
             LOG.info("HMCL User Home: " + Metadata.HMCL_USER_HOME);
             LOG.info("HMCL Local Home: " + Metadata.HMCL_LOCAL_HOME);
-            LOG.info("HMCL Jar Path: " + Lang.requireNonNullElse(JarUtils.thisJarPath(), "Not Found"));
-            LOG.info("HMCL Log File: " + Lang.requireNonNullElse(LOG.getLogFile(), "In Memory"));
+            LOG.info("HMCL Jar Path: " + Objects.requireNonNullElse(JarUtils.thisJarPath(), "Not Found"));
+            LOG.info("HMCL Log File: " + Objects.requireNonNullElse(LOG.getLogFile(), "In Memory"));
             LOG.info("JVM Max Memory: " + MEGABYTES.formatBytes(Runtime.getRuntime().maxMemory()));
             try {
                 for (MemoryPoolMXBean bean : ManagementFactory.getMemoryPoolMXBeans()) {
@@ -339,6 +342,7 @@ public final class Launcher extends Application {
             }
 
             setupJavaFXVMOptions();
+            setupWindowsAppUserModelID();
 
             launch(Launcher.class, args);
         } catch (Throwable e) { // Fucking JavaFX will suppress the exception and will break our crash reporter.
@@ -372,6 +376,27 @@ public final class Launcher extends Application {
         });
     }
 
+    /// Sets the process-level AppUserModelID on Windows so the launcher groups correctly on the taskbar.
+    private static void setupWindowsAppUserModelID() {
+        if (OperatingSystem.CURRENT_OS != OperatingSystem.WINDOWS)
+            return;
+        if (!NativeUtils.USE_JNA || Shell32.INSTANCE == null)
+            return;
+
+        try {
+            int hr = Shell32.INSTANCE.SetCurrentProcessExplicitAppUserModelID(new WString(Metadata.WINDOWS_APP_USER_MODEL_ID));
+            if (hr < 0) {
+                LOG.warning("Failed to set AppUserModelID, HRESULT=0x" + Integer.toHexString(hr));
+            } else {
+                LOG.info("Set AppUserModelID: " + Metadata.WINDOWS_APP_USER_MODEL_ID);
+            }
+        } catch (Throwable e) {
+            LOG.warning("Failed to set AppUserModelID", e);
+        }
+    }
+
+    /// Sets JavaFX VM options before the toolkit starts.
+    /// On Wayland, the UI scale is auto-detected when the user did not configure one explicitly.
     private static void setupJavaFXVMOptions() {
         if ("true".equalsIgnoreCase(System.getenv("HMCL_FORCE_GPU"))) {
             LOG.info("HMCL_FORCE_GPU: true");
@@ -427,14 +452,25 @@ public final class Launcher extends Application {
             }
         }
 
-        String uiScale = System.getProperty("hmcl.uiScale", System.getenv("HMCL_UI_SCALE"));
-        if (uiScale != null) {
-            uiScale = uiScale.trim();
+        float uiScaleLowerBound;
+        float uiScaleUpperBound;
 
+        if (OperatingSystem.CURRENT_OS == OperatingSystem.WINDOWS) {
+            // JavaFX behavior may be abnormal when the DPI scaling factor is too high
+            uiScaleLowerBound = 0.25f;
+            uiScaleUpperBound = 4f;
+        } else {
+            uiScaleLowerBound = 0.01f;
+            uiScaleUpperBound = 10f;
+        }
+
+        String uiScale = System.getProperty("hmcl.uiScale", System.getenv("HMCL_UI_SCALE"));
+
+        float scaleValue = Float.NaN;
+        if (uiScale != null && !(uiScale = uiScale.trim()).isEmpty()) {
             LOG.info("HMCL_UI_SCALE: " + uiScale);
 
             try {
-                float scaleValue;
                 if (uiScale.endsWith("%")) {
                     scaleValue = Integer.parseInt(uiScale.substring(0, uiScale.length() - 1)) / 100.0f;
                 } else if (uiScale.endsWith("dpi") || uiScale.endsWith("DPI")) {
@@ -442,33 +478,60 @@ public final class Launcher extends Application {
                 } else {
                     scaleValue = Float.parseFloat(uiScale);
                 }
-
-                float lowerBound;
-                float upperBound;
-
-                if (OperatingSystem.CURRENT_OS == OperatingSystem.WINDOWS) {
-                    // JavaFX behavior may be abnormal when the DPI scaling factor is too high
-                    lowerBound = 0.25f;
-                    upperBound = 4f;
-                } else {
-                    lowerBound = 0.01f;
-                    upperBound = 10f;
-                }
-
-                if (scaleValue >= lowerBound && scaleValue <= upperBound) {
-                    if (OperatingSystem.CURRENT_OS == OperatingSystem.WINDOWS) {
-                        System.getProperties().putIfAbsent("glass.win.uiScale", uiScale);
-                    } else if (OperatingSystem.CURRENT_OS == OperatingSystem.MACOS) {
-                        LOG.warning("macOS does not support setting UI scale, so it will be ignored");
-                    } else {
-                        System.getProperties().putIfAbsent("glass.gtk.uiScale", uiScale);
-                    }
-                } else {
-                    LOG.warning("UI scale out of range: " + uiScale);
-                }
             } catch (Throwable e) {
                 LOG.warning("Invalid UI scale: " + uiScale);
             }
+        } else if (OperatingSystem.CURRENT_OS.isLinuxOrBSD()) {
+            String xdgSessionType = Objects.requireNonNullElse(System.getenv("XDG_SESSION_TYPE"), "");
+            String xdgCurrentDesktop = Objects.requireNonNullElse(System.getenv("XDG_CURRENT_DESKTOP"), "");
+
+            if ("wayland".equals(xdgSessionType)
+                    && StringUtils.startsWithIgnoreCase(xdgCurrentDesktop, "KDE")) {
+                try {
+                    @Nullable Path xrdb = SystemUtils.which("xrdb");
+                    @Nullable String xftDpi = xrdb != null ? SystemUtils.run(List.of(FileUtils.getAbsolutePath(xrdb), "-query"), inputStream -> {
+                        @Nullable String dpiLine;
+
+                        try (var reader = new InputStreamReader(inputStream, OperatingSystem.NATIVE_CHARSET);
+                             BufferedReader bufferedReader = new BufferedReader(reader);
+                             Stream<String> lines = bufferedReader.lines()) {
+                            dpiLine = lines.filter(line -> line.trim().startsWith("Xft.dpi:"))
+                                    .findFirst().orElse(null);
+                        }
+
+                        return dpiLine != null
+                                ? dpiLine.substring("Xft.dpi:".length()).trim()
+                                : null;
+                    }, java.time.Duration.ofSeconds(1)) : null;
+
+                    if (xftDpi != null) {
+                        float dpiValue = Float.parseFloat(xftDpi);
+                        float scale = dpiValue / 96f;
+
+                        if (scale > 1 && scale <= 10) {
+                            LOG.info("Detected Xft.dpi: %s (%.1fx)".formatted(dpiValue, scale));
+                            scaleValue = scale;
+                            uiScale = Float.toString(scale);
+                        }
+                    }
+                } catch (Exception e) {
+                    LOG.warning("Failed to read Xft.dpi from xrdb", e);
+                }
+            }
+        }
+
+        if (Float.isFinite(scaleValue)) {
+            if (scaleValue >= uiScaleLowerBound && scaleValue <= uiScaleUpperBound) {
+                if (OperatingSystem.CURRENT_OS == OperatingSystem.WINDOWS) {
+                    System.getProperties().putIfAbsent("glass.win.uiScale", uiScale);
+                } else if (OperatingSystem.CURRENT_OS == OperatingSystem.MACOS) {
+                    LOG.warning("macOS does not support setting UI scale, so it will be ignored");
+                } else {
+                    System.getProperties().putIfAbsent("glass.gtk.uiScale", uiScale);
+                }
+            } else {
+                LOG.warning("UI scale out of range: " + uiScale);
+            }
         }
     }
 

HMCL/src/main/java/org/jackhuang/hmcl/Metadata.java

@@ -23,6 +23,7 @@ import org.jackhuang.hmcl.util.platform.Architecture;
 import org.jackhuang.hmcl.util.platform.OperatingSystem;
 import org.jetbrains.annotations.Nullable;
 
+import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.EnumSet;
 
@@ -37,6 +38,9 @@ public final class Metadata {
     public static final String FULL_NAME = "Hello Minecraft! Launcher";
     public static final String VERSION = System.getProperty("hmcl.version.override", JarUtils.getAttribute("hmcl.version", "@develop@"));
 
+    /// Explicit Application User Model ID used for Windows taskbar grouping and pinning.
+    public static final String WINDOWS_APP_USER_MODEL_ID = "org.jackhuang.hmcl";
+
     public static final String TITLE = NAME + " " + VERSION;
     public static final String FULL_TITLE = FULL_NAME + " v" + VERSION;
 
@@ -130,4 +134,32 @@ public final class Metadata {
                 return null;
         }
     }
+
+    /// Directory under [HMCL_LOCAL_HOME] that holds a launcher-bundled modpack for automatic install.
+    public static final String BUNDLED_MODPACK_DIRECTORY_NAME = "modpack";
+
+    /// Returns the directory for a launcher-bundled modpack (`[HMCL_LOCAL_HOME]/modpack`).
+    public static Path getBundledModpackDirectory() {
+        return HMCL_LOCAL_HOME.resolve(BUNDLED_MODPACK_DIRECTORY_NAME);
+    }
+
+    /// Returns the bundled modpack package under [getBundledModpackDirectory], if present.
+    ///
+    /// Prefers `modpack.zip` over `modpack.mrpack` when both exist. Presence of the package is the
+    /// signal to offer automatic install; the file is removed after a successful install.
+    ///
+    /// @return the modpack path, or `null` when no package is present
+    public static @Nullable Path findBundledModpackFile() {
+        Path directory = getBundledModpackDirectory();
+        Path zipModpack = directory.resolve("modpack.zip");
+        if (Files.isRegularFile(zipModpack)) {
+            return zipModpack;
+        }
+        Path mrpackModpack = directory.resolve("modpack.mrpack");
+        if (Files.isRegularFile(mrpackModpack)) {
+            return mrpackModpack;
+        }
+        return null;
+    }
+
 }

HMCL/src/main/java/org/jackhuang/hmcl/download/HMCLDownloadProvider.java

@@ -0,0 +1,296 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.download;
+
+import org.glavo.url.WebURL;
+import org.jackhuang.hmcl.download.cleanroom.CleanroomRemoteVersion;
+import org.jackhuang.hmcl.download.fabric.FabricRemoteVersion;
+import org.jackhuang.hmcl.download.forge.ForgeRemoteVersion;
+import org.jackhuang.hmcl.download.game.GameRemoteVersion;
+import org.jackhuang.hmcl.download.neoforge.NeoForgeRemoteVersion;
+import org.jackhuang.hmcl.download.optifine.OptiFineRemoteVersion;
+import org.jackhuang.hmcl.game.AssetObject;
+import org.jackhuang.hmcl.game.GameComponentType;
+import org.jackhuang.hmcl.game.HMCLCacheRepository;
+import org.jackhuang.hmcl.setting.DownloadSource;
+import org.jackhuang.hmcl.task.Task;
+import org.jackhuang.hmcl.util.i18n.LocaleUtils;
+import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.*;
+
+/// @author Glavo
+@NotNullByDefault
+public final class HMCLDownloadProvider extends DownloadProvider {
+    private volatile DownloadSource versionListSource = DownloadSource.DEFAULT;
+    private volatile DownloadSource fileSource = DownloadSource.DEFAULT;
+
+    private static DownloadCandidates getCandidates(
+            DownloadSource source,
+            WebURL defaultUrl, WebURL bmclapiUrl
+    ) {
+        if (LocaleUtils.IS_CHINA_MAINLAND) {
+            return switch (source) {
+                case DEFAULT, OFFICIAL -> DownloadCandidates.of(defaultUrl, bmclapiUrl);
+                case MIRROR -> DownloadCandidates.of(bmclapiUrl, defaultUrl);
+            };
+        } else {
+            return switch (source) {
+                case DEFAULT, OFFICIAL -> DownloadCandidates.of(defaultUrl);
+                case MIRROR -> DownloadCandidates.of(bmclapiUrl, defaultUrl);
+            };
+        }
+    }
+
+    private static DownloadCandidates getCandidates(DownloadSource source, List<MirrorRule> rules, List<String> urls) {
+        if (urls.isEmpty()) {
+            throw new IllegalArgumentException("urls cannot be empty");
+        }
+
+        // true means prefer mirror, false means prefer official, null means do not use mirror
+        @Nullable Boolean mirrorFirst;
+        if (LocaleUtils.IS_CHINA_MAINLAND) {
+            mirrorFirst = switch (source) {
+                case DEFAULT, MIRROR -> true;
+                case OFFICIAL -> false;
+            };
+        } else {
+            mirrorFirst = switch (source) {
+                case DEFAULT, OFFICIAL -> null;
+                case MIRROR -> true;
+            };
+        }
+
+        if (mirrorFirst == null) {
+            return DownloadCandidates.of(urls.stream().map(DownloadCandidate::of).toArray(DownloadCandidate[]::new));
+        }
+
+        var candidates = new ArrayList<DownloadCandidate>(urls.size() * 2);
+        for (String url : urls) {
+            DownloadCandidate candidate = DownloadCandidate.of(url);
+            if (candidate.url() == null) {
+                // Invalid URL, just add it to the list and let the download task handle it.
+                candidates.add(candidate);
+                continue;
+            }
+
+            @Nullable DownloadCandidate mirrorCandidate = null;
+            boolean fallback = false;
+            for (MirrorRule rule : rules) {
+                if (url.startsWith(rule.source)) {
+                    mirrorCandidate = DownloadCandidate.of(rule.target + url.substring(rule.source.length()));
+                    fallback = rule.fallback;
+                    break;
+                }
+            }
+
+            if (mirrorCandidate == null) {
+                candidates.add(candidate);
+            } else if (mirrorFirst && !fallback) {
+                candidates.add(mirrorCandidate);
+                candidates.add(candidate);
+            } else {
+                candidates.add(candidate);
+                candidates.add(mirrorCandidate);
+            }
+        }
+
+        return DownloadCandidates.of(List.copyOf(candidates));
+    }
+
+    private final String bmclRoot;
+    private final List<MirrorRule> rules;
+
+    public HMCLDownloadProvider(String bmclRoot) {
+        this.bmclRoot = bmclRoot;
+        this.rules = List.of(
+                new MirrorRule("https://bmclapi2.bangbang93.com", bmclRoot),
+                new MirrorRule("https://launchermeta.mojang.com", bmclRoot),
+                new MirrorRule("https://piston-meta.mojang.com", bmclRoot),
+                new MirrorRule("https://piston-data.mojang.com", bmclRoot),
+                new MirrorRule("https://launcher.mojang.com", bmclRoot),
+                new MirrorRule("https://libraries.minecraft.net", bmclRoot + "/libraries"),
+                new MirrorRule("http://files.minecraftforge.net/maven", bmclRoot + "/maven"),
+                new MirrorRule("https://files.minecraftforge.net/maven", bmclRoot + "/maven"),
+                new MirrorRule("https://maven.minecraftforge.net", bmclRoot + "/maven"),
+                new MirrorRule("https://maven.neoforged.net/releases/", bmclRoot + "/maven/"),
+                new MirrorRule("http://dl.liteloader.com/versions", bmclRoot + "/maven"),
+                new MirrorRule("https://dl.liteloader.com/versions", bmclRoot + "/maven"),
+                new MirrorRule("https://meta.fabricmc.net", bmclRoot + "/fabric-meta"),
+                new MirrorRule("https://maven.fabricmc.net", bmclRoot + "/maven"),
+                new MirrorRule("https://authlib-injector.yushi.moe", bmclRoot + "/mirrors/authlib-injector"),
+                new MirrorRule("https://repo1.maven.org/maven2", "https://mirrors.cloud.tencent.com/nexus/repository/maven-public"),
+                new MirrorRule("https://repo.maven.apache.org/maven2", "https://mirrors.cloud.tencent.com/nexus/repository/maven-public"),
+                new MirrorRule("https://hmcl.glavo.site/metadata/cleanroom", "https://alist.8mi.tech/d/mirror/HMCL-Metadata/Auto/cleanroom"),
+                new MirrorRule("https://hmcl.glavo.site/metadata/fmllibs", "https://alist.8mi.tech/d/mirror/HMCL-Metadata/Auto/fmllibs"),
+                new MirrorRule("https://zkitefly.github.io/unlisted-versions-of-minecraft", "https://alist.8mi.tech/d/mirror/unlisted-versions-of-minecraft/Auto"),
+
+                // https://github.com/mcmod-info-mirror/mcim-rust-api
+                new MirrorRule("https://api.modrinth.com", "https://mod.mcimirror.top/modrinth", true),
+                new MirrorRule("https://cdn.modrinth.com", "https://mod.mcimirror.top", true),
+                new MirrorRule("https://api.curseforge.com", "https://mod.mcimirror.top/curseforge", true),
+                new MirrorRule("https://edge.forgecdn.net", "https://mod.mcimirror.top", true)
+        );
+    }
+
+    @Override
+    protected Task<? extends ComponentRemoteVersionList<?>> fetchVersionsAsync(GameComponentType type, @Nullable GameVersionNumber gameVersion) {
+        assert (gameVersion == null) == (type == GameComponentType.GAME);
+        switch (type) {
+            case FORGE -> {
+                Task<ComponentRemoteVersionList<ForgeRemoteVersion>> fetchOfficial = ForgeRemoteVersion.fetchAsync(this, gameVersion);
+
+                DownloadSource source = versionListSource;
+                if (!LocaleUtils.IS_CHINA_MAINLAND && (source == DownloadSource.DEFAULT || source == DownloadSource.OFFICIAL)) {
+                    return fetchOfficial;
+                }
+
+                Task<ComponentRemoteVersionList<ForgeRemoteVersion>> fetchBMCL = ForgeRemoteVersion.fetchBMCLAsync(this, bmclRoot, gameVersion);
+                if (source == DownloadSource.MIRROR) {
+                    return new FallbackTask<>(fetchBMCL, fetchOfficial);
+                } else {
+                    return new FallbackTask<>(fetchOfficial, fetchBMCL);
+                }
+            }
+            case NEO_FORGE -> {
+                Task<ComponentRemoteVersionList<NeoForgeRemoteVersion>> fetchOfficial = NeoForgeRemoteVersion.fetchAsync(this, gameVersion);
+
+                DownloadSource source = versionListSource;
+                if (!LocaleUtils.IS_CHINA_MAINLAND && (source == DownloadSource.DEFAULT || source == DownloadSource.OFFICIAL)) {
+                    return fetchOfficial;
+                }
+                Task<ComponentRemoteVersionList<NeoForgeRemoteVersion>> fetchBMCL = NeoForgeRemoteVersion.fetchBMCLAsync(bmclRoot, gameVersion);
+                if (source == DownloadSource.MIRROR || source == DownloadSource.DEFAULT) {
+                    return new FallbackTask<>(fetchBMCL, fetchOfficial);
+                } else {
+                    return new FallbackTask<>(fetchOfficial, fetchBMCL);
+                }
+            }
+            case OPTIFINE -> {
+                return OptiFineRemoteVersion.fetchBMCLAsync(this, bmclRoot, gameVersion);
+            }
+        }
+
+        return super.fetchVersionsAsync(type, gameVersion);
+    }
+
+    public void setFileSource(DownloadSource fileSource) {
+        this.fileSource = Objects.requireNonNull(fileSource);
+    }
+
+    public void setVersionListSource(DownloadSource versionListSource) {
+        this.versionListSource = Objects.requireNonNull(versionListSource);
+    }
+
+    @Override
+    public HMCLCacheRepository getCacheRepository() {
+        return HMCLCacheRepository.REPOSITORY;
+    }
+
+    @Override
+    public DownloadCandidates getGameVersionListCandidates() {
+        return getCandidates(
+                versionListSource,
+                GameRemoteVersion.VERSION_MANIFEST_URL,
+                WebURL.parse(bmclRoot + "/mc/game/version_manifest.json")
+        );
+    }
+
+    @Override
+    public FabricLikeVersionListCandidates getFabricVersionListCandidates() {
+        DownloadSource source = versionListSource;
+        return new FabricLikeVersionListCandidates(
+                getCandidates(source, FabricRemoteVersion.LOADER_META_URL, WebURL.parse(bmclRoot + "/fabric-meta/v2/versions/loader")),
+                getCandidates(source, FabricRemoteVersion.GAME_META_URL, WebURL.parse(bmclRoot + "/fabric-meta/v2/versions/game"))
+        );
+    }
+
+    @Override
+    public DownloadCandidates getCleanroomVersionListCandidates() {
+        return LocaleUtils.IS_CHINA_MAINLAND
+                ? DownloadCandidates.of(CleanroomRemoteVersion.LOADER_LIST_URL, WebURL.parse("https://alist.8mi.tech/d/mirror/HMCL-Metadata/Auto/cleanroom/index.json"))
+                : DownloadCandidates.of(CleanroomRemoteVersion.LOADER_LIST_URL);
+    }
+
+    @Override
+    public DownloadCandidates getDownloadCandidates(List<String> urls) {
+        return getCandidates(fileSource, rules, urls);
+    }
+
+    @Override
+    public DownloadCandidates getVersionListCandidates(List<String> urls) {
+        return getCandidates(versionListSource, rules, urls);
+    }
+
+    @Override
+    public DownloadCandidates getAssetObjectCandidates(AssetObject assetObject) {
+        return getCandidates(
+                fileSource,
+                WebURL.parse("https://resources.download.minecraft.net/" + assetObject.getLocation()),
+                WebURL.parse(bmclRoot + "/assets/" + assetObject.getLocation())
+        );
+    }
+
+    @NotNullByDefault
+    private static final class FallbackTask<T> extends Task<T> {
+
+        private final Task<? extends T> task;
+        private final Task<? extends T> fallback;
+
+        private List<Task<?>> dependencies = List.of();
+
+        public FallbackTask(Task<? extends T> task, Task<? extends T> fallback) {
+            this.task = task;
+            this.fallback = fallback;
+        }
+
+        @Override
+        public Collection<? extends Task<?>> getDependents() {
+            return List.of(task);
+        }
+
+        @Override
+        public boolean isRelyingOnDependents() {
+            return false;
+        }
+
+        @Override
+        public void execute() throws Exception {
+            if (isDependentsSucceeded()) {
+                setResult(task.getResult());
+            } else {
+                dependencies = List.of(fallback);
+                fallback.storeTo(this::setResult);
+            }
+        }
+
+        @Override
+        public List<Task<?>> getDependencies() {
+            return dependencies;
+        }
+    }
+
+    private record MirrorRule(String source, String target, boolean fallback) {
+        public MirrorRule(String source, String target) {
+            this(source, target, false);
+        }
+    }
+}
+

HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLDependencyManager.java

@@ -0,0 +1,65 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.game;
+
+import org.jackhuang.hmcl.download.DefaultCacheRepository;
+import org.jackhuang.hmcl.download.DefaultDependencyManager;
+import org.jackhuang.hmcl.download.DownloadProvider;
+import org.jetbrains.annotations.NotNullByDefault;
+
+/// Provides HMCL-specific game builders for an HMCL game repository.
+@NotNullByDefault
+public class HMCLDependencyManager extends DefaultDependencyManager {
+    /// Creates a dependency manager for a repository and download context.
+    ///
+    /// @param repository       the associated game repository
+    /// @param downloadProvider the remote download provider
+    /// @param cacheRepository  the artifact cache
+    public HMCLDependencyManager(
+            HMCLGameRepository repository,
+            DownloadProvider downloadProvider,
+            DefaultCacheRepository cacheRepository) {
+        super(repository, downloadProvider, cacheRepository);
+    }
+
+    /// {@inheritDoc}
+    @Override
+    public HMCLGameRepository getGameRepository() {
+        return (HMCLGameRepository) super.getGameRepository();
+    }
+
+    /// {@inheritDoc}
+    @Override
+    public HMCLGameBuilder newGameBuilder(GameInstanceID instanceId) {
+        GameInstanceManifest initialManifest = new GameInstanceManifest(instanceId);
+        DefaultGameRepositoryDraft draft = openGameBuilderDraft(initialManifest, null);
+        return new HMCLGameBuilder(this, instanceId, null, draft, initialManifest);
+    }
+
+    /// {@inheritDoc}
+    @Override
+    public HMCLGameBuilder newGameBuilder(GameInstance instance) {
+        validateGameInstance(instance);
+        HMCLGameInstance updateTarget = (HMCLGameInstance) instance;
+
+        GameInstanceManifest initialManifest = new GameInstanceManifest(updateTarget.getId());
+        DefaultGameRepositoryDraft draft = openGameBuilderDraft(initialManifest, updateTarget);
+        return new HMCLGameBuilder(
+                this, updateTarget.getId(), updateTarget, draft, initialManifest);
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLGameBuilder.java

@@ -0,0 +1,53 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.game;
+
+import org.jackhuang.hmcl.download.DefaultGameBuilder;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
+
+/// Builds game instances and applies HMCL-specific post-installation settings.
+@NotNullByDefault
+public class HMCLGameBuilder extends DefaultGameBuilder {
+    /// Creates a builder around an HMCL target already reserved by its dependency manager.
+    ///
+    /// @param dependencyManager the dependency manager for the target repository
+    /// @param instanceId        the id of the reserved instance
+    /// @param updateTarget      the exact update target retained by the draft, or `null` for install
+    /// @param draft             the open draft containing `initialManifest`
+    /// @param initialManifest   the empty target manifest retained by `draft`
+    HMCLGameBuilder(
+            HMCLDependencyManager dependencyManager,
+            GameInstanceID instanceId,
+            @Nullable HMCLGameInstance updateTarget,
+            DefaultGameRepositoryDraft draft,
+            GameInstanceManifest initialManifest) {
+        super(dependencyManager, instanceId, updateTarget, draft, initialManifest);
+    }
+
+    /// {@inheritDoc}
+    ///
+    /// When isolation was enabled, persists the corresponding HMCL instance setting so subsequent
+    /// launches use the instance root. A read-only instance retains its existing setting.
+    @Override
+    protected void onInstanceCommitted(DefaultGameInstance instance) {
+        if (isolationEnabled) {
+            ((HMCLGameInstance) instance).enableIsolation();
+        }
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLGameInstance.java

@@ -0,0 +1,856 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.game;
+
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParseException;
+import com.google.gson.reflect.TypeToken;
+import javafx.beans.property.ReadOnlyObjectProperty;
+import javafx.beans.property.ReadOnlyObjectPropertyBase;
+import javafx.scene.image.Image;
+import org.jackhuang.hmcl.Metadata;
+import org.jackhuang.hmcl.addon.mod.ModLoaderType;
+import org.jackhuang.hmcl.java.JavaRuntime;
+import org.jackhuang.hmcl.modpack.ModpackConfiguration;
+import org.jackhuang.hmcl.modpack.ModpackProvider;
+import org.jackhuang.hmcl.setting.*;
+import org.jackhuang.hmcl.ui.FXUtils;
+import org.jackhuang.hmcl.util.FileSaver;
+import org.jackhuang.hmcl.util.Lang;
+import org.jackhuang.hmcl.util.StringUtils;
+import org.jackhuang.hmcl.util.gson.JsonSchema;
+import org.jackhuang.hmcl.util.gson.JsonUtils;
+import org.jackhuang.hmcl.util.io.FileUtils;
+import org.jackhuang.hmcl.util.platform.SystemInfo;
+import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
+
+import java.io.IOException;
+import java.lang.ref.WeakReference;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Locale;
+import java.util.Objects;
+import java.util.stream.Collectors;
+
+import static org.jackhuang.hmcl.setting.SettingsManager.settings;
+import static org.jackhuang.hmcl.util.Pair.pair;
+import static org.jackhuang.hmcl.util.logging.Logger.LOG;
+
+/// HMCL-specific game instance that owns instance-local settings and run-directory policy.
+@NotNullByDefault
+public class HMCLGameInstance extends DefaultGameInstance {
+
+    /// Whether the instance-local game settings file has already been inspected.
+    private boolean gameSettingsLoaded;
+
+    /// Whether the instance-local game settings file cannot be overwritten safely.
+    private boolean gameSettingsReadOnly;
+
+    /// Cached instance-local game settings, or `null` when none exist after loading.
+    private GameSettings.@Nullable Instance gameSettings;
+
+    /// Creates a registered instance bound to the given repository snapshot.
+    ///
+    /// @param snapshot the repository snapshot that owns this instance
+    /// @param id       the instance id
+    /// @param manifest the stored instance manifest
+    protected HMCLGameInstance(DefaultGameRepositorySnapshot snapshot, GameInstanceID id, GameInstanceManifest manifest) {
+        this(snapshot, id, manifest, (Path) null);
+    }
+
+    /// Creates a registered instance with an optional non-conventional manifest path.
+    ///
+    /// @param snapshot     the repository snapshot that owns this instance
+    /// @param id           the instance id
+    /// @param manifest     the stored instance manifest
+    /// @param manifestFile the actual manifest JSON path, or `null` for the layout default
+    protected HMCLGameInstance(
+            DefaultGameRepositorySnapshot snapshot,
+            GameInstanceID id,
+            GameInstanceManifest manifest,
+            @Nullable Path manifestFile) {
+        super(snapshot, id, manifest, manifestFile);
+    }
+
+    /// Creates an instance that shares mutable instance-local state with another instance.
+    ///
+    /// Used when the repository clones a snapshot so that settings and the icon property remain
+    /// available on the new wrapper.
+    private HMCLGameInstance(
+            DefaultGameRepositorySnapshot snapshot,
+            GameInstanceID id,
+            GameInstanceManifest manifest,
+            HMCLGameInstance shareState) {
+        super(snapshot, id, manifest, shareState);
+        this.gameSettingsLoaded = shareState.gameSettingsLoaded;
+        this.gameSettingsReadOnly = shareState.gameSettingsReadOnly;
+        this.gameSettings = shareState.gameSettings;
+    }
+
+    @Override
+    protected HMCLGameInstance withNewSnapshot(DefaultGameRepositorySnapshot newSnapshot) {
+        return new HMCLGameInstance(newSnapshot, id, manifest, this);
+    }
+
+    @Override
+    protected HMCLGameInstance withManifest(DefaultGameRepositorySnapshot newSnapshot, GameInstanceManifest manifest) {
+        return new HMCLGameInstance(newSnapshot, id, manifest, this);
+    }
+
+    @Override
+    public HMCLGameRepository getRepository() {
+        return (HMCLGameRepository) super.getRepository();
+    }
+
+    @Override
+    public HMCLGameRepositoryLayout getLayout() {
+        return (HMCLGameRepositoryLayout) super.getLayout();
+    }
+
+    /// Returns the HMCL modpack configuration file for this instance.
+    ///
+    /// @return the `modpack.cfg` path in the instance root
+    @Override
+    public Path getModpackConfigurationFile() {
+        return getLayout().getModpackConfigurationFile(getId());
+    }
+
+    /// Returns whether this instance has an HMCL modpack configuration file.
+    ///
+    /// @return whether [#getModpackConfigurationFile()] exists
+    public boolean isModpack() {
+        return Files.exists(getModpackConfigurationFile());
+    }
+
+    /// Reads this instance's HMCL modpack configuration.
+    ///
+    /// @return the parsed configuration, or `null` when the file does not exist
+    /// @throws IOException if the configuration cannot be read
+    public @Nullable ModpackConfiguration<?> readModpackConfiguration() throws IOException {
+        Path file = getModpackConfigurationFile();
+        if (Files.notExists(file)) {
+            return null;
+        }
+        try {
+            return JsonUtils.fromJsonFile(file, ModpackConfiguration.class);
+        } catch (JsonParseException e) {
+            throw new IOException("Malformed modpack configuration: " + file, e);
+        }
+    }
+
+    @Override
+    public Path getRunDirectory() {
+        return getRepository().computeRunDirectory(getId(), isModpack(), getSettings());
+    }
+
+    /// Returns the loaded instance-local game settings, loading them while this instance is current.
+    ///
+    /// @return the settings, or `null` when no local settings exist after loading
+    public @Nullable GameSettings.Instance getSettings() {
+        ensureGameSettingsLoaded();
+        return gameSettings;
+    }
+
+    /// Returns the instance-local game settings, creating an empty settings object when absent.
+    ///
+    /// @return the settings, or `null` when the settings file is read-only and no settings are loaded
+    public @Nullable GameSettings.Instance getSettingsOrCreate() {
+        GameSettings.Instance setting = getSettings();
+        if (setting == null) {
+            setting = createSettings();
+        }
+        return setting;
+    }
+
+    /// Resolves this instance's effective settings against its selected parent preset.
+    ///
+    /// @return the effective settings
+    public GameSettings.Effective getEffectiveSettings() {
+        @Nullable GameSettings.Instance setting = getSettings();
+        return GameSettings.resolve(getRepository().getParentGameSettings(setting), setting);
+    }
+
+    /// Creates empty instance-local game settings when none are loaded.
+    ///
+    /// @return the settings, or `null` when settings are read-only or already present in a non-creatable state
+    public @Nullable GameSettings.Instance createSettings() {
+        ensureGameSettingsLoaded();
+        if (gameSettingsReadOnly) {
+            return null;
+        }
+        if (gameSettings != null) {
+            return gameSettings;
+        }
+        return initSettings(new GameSettings.Instance(), true);
+    }
+
+    /// Returns whether the instance-local game settings file cannot be overwritten safely.
+    ///
+    /// @return whether the settings are loaded in read-only mode
+    public boolean isSettingsReadOnly() {
+        ensureGameSettingsLoaded();
+        return gameSettingsReadOnly;
+    }
+
+    /// Enables instance-local running-directory selection for this instance.
+    ///
+    /// A blank local running directory resolves to the instance root. This operation is idempotent
+    /// and schedules a settings save only when it adds the override. It leaves the instance
+    /// unchanged when its local settings cannot be written safely.
+    public void enableIsolation() {
+        if (isSettingsReadOnly()) {
+            return;
+        }
+
+        @Nullable GameSettings.Instance setting = getSettingsOrCreate();
+        if (setting != null
+                && setting.getOverrideProperties().add(GameSettings.PROPERTY_RUNNING_DIRECTORY)) {
+            saveSettings();
+        }
+    }
+
+    /// Backs up and overwrites the settings file when this instance still owns its settings.
+    public void forceOverwriteSettings() {
+        ensureGameSettingsLoaded();
+        if (!ownsGameSettings()) {
+            return;
+        }
+
+        GameSettings.Instance setting = gameSettings;
+        if (setting == null) {
+            setting = new GameSettings.Instance();
+            gameSettings = setting;
+            gameSettingsLoaded = true;
+        }
+
+        boolean installAutoSave = !setting.isSavable();
+        Path file = getGameSettingsFile().toAbsolutePath().normalize();
+        SettingFileUtils.backupInvalidConfig(file);
+        setting.setSchema(GameSettings.Instance.CURRENT_SCHEMA);
+        setting.setSavable(true);
+        setting.setBackupOnNextSave(false);
+        gameSettingsReadOnly = false;
+        saveSettings();
+        if (installAutoSave) {
+            setting.addListener(a -> saveSettings());
+        }
+    }
+
+    /// Saves the settings asynchronously when writable and still owned by the current instance.
+    public void saveSettings() {
+        if (gameSettings == null || gameSettingsReadOnly || !ownsGameSettings()) {
+            return;
+        }
+
+        GameSettings.Instance setting = gameSettings;
+        Path file = getGameSettingsFile().toAbsolutePath().normalize();
+        try {
+            Files.createDirectories(file.getParent());
+        } catch (IOException e) {
+            LOG.warning("Failed to create directory: " + file.getParent(), e);
+        }
+
+        if (setting.isBackupOnNextSave()) {
+            setting.setBackupOnNextSave(false);
+            SettingFileUtils.backupInvalidConfig(file);
+        }
+        FileSaver.save(file, LauncherSettings.SETTINGS_GSON.toJson(setting));
+    }
+
+    /// Saves the settings synchronously when writable and still owned by the current instance.
+    ///
+    /// @throws IOException if saving the file fails
+    public void saveSettingsSync() throws IOException {
+        if (gameSettings == null || gameSettingsReadOnly || !ownsGameSettings()) {
+            return;
+        }
+
+        GameSettings.Instance setting = gameSettings;
+        Path file = getGameSettingsFile().toAbsolutePath().normalize();
+        Files.createDirectories(file.getParent());
+        if (setting.isBackupOnNextSave()) {
+            setting.setBackupOnNextSave(false);
+            SettingFileUtils.backupInvalidConfig(file);
+        }
+        FileUtils.saveSafely(file, LauncherSettings.SETTINGS_GSON.toJson(setting));
+    }
+
+    /// Initializes this instance with the given settings object.
+    ///
+    /// @param setting   the settings to install
+    /// @param allowSave whether the settings may be written back to disk
+    /// @return the installed settings
+    public GameSettings.Instance initSettings(GameSettings.Instance setting, boolean allowSave) {
+        normalizeRunningDirectoryOverride(setting);
+        setting.setSavable(allowSave);
+        gameSettingsLoaded = true;
+        gameSettings = setting;
+        setting.iconProperty().addListener(observable -> invalidateIconImage());
+        if (allowSave) {
+            gameSettingsReadOnly = false;
+            setting.addListener(a -> saveSettings());
+        } else {
+            gameSettingsReadOnly = true;
+        }
+        return setting;
+    }
+
+    /// Returns a deep copy of the currently loaded settings, or a new settings object that inherits
+    /// the effective parent preset when no local settings exist.
+    ///
+    /// @return a detached copy suitable for installing into another instance
+    public GameSettings.Instance copySettings() {
+        @Nullable GameSettings.Instance setting = getSettings();
+        if (setting != null) {
+            return JsonUtils.clone(LauncherSettings.SETTINGS_GSON, setting, TypeToken.get(GameSettings.Instance.class));
+        }
+
+        GameSettings.Instance copied = new GameSettings.Instance();
+        copied.parentProperty().setValue(
+                getEffectiveSettings().getPreset().idProperty().getValue());
+        return copied;
+    }
+
+    /// Returns the first custom icon file found in this instance's root directory.
+    ///
+    /// @return the icon file, or empty when no supported icon file exists
+    public @Nullable Path getIconFile() {
+        for (String extension : FXUtils.IMAGE_EXTENSIONS) {
+            Path file = getInstanceRoot().resolve("icon." + extension);
+            if (Files.exists(file)) {
+                return file;
+            }
+        }
+        return null;
+    }
+
+    /// Replaces this instance's custom icon file.
+    ///
+    /// Existing supported icon files are removed before `iconFile` is copied.
+    ///
+    /// @param iconFile the source icon file
+    /// @throws IOException              if the icon cannot be copied
+    /// @throws IllegalArgumentException if the file extension is unsupported
+    public void setIconFile(Path iconFile) throws IOException {
+        String extension = FileUtils.getExtension(iconFile).toLowerCase(Locale.ROOT);
+        if (!FXUtils.IMAGE_EXTENSIONS.contains(extension)) {
+            throw new IllegalArgumentException("Unsupported icon file: " + extension);
+        }
+
+        clearIconFiles();
+        FileUtils.copyFile(iconFile, getInstanceRoot().resolve("icon." + extension));
+        invalidateIconImage();
+    }
+
+    /// Deletes all supported custom icon files for this instance.
+    ///
+    /// Individual deletion failures are logged and do not stop later files from being attempted.
+    public void deleteIconFile() {
+        clearIconFiles();
+        invalidateIconImage();
+    }
+
+    private void clearIconFiles() {
+        for (String extension : FXUtils.IMAGE_EXTENSIONS) {
+            Path file = getInstanceRoot().resolve("icon." + extension);
+            try {
+                Files.deleteIfExists(file);
+            } catch (IOException e) {
+                LOG.warning("Failed to delete instance icon file: " + file, e);
+            }
+        }
+    }
+
+    /// Soft-cached icon image for this instance id.
+    ///
+    /// Shared across COW snapshot wrappers. The computed [Image] is retained only via a
+    /// [WeakReference], so it can be reclaimed under memory pressure when nothing else holds it.
+    private @Nullable WeakCachedIconImageProperty iconImage;
+
+    /// Returns the observable icon image for this instance.
+    ///
+    /// The image is stored in a [WeakReference] cache: when nothing else strongly references it
+    /// (for example no UI node is displaying it), the JVM may reclaim the [Image] under memory
+    /// pressure. The next [#getIconImage] reloads it.
+    ///
+    /// @return the icon image property
+    public ReadOnlyObjectProperty<Image> iconImageProperty() {
+        if (iconImage == null) {
+            iconImage = new WeakCachedIconImageProperty();
+        }
+        return iconImage;
+    }
+
+    /// Returns the icon image selected for this instance.
+    ///
+    /// Equivalent to [ReadOnlyObjectProperty#get()] on [#iconImageProperty].
+    ///
+    /// @return the selected or derived icon image
+    public Image getIconImage() {
+        return iconImageProperty().get();
+    }
+
+    /// Drops the soft-cached icon image and notifies observers.
+    public void invalidateIconImage() {
+        ((WeakCachedIconImageProperty) iconImageProperty()).invalidate();
+    }
+
+    /// Soft-cached read-only icon property compatible with JavaFX versions before 19.
+    private final class WeakCachedIconImageProperty extends ReadOnlyObjectPropertyBase<Image> {
+        private @Nullable WeakReference<Image> cache;
+
+        @Override
+        public Object getBean() {
+            return HMCLGameInstance.this;
+        }
+
+        @Override
+        public String getName() {
+            return "iconImage";
+        }
+
+        @Override
+        public Image get() {
+            WeakReference<Image> current = cache;
+            Image image = current != null ? current.get() : null;
+            if (image != null) {
+                return image;
+            }
+
+            image = computeIconImage();
+            cache = new WeakReference<>(image);
+            return image;
+        }
+
+        /// Computes the icon image from settings, custom files, and the launch manifest.
+        ///
+        /// @return the selected or derived icon image
+        private Image computeIconImage() {
+            @Nullable GameSettings.Instance setting = getSettings();
+            GameInstanceIconType iconType = setting != null
+                    ? Lang.requireNonNullElse(setting.iconProperty().getValue(), GameInstanceIconType.DEFAULT)
+                    : GameInstanceIconType.DEFAULT;
+            if (iconType != GameInstanceIconType.DEFAULT) {
+                return iconType.getIcon();
+            }
+
+            @Nullable Path iconFile = getIconFile();
+            if (iconFile != null) {
+                try {
+                    return FXUtils.loadImage(iconFile, 64, 64, true, true);
+                } catch (Exception e) {
+                    LOG.warning("Failed to load instance icon for " + getId(), e);
+                }
+            }
+
+            for (ModLoaderType modLoader : getModLoaders()) {
+                return GameInstanceIconType.getIconType(modLoader).getIcon();
+            }
+
+            if (hasComponent(GameComponentType.OPTIFINE))
+                return GameInstanceIconType.OPTIFINE.getIcon();
+
+            GameVersionNumber version = getVersion();
+            if (version.isAprilFools())
+                return GameInstanceIconType.APRIL_FOOLS.getIcon();
+            else if (version instanceof GameVersionNumber.LegacySnapshot || version instanceof GameVersionNumber.Release release && release.getEaType() != GameVersionNumber.Release.ReleaseType.GA)
+                return GameInstanceIconType.COMMAND.getIcon();
+            else if (version instanceof GameVersionNumber.Old)
+                return GameInstanceIconType.CRAFT_TABLE.getIcon();
+            else
+                return GameInstanceIconType.GRASS.getIcon();
+        }
+
+        /// Clears the weak cache and notifies listeners.
+        void invalidate() {
+            cache = null;
+            fireValueChangedEvent();
+        }
+    }
+
+    /// Creates the marker indicating that the most recent launch ended abnormally.
+    public void markLaunchedAbnormally() {
+        try {
+            Files.createFile(getInstanceRoot().resolve(".abnormal"));
+        } catch (IOException ignored) {
+        }
+    }
+
+    /// Deletes the abnormal-launch marker when present.
+    ///
+    /// @return whether a regular marker file was present
+    public boolean unmarkLaunchedAbnormally() {
+        Path file = getInstanceRoot().resolve(".abnormal");
+        if (!Files.isRegularFile(file)) {
+            return false;
+        }
+
+        try {
+            Files.delete(file);
+        } catch (IOException e) {
+            LOG.warning("Failed to delete abnormal launch marker: " + file, e);
+        }
+        return true;
+    }
+
+    /// Loads settings once while this object is the repository's current instance.
+    private void ensureGameSettingsLoaded() {
+        if (!gameSettingsLoaded && getRepository().findInstance(id) == this) {
+            loadGameSettings();
+        }
+    }
+
+    /// Returns whether this instance still owns the settings object used by the current snapshot.
+    private boolean ownsGameSettings() {
+        @Nullable HMCLGameInstance current = getRepository().findInstance(id);
+        boolean owns = current == this
+                || current != null && gameSettings != null && current.gameSettings == gameSettings;
+        if (!owns && gameSettings != null) {
+            gameSettings.setSavable(false);
+        }
+        return owns;
+    }
+
+    private void loadGameSettings() {
+        gameSettingsLoaded = true;
+        LoadResult result = loadGameSettingsFile(getGameSettingsFile());
+        if (result.setting() != null) {
+            initSettings(result.setting(), result.allowSave());
+            return;
+        }
+        if (!result.allowSave()) {
+            gameSettingsReadOnly = true;
+            return;
+        }
+
+        @Nullable GameSettingsPresetID legacyParent = getRepository().getGameDirectory().getLegacyGameSettings();
+        if (SettingsManager.getGameSettings(legacyParent) == null) {
+            legacyParent = null;
+        }
+
+        LegacyGameSettingsMigrator.InstanceMigrationResult migrationResult =
+                LegacyGameSettingsMigrator.migrateInstanceGameSettings(
+                        getRepository(), id, legacyParent);
+        if (migrationResult != null) {
+            initSettings(migrationResult.setting(), true);
+            try {
+                saveSettingsSync();
+                migrationResult.saveReceipt();
+            } catch (IOException e) {
+                LOG.warning("Failed to save migrated instance game settings for " + id, e);
+            }
+        }
+    }
+
+    private Path getGameSettingsFile() {
+        return getLayout().getInstanceGameSettingsFile(id);
+    }
+
+    public LaunchOptions.Builder getLaunchOptions(JavaRuntime javaVersion, Path gameDir, List<String> javaAgents, List<String> javaArguments, boolean makeLaunchScript) {
+        GameSettings.Effective vs = getEffectiveSettings();
+        boolean noJVMOptions = vs.getInheritable(GameSettings::noJVMOptionsProperty);
+        boolean autoMemory = vs.getInheritable(GameSettings::autoMemoryProperty);
+        GameVersionNumber gameVersionNumber = getVersion();
+
+        @Nullable Integer maxMemory;
+        if (autoMemory) {
+            maxMemory = noJVMOptions
+                    ? null
+                    : Math.toIntExact(HMCLGameRepository.getAutoAllocatedMemory(
+                            SystemInfo.getPhysicalMemoryStatus().available(),
+                            javaVersion.getPlatform()) / 1024L / 1024L);
+        } else {
+            maxMemory = vs.getMaxMemory();
+        }
+
+        LaunchOptions.Builder builder = new LaunchOptions.Builder()
+                .setInstanceId(getId())
+                .setGameDir(gameDir)
+                .setJava(javaVersion)
+                .setVersionType(Metadata.TITLE)
+                .setVersionName(getId().id())
+                .setProfileName(Metadata.TITLE)
+                .setGameArguments(StringUtils.tokenize(vs.getInheritable(GameSettings::gameArgumentsProperty)))
+                .setOverrideJavaArguments(StringUtils.tokenize(vs.getInheritable(GameSettings::jvmOptionsProperty)))
+                .setMaxMemory(maxMemory)
+                .setMinMemory(vs.getInheritable(GameSettings::minMemoryProperty))
+                .setMetaspace(Lang.toIntOrNull(vs.getInheritable(GameSettings::permSizeProperty)))
+                .setEnvironmentVariables(
+                        Lang.mapOf(StringUtils.tokenize(vs.getInheritable(GameSettings::environmentVariablesProperty))
+                                .stream()
+                                .map(it -> {
+                                    int idx = it.indexOf('=');
+                                    return idx >= 0 ? pair(it.substring(0, idx), it.substring(idx + 1)) : pair(it, "");
+                                })
+                                .collect(Collectors.toList())
+                        )
+                )
+                .setWidth(vs.getWidth())
+                .setHeight(vs.getHeight())
+                .setFullscreen(vs.getInheritable(GameSettings::windowTypeProperty) == GameWindowType.FULLSCREEN)
+                .setWrapper(vs.getInheritable(GameSettings::commandWrapperProperty))
+                .setProxyOption(getProxyOption())
+                .setPreLaunchCommand(vs.getInheritable(GameSettings::preLaunchCommandProperty))
+                .setPostExitCommand(vs.getInheritable(GameSettings::postExitCommandProperty))
+                .setNoGeneratedJVMArgs(noJVMOptions)
+                .setNoGeneratedOptimizingJVMArgs(vs.getInheritable(GameSettings::noOptimizingJVMOptionsProperty))
+                .setUseCustomNatives(vs.getInheritable(GameSettings::useCustomNativesProperty))
+                .setNativesDir(vs.getInheritable(GameSettings::nativesDirectoryProperty))
+                .setProcessPriority(vs.getInheritable(GameSettings::processPriorityProperty))
+                .setGraphicsBackend(vs.getInheritable(GameSettings::graphicsBackendProperty))
+                .setRenderer(vs.getRenderer(gameVersionNumber))
+                .setEnableDebugLogOutput(vs.getInheritable(GameSettings::enableDebugLogOutputProperty))
+                .setAllowAutoAgent(vs.getInheritable(GameSettings::allowAutoAgentProperty))
+                .setDisableAutoGameOptions(vs.getInheritable(GameSettings::disableAutoGameOptionsProperty))
+                .setUseNativeGLFWorSDL(vs.getInheritable(GameSettings::useNativeGLFWorSDLProperty))
+                .setUseNativeOpenAL(vs.getInheritable(GameSettings::useNativeOpenALProperty))
+                .setUseHighPerformanceGPU(vs.getInheritable(GameSettings::highPerformanceProperty))
+                .setDaemon(!makeLaunchScript && vs.getInheritable(GameSettings::launcherVisibilityProperty).isDaemon())
+                .setJavaAgents(javaAgents)
+                .setJavaArguments(javaArguments);
+
+        QuickPlayOption quickPlayOption = vs.getQuickPlayOption();
+        if (quickPlayOption != null) {
+            builder.setQuickPlayOption(quickPlayOption);
+        }
+
+        Path json = getModpackConfigurationFile();
+        if (Files.exists(json)) {
+            try {
+                String jsonText = Files.readString(json);
+                ModpackConfiguration<?> modpackConfiguration = JsonUtils.GSON.fromJson(jsonText, ModpackConfiguration.class);
+                ModpackProvider provider = ModpackHelper.getProviderByType(modpackConfiguration.getType());
+                if (provider != null) provider.injectLaunchOptions(jsonText, builder);
+            } catch (IOException | JsonParseException e) {
+                LOG.warning("Failed to parse modpack configuration file " + json, e);
+            }
+        }
+
+        if (autoMemory && builder.getJavaArguments().stream().anyMatch(it -> it.startsWith("-Xmx")))
+            builder.setMaxMemory(null);
+
+        return builder;
+    }
+
+    private static ProxyOption getProxyOption() {
+        return switch (settings().proxyTypeProperty().get()) {
+            case SYSTEM -> ProxyOption.Default.INSTANCE;
+            case DIRECT -> ProxyOption.Direct.INSTANCE;
+            case HTTP, SOCKS -> {
+                String proxyHost = settings().proxyHostProperty().get();
+                int proxyPort = settings().proxyPortProperty().get();
+
+                if (StringUtils.isBlank(proxyHost) || proxyPort < 0 || proxyPort > 0xFFFF) {
+                    yield ProxyOption.Default.INSTANCE;
+                }
+
+                String proxyUser = settings().proxyUserProperty().get();
+                String proxyPass = settings().proxyPasswordProperty().get();
+
+                if (StringUtils.isBlank(proxyUser)) {
+                    proxyUser = null;
+                    proxyPass = null;
+                } else if (proxyPass == null) {
+                    proxyPass = "";
+                }
+
+                if (settings().proxyTypeProperty().get() == ProxyType.HTTP) {
+                    yield new ProxyOption.Http(proxyHost, proxyPort, proxyUser, proxyPass);
+                } else {
+                    yield new ProxyOption.Socks(proxyHost, proxyPort, proxyUser, proxyPass);
+                }
+            }
+        };
+    }
+
+    /// Loads a new-format instance game settings file.
+    private static LoadResult loadGameSettingsFile(Path file) {
+        if (!Files.exists(file)) {
+            return new LoadResult(null, true);
+        }
+
+        try {
+            JsonObject jsonObject = JsonUtils.fromJsonFile(LauncherSettings.SETTINGS_GSON, file, JsonObject.class);
+            if (jsonObject == null) {
+                LOG.warning("Instance game settings are empty: " + file);
+                GameSettings.Instance fallback = new GameSettings.Instance();
+                return new LoadResult(fallback, true);
+            }
+
+            JsonSchema.CompatibilityResult schemaResult =
+                    JsonSchema.check(jsonObject, GameSettings.Instance.CURRENT_SCHEMA);
+            switch (schemaResult.status()) {
+                case MISSING -> LOG.warning("Missing schema in instance game settings: " + file);
+                case INVALID -> LOG.warning("Invalid schema in instance game settings: %s, Actual: %s".formatted(file, schemaResult.invalidValue()));
+                case UNPARSEABLE -> LOG.warning("Unparseable schema in instance game settings: %s, Actual: %s".formatted(file, schemaResult.actual()));
+                case UNEXPECTED_ID -> LOG.warning("Unexpected instance game settings schema. Expected: %s, Actual: %s".formatted(GameSettings.Instance.CURRENT_SCHEMA, schemaResult.actual()));
+                case UNSUPPORTED_MAJOR, READ_ONLY_PRESERVE_SCHEMA -> LOG.warning("Unsupported instance game settings schema. Expected: %s, Actual: %s".formatted(GameSettings.Instance.CURRENT_SCHEMA, schemaResult.actual()));
+                case READ_WRITE, READ_WRITE_PRESERVE_SCHEMA -> {
+                }
+            }
+            if (!schemaResult.readable()) {
+                GameSettings.Instance fallback = new GameSettings.Instance();
+                fallback.setSavable(false);
+                return new LoadResult(fallback, false);
+            }
+
+            GameSettings.@Nullable Instance setting =
+                    LauncherSettings.SETTINGS_GSON.fromJson(jsonObject, GameSettings.Instance.class);
+            if (setting == null) {
+                LOG.warning("Instance game settings deserialized to null: " + file);
+                GameSettings.Instance fallback = new GameSettings.Instance();
+                fallback.setBackupOnNextSave(true);
+                return new LoadResult(fallback, true);
+            }
+            if (!schemaResult.preserveSchema() && !GameSettings.Instance.CURRENT_SCHEMA.equals(setting.getSchema())) {
+                setting.setSchema(GameSettings.Instance.CURRENT_SCHEMA);
+            }
+            return new LoadResult(setting, schemaResult.allowSave());
+        } catch (JsonParseException ex) {
+            LOG.warning("Failed to parse game setting " + file, ex);
+            GameSettings.Instance fallback = new GameSettings.Instance();
+            fallback.setBackupOnNextSave(true);
+            return new LoadResult(fallback, true);
+        } catch (Exception ex) {
+            LOG.warning("Failed to load game setting " + file, ex);
+            return new LoadResult(null, false);
+        }
+    }
+
+    /// Keeps old local custom running directories effective under the new source-selection model.
+    private static void normalizeRunningDirectoryOverride(GameSettings.Instance setting) {
+        if (StringUtils.isNotBlank(setting.runningDirectoryProperty().getValue())) {
+            setting.getOverrideProperties().add(GameSettings.PROPERTY_RUNNING_DIRECTORY);
+        }
+    }
+
+    /// Result of loading an instance-specific game settings file.
+    ///
+    /// @param setting   the loaded instance settings, or `null` when unavailable
+    /// @param allowSave whether the file may be overwritten
+    private record LoadResult(@Nullable GameSettings.Instance setting, boolean allowSave) {
+    }
+
+    /// Optional reference to an HMCL game instance bound to a repository.
+    ///
+    /// Replaces the former `(repository, instanceId)` pair for UI and service context that may or
+    /// may not have a selected instance. When present, [#instance()] is a snapshot member and may
+    /// become stale after the repository publishes a new snapshot; call [#refreshed()] to re-resolve
+    /// from the current snapshot while preserving repository context.
+    @NotNullByDefault
+    public static final class Optional {
+        private final HMCLGameRepository repository;
+        private final @Nullable HMCLGameInstance instance;
+
+        /// Creates an empty optional bound only to a repository.
+        ///
+        /// @param repository the repository
+        public Optional(HMCLGameRepository repository) {
+            this.repository = Objects.requireNonNull(repository);
+            this.instance = null;
+        }
+
+        /// Creates an optional that holds the given instance.
+        ///
+        /// @param instance the instance
+        public Optional(HMCLGameInstance instance) {
+            this.repository = instance.getRepository();
+            this.instance = instance;
+        }
+
+        /// Creates an optional by resolving `instanceId` from the repository's current snapshot.
+        ///
+        /// @param repository the repository
+        /// @param instanceId the instance id, or `null` for an empty optional
+        /// @return an optional that is empty when `instanceId` is null or not registered
+        public static Optional of(HMCLGameRepository repository, @Nullable GameInstanceID instanceId) {
+            if (instanceId == null) {
+                return new Optional(repository);
+            }
+            HMCLGameInstance instance = repository.findInstance(instanceId);
+            return instance != null ? new Optional(instance) : new Optional(repository);
+        }
+
+        /// Creates an optional that holds the given instance.
+        ///
+        /// @param instance the instance
+        /// @return the optional
+        public static Optional of(HMCLGameInstance instance) {
+            return new Optional(instance);
+        }
+
+        /// Creates an empty optional bound only to a repository.
+        ///
+        /// @param repository the repository
+        /// @return the empty optional
+        public static Optional empty(HMCLGameRepository repository) {
+            return new Optional(repository);
+        }
+
+        /// Returns the repository associated with this optional.
+        ///
+        /// @return the repository
+        public HMCLGameRepository repository() {
+            return repository;
+        }
+
+        /// Returns the held instance, if any.
+        ///
+        /// @return the instance, or `null` when empty
+        @Contract(pure = true)
+        public @Nullable HMCLGameInstance instance() {
+            return instance;
+        }
+
+        /// Returns the held instance id, if any.
+        ///
+        /// @return the instance id, or `null` when empty
+        @Contract(pure = true)
+        public @Nullable GameInstanceID instanceId() {
+            return instance != null ? instance.getId() : null;
+        }
+
+        /// Returns whether an instance is present.
+        ///
+        /// @return whether [#instance()] is non-null
+        public boolean isPresent() {
+            return instance != null;
+        }
+
+        /// Returns whether no instance is present.
+        ///
+        /// @return whether [#instance()] is null
+        public boolean isEmpty() {
+            return instance == null;
+        }
+
+        /// Re-resolves the held instance id from the repository's current snapshot.
+        ///
+        /// @return this optional when empty; otherwise a fresh optional for the same id
+        public Optional refreshed() {
+            if (instance == null) {
+                return this;
+            }
+            return of(repository, instance.getId());
+        }
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLGameLauncher.java

@@ -42,16 +42,27 @@ import static org.jackhuang.hmcl.util.logging.Logger.LOG;
  */
 public final class HMCLGameLauncher extends DefaultLauncher {
 
-    public HMCLGameLauncher(GameRepository repository, Version version, AuthInfo authInfo, LaunchOptions options) {
-        this(repository, version, authInfo, options, null);
+    /// Creates a launcher with daemon process monitors.
+    ///
+    /// @param instance the instance being launched
+    /// @param manifest the effective launch-time manifest
+    /// @param authInfo authentication information for the game process
+    /// @param options  launch options
+    /// @param listener process listener, or `null` to inherit IO
+    public HMCLGameLauncher(GameInstance instance, GameInstanceManifest manifest, AuthInfo authInfo, LaunchOptions options, ProcessListener listener) {
+        this(instance, manifest, authInfo, options, listener, true);
     }
 
-    public HMCLGameLauncher(GameRepository repository, Version version, AuthInfo authInfo, LaunchOptions options, ProcessListener listener) {
-        this(repository, version, authInfo, options, listener, true);
-    }
-
-    public HMCLGameLauncher(GameRepository repository, Version version, AuthInfo authInfo, LaunchOptions options, ProcessListener listener, boolean daemon) {
-        super(repository, version, authInfo, options, listener, daemon);
+    /// Creates a launcher for the given instance and launch plan.
+    ///
+    /// @param instance the instance being launched
+    /// @param manifest the effective launch-time manifest
+    /// @param authInfo authentication information for the game process
+    /// @param options  launch options
+    /// @param listener process listener, or `null` to inherit IO
+    /// @param daemon   whether monitors should be daemon threads
+    public HMCLGameLauncher(GameInstance instance, GameInstanceManifest manifest, AuthInfo authInfo, LaunchOptions options, ProcessListener listener, boolean daemon) {
+        super(instance, manifest, authInfo, options, listener, daemon);
     }
 
     @Override
@@ -66,7 +77,7 @@ public final class HMCLGameLauncher extends DefaultLauncher {
         if (options.isDisableAutoGameOptions())
             return;
 
-        Path runDir = repository.getRunDirectory(version.getId());
+        Path runDir = instance.getRunDirectory();
         Path optionsFile = runDir.resolve("options.txt");
         Path configFolder = runDir.resolve("config");
 
@@ -91,8 +102,8 @@ public final class HMCLGameLauncher extends DefaultLauncher {
          *  1.11 ~ 1.12 : zh_cn works fine, zh_CN will display Chinese but the language setting will incorrectly show English as selected
          *  1.13+       : zh_cn works fine, zh_CN will automatically switch to English
          */
-        GameVersionNumber gameVersion = GameVersionNumber.asGameVersion(repository.getGameVersion(version));
-        if (gameVersion.compareTo("1.1") < 0)
+        GameVersionNumber gameVersion = instance.getVersion();
+        if (gameVersion == GameVersionNumber.unknown() || gameVersion.compareTo("1.1") < 0)
             return;
 
         String lang = normalizedLanguageTag(locale, gameVersion);
@@ -161,7 +172,7 @@ public final class HMCLGameLauncher extends DefaultLauncher {
         if (options.isAllowAutoAgent()
                 && !options.isNoGeneratedJVMArgs()
                 && !options.isNoGeneratedOptimizingJVMArgs()
-                && NativePatcher.needPatchMemoryUtil(version, options.getJava().getParsedVersion())) {
+                && NativePatcher.needPatchMemoryUtil(manifest, options.getJava().getParsedVersion())) {
             LOG.info("Attempting to patch game with lwjgl-unsafe-agent");
             try {
                 result.add("-javaagent:" + extractLwjglUnsafeAgent());
@@ -178,9 +189,9 @@ public final class HMCLGameLauncher extends DefaultLauncher {
         }
 
         Library library = new Library(new Artifact("org.glavo", "lwjgl-unsafe-agent", agentVersion));
-        String fileName = library.getArtifact().getFileName();
+        String fileName = library.artifact().getFileName();
 
-        Path agentPath = repository.getLibraryFile(version, library).toAbsolutePath().normalize();
+        Path agentPath = instance.getLayout().getLibraryFile(instance.getId(), library).toAbsolutePath().normalize();
         if (agentPath.toString().contains("=")) {
             throw new IOException("Invalid library path: " + agentPath);
         }

HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLGameRepositoryLayout.java

@@ -0,0 +1,63 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.game;
+
+import org.jetbrains.annotations.NotNullByDefault;
+
+import java.nio.file.Path;
+
+@NotNullByDefault
+public final class HMCLGameRepositoryLayout extends DefaultGameRepositoryLayout {
+    /// Directory under the instance root that stores HMCL-managed instance metadata.
+    private static final String INSTANCE_METADATA_DIRECTORY = ".hmcl";
+
+    /// Directory under the instance metadata directory that stores instance configuration files.
+    private static final String INSTANCE_CONFIG_DIRECTORY = "config";
+
+    /// Directory under the instance metadata directory that stores instance state files.
+    private static final String INSTANCE_STATE_DIRECTORY = "state";
+
+    /// Current file name for instance-specific game settings.
+    private static final String INSTANCE_GAME_SETTINGS_FILENAME = "instance-game-settings.json";
+
+    public HMCLGameRepositoryLayout(Path baseDirectory) {
+        super(baseDirectory);
+    }
+
+    /// Returns the HMCL-managed metadata directory under the instance root.
+    ///
+    /// This directory stores instance-scoped files owned by HMCL.
+    public Path getInstanceMetadataDirectory(GameInstanceID instanceId) {
+        return getInstanceRoot(instanceId).resolve(INSTANCE_METADATA_DIRECTORY);
+    }
+
+    /// Returns the HMCL-managed configuration directory under the instance metadata directory.
+    public Path getInstanceConfigDirectory(GameInstanceID instanceId) {
+        return getInstanceMetadataDirectory(instanceId).resolve(INSTANCE_CONFIG_DIRECTORY);
+    }
+
+    /// Returns the HMCL-managed state directory under the instance metadata directory.
+    public Path getInstanceStateDirectory(GameInstanceID instanceId) {
+        return getInstanceMetadataDirectory(instanceId).resolve(INSTANCE_STATE_DIRECTORY);
+    }
+
+    /// Returns the current local game settings path under the instance configuration directory.
+    public Path getInstanceGameSettingsFile(GameInstanceID instanceId) {
+        return getInstanceConfigDirectory(instanceId).resolve(INSTANCE_GAME_SETTINGS_FILENAME);
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLGameRepositorySnapshot.java

@@ -0,0 +1,55 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.game;
+
+import org.jetbrains.annotations.NotNullByDefault;
+
+import java.util.Collection;
+
+/// HMCL repository snapshot, parallel to [HMCLGameInstance] in the instance hierarchy.
+@NotNullByDefault
+public class HMCLGameRepositorySnapshot extends DefaultGameRepositorySnapshot {
+    /// Creates an empty unsealed HMCL snapshot.
+    ///
+    /// @param repository the owning repository
+    /// @param layout     the HMCL layout for this snapshot
+    public HMCLGameRepositorySnapshot(HMCLGameRepository repository, HMCLGameRepositoryLayout layout) {
+        super(repository, layout);
+    }
+
+    @Override
+    public HMCLGameRepository getRepository() {
+        return (HMCLGameRepository) super.getRepository();
+    }
+
+    @Override
+    public HMCLGameRepositoryLayout getLayout() {
+        return (HMCLGameRepositoryLayout) super.getLayout();
+    }
+
+    @Override
+    protected HMCLGameRepositorySnapshot newEmpty() {
+        return new HMCLGameRepositorySnapshot(getRepository(), getLayout());
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public Collection<HMCLGameInstance> getInstances() {
+        return (Collection<HMCLGameInstance>) super.getInstances();
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLModpackInstallTask.java

@@ -19,7 +19,7 @@ package org.jackhuang.hmcl.game;
 
 import com.google.gson.JsonParseException;
 import org.jackhuang.hmcl.download.DefaultDependencyManager;
-import org.jackhuang.hmcl.download.LibraryAnalyzer;
+import org.jackhuang.hmcl.download.GameBuilder;
 import org.jackhuang.hmcl.modpack.MinecraftInstanceTask;
 import org.jackhuang.hmcl.modpack.Modpack;
 import org.jackhuang.hmcl.modpack.ModpackConfiguration;
@@ -27,53 +27,110 @@ import org.jackhuang.hmcl.modpack.ModpackInstallTask;
 import org.jackhuang.hmcl.task.Task;
 import org.jackhuang.hmcl.util.gson.JsonUtils;
 import org.jackhuang.hmcl.util.io.CompressingUtils;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
 
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
-import java.util.Collections;
 import java.util.List;
+import java.util.regex.Matcher;
 
+/// Installs or updates an HMCL modpack by rebuilding its recognized game components.
+@NotNullByDefault
 public final class HMCLModpackInstallTask extends Task<Void> {
     private final Path zipFile;
-    private final String name;
+    private final GameInstanceID instanceId;
+
+    /// Existing instance selecting update mode, or `null` for a new installation.
+    private final @Nullable DefaultGameInstance updateTarget;
+
     private final HMCLGameRepository repository;
     private final DefaultDependencyManager dependency;
     private final Modpack modpack;
     private final List<Task<?>> dependencies = new ArrayList<>(1);
     private final List<Task<?>> dependents = new ArrayList<>(4);
 
-    public HMCLModpackInstallTask(HMCLGameRepository repository, Path zipFile, Modpack modpack, String name) {
+    /// Creates a task that installs a new HMCL modpack instance.
+    ///
+    /// @param repository the target HMCL game repository
+    /// @param zipFile    the HMCL modpack archive
+    /// @param modpack    the parsed modpack metadata
+    /// @param instanceId the id of the new instance
+    public HMCLModpackInstallTask(
+            HMCLGameRepository repository,
+            Path zipFile,
+            Modpack modpack,
+            GameInstanceID instanceId) {
+        this(repository, zipFile, modpack, instanceId, null);
+    }
+
+    /// Creates a task that updates an existing HMCL modpack instance.
+    ///
+    /// @param repository the target HMCL game repository
+    /// @param zipFile    the HMCL modpack archive
+    /// @param modpack    the parsed modpack metadata
+    /// @param instance   the existing instance to update
+    /// @throws IllegalArgumentException if `instance` belongs to another repository, has no
+    ///                                  modpack configuration, or records another provider type
+    public HMCLModpackInstallTask(
+            HMCLGameRepository repository,
+            Path zipFile,
+            Modpack modpack,
+            DefaultGameInstance instance) {
+        this(repository, zipFile, modpack, instance.getId(), instance);
+    }
+
+    /// Creates an HMCL modpack task in the mode selected by `updateTarget`.
+    ///
+    /// @param repository   the target HMCL game repository
+    /// @param zipFile      the HMCL modpack archive
+    /// @param modpack      the parsed modpack metadata
+    /// @param instanceId   the target instance id
+    /// @param updateTarget the existing instance selecting update mode, or `null` for install
+    /// @throws IllegalArgumentException if an update target belongs to another repository or has
+    ///                                  no compatible configuration
+    private HMCLModpackInstallTask(
+            HMCLGameRepository repository,
+            Path zipFile,
+            Modpack modpack,
+            GameInstanceID instanceId,
+            @Nullable DefaultGameInstance updateTarget) {
         this.repository = repository;
         this.dependency = repository.getDependency();
         this.zipFile = zipFile;
-        this.name = name;
+        this.instanceId = instanceId;
+        this.updateTarget = updateTarget;
         this.modpack = modpack;
+        if (this.updateTarget != null) {
+            dependency.validateGameInstance(this.updateTarget);
+        }
 
-        Path run = repository.getRunDirectory(name);
-        Path json = repository.getModpackConfiguration(name);
-        if (repository.hasVersion(name) && Files.notExists(json))
-            throw new IllegalArgumentException("Version " + name + " already exists");
+        Path run = repository.getLayout().getInstanceRoot(this.instanceId);
+        Path json = repository.getLayout().getModpackConfigurationFile(this.instanceId);
+        if (this.updateTarget != null && Files.notExists(json))
+            throw new IllegalArgumentException("Instance " + instanceId + " is not a HMCL modpack. Cannot update this instance.");
 
-        dependents.add(dependency.gameBuilder().name(name).gameVersion(modpack.getGameVersion()).buildAsync());
-
-        onDone().register(event -> {
-            if (event.isFailed()) repository.removeVersionFromDisk(name);
-        });
-
-        ModpackConfiguration<Modpack> config = null;
+        @Nullable ModpackConfiguration<Modpack> config = null;
         try {
-            if (Files.exists(json)) {
+            if (this.updateTarget != null && Files.exists(json)) {
                 config = JsonUtils.fromJsonFile(json, ModpackConfiguration.typeOf(Modpack.class));
 
-                if (!HMCLModpackProvider.INSTANCE.getName().equals(config.getType()))
-                    throw new IllegalArgumentException("Version " + name + " is not a HMCL modpack. Cannot update this version.");
+                if (config == null || !HMCLModpackProvider.INSTANCE.getName().equals(config.getType()))
+                    throw new IllegalArgumentException("Instance " + instanceId + " is not a HMCL modpack. Cannot update this instance.");
             }
         } catch (JsonParseException | IOException ignore) {
         }
-        dependents.add(new ModpackInstallTask<>(zipFile, run, modpack.getEncoding(), Collections.singletonList("/minecraft"), it -> !"pack.json".equals(it), config));
-        dependents.add(new MinecraftInstanceTask<>(zipFile, modpack.getEncoding(), Collections.singletonList("/minecraft"), modpack, HMCLModpackProvider.INSTANCE, modpack.getName(), modpack.getVersion(), repository.getModpackConfiguration(name)).withStage("hmcl.modpack"));
+
+        onDone().register(event -> {
+            if (this.updateTarget == null && event.isFailed()) {
+                repository.removeInstanceFromDisk(this.instanceId);
+            }
+        });
+
+        dependents.add(new ModpackInstallTask<>(zipFile, run, modpack.getEncoding(), List.of("/minecraft"), it -> !"pack.json".equals(it), config));
+        dependents.add(new MinecraftInstanceTask<>(zipFile, modpack.getEncoding(), List.of("/minecraft"), modpack, HMCLModpackProvider.INSTANCE, modpack.getName(), modpack.getVersion(), repository.getLayout().getModpackConfigurationFile(this.instanceId)).withStage("hmcl.modpack"));
     }
 
     @Override
@@ -86,20 +143,43 @@ public final class HMCLModpackInstallTask extends Task<Void> {
         return dependents;
     }
 
+    /// Reads the legacy pack manifest and schedules one builder for all recognized components.
+    ///
+    /// The pack manifest is used only for component detection. The builder creates a new
+    /// patch-structured manifest instead of attempting to mutate the legacy flattened manifest.
     @Override
     public void execute() throws Exception {
         String json = CompressingUtils.readTextZipEntry(zipFile, "minecraft/pack.json");
-        Version originalVersion = JsonUtils.GSON.fromJson(json, Version.class).setId(name).setJar(null);
-        LibraryAnalyzer analyzer = LibraryAnalyzer.analyze(originalVersion, null);
-        Task<Version> libraryTask = Task.supplyAsync(() -> originalVersion);
-        // reinstall libraries
-        // libraries of Forge and OptiFine should be obtained by installation.
-        for (LibraryAnalyzer.LibraryMark mark : analyzer) {
-            if (LibraryAnalyzer.LibraryType.MINECRAFT.getPatchId().equals(mark.getLibraryId()))
-                continue;
-            libraryTask = libraryTask.thenComposeAsync(version -> dependency.installLibraryAsync(modpack.getGameVersion(), version, mark.getLibraryId(), mark.getLibraryVersion()));
-        }
+        GameInstanceManifest originalManifest = JsonUtils.fromNonNullJson(json, GameInstanceManifest.class)
+                .withId(instanceId)
+                .withJar(null);
+        GameComponentAnalyzer analyzer = GameComponentAnalyzer.analyze(originalManifest, null);
 
-        dependencies.add(libraryTask.thenComposeAsync(repository::saveAsync));
+        try (GameBuilder builder = updateTarget == null
+                ? dependency.newGameBuilder(instanceId)
+                : dependency.newGameBuilder(updateTarget)) {
+            builder.enableIsolation();
+
+            String gameVersion = modpack.getGameVersion();
+            builder.component(GameComponentType.GAME, gameVersion);
+            for (GameComponentAnalyzer.Mark mark : analyzer) {
+                if (mark.componentType() == GameComponentType.GAME) {
+                    continue;
+                }
+
+                @Nullable String componentVersion = mark.version();
+                if (componentVersion != null) {
+                    if (mark.componentType() == GameComponentType.OPTIFINE) {
+                        Matcher matcher = GameComponentAnalyzer.OPTIFINE_VERSION_PATTERN.matcher(componentVersion);
+                        if (matcher.matches()) {
+                            componentVersion = matcher.group("optifine");
+                        }
+                    }
+                    builder.component(mark.componentType(), componentVersion);
+                }
+            }
+            dependencies.add(builder.buildAsync());
+        }
     }
+
 }

HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLModpackProvider.java

@@ -28,10 +28,12 @@ import org.jackhuang.hmcl.task.Task;
 import org.jackhuang.hmcl.util.StringUtils;
 import org.jackhuang.hmcl.util.gson.JsonUtils;
 import org.jackhuang.hmcl.util.io.CompressingUtils;
+import org.jetbrains.annotations.Nullable;
 
 import java.io.IOException;
 import java.nio.charset.Charset;
 import java.nio.file.Path;
+import java.util.Set;
 
 public final class HMCLModpackProvider implements ModpackProvider {
     public static final HMCLModpackProvider INSTANCE = new HMCLModpackProvider();
@@ -42,12 +44,17 @@ public final class HMCLModpackProvider implements ModpackProvider {
     }
 
     @Override
-    public Task<?> createCompletionTask(DefaultDependencyManager dependencyManager, String version) {
+    public @Nullable Task<?> createCompletionTask(DefaultDependencyManager dependencyManager, DefaultGameInstance instance) {
         return null;
     }
 
     @Override
-    public Task<?> createUpdateTask(DefaultDependencyManager dependencyManager, String name, Path zipFile, Modpack modpack) throws MismatchedModpackTypeException {
+    public Task<?> createUpdateTask(
+            DefaultDependencyManager dependencyManager,
+            DefaultGameInstance instance,
+            Path zipFile,
+            Modpack modpack,
+            @Nullable Set<String> excludedFiles) throws MismatchedModpackTypeException {
         if (!(modpack.getManifest() instanceof HMCLModpackManifest))
             throw new MismatchedModpackTypeException(getName(), modpack.getManifest().getProvider().getName());
 
@@ -55,7 +62,7 @@ public final class HMCLModpackProvider implements ModpackProvider {
             throw new IllegalArgumentException("HMCLModpackProvider requires HMCLGameRepository");
         }
 
-        return new ModpackUpdateTask(dependencyManager.getGameRepository(), name, new HMCLModpackInstallTask(repository, zipFile, modpack, name));
+        return new ModpackUpdateTask(instance, new HMCLModpackInstallTask(repository, zipFile, modpack, instance));
     }
 
     @Override
@@ -63,21 +70,26 @@ public final class HMCLModpackProvider implements ModpackProvider {
         String manifestJson = CompressingUtils.readTextZipEntry(file, "modpack.json");
         Modpack manifest = JsonUtils.fromNonNullJson(manifestJson, HMCLModpack.class).setEncoding(encoding);
         String gameJson = CompressingUtils.readTextZipEntry(file, "minecraft/pack.json");
-        Version game = JsonUtils.fromNonNullJson(gameJson, Version.class);
-        if (game.getJar() == null)
+        GameInstanceManifest game = JsonUtils.fromNonNullJson(gameJson, GameInstanceManifest.class);
+        if (game.jar() == null)
             if (StringUtils.isBlank(manifest.getVersion()))
                 throw new JsonParseException("Cannot recognize the game version of modpack " + file + ".");
             else
                 manifest.setManifest(HMCLModpackManifest.INSTANCE);
         else
-            manifest.setManifest(HMCLModpackManifest.INSTANCE).setGameVersion(game.getJar());
+            manifest.setManifest(HMCLModpackManifest.INSTANCE).setGameVersion(game.jar().id());
         return manifest;
     }
 
     private final static class HMCLModpack extends Modpack {
         @Override
-        public Task<?> getInstallTask(DefaultDependencyManager dependencyManager, Path zipFile, String name, String iconUrl) {
-            return new HMCLModpackInstallTask((HMCLGameRepository) dependencyManager.getGameRepository(), zipFile, this, name);
+        public Task<?> getInstallTask(
+                DefaultDependencyManager dependencyManager,
+                Path zipFile,
+                GameInstanceID instanceId,
+                String iconUrl,
+                @Nullable Set<String> excludedFiles) {
+            return new HMCLModpackInstallTask((HMCLGameRepository) dependencyManager.getGameRepository(), zipFile, this, instanceId);
         }
     }
 

HMCL/src/main/java/org/jackhuang/hmcl/game/LauncherHelper.java

@@ -25,8 +25,6 @@ import org.jackhuang.hmcl.auth.authlibinjector.AuthlibInjectorDownloadException;
 import org.jackhuang.hmcl.auth.offline.OfflineAccount;
 import org.jackhuang.hmcl.download.DefaultDependencyManager;
 import org.jackhuang.hmcl.download.DownloadProvider;
-import org.jackhuang.hmcl.download.LibraryAnalyzer;
-import org.jackhuang.hmcl.download.MaintainTask;
 import org.jackhuang.hmcl.download.game.*;
 import org.jackhuang.hmcl.java.JavaManager;
 import org.jackhuang.hmcl.java.JavaRuntime;
@@ -34,15 +32,14 @@ import org.jackhuang.hmcl.launch.*;
 import org.jackhuang.hmcl.modpack.ModpackCompletionException;
 import org.jackhuang.hmcl.modpack.ModpackConfiguration;
 import org.jackhuang.hmcl.modpack.ModpackProvider;
-import org.jackhuang.hmcl.setting.DownloadProviders;
 import org.jackhuang.hmcl.setting.GameSettings;
 import org.jackhuang.hmcl.setting.JavaVersionType;
 import org.jackhuang.hmcl.setting.LauncherVisibility;
 import org.jackhuang.hmcl.task.*;
 import org.jackhuang.hmcl.ui.*;
 import org.jackhuang.hmcl.ui.construct.DialogCloseEvent;
-import org.jackhuang.hmcl.ui.construct.MessageDialogPane;
 import org.jackhuang.hmcl.ui.construct.MessageDialogPane.MessageType;
+import org.jackhuang.hmcl.ui.construct.MessageDialogPane;
 import org.jackhuang.hmcl.ui.construct.PromptDialogPane;
 import org.jackhuang.hmcl.ui.construct.TaskExecutorDialogPane;
 import org.jackhuang.hmcl.util.*;
@@ -50,6 +47,7 @@ import org.jackhuang.hmcl.util.i18n.I18n;
 import org.jackhuang.hmcl.util.io.FileUtils;
 import org.jackhuang.hmcl.util.io.ResponseCodeException;
 import org.jackhuang.hmcl.util.platform.*;
+import org.jackhuang.hmcl.util.platform.windows.WinReg;
 import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
 import org.jackhuang.hmcl.util.versioning.VersionNumber;
 import org.jetbrains.annotations.Nullable;
@@ -58,7 +56,6 @@ import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.lang.ref.WeakReference;
 import java.net.SocketTimeoutException;
-import java.net.URI;
 import java.nio.file.AccessDeniedException;
 import java.nio.file.Path;
 import java.time.Instant;
@@ -83,9 +80,8 @@ public final class LauncherHelper {
 
     private static final String LWJGL_3_4_1_TIP = "lwjgl3.4.1-ffm";
 
-    private final HMCLGameRepository repository;
+    private final HMCLGameInstance gameInstance;
     private Account account;
-    private final String selectedVersion;
     private Path scriptFile;
     private final GameSettings.Effective setting;
     private LauncherVisibility launcherVisibility;
@@ -93,14 +89,21 @@ public final class LauncherHelper {
     private QuickPlayOption quickPlayOption;
     private boolean disableOfflineSkin = false;
 
-    public LauncherHelper(HMCLGameRepository repository, Account account, String selectedVersion) {
-        this.repository = Objects.requireNonNull(repository);
+    public LauncherHelper(HMCLGameInstance gameInstance, Account account) {
+        this.gameInstance = Objects.requireNonNull(gameInstance);
         this.account = Objects.requireNonNull(account);
-        this.selectedVersion = Objects.requireNonNull(selectedVersion);
-        this.setting = repository.getEffectiveGameSettings(selectedVersion);
+        this.setting = gameInstance.getEffectiveSettings();
         this.launcherVisibility = setting.getInheritable(GameSettings::launcherVisibilityProperty);
         this.showLogs = setting.getInheritable(GameSettings::showLogsProperty);
-        this.launchingStepsPane.setTitle(i18n("version.launch"));
+        this.launchingStepsPane.setTitle(i18n("instance.launch"));
+    }
+
+    public HMCLGameInstance getGameInstance() {
+        return gameInstance;
+    }
+
+    private HMCLGameRepository repository() {
+        return gameInstance.getRepository();
     }
 
     private final TaskExecutorDialogPane launchingStepsPane = new TaskExecutorDialogPane(TaskCancellationAction.NORMAL);
@@ -133,7 +136,7 @@ public final class LauncherHelper {
     public void launch() {
         FXUtils.checkFxUserThread();
 
-        LOG.info("Launching game version: " + selectedVersion);
+        LOG.info("Launching game instance: " + gameInstance.getId());
 
         Controllers.dialog(launchingStepsPane);
         launch0();
@@ -144,48 +147,55 @@ public final class LauncherHelper {
         launch();
     }
 
+    /// Builds and executes the launch pipeline for the captured game instance.
     private void launch0() {
         // https://github.com/HMCL-dev/HMCL/pull/4121
         PROCESSES.removeIf(it -> it.get() == null);
 
+        HMCLGameRepository repository = repository();
         DefaultDependencyManager dependencyManager = repository.getDependency();
-        AtomicReference<Version> version = new AtomicReference<>(MaintainTask.maintain(repository, repository.getResolvedVersion(selectedVersion)));
-        Optional<String> gameVersion = repository.getGameVersion(version.get());
-        boolean integrityCheck = repository.unmarkVersionLaunchedAbnormally(selectedVersion);
+        // Resolve already deduplicated libraries; apply loader-specific argument repairs for this launch.
+        var launchManifest = new AtomicReference<>(LaunchManifestNormalizer.repairForLaunch(gameInstance.getResolvedManifest()));
+        boolean integrityCheck = gameInstance.unmarkLaunchedAbnormally();
         CountDownLatch launchingLatch = new CountDownLatch(1);
         List<String> javaAgents = new ArrayList<>(0);
         List<String> javaArguments = new ArrayList<>(0);
 
         AtomicReference<JavaRuntime> javaVersionRef = new AtomicReference<>();
 
-        TaskExecutor executor = checkGameState(repository, setting, version.get())
+        TaskExecutor executor = checkGameState(gameInstance, setting, launchManifest.get())
                 .thenComposeAsync(java -> {
                     javaVersionRef.set(Objects.requireNonNull(java));
-                    version.set(NativePatcher.patchNative(repository, version.get(), gameVersion.orElse(null), java, setting, javaArguments));
+                    launchManifest.set(NativePatcher.patchNative(gameInstance, launchManifest.get(), java, setting, javaArguments));
                     if (setting.getInheritable(GameSettings::notCheckGameProperty))
                         return null;
                     return Task.allOf(
-                            dependencyManager.checkGameCompletionAsync(version.get(), integrityCheck),
+                            dependencyManager.checkGameCompletionAsync(gameInstance, launchManifest.get(), integrityCheck),
                             Task.composeAsync(() -> {
                                 try {
-                                    ModpackConfiguration<?> configuration = ModpackHelper.readModpackConfiguration(repository.getModpackConfiguration(selectedVersion));
-                                    ModpackProvider provider = ModpackHelper.getProviderByType(configuration.getType());
+                                    @Nullable ModpackConfiguration<?> configuration =
+                                            gameInstance.readModpackConfiguration();
+                                    if (configuration == null) return null;
+                                    @Nullable ModpackProvider provider =
+                                            ModpackHelper.getProviderByType(configuration.getType());
                                     if (provider == null) return null;
-                                    else return provider.createCompletionTask(dependencyManager, selectedVersion);
+                                    else return provider.createCompletionTask(
+                                            dependencyManager,
+                                            gameInstance);
                                 } catch (IOException e) {
                                     return null;
                                 }
                             }),
                             Task.composeAsync(() -> {
                                 if (OperatingSystem.CURRENT_OS != OperatingSystem.WINDOWS
-                                        || !(setting.getRenderer(GameVersionNumber.asGameVersion(gameVersion)) instanceof Renderer.Driver renderer)
+                                        || !(setting.getRenderer(gameInstance.getVersion()) instanceof Renderer.Driver renderer)
                                         || renderer.mesaDriverName() == null)
                                     return null;
 
                                 Library lib = NativePatcher.getWindowsMesaLoader(java, renderer, OperatingSystem.SYSTEM_VERSION);
                                 if (lib == null)
                                     return null;
-                                Path file = dependencyManager.getGameRepository().getLibraryFile(version.get(), lib);
+                                Path file = gameInstance.getLayout().getLibraryFile(gameInstance.getId(), lib);
                                 if (file.toAbsolutePath().toString().indexOf('=') >= 0) {
                                     LOG.warning("Invalid character '=' in the libraries directory path, unable to attach software renderer loader");
                                     return null;
@@ -193,7 +203,7 @@ public final class LauncherHelper {
 
                                 String agent = FileUtils.getAbsolutePath(file) + "=" + renderer.mesaDriverName();
 
-                                if (GameLibrariesTask.shouldDownloadLibrary(repository, version.get(), lib, integrityCheck)) {
+                                if (GameLibrariesTask.shouldDownloadLibrary(repository, launchManifest.get(), lib, integrityCheck)) {
                                     return new LibraryDownloadTask(dependencyManager, file, lib)
                                             .thenRunAsync(() -> javaAgents.add(agent));
                                 } else {
@@ -203,13 +213,13 @@ public final class LauncherHelper {
                             })
                     );
                 }).withStage("launch.state.dependencies")
-                .thenComposeAsync(() -> gameVersion.map(s -> new GameVerificationFixTask(dependencyManager, s, version.get())).orElse(null))
+                .thenComposeAsync(() -> new GameVerificationFixTask(gameInstance, gameInstance.getVersion(), launchManifest.get()))
                 .thenComposeAsync(() -> {
                     if (setting.getInheritable(GameSettings::allowAutoAgentProperty)
                             || setting.getInheritable(GameSettings::noJVMOptionsProperty)
                             || setting.getInheritable(GameSettings::noOptimizingJVMOptionsProperty)
                             || Boolean.TRUE.equals(state().getShownTips().get(LWJGL_3_4_1_TIP))
-                            || !NativePatcher.needPatchMemoryUtil(version.get(), javaVersionRef.get().getParsedVersion())) {
+                            || !NativePatcher.needPatchMemoryUtil(launchManifest.get(), javaVersionRef.get().getParsedVersion())) {
                         return Task.completed(null);
                     } else {
                         CompletableFuture<Void> future = new CompletableFuture<>();
@@ -228,8 +238,8 @@ public final class LauncherHelper {
                 })
                 .thenComposeAsync(() -> logIn(account).withStage("launch.state.logging_in"))
                 .thenComposeAsync(authInfo -> Task.supplyAsync(() -> {
-                    LaunchOptions.Builder launchOptionsBuilder = repository.getLaunchOptions(
-                            selectedVersion, javaVersionRef.get(), repository.getBaseDirectory(), javaAgents, javaArguments, scriptFile != null);
+                    LaunchOptions.Builder launchOptionsBuilder = gameInstance.getLaunchOptions(
+                            javaVersionRef.get(), repository.getBaseDirectory(), javaAgents, javaArguments, scriptFile != null);
                     if (disableOfflineSkin) {
                         launchOptionsBuilder.setDaemon(false);
                     }
@@ -237,18 +247,48 @@ public final class LauncherHelper {
                         launchOptionsBuilder.setQuickPlayOption(quickPlayOption);
                     }
 
+                    if (OperatingSystem.CURRENT_OS == OperatingSystem.WINDOWS && setting.getInheritable(GameSettings::highPerformanceProperty)) {
+                        @Nullable String javaPathGpuReg = FileUtils.getAbsolutePath(javaVersionRef.get().getBinary());
+                        try {
+                            WinReg reg = WinReg.INSTANCE;
+                            if (reg != null) {
+                                Object current = reg.queryValue(
+                                        WinReg.HKEY.HKEY_CURRENT_USER,
+                                        "Software\\Microsoft\\DirectX\\UserGpuPreferences",
+                                        javaPathGpuReg
+                                );
+                                if (current == null) {
+                                    boolean result = reg.setValue(
+                                            WinReg.HKEY.HKEY_CURRENT_USER,
+                                            "Software\\Microsoft\\DirectX\\UserGpuPreferences",
+                                            javaPathGpuReg,
+                                            "GpuPreference=2;"
+                                    );
+                                    if (result)
+                                        LOG.info("Successfully applied high performance GPU preference for java: " + javaPathGpuReg);
+                                    else
+                                        LOG.warning("Failed to apply high performance GPU preference for java: " + javaPathGpuReg);
+                                } else {
+                                    LOG.info("GPU preference for %s already exists: %s".formatted(javaPathGpuReg, current));
+                                }
+                            }
+                        } catch (Exception e) {
+                            LOG.warning("Failed to apply high performance GPU preference", e);
+                        }
+                    }
+
                     LaunchOptions launchOptions = launchOptionsBuilder.create();
 
-                    LOG.info("Here's the structure of game mod directory:\n" + FileUtils.printFileStructure(repository.getModsDirectory(selectedVersion), 10));
+                    LOG.info("Here's the structure of game mod directory:\n" + FileUtils.printFileStructure(gameInstance.getModsDirectory(), 10));
 
                     return new HMCLGameLauncher(
-                            repository,
-                            version.get(),
+                            gameInstance,
+                            launchManifest.get(),
                             authInfo,
                             launchOptions,
                             launcherVisibility == LauncherVisibility.CLOSE
                                     ? null // Unnecessary to start listening to game process output when close launcher immediately after game launched.
-                                    : new HMCLProcessListener(repository, version.get(), authInfo, launchOptions, launchingLatch, gameVersion.isPresent())
+                                    : new HMCLProcessListener(authInfo, launchOptions, launchingLatch, gameInstance.getVersion().compareTo(GameVersionNumber.unknown()) != 0)
                     );
                 }).thenComposeAsync(launcher -> { // launcher is prev task's result
                     if (scriptFile == null) {
@@ -272,7 +312,7 @@ public final class LauncherHelper {
                     } else {
                         runLater(() -> {
                             launchingStepsPane.fireEvent(new DialogCloseEvent());
-                            Controllers.dialog(i18n("version.launch_script.success", FileUtils.getAbsolutePath(scriptFile)));
+                            Controllers.dialog(i18n("instance.launch_script.success", FileUtils.getAbsolutePath(scriptFile)));
                         });
                     }
                 }).withFakeProgress(
@@ -311,31 +351,29 @@ public final class LauncherHelper {
                                 } else if (ex instanceof NotDecompressingNativesException) {
                                     message = i18n("launch.failed.decompressing_natives") + "\n" + ex.getLocalizedMessage();
                                 } else if (ex instanceof LibraryDownloadException) {
-                                    message = i18n("launch.failed.download_library", ((LibraryDownloadException) ex).getLibrary().getName()) + "\n";
-                                    if (ex.getCause() instanceof ResponseCodeException) {
-                                        ResponseCodeException rce = (ResponseCodeException) ex.getCause();
+                                    message = i18n("launch.failed.download_library", ((LibraryDownloadException) ex).getLibrary().name()) + "\n";
+                                    if (ex.getCause() instanceof ResponseCodeException rce) {
                                         int responseCode = rce.getResponseCode();
-                                        String uri = rce.getUri();
+                                        String url = rce.getUrl();
                                         if (responseCode == 404)
-                                            message += i18n("download.code.404", uri);
+                                            message += i18n("download.code.404", url);
                                         else
-                                            message += i18n("download.failed", uri, responseCode);
+                                            message += i18n("download.failed", url, responseCode);
                                     } else {
                                         message += StringUtils.getStackTrace(ex.getCause());
                                     }
-                                } else if (ex instanceof DownloadException) {
-                                    URI uri = ((DownloadException) ex).getUri();
+                                } else if (ex instanceof DownloadException de) {
+                                    String url = de.getUrl();
                                     if (ex.getCause() instanceof SocketTimeoutException) {
-                                        message = i18n("install.failed.downloading.timeout", uri);
-                                    } else if (ex.getCause() instanceof ResponseCodeException) {
-                                        ResponseCodeException responseCodeException = (ResponseCodeException) ex.getCause();
+                                        message = i18n("install.failed.downloading.timeout", url);
+                                    } else if (ex.getCause() instanceof ResponseCodeException responseCodeException) {
                                         if (I18n.hasKey("download.code." + responseCodeException.getResponseCode())) {
-                                            message = i18n("download.code." + responseCodeException.getResponseCode(), uri);
+                                            message = i18n("download.code." + responseCodeException.getResponseCode(), url);
                                         } else {
-                                            message = i18n("install.failed.downloading.detail", uri) + "\n" + StringUtils.getStackTrace(ex.getCause());
+                                            message = i18n("install.failed.downloading.detail", url) + "\n" + StringUtils.getStackTrace(ex.getCause());
                                         }
                                     } else {
-                                        message = i18n("install.failed.downloading.detail", uri) + "\n" + StringUtils.getStackTrace(ex.getCause());
+                                        message = i18n("install.failed.downloading.detail", url) + "\n" + StringUtils.getStackTrace(ex.getCause());
                                     }
                                 } else if (ex instanceof GameAssetIndexDownloadTask.GameAssetIndexMalformedException) {
                                     message = i18n("assets.index.malformed");
@@ -343,14 +381,13 @@ public final class LauncherHelper {
                                     message = i18n("account.failed.injector_download_failure");
                                 } else if (ex instanceof CharacterDeletedException) {
                                     message = i18n("account.failed.character_deleted");
-                                } else if (ex instanceof ResponseCodeException) {
-                                    ResponseCodeException rce = (ResponseCodeException) ex;
+                                } else if (ex instanceof ResponseCodeException rce) {
                                     int responseCode = rce.getResponseCode();
-                                    String uri = rce.getUri();
+                                    String url = rce.getUrl();
                                     if (responseCode == 404)
-                                        message = i18n("download.code.404", uri);
+                                        message = i18n("download.code.404", url);
                                     else
-                                        message = i18n("download.failed", uri, responseCode);
+                                        message = i18n("download.failed", url, responseCode);
                                 } else if (ex instanceof CommandTooLongException) {
                                     message = i18n("launch.failed.command_too_long");
                                 } else if (ex instanceof ExecutionPolicyLimitException) {
@@ -374,7 +411,7 @@ public final class LauncherHelper {
                                     message = StringUtils.getStackTrace(ex);
                                 }
                                 Controllers.dialog(message,
-                                        scriptFile == null ? i18n("launch.failed") : i18n("version.launch_script.failed"),
+                                        scriptFile == null ? i18n("launch.failed") : i18n("instance.launch_script.failed"),
                                         MessageType.ERROR);
                             }
                         }
@@ -387,13 +424,13 @@ public final class LauncherHelper {
         executor.start();
     }
 
-    private static Task<JavaRuntime> checkGameState(HMCLGameRepository repository, GameSettings.Effective setting, Version version) {
-        LibraryAnalyzer analyzer = LibraryAnalyzer.analyze(version, repository.getGameVersion(version).orElse(null));
-        GameVersionNumber gameVersion = GameVersionNumber.asGameVersion(analyzer.getVersion(LibraryAnalyzer.LibraryType.MINECRAFT));
+    private static Task<JavaRuntime> checkGameState(HMCLGameInstance gameInstance, GameSettings.Effective setting, GameInstanceManifest manifest) {
+        GameComponentAnalyzer analyzer = GameComponentAnalyzer.analyze(manifest, gameInstance.getVersion());
+        GameVersionNumber gameVersion = gameInstance.getVersion();
 
         Task<JavaRuntime> getJavaTask = Task.supplyAsync(() -> {
             try {
-                return setting.getJava(gameVersion, version);
+                return setting.getJava(gameVersion, manifest);
             } catch (InterruptedException e) {
                 throw new CancellationException();
             }
@@ -420,9 +457,9 @@ public final class LauncherHelper {
                         int targetJavaVersionMajor = Integer.parseInt(setting.getInheritable(GameSettings::customJavaVersionProperty));
                         GameJavaVersion minimumJavaVersion = null;
                         if (gameVersion.compareTo("1.12.2") == 0) {
-                            Optional<String> cleanroomVersion = analyzer.getVersion(LibraryAnalyzer.LibraryType.CLEANROOM);
-                            if (cleanroomVersion.isPresent()) {
-                                minimumJavaVersion = GameJavaVersion.getCleanroomJavaVersion(cleanroomVersion.get());
+                            @Nullable String cleanroomVersion = analyzer.getVersion(GameComponentType.CLEANROOM);
+                            if (cleanroomVersion != null) {
+                                minimumJavaVersion = GameJavaVersion.getCleanroomJavaVersion(cleanroomVersion);
                             }
                         }
 
@@ -444,18 +481,18 @@ public final class LauncherHelper {
                     }
                 } else {
                     if (gameVersion.compareTo("1.12.2") == 0) {
-                        Optional<String> cleanroomVersion = analyzer.getVersion(LibraryAnalyzer.LibraryType.CLEANROOM);
-                        if (cleanroomVersion.isPresent()) {
-                            targetJavaVersion = GameJavaVersion.getCleanroomJavaVersion(cleanroomVersion.get());
+                        @Nullable String cleanroomVersion = analyzer.getVersion(GameComponentType.CLEANROOM);
+                        if (cleanroomVersion != null) {
+                            targetJavaVersion = GameJavaVersion.getCleanroomJavaVersion(cleanroomVersion);
                         }
                     }
 
                     if (targetJavaVersion == null)
-                        targetJavaVersion = version.getJavaVersion();
+                        targetJavaVersion = manifest.javaVersion();
                 }
 
                 if (targetJavaVersion != null && supportedVersions.contains(targetJavaVersion)) {
-                    downloadJava(targetJavaVersion, repository)
+                    downloadJava(targetJavaVersion, gameInstance.getRepository())
                             .whenCompleteAsync((downloadedJava, exception) -> {
                                 if (exception == null) {
                                     future.complete(downloadedJava);
@@ -481,8 +518,8 @@ public final class LauncherHelper {
 
                 if (java != null) {
                     for (JavaVersionConstraint constraint : JavaVersionConstraint.ALL) {
-                        if (constraint.appliesToVersion(gameVersion, version, java, analyzer)) {
-                            if (!constraint.checkJava(gameVersion, version, java, analyzer)) {
+                        if (constraint.appliesToVersion(gameVersion, manifest, java, analyzer)) {
+                            if (!constraint.checkJava(gameVersion, manifest, java, analyzer)) {
                                 if (constraint.isMandatory()) {
                                     violatedMandatoryConstraints.add(constraint);
                                 } else {
@@ -498,7 +535,7 @@ public final class LauncherHelper {
                 Runnable breakAction = () -> future.completeExceptionally(new CancellationException("Launch operation was cancelled by user"));
 
                 if (java == null || !violatedMandatoryConstraints.isEmpty()) {
-                    JavaRuntime suggestedJava = JavaManager.findSuitableJava(gameVersion, version);
+                    JavaRuntime suggestedJava = JavaManager.findSuitableJava(gameVersion, manifest);
                     if (suggestedJava != null) {
                         FXUtils.runInFX(() -> {
                             Controllers.confirm(i18n("launch.advice.java.auto"), i18n("message.warning"), () -> {
@@ -518,21 +555,20 @@ public final class LauncherHelper {
                     } else {
                         GameJavaVersion gameJavaVersion;
                         if (violatedMandatoryConstraints.contains(JavaVersionConstraint.CLEANROOM)) {
-                            String cleanroomVersion = analyzer.getVersion(LibraryAnalyzer.LibraryType.CLEANROOM)
-                                    .orElse("");
+                            @Nullable String cleanroomVersion = analyzer.getVersion(GameComponentType.CLEANROOM);
 
-                            gameJavaVersion = !cleanroomVersion.isEmpty()
+                            gameJavaVersion = cleanroomVersion != null
                                     ? GameJavaVersion.getCleanroomJavaVersion(cleanroomVersion)
                                     : GameJavaVersion.JAVA_21;
                         } else if (violatedMandatoryConstraints.contains(JavaVersionConstraint.GAME_JSON))
-                            gameJavaVersion = version.getJavaVersion();
+                            gameJavaVersion = manifest.javaVersion();
                         else if (violatedMandatoryConstraints.contains(JavaVersionConstraint.VANILLA))
                             gameJavaVersion = GameJavaVersion.getMinimumJavaVersion(gameVersion);
                         else
                             gameJavaVersion = null;
 
                         if (gameJavaVersion != null) {
-                            FXUtils.runInFX(() -> downloadJava(gameJavaVersion, repository).whenCompleteAsync((downloadedJava, throwable) -> {
+                            FXUtils.runInFX(() -> downloadJava(gameJavaVersion, gameInstance.getRepository()).whenCompleteAsync((downloadedJava, throwable) -> {
                                 if (throwable == null) {
                                     setting.setJavaAutoSelected();
                                     future.complete(downloadedJava);
@@ -602,7 +638,7 @@ public final class LauncherHelper {
                             break;
                         case MODDED_JAVA_16:
                             // Minecraft<=1.17.1+Forge[37.0.0,37.0.60) not compatible with Java 17
-                            String forgePatchVersion = analyzer.getVersion(LibraryAnalyzer.LibraryType.FORGE).orElse(null);
+                            @Nullable String forgePatchVersion = analyzer.getVersion(GameComponentType.FORGE);
                             if (forgePatchVersion != null && VersionNumber.compare(forgePatchVersion, "37.0.60") < 0)
                                 suggestions.add(i18n("launch.advice.forge37_0_60"));
                             else
@@ -615,8 +651,8 @@ public final class LauncherHelper {
                             suggestions.add(i18n("launch.advice.modded_java", 21, gameVersion));
                             break;
                         case CLEANROOM: {
-                            String cleanroomVersion = analyzer.getVersion(LibraryAnalyzer.LibraryType.CLEANROOM).orElse("");
-                            if (!cleanroomVersion.isEmpty())
+                            @Nullable String cleanroomVersion = analyzer.getVersion(GameComponentType.CLEANROOM);
+                            if (cleanroomVersion != null)
                                 suggestions.add(i18n("launch.advice.cleanroom", GameJavaVersion.getCleanroomJavaVersion(cleanroomVersion).majorVersion(), cleanroomVersion));
                             else
                                 suggestions.add(i18n("launch.advice.cleanroom", 21, ""));
@@ -645,20 +681,20 @@ public final class LauncherHelper {
                     suggestions.add(i18n("launch.advice.not_enough_space", totalMemorySizeMB));
                 }
 
-                VersionNumber forgeVersion = analyzer.getVersion(LibraryAnalyzer.LibraryType.FORGE)
+                VersionNumber forgeVersion = Optional.ofNullable(analyzer.getVersion(GameComponentType.FORGE))
                         .map(VersionNumber::asVersion)
                         .orElse(null);
 
                 // Forge 2760~2773 will crash game with LiteLoader.
                 boolean hasForge2760 = forgeVersion != null && (forgeVersion.compareTo("1.12.2-14.23.5.2760") >= 0) && (forgeVersion.compareTo("1.12.2-14.23.5.2773") < 0);
-                boolean hasLiteLoader = version.getLibraries().stream().anyMatch(it -> it.is("com.mumfrey", "liteloader"));
+                boolean hasLiteLoader = manifest.getLibraries().stream().anyMatch(it -> it.is("com.mumfrey", "liteloader"));
                 if (hasForge2760 && hasLiteLoader && gameVersion.compareTo("1.12.2") == 0) {
                     suggestions.add(i18n("launch.advice.forge2760_liteloader"));
                 }
 
                 // OptiFine 1.14.4 is not compatible with Forge 28.2.2 and later versions.
                 boolean hasForge28_2_2 = forgeVersion != null && (forgeVersion.compareTo("1.14.4-28.2.2") >= 0);
-                boolean hasOptiFine = version.getLibraries().stream().anyMatch(it -> it.is("optifine", "OptiFine"));
+                boolean hasOptiFine = manifest.getLibraries().stream().anyMatch(it -> it.is("optifine", "OptiFine"));
                 if (hasForge28_2_2 && hasOptiFine && gameVersion.compareTo("1.14.4") == 0) {
                     suggestions.add(i18n("launch.advice.forge28_2_2_optifine"));
                 }
@@ -706,7 +742,7 @@ public final class LauncherHelper {
                                     Throwable resolvedException = resolveException(exception);
                                     LOG.warning("Failed to download java", exception);
                                     if (!(resolvedException instanceof CancellationException)) {
-                                        Controllers.dialog(DownloadProviders.localizeErrorMessage(resolvedException), i18n("install.failed"));
+                                        Controllers.dialog(I18n.localizeErrorMessage(resolvedException), i18n("install.failed"));
                                     }
                                     future.completeExceptionally(new CancellationException());
                                 }
@@ -793,16 +829,12 @@ public final class LauncherHelper {
         }
     }
 
-    /**
-     * The managed process listener.
-     * Guarantee that one [JavaProcess], one [HMCLProcessListener].
-     * Because every time we launched a game, we generates a new [HMCLProcessListener]
-     */
+    /// The managed process listener.
+    /// Guarantee that one Java [Process], one [HMCLProcessListener].
+    /// Because every time we launched a game, we generates a new [HMCLProcessListener]
     private final class HMCLProcessListener implements ProcessListener {
 
         private final ReentrantLock lock = new ReentrantLock();
-        private final HMCLGameRepository repository;
-        private final Version version;
         private final LaunchOptions launchOptions;
         private ManagedProcess process;
         private volatile boolean lwjgl;
@@ -814,9 +846,7 @@ public final class LauncherHelper {
         private Thread submitLogThread;
         private LinkedBlockingQueue<Log> logBuffer;
 
-        public HMCLProcessListener(HMCLGameRepository repository, Version version, AuthInfo authInfo, LaunchOptions launchOptions, CountDownLatch launchingLatch, boolean detectWindow) {
-            this.repository = repository;
-            this.version = version;
+        public HMCLProcessListener(AuthInfo authInfo, LaunchOptions launchOptions, CountDownLatch launchingLatch, boolean detectWindow) {
             this.launchOptions = launchOptions;
             this.launchingLatch = launchingLatch;
             this.detectWindow = detectWindow;
@@ -943,7 +973,7 @@ public final class LauncherHelper {
             Log4jLevel level = isErrorStream && !log.startsWith("[authlib-injector]") ? Log4jLevel.ERROR : null;
             if (showLogs) {
                 if (level == null)
-                    level = Lang.requireNonNullElse(Log4jLevel.guessLevel(log), Log4jLevel.INFO);
+                    level = Objects.requireNonNullElse(Log4jLevel.guessLevel(log), Log4jLevel.INFO);
                 logBuffer.add(new Log(log, level));
             } else {
                 lock.lock();
@@ -1001,8 +1031,8 @@ public final class LauncherHelper {
             }
 
             if (exitType != ExitType.NORMAL) {
-                repository.markVersionLaunchedAbnormally(version.getId());
-                runLater(() -> new GameCrashWindow(process, exitType, repository, version, launchOptions, logs).show());
+                gameInstance.markLaunchedAbnormally();
+                runLater(() -> new GameCrashWindow(process, exitType, gameInstance, launchOptions, logs).show());
             }
 
             checkExit();

HMCL/src/main/java/org/jackhuang/hmcl/game/LocalizedRemoteAddonRepository.java

@@ -20,9 +20,10 @@ package org.jackhuang.hmcl.game;
 import org.jackhuang.hmcl.download.DownloadProvider;
 import org.jackhuang.hmcl.addon.RemoteAddon;
 import org.jackhuang.hmcl.addon.RemoteAddonRepository;
-import org.jackhuang.hmcl.ui.versions.ModTranslations;
+import org.jackhuang.hmcl.ui.instances.ModTranslations;
 import org.jackhuang.hmcl.util.Pair;
 import org.jackhuang.hmcl.util.StringUtils;
+import org.jetbrains.annotations.NotNull;
 
 import java.io.IOException;
 import java.nio.file.Path;
@@ -38,18 +39,26 @@ public abstract class LocalizedRemoteAddonRepository implements RemoteAddonRepos
 
     protected abstract RemoteAddonRepository getBackedRemoteModRepository();
 
-    protected abstract SortType getBackedRemoteModRepositorySortOrder();
+    @Override
+    public String getApiBaseUrl() {
+        return getBackedRemoteModRepository().getApiBaseUrl();
+    }
 
     @Override
-    public SearchResult search(DownloadProvider downloadProvider, String gameVersion, Category category, int pageOffset, int pageSize, String searchFilter, SortType sort, SortOrder sortOrder) throws IOException {
+    public String getBaseUrl() {
+        return getBackedRemoteModRepository().getBaseUrl();
+    }
+
+    @Override
+    public SearchResult search(DownloadProvider downloadProvider, RemoteAddon.Type type, String gameVersion, Category category, int pageOffset, int pageSize, String searchFilter, SortType sort, SortOrder sortOrder) throws IOException {
         if (!StringUtils.containsChinese(searchFilter)) {
-            return getBackedRemoteModRepository().search(downloadProvider, gameVersion, category, pageOffset, pageSize, searchFilter, sort, sortOrder);
+            return getBackedRemoteModRepository().search(downloadProvider, type, gameVersion, category, pageOffset, pageSize, searchFilter, sort, sortOrder);
         }
 
         Set<String> englishSearchFiltersSet = new LinkedHashSet<>(INITIAL_CAPACITY);
 
         int count = 0;
-        for (ModTranslations.Mod mod : ModTranslations.getTranslationsByRepositoryType(getType()).searchMod(searchFilter)) {
+        for (ModTranslations.Mod mod : ModTranslations.getTranslationsByAddonType(type).searchMod(searchFilter)) {
             String englishSearchFilter = String.join(" ", StringUtils.tokenize(StringUtils.isNotBlank(mod.getSubname()) ? mod.getSubname() : mod.getName()));
             if (StringUtils.isNotBlank(englishSearchFilter)) {
                 englishSearchFiltersSet.add(englishSearchFilter);
@@ -60,7 +69,7 @@ public abstract class LocalizedRemoteAddonRepository implements RemoteAddonRepos
         }
 
         if (englishSearchFiltersSet.isEmpty()) {
-            return getBackedRemoteModRepository().search(downloadProvider, gameVersion, category, pageOffset, pageSize, searchFilter, sort, sortOrder);
+            return getBackedRemoteModRepository().search(downloadProvider, type, gameVersion, category, pageOffset, pageSize, searchFilter, sort, sortOrder);
         }
 
         RemoteAddon[] searchResultArray = new RemoteAddon[pageSize];
@@ -69,8 +78,8 @@ public abstract class LocalizedRemoteAddonRepository implements RemoteAddonRepos
             SearchResult searchResult = null;
             List<RemoteAddon> remoteAddons = List.of();
             for (String englishSearchFilter : englishSearchFiltersSet) {
-                searchResult = getBackedRemoteModRepository().search(downloadProvider, gameVersion, category, pageOffset, pageSize, englishSearchFilter, getBackedRemoteModRepositorySortOrder(), sortOrder);
-                remoteAddons = searchResult.getUnsortedResults().toList();
+                searchResult = getBackedRemoteModRepository().search(downloadProvider, type, gameVersion, category, pageOffset, pageSize, englishSearchFilter, SortType.RELEVANCY, sortOrder);
+                remoteAddons = searchResult.results().toList();
                 if (!remoteAddons.isEmpty()) {
                     break;
                 }
@@ -82,19 +91,19 @@ public abstract class LocalizedRemoteAddonRepository implements RemoteAddonRepos
                     continue;
                 }
 
-                ModTranslations.Mod chineseTranslation = ModTranslations.getTranslationsByRepositoryType(getType()).getModByCurseForgeId(remoteAddon.slug());
+                ModTranslations.Mod chineseTranslation = ModTranslations.getTranslationsByAddonType(type).getModByCurseForgeId(remoteAddon.slug());
                 if (chineseTranslation != null && !StringUtils.isBlank(chineseTranslation.getName()) && StringUtils.containsChinese(chineseTranslation.getName())) {
                     searchResultArray[chineseIndex++] = remoteAddon;
                 } else {
                     searchResultArray[englishIndex--] = remoteAddon;
                 }
             }
-            totalPages = searchResult.getTotalPages();
+            totalPages = searchResult.totalPages();
         }
 
         StringUtils.LevCalculator levCalculator = new StringUtils.LevCalculator();
         return new SearchResult(Stream.concat(Arrays.stream(searchResultArray, 0, chineseIndex).map(remoteMod -> {
-            ModTranslations.Mod chineseRemoteMod = ModTranslations.getTranslationsByRepositoryType(getType()).getModByCurseForgeId(remoteMod.slug());
+            ModTranslations.Mod chineseRemoteMod = ModTranslations.getTranslationsByAddonType(type).getModByCurseForgeId(remoteMod.slug());
             if (chineseRemoteMod == null || StringUtils.isBlank(chineseRemoteMod.getName()) || !StringUtils.containsChinese(chineseRemoteMod.getName())) {
                 return Pair.pair(remoteMod, Integer.MAX_VALUE);
             }
@@ -113,8 +122,8 @@ public abstract class LocalizedRemoteAddonRepository implements RemoteAddonRepos
     }
 
     @Override
-    public Stream<Category> getCategories() throws IOException {
-        return getBackedRemoteModRepository().getCategories();
+    public Stream<Category> getCategories(RemoteAddon.Type type) throws IOException {
+        return getBackedRemoteModRepository().getCategories(type);
     }
 
     @Override
@@ -123,17 +132,32 @@ public abstract class LocalizedRemoteAddonRepository implements RemoteAddonRepos
     }
 
     @Override
-    public RemoteAddon getModById(DownloadProvider downloadProvider, String id) throws IOException {
-        return getBackedRemoteModRepository().getModById(downloadProvider, id);
+    public RemoteAddon getAddonById(DownloadProvider downloadProvider, String id) throws IOException {
+        return getBackedRemoteModRepository().getAddonById(downloadProvider, id);
     }
 
     @Override
-    public RemoteAddon.File getModFile(String modId, String fileId) throws IOException {
-        return getBackedRemoteModRepository().getModFile(modId, fileId);
+    public RemoteAddon resolveDependency(DownloadProvider downloadProvider, String id) throws IOException {
+        return getBackedRemoteModRepository().resolveDependency(downloadProvider, id);
+    }
+
+    @Override
+    public RemoteAddon.File getAddonFile(String projectId, String fileId) throws IOException {
+        return getBackedRemoteModRepository().getAddonFile(projectId, fileId);
     }
 
     @Override
     public Stream<RemoteAddon.Version> getRemoteVersionsById(DownloadProvider downloadProvider, String id) throws IOException {
         return getBackedRemoteModRepository().getRemoteVersionsById(downloadProvider, id);
     }
+
+    @Override
+    public String getAddonChangelog(DownloadProvider downloadProvider, String addonId, String versionId) throws IOException {
+        return getBackedRemoteModRepository().getAddonChangelog(downloadProvider, addonId, versionId);
+    }
+
+    @Override
+    public @NotNull String getVersionPageUrl(RemoteAddon.Version version) throws IOException {
+        return getBackedRemoteModRepository().getVersionPageUrl(version);
+    }
 }

HMCL/src/main/java/org/jackhuang/hmcl/game/LogExporter.java

@@ -17,15 +17,18 @@
  */
 package org.jackhuang.hmcl.game;
 
-import kala.encdet.EncodingDetector;
-import org.jackhuang.hmcl.util.StringUtils;
+import org.jackhuang.hmcl.util.gson.JsonUtils;
+import org.jackhuang.hmcl.util.io.IOUtils;
 import org.jackhuang.hmcl.util.io.Zipper;
 import org.jackhuang.hmcl.util.logging.Logger;
 import org.jackhuang.hmcl.util.platform.OperatingSystem;
+import org.jetbrains.annotations.Nullable;
 
 import java.io.BufferedReader;
 import java.io.IOException;
+import java.io.OutputStreamWriter;
 import java.io.UncheckedIOException;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.DirectoryStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -42,22 +45,24 @@ public final class LogExporter {
     }
 
     public static CompletableFuture<Void> exportLogs(
-            Path zipFile, DefaultGameRepository gameRepository, String versionId, String logs, String launchScript,
+            Path zipFile, DefaultGameInstance instance, LaunchOptions options, String logs, String launchScript,
             PathMatcher logMatcher) {
-        Path runDirectory = gameRepository.getRunDirectory(versionId);
-        Path baseDirectory = gameRepository.getBaseDirectory();
-        List<String> versions = new ArrayList<>();
+        DefaultGameRepositorySnapshot repositorySnapshot = instance.getSnapshot();
+        Path runDirectory = options.getGameDir();
+        List<GameInstanceID> instances = new ArrayList<>();
 
-        String currentVersionId = versionId;
-        HashSet<String> resolvedSoFar = new HashSet<>();
+        GameInstanceID currentInstanceId = instance.id;
+        HashSet<GameInstanceID> resolvedSoFar = new HashSet<>();
         while (true) {
-            if (resolvedSoFar.contains(currentVersionId)) break;
-            resolvedSoFar.add(currentVersionId);
-            Version currentVersion = gameRepository.getVersion(currentVersionId);
-            versions.add(currentVersionId);
+            if (resolvedSoFar.contains(currentInstanceId)) break;
+            resolvedSoFar.add(currentInstanceId);
+            @Nullable DefaultGameInstance currentInstance = repositorySnapshot.get(currentInstanceId);
+            if (currentInstance == null)
+                break;
+            instances.add(currentInstanceId);
 
-            if (StringUtils.isNotBlank(currentVersion.getInheritsFrom())) {
-                currentVersionId = currentVersion.getInheritsFrom();
+            if (currentInstance.getManifest().inheritsFrom() != null) {
+                currentInstanceId = currentInstance.getManifest().inheritsFrom();
             } else {
                 break;
             }
@@ -74,10 +79,12 @@ public final class LogExporter {
                 zipper.putTextFile(logs, "minecraft.log");
                 zipper.putTextFile(Logger.filterForbiddenToken(launchScript), OperatingSystem.CURRENT_OS == OperatingSystem.WINDOWS ? "launch.bat" : "launch.sh");
 
-                for (String id : versions) {
-                    Path versionJson = baseDirectory.resolve("versions").resolve(id).resolve(id + ".json");
-                    if (Files.exists(versionJson)) {
-                        zipper.putFile(versionJson, id + ".json");
+                for (GameInstanceID id : instances) {
+                    @Nullable DefaultGameInstance currentInstance = repositorySnapshot.get(id);
+                    if (currentInstance != null) {
+                        try (var writer = new OutputStreamWriter(zipper.putStream(id + ".json"), StandardCharsets.UTF_8)) {
+                            JsonUtils.GSON.toJson(currentInstance.getManifest(), writer);
+                        }
                     }
                 }
             } catch (IOException e) {
@@ -91,7 +98,7 @@ public final class LogExporter {
             for (Path file : stream) {
                 if (Files.isRegularFile(file)) {
                     if (logMatcher == null || logMatcher.matches(file)) {
-                        try (BufferedReader reader = EncodingDetector.MODERN_WEB.newBufferedReader(file)) {
+                        try (BufferedReader reader = IOUtils.newBufferedReaderMaybeNativeEncoding(file)) {
                             zipper.putLines(reader.lines().map(Logger::filterForbiddenToken), file.getFileName().toString());
                         } catch (IOException e) {
                             LOG.warning("Failed to read log file: " + file, e);

HMCL/src/main/java/org/jackhuang/hmcl/game/ManuallyCreatedModpackInstallTask.java

@@ -18,11 +18,9 @@
 package org.jackhuang.hmcl.game;
 
 import org.jackhuang.hmcl.task.Task;
-import org.jackhuang.hmcl.util.io.CompressingUtils;
 import org.jackhuang.hmcl.util.io.Unzipper;
 
 import java.nio.charset.Charset;
-import java.nio.file.FileSystem;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 
@@ -44,17 +42,14 @@ public class ManuallyCreatedModpackInstallTask extends Task<Path> {
 
     @Override
     public void execute() throws Exception {
-        Path subdirectory;
-        try (FileSystem fs = CompressingUtils.readonly(zipFile).setEncoding(charset).build()) {
-            subdirectory = ModpackHelper.findMinecraftDirectoryInManuallyCreatedModpack(zipFile.toString(), fs);
-        }
+        String subdirectory = ModpackHelper.findMinecraftDirectoryInManuallyCreatedModpack(zipFile.toString(), zipFile);
 
         Path dest = Paths.get("externalgames").resolve(name);
 
         setResult(dest);
 
         new Unzipper(zipFile, dest)
-                .setSubDirectory(subdirectory.toString())
+                .setSubDirectory(subdirectory)
                 .setTerminateIfSubDirectoryNotExists()
                 .setEncoding(charset)
                 .unzip();

HMCL/src/main/java/org/jackhuang/hmcl/game/ModpackHelper.java

@@ -31,11 +31,7 @@ import org.jackhuang.hmcl.modpack.multimc.MultiMCModpackProvider;
 import org.jackhuang.hmcl.modpack.server.ServerModpackManifest;
 import org.jackhuang.hmcl.modpack.server.ServerModpackProvider;
 import org.jackhuang.hmcl.modpack.server.ServerModpackRemoteInstallTask;
-import org.jackhuang.hmcl.setting.GameSettings;
-import org.jackhuang.hmcl.setting.GameWindowType;
-import org.jackhuang.hmcl.setting.JavaVersionType;
-import org.jackhuang.hmcl.setting.GameDirectory;
-import org.jackhuang.hmcl.setting.GameDirectoryManager;
+import org.jackhuang.hmcl.setting.*;
 import org.jackhuang.hmcl.task.Schedulers;
 import org.jackhuang.hmcl.task.Task;
 import org.jackhuang.hmcl.util.Lang;
@@ -46,13 +42,13 @@ import org.jackhuang.hmcl.util.gson.JsonUtils;
 import org.jackhuang.hmcl.util.i18n.LocalizedText;
 import org.jackhuang.hmcl.util.io.CompressingUtils;
 import org.jackhuang.hmcl.util.io.FileUtils;
+import org.jackhuang.hmcl.util.tree.ArchiveFileTree;
 import org.jetbrains.annotations.NotNullByDefault;
 import org.jetbrains.annotations.Nullable;
 
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.nio.charset.Charset;
-import java.nio.file.FileSystem;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
@@ -60,10 +56,9 @@ import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
-import java.util.stream.Stream;
+import java.util.Set;
 
 import static org.jackhuang.hmcl.util.Lang.mapOf;
-import static org.jackhuang.hmcl.util.Lang.toIterable;
 import static org.jackhuang.hmcl.util.Pair.pair;
 
 /// Utilities for reading, installing, and applying modpack-specific game settings.
@@ -114,8 +109,8 @@ public final class ModpackHelper {
         } catch (IOException ignored) {
         }
 
-        try (FileSystem fs = CompressingUtils.createReadOnlyZipFileSystem(file, charset)) {
-            findMinecraftDirectoryInManuallyCreatedModpack(file.toString(), fs);
+        try {
+            findMinecraftDirectoryInManuallyCreatedModpack(file.toString(), file);
             throw new ManuallyCreatedModpackException(file);
         } catch (IOException e) {
             // ignore it
@@ -124,28 +119,35 @@ public final class ModpackHelper {
         throw new UnsupportedModpackException(file.toString());
     }
 
-    public static Path findMinecraftDirectoryInManuallyCreatedModpack(String modpackName, FileSystem fs) throws IOException, UnsupportedModpackException {
-        Path root = fs.getPath("/");
-        if (isMinecraftDirectory(root)) return root;
-        try (Stream<Path> firstLayer = Files.list(root)) {
-            for (Path dir : toIterable(firstLayer)) {
-                if (isMinecraftDirectory(dir)) return dir;
+    public static String findMinecraftDirectoryInManuallyCreatedModpack(String modpackName, Path zipPath)
+            throws IOException, UnsupportedModpackException {
 
-                try (Stream<Path> secondLayer = Files.list(dir)) {
-                    for (Path subdir : toIterable(secondLayer)) {
-                        if (isMinecraftDirectory(subdir)) return subdir;
+        try (ArchiveFileTree<?, ?> tree = ArchiveFileTree.open(zipPath)) {
+            ArchiveFileTree.Dir<?> rootDir = tree.getRoot();
+
+            if (isMinecraftDirectory(rootDir)) {
+                return "";
+            }
+
+
+            for (ArchiveFileTree.Dir<?> firstLayer : rootDir.getSubDirs().values()) {
+                if (isMinecraftDirectory(firstLayer)) {
+                    return firstLayer.getName();
+                }
+
+                for (ArchiveFileTree.Dir<?> secondLayer : firstLayer.getSubDirs().values()) {
+                    if (isMinecraftDirectory(secondLayer)) {
+                        return firstLayer.getName() + "/" + secondLayer.getName();
                     }
-                } catch (IOException ignored) {
                 }
             }
-        } catch (IOException ignored) {
         }
+
         throw new UnsupportedModpackException(modpackName);
     }
 
-    private static boolean isMinecraftDirectory(Path path) {
-        return Files.isDirectory(path.resolve("versions")) &&
-                (path.getFileName() == null || ".minecraft".equals(FileUtils.getName(path)));
+    private static boolean isMinecraftDirectory(ArchiveFileTree.Dir<?> dir) {
+        return dir.getSubDirs().containsKey("versions") && (dir.isRoot() || ".minecraft".equals(dir.getName()));
     }
 
     public static ModpackConfiguration<?> readModpackConfiguration(Path file) throws IOException {
@@ -156,16 +158,10 @@ public final class ModpackHelper {
         }
     }
 
-    public static Task<?> getInstallTask(HMCLGameRepository repository, ServerModpackManifest manifest, String name, Modpack modpack) {
-        repository.markVersionAsModpack(name);
-
+    public static Task<?> getInstallTask(HMCLGameRepository repository, ServerModpackManifest manifest, GameInstanceID instanceId, Modpack modpack) {
         ExceptionalRunnable<?> success = () -> {
-            repository.refreshVersions();
-            GameSettings.Instance setting = repository.getInstanceGameSettingsOrCreate(name);
-            repository.undoMark(name);
-            if (setting != null) {
-                setting.getOverrideProperties().add(GameSettings.PROPERTY_RUNNING_DIRECTORY);
-            }
+            repository.refresh();
+            repository.getInstance(instanceId).enableIsolation();
         };
 
         ExceptionalConsumer<Exception, ?> failure = ex -> {
@@ -175,7 +171,7 @@ public final class ModpackHelper {
             }
         };
 
-        return new ServerModpackRemoteInstallTask(repository.getDependency(), manifest, name)
+        return new ServerModpackRemoteInstallTask(repository.getDependency(), manifest, instanceId)
                 .whenComplete(Schedulers.defaultScheduler(), success, failure)
                 .withStagesHints(new Task.StagesHint("hmcl.modpack"), new Task.StagesHint("hmcl.modpack.download", List.of("hmcl.install.assets", "hmcl.install.libraries")));
     }
@@ -200,16 +196,30 @@ public final class ModpackHelper {
                 });
     }
 
-    public static Task<?> getInstallTask(HMCLGameRepository repository, Path zipFile, String name, Modpack modpack, String iconUrl) {
-        repository.markVersionAsModpack(name);
+    public static Task<?> getInstallTask(HMCLGameRepository repository, Path zipFile, GameInstanceID instanceId, Modpack modpack, @Nullable String iconUrl) {
+        return getInstallTask(repository, zipFile, instanceId, modpack, iconUrl, null);
+    }
 
+    /// Creates an install task that respects optional-file selection.
+    ///
+    /// @param repository      the target repository
+    /// @param zipFile         the modpack archive
+    /// @param instanceId      the new instance id
+    /// @param modpack         the parsed modpack
+    /// @param iconUrl         the optional icon URL, or `null`
+    /// @param excludedFiles keys of optional files the user chose not to install; `null` means install all.
+    ///                        When non-null, must not contain `null` elements.
+    /// @return the install task
+    public static Task<?> getInstallTask(
+            HMCLGameRepository repository,
+            Path zipFile,
+            GameInstanceID instanceId,
+            Modpack modpack,
+            @Nullable String iconUrl,
+            @Nullable Set<String> excludedFiles) {
         ExceptionalRunnable<?> success = () -> {
-            repository.refreshVersions();
-            GameSettings.Instance setting = repository.getInstanceGameSettingsOrCreate(name);
-            repository.undoMark(name);
-            if (setting != null) {
-                setting.getOverrideProperties().add(GameSettings.PROPERTY_RUNNING_DIRECTORY);
-            }
+            repository.refresh();
+            repository.getInstance(instanceId).enableIsolation();
         };
 
         ExceptionalConsumer<Exception, ?> failure = ex -> {
@@ -220,45 +230,70 @@ public final class ModpackHelper {
         };
 
         if (modpack.getManifest() instanceof MultiMCInstanceConfiguration)
-            return modpack.getInstallTask(repository.getDependency(), zipFile, name, iconUrl)
+            return modpack.getInstallTask(repository.getDependency(), zipFile, instanceId, iconUrl, excludedFiles)
                     .whenComplete(Schedulers.defaultScheduler(), success, failure)
-                    .thenComposeAsync(createMultiMCPostInstallTask(repository, (MultiMCInstanceConfiguration) modpack.getManifest(), name))
+                    .thenComposeAsync(createMultiMCPostInstallTask(repository, (MultiMCInstanceConfiguration) modpack.getManifest(), instanceId))
                     .withStagesHints(new Task.StagesHint("hmcl.modpack"), new Task.StagesHint("hmcl.modpack.download", List.of("hmcl.install.assets", "hmcl.install.libraries")));
         else if (modpack.getManifest() instanceof McbbsModpackManifest)
-            return modpack.getInstallTask(repository.getDependency(), zipFile, name, iconUrl)
+            return modpack.getInstallTask(repository.getDependency(), zipFile, instanceId, iconUrl, excludedFiles)
                     .whenComplete(Schedulers.defaultScheduler(), success, failure)
-                    .thenComposeAsync(createMcbbsPostInstallTask(repository, (McbbsModpackManifest) modpack.getManifest(), name))
+                    .thenComposeAsync(createMcbbsPostInstallTask(repository, (McbbsModpackManifest) modpack.getManifest(), instanceId))
                     .withStagesHints(new Task.StagesHint("hmcl.modpack"), new Task.StagesHint("hmcl.modpack.download", List.of("hmcl.install.assets", "hmcl.install.libraries")));
         else
-            return modpack.getInstallTask(repository.getDependency(), zipFile, name, iconUrl)
+            return modpack.getInstallTask(repository.getDependency(), zipFile, instanceId, iconUrl, excludedFiles)
                     .whenComplete(Schedulers.defaultScheduler(), success, failure)
                     .withStagesHints(new Task.StagesHint("hmcl.modpack"), new Task.StagesHint("hmcl.modpack.download", List.of("hmcl.install.assets", "hmcl.install.libraries")));
     }
 
-    public static Task<Void> getUpdateTask(HMCLGameRepository repository, ServerModpackManifest manifest, Charset charset, String name, ModpackConfiguration<?> configuration) throws UnsupportedModpackException {
+    public static Task<Void> getUpdateTask(HMCLGameRepository repository, ServerModpackManifest manifest, Charset charset, GameInstanceID instanceId, ModpackConfiguration<?> configuration) throws UnsupportedModpackException {
         switch (configuration.getType()) {
-            case ServerModpackRemoteInstallTask.MODPACK_TYPE:
-                return new ModpackUpdateTask(repository, name, new ServerModpackRemoteInstallTask(repository.getDependency(), manifest, name))
-                        .thenComposeAsync(repository.refreshVersionsAsync())
+            case ServerModpackRemoteInstallTask.MODPACK_TYPE: {
+                HMCLGameInstance instance = repository.getInstance(instanceId);
+                return new ModpackUpdateTask(
+                        instance,
+                        new ServerModpackRemoteInstallTask(repository.getDependency(), manifest, instance))
+                        .thenComposeAsync(repository.refreshAsync())
                         .withStagesHints(new Task.StagesHint("hmcl.modpack"), new Task.StagesHint("hmcl.modpack.download", List.of("hmcl.install.assets", "hmcl.install.libraries")));
+            }
             default:
                 throw new UnsupportedModpackException();
         }
     }
 
-    public static Task<?> getUpdateTask(HMCLGameRepository repository, Path zipFile, Charset charset, String name, ModpackConfiguration<?> configuration) throws UnsupportedModpackException, ManuallyCreatedModpackException, MismatchedModpackTypeException {
+    public static Task<?> getUpdateTask(HMCLGameRepository repository, Path zipFile, Charset charset, GameInstanceID instanceId, ModpackConfiguration<?> configuration) throws UnsupportedModpackException, ManuallyCreatedModpackException, MismatchedModpackTypeException {
+        return getUpdateTask(repository, zipFile, charset, instanceId, configuration, null);
+    }
+
+    /// Creates an update task that respects optional-file selection.
+    ///
+    /// @param repository      the target repository
+    /// @param zipFile         the modpack archive
+    /// @param charset         the archive encoding
+    /// @param instanceId      the instance to update
+    /// @param configuration   the existing modpack configuration
+    /// @param excludedFiles keys of optional files the user chose not to install; `null` means install all.
+    ///                        When non-null, must not contain `null` elements.
+    /// @return the update task
+    public static Task<?> getUpdateTask(
+            HMCLGameRepository repository,
+            Path zipFile,
+            Charset charset,
+            GameInstanceID instanceId,
+            ModpackConfiguration<?> configuration,
+            @Nullable Set<String> excludedFiles)
+            throws UnsupportedModpackException, ManuallyCreatedModpackException, MismatchedModpackTypeException {
         Modpack modpack = ModpackHelper.readModpackManifest(zipFile, charset);
         ModpackProvider provider = getProviderByType(configuration.getType());
         if (provider == null) {
             throw new UnsupportedModpackException();
         }
         if (modpack.getManifest() instanceof MultiMCInstanceConfiguration)
-            return provider.createUpdateTask(repository.getDependency(), name, zipFile, modpack)
-                    .thenComposeAsync(() -> createMultiMCPostUpdateTask(repository, (MultiMCInstanceConfiguration) modpack.getManifest(), name))
-                    .thenComposeAsync(repository.refreshVersionsAsync());
+            return provider.createUpdateTask(repository.getDependency(), repository.getInstance(instanceId), zipFile, modpack, excludedFiles)
+                    .thenComposeAsync(() -> createMultiMCPostUpdateTask(repository, (MultiMCInstanceConfiguration) modpack.getManifest(), instanceId))
+                    .thenComposeAsync(repository.refreshAsync());
         else
-            return provider.createUpdateTask(repository.getDependency(), name, zipFile, modpack)
-                    .thenComposeAsync(repository.refreshVersionsAsync());
+            return provider.createUpdateTask(repository.getDependency(), repository.getInstance(instanceId), zipFile, modpack, excludedFiles)
+                    .thenComposeAsync(repository.refreshAsync());
     }
 
     public static void toGameSettings(MultiMCInstanceConfiguration c, GameSettings.Instance setting) {
@@ -333,25 +368,25 @@ public final class ModpackHelper {
         }
     }
 
-    private static Task<Void> createMultiMCPostUpdateTask(HMCLGameRepository repository, MultiMCInstanceConfiguration manifest, String version) {
+    private static Task<Void> createMultiMCPostUpdateTask(HMCLGameRepository repository, MultiMCInstanceConfiguration manifest, GameInstanceID instanceId) {
         return Task.runAsync(Schedulers.javafx(), () -> {
-            GameSettings.Instance setting = Objects.requireNonNull(repository.getInstanceGameSettingsOrCreate(version));
+            GameSettings.Instance setting = Objects.requireNonNull(repository.getInstanceGameSettingsOrCreate(instanceId));
             ModpackHelper.applyCommandAndJvmSettings(manifest, setting);
         });
     }
 
-    private static Task<Void> createMultiMCPostInstallTask(HMCLGameRepository repository, MultiMCInstanceConfiguration manifest, String version) {
+    private static Task<Void> createMultiMCPostInstallTask(HMCLGameRepository repository, MultiMCInstanceConfiguration manifest, GameInstanceID instanceId) {
         return Task.runAsync(Schedulers.javafx(), () -> {
-            GameSettings.Instance setting = Objects.requireNonNull(repository.getInstanceGameSettingsOrCreate(version));
+            GameSettings.Instance setting = Objects.requireNonNull(repository.getInstanceGameSettingsOrCreate(instanceId));
             ModpackHelper.toGameSettings(manifest, setting);
         });
     }
 
-    private static Task<Void> createMcbbsPostInstallTask(HMCLGameRepository repository, McbbsModpackManifest manifest, String version) {
+    private static Task<Void> createMcbbsPostInstallTask(HMCLGameRepository repository, McbbsModpackManifest manifest, GameInstanceID instanceId) {
         return Task.runAsync(Schedulers.javafx(), () -> {
-            GameSettings.Effective effective = repository.getEffectiveGameSettings(version);
+            GameSettings.Effective effective = repository.getEffectiveGameSettings(instanceId);
             if (manifest.getLaunchInfo().getMinMemory() > effective.getMaxMemory()) {
-                GameSettings.Instance setting = Objects.requireNonNull(repository.getInstanceGameSettingsOrCreate(version));
+                GameSettings.Instance setting = Objects.requireNonNull(repository.getInstanceGameSettingsOrCreate(instanceId));
                 setting.getOverrideProperties().addAll(List.of(
                         GameSettings.PROPERTY_AUTO_MEMORY,
                         GameSettings.PROPERTY_MIN_MEMORY,

HMCL/src/main/java/org/jackhuang/hmcl/game/OAuthServer.java

@@ -53,7 +53,7 @@ public final class OAuthServer extends NanoHTTPD implements OAuth.Session {
     private String idToken;
 
     private OAuthServer(int port) {
-        super(port);
+        super("localhost", port);
 
         this.port = port;
 

HMCL/src/main/java/org/jackhuang/hmcl/game/TexturesLoader.java

@@ -33,6 +33,7 @@ import org.jackhuang.hmcl.auth.microsoft.MicrosoftAccount;
 import org.jackhuang.hmcl.auth.offline.OfflineAccount;
 import org.jackhuang.hmcl.auth.offline.Skin;
 import org.jackhuang.hmcl.auth.yggdrasil.*;
+import org.jackhuang.hmcl.setting.DownloadProviders;
 import org.jackhuang.hmcl.task.FileDownloadTask;
 import org.jackhuang.hmcl.task.Schedulers;
 import org.jackhuang.hmcl.ui.FXUtils;
@@ -99,7 +100,7 @@ public final class TexturesLoader {
         if (!Files.isRegularFile(file)) {
             // download it
             try {
-                new FileDownloadTask(texture.url(), file).run();
+                new FileDownloadTask(DownloadProviders.getDownloadProvider().getDownloadCandidates(texture.url()), file).run();
                 LOG.info("Texture downloaded: " + texture.url());
             } catch (Exception e) {
                 if (Files.isRegularFile(file)) {

HMCL/src/main/java/org/jackhuang/hmcl/java/JavaManager.java

@@ -26,18 +26,13 @@ import javafx.beans.property.ObjectProperty;
 import javafx.beans.property.SimpleObjectProperty;
 import org.jackhuang.hmcl.Metadata;
 import org.jackhuang.hmcl.download.DownloadProvider;
-import org.jackhuang.hmcl.download.LibraryAnalyzer;
-import org.jackhuang.hmcl.game.GameJavaVersion;
-import org.jackhuang.hmcl.game.JavaVersionConstraint;
-import org.jackhuang.hmcl.game.Version;
+import org.jackhuang.hmcl.game.*;
 import org.jackhuang.hmcl.setting.SettingsManager;
 import org.jackhuang.hmcl.task.Schedulers;
 import org.jackhuang.hmcl.task.Task;
 import org.jackhuang.hmcl.ui.FXUtils;
-import org.jackhuang.hmcl.util.CacheRepository;
 import org.jackhuang.hmcl.util.DigestUtils;
 import org.jackhuang.hmcl.util.FXThread;
-import org.jackhuang.hmcl.util.Lang;
 import org.jackhuang.hmcl.util.gson.JsonUtils;
 import org.jackhuang.hmcl.util.io.FileUtils;
 import org.jackhuang.hmcl.util.platform.Architecture;
@@ -315,13 +310,13 @@ public final class JavaManager {
     }
 
     @Nullable
-    public static JavaRuntime findSuitableJava(GameVersionNumber gameVersion, Version version) throws InterruptedException {
-        return findSuitableJava(getAllJava(), gameVersion, version);
+    public static JavaRuntime findSuitableJava(GameVersionNumber gameVersion, GameInstanceManifest manifest) throws InterruptedException {
+        return findSuitableJava(getAllJava(), gameVersion, manifest);
     }
 
     @Nullable
-    public static JavaRuntime findSuitableJava(Collection<JavaRuntime> javaRuntimes, GameVersionNumber gameVersion, Version version) {
-        LibraryAnalyzer analyzer = version != null ? LibraryAnalyzer.analyze(version, gameVersion != null ? gameVersion.toString() : null) : null;
+    public static JavaRuntime findSuitableJava(Collection<JavaRuntime> javaRuntimes, GameVersionNumber gameVersion, GameInstanceManifest manifest) {
+        GameComponentAnalyzer analyzer = manifest != null ? GameComponentAnalyzer.analyze(manifest, gameVersion) : null;
 
         boolean forceX86 = Architecture.SYSTEM_ARCH == Architecture.ARM64
                 && (OperatingSystem.CURRENT_OS == OperatingSystem.WINDOWS || OperatingSystem.CURRENT_OS == OperatingSystem.MACOS)
@@ -342,8 +337,8 @@ public final class JavaManager {
             boolean violationSuggested = false;
 
             for (JavaVersionConstraint constraint : JavaVersionConstraint.ALL) {
-                if (constraint.appliesToVersion(gameVersion, version, java, analyzer)) {
-                    if (!constraint.checkJava(gameVersion, version, java, analyzer)) {
+                if (constraint.appliesToVersion(gameVersion, manifest, java, analyzer)) {
+                    if (!constraint.checkJava(gameVersion, manifest, java, analyzer)) {
                         if (constraint.isMandatory()) {
                             violationMandatory = true;
                         } else {
@@ -438,14 +433,14 @@ public final class JavaManager {
             FileUtils.tryGetPath(System.getenv("localappdata"), "Packages\\Microsoft.4297127D64EC6_8wekyb3d8bbwe\\LocalCache\\Local\\runtime")
                     .ifPresent(it -> searcher.searchAllOfficialJava(it, false));
 
-            FileUtils.tryGetPath(Lang.requireNonNullElse(System.getenv("ProgramFiles(x86)"), "C:\\Program Files (x86)"), "Minecraft Launcher\\runtime")
+            FileUtils.tryGetPath(Objects.requireNonNullElse(System.getenv("ProgramFiles(x86)"), "C:\\Program Files (x86)"), "Minecraft Launcher\\runtime")
                     .ifPresent(it -> searcher.searchAllOfficialJava(it, false));
         } else if (OperatingSystem.CURRENT_OS == OperatingSystem.LINUX && Architecture.SYSTEM_ARCH == Architecture.X86_64) {
             searcher.searchAllOfficialJava(Path.of(System.getProperty("user.home"), ".minecraft/runtime"), false);
         } else if (OperatingSystem.CURRENT_OS == OperatingSystem.MACOS) {
             searcher.searchAllOfficialJava(Path.of(System.getProperty("user.home"), "Library/Application Support/minecraft/runtime"), false);
         }
-        searcher.searchAllOfficialJava(CacheRepository.getInstance().getCacheDirectory().resolve("java"), true);
+        searcher.searchAllOfficialJava(HMCLCacheRepository.REPOSITORY.getCacheDirectory().resolve("java"), true);
 
         // Search in PATH.
         if (System.getenv("PATH") != null) {
@@ -499,7 +494,7 @@ public final class JavaManager {
                         it.isJDK() ? "JDK" : "JRE",
                         it.getVersion(),
                         it.getPlatform().getArchitecture().getDisplayName(),
-                        Lang.requireNonNullElse(it.getVendor(), "Unknown"),
+                        Objects.requireNonNullElse(it.getVendor(), "Unknown"),
                         it.getBinary()))
                 .collect(Collectors.joining("\n", "Finished Java lookup, found " + searcher.javaRuntimes.size() + "\n", "")));
         return searcher.javaRuntimes;
@@ -842,7 +837,7 @@ public final class JavaManager {
         }
 
         void searchJavaInProgramFiles(String env, String defaultValue) {
-            String programFiles = Lang.requireNonNullElse(System.getenv(env), defaultValue);
+            String programFiles = Objects.requireNonNullElse(System.getenv(env), defaultValue);
             Path path;
             try {
                 path = Path.of(programFiles);

HMCL/src/main/java/org/jackhuang/hmcl/setting/Accounts.java

@@ -47,13 +47,8 @@ import java.util.*;
 
 import static java.util.stream.Collectors.toList;
 import static javafx.collections.FXCollections.observableArrayList;
-import static org.jackhuang.hmcl.setting.SettingsManager.settings;
-import static org.jackhuang.hmcl.setting.SettingsManager.getAccountMetadataRecords;
-import static org.jackhuang.hmcl.setting.SettingsManager.getAuthlibInjectorServers;
-import static org.jackhuang.hmcl.setting.SettingsManager.getUserAccountMetadataRecords;
-import static org.jackhuang.hmcl.setting.SettingsManager.userSettings;
+import static org.jackhuang.hmcl.setting.SettingsManager.*;
 import static org.jackhuang.hmcl.ui.FXUtils.onInvalidating;
-import static org.jackhuang.hmcl.util.Lang.immutableListOf;
 import static org.jackhuang.hmcl.util.Lang.mapOf;
 import static org.jackhuang.hmcl.util.Pair.pair;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
@@ -73,7 +68,7 @@ public final class Accounts {
     public static final OfflineAccountFactory FACTORY_OFFLINE = new OfflineAccountFactory(AUTHLIB_INJECTOR_DOWNLOADER);
     public static final AuthlibInjectorAccountFactory FACTORY_AUTHLIB_INJECTOR = new AuthlibInjectorAccountFactory(AUTHLIB_INJECTOR_DOWNLOADER, Accounts::getOrCreateAuthlibInjectorServer);
     public static final MicrosoftAccountFactory FACTORY_MICROSOFT = new MicrosoftAccountFactory(new MicrosoftService(OAUTH_CALLBACK));
-    public static final List<AccountFactory<?>> FACTORIES = immutableListOf(FACTORY_OFFLINE, FACTORY_MICROSOFT, FACTORY_AUTHLIB_INJECTOR);
+    public static final List<AccountFactory<?>> FACTORIES = List.of(FACTORY_OFFLINE, FACTORY_MICROSOFT, FACTORY_AUTHLIB_INJECTOR);
 
     // ==== login type / account factory mapping ====
     private static final Map<String, AccountFactory<?>> type2factory = new HashMap<>();

HMCL/src/main/java/org/jackhuang/hmcl/setting/DownloadProviders.java

@@ -18,44 +18,47 @@
 package org.jackhuang.hmcl.setting;
 
 import javafx.beans.InvalidationListener;
+import org.glavo.url.WebURL;
 import org.jackhuang.hmcl.download.*;
-import org.jackhuang.hmcl.task.DownloadException;
 import org.jackhuang.hmcl.task.FetchTask;
+import org.jackhuang.hmcl.ui.FXUtils;
 import org.jackhuang.hmcl.util.StringUtils;
-import org.jackhuang.hmcl.util.i18n.I18n;
-import org.jackhuang.hmcl.util.i18n.LocaleUtils;
-import org.jackhuang.hmcl.util.io.ResponseCodeException;
-
-import javax.net.ssl.SSLHandshakeException;
-import java.io.FileNotFoundException;
-import java.net.SocketTimeoutException;
-import java.net.URI;
-import java.nio.file.AccessDeniedException;
-import java.util.List;
-import java.util.concurrent.CancellationException;
+import org.jetbrains.annotations.Nullable;
 
 import static org.jackhuang.hmcl.setting.SettingsManager.settings;
 import static org.jackhuang.hmcl.task.FetchTask.DEFAULT_CONCURRENCY;
-import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
+import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 
 public final class DownloadProviders {
     private DownloadProviders() {
     }
 
-    private static final DownloadProviderWrapper PROVIDER_WRAPPER;
-
-    private static final DownloadProvider MOJANG_PROVIDER;
-    private static final BMCLAPIDownloadProvider BMCLAPI_PROVIDER;
-    private static final DownloadProvider DEFAULT_PROVIDER;
+    private static final String DEFAULT_BMCLAPI_ROOT = "https://bmclapi2.bangbang93.com";
+    private static final String BMCLAPI_ROOT;
 
     static {
-        String bmclapiRoot = System.getProperty("hmcl.bmclapi.override", "https://bmclapi2.bangbang93.com");
-        BMCLAPI_PROVIDER = new BMCLAPIDownloadProvider(bmclapiRoot);
-        MOJANG_PROVIDER = new MojangDownloadProvider();
-        DEFAULT_PROVIDER = createDownloadProvider(DownloadSource.DEFAULT, DownloadSource.DEFAULT);
-        PROVIDER_WRAPPER = new DownloadProviderWrapper(DEFAULT_PROVIDER);
+        @Nullable String bmclOverride = System.getProperty("hmcl.bmclapi.override");
+        if (StringUtils.isBlank(bmclOverride)) {
+            BMCLAPI_ROOT = DEFAULT_BMCLAPI_ROOT;
+        } else {
+            WebURL url;
+            try {
+                url = WebURL.parseBrowserInput(bmclOverride);
+            } catch (Exception e) {
+                url = null;
+                LOG.warning("Invalid BMCLAPI override URL: " + bmclOverride, e);
+            }
+
+            if (url == null) {
+                BMCLAPI_ROOT = DEFAULT_BMCLAPI_ROOT;
+            } else {
+                BMCLAPI_ROOT = StringUtils.removeSuffix(url.toString(), "/");
+            }
+        }
     }
 
+    private static final HMCLDownloadProvider PROVIDER = new HMCLDownloadProvider(BMCLAPI_ROOT);
+
     /// Initializes download provider settings and synchronizes download thread settings.
     public static void init() {
         InvalidationListener onChangeDownloadThreads = observable -> {
@@ -67,73 +70,15 @@ public final class DownloadProviders {
         settings().downloadThreadsProperty().addListener(onChangeDownloadThreads);
         onChangeDownloadThreads.invalidated(null);
 
-        InvalidationListener onChangeDownloadSource = observable -> {
-            PROVIDER_WRAPPER.setProvider(createDownloadProvider(
-                    settings().versionListSourceProperty().get(),
-                    settings().fileDownloadSourceProperty().get()));
-        };
-        settings().versionListSourceProperty().addListener(onChangeDownloadSource);
-        settings().fileDownloadSourceProperty().addListener(onChangeDownloadSource);
-        onChangeDownloadSource.invalidated(null);
-    }
-
-    /// Creates a download provider with independent version-list and file download preferences.
-    private static DownloadProvider createDownloadProvider(DownloadSource versionListSource, DownloadSource fileDownloadSource) {
-        return new AutoDownloadProvider(
-                getCandidates(versionListSource),
-                getCandidates(fileDownloadSource));
-    }
-
-    /// Returns provider candidates ordered by the given source preference.
-    private static List<DownloadProvider> getCandidates(DownloadSource source) {
-        DownloadSource normalized = source != null ? source : DownloadSource.DEFAULT;
-        return switch (normalized) {
-            case DEFAULT -> LocaleUtils.IS_CHINA_MAINLAND
-                    ? List.of(BMCLAPI_PROVIDER, MOJANG_PROVIDER)
-                    : List.of(MOJANG_PROVIDER, BMCLAPI_PROVIDER);
-            case OFFICIAL -> List.of(MOJANG_PROVIDER);
-            case MIRROR -> List.of(BMCLAPI_PROVIDER, MOJANG_PROVIDER);
-        };
+        FXUtils.onChangeAndOperate(settings().versionListSourceProperty(), PROVIDER::setVersionListSource);
+        FXUtils.onChangeAndOperate(settings().fileDownloadSourceProperty(), PROVIDER::setFileSource);
     }
 
     /**
      * Get current primary preferred download provider
      */
     public static DownloadProvider getDownloadProvider() {
-        return PROVIDER_WRAPPER;
+        return PROVIDER;
     }
 
-    public static String localizeErrorMessage(Throwable exception) {
-        if (exception instanceof DownloadException) {
-            URI uri = ((DownloadException) exception).getUri();
-            if (exception.getCause() instanceof SocketTimeoutException) {
-                return i18n("install.failed.downloading.timeout", uri);
-            } else if (exception.getCause() instanceof ResponseCodeException) {
-                ResponseCodeException responseCodeException = (ResponseCodeException) exception.getCause();
-                if (I18n.hasKey("download.code." + responseCodeException.getResponseCode())) {
-                    return i18n("download.code." + responseCodeException.getResponseCode(), uri);
-                } else {
-                    return i18n("install.failed.downloading.detail", uri) + "\n" + StringUtils.getStackTrace(exception.getCause());
-                }
-            } else if (exception.getCause() instanceof FileNotFoundException) {
-                return i18n("download.code.404", uri);
-            } else if (exception.getCause() instanceof AccessDeniedException) {
-                return i18n("install.failed.downloading.detail", uri) + "\n" + i18n("exception.access_denied", ((AccessDeniedException) exception.getCause()).getFile());
-            } else if (exception.getCause() instanceof ArtifactMalformedException) {
-                return i18n("install.failed.downloading.detail", uri) + "\n" + i18n("exception.artifact_malformed");
-            } else if (exception.getCause() instanceof SSLHandshakeException && !(exception.getCause().getMessage() != null && exception.getCause().getMessage().contains("Remote host terminated"))) {
-                if (exception.getCause().getMessage() != null && (exception.getCause().getMessage().contains("No name matching") || exception.getCause().getMessage().contains("No subject alternative DNS name matching"))) {
-                    return i18n("install.failed.downloading.detail", uri) + "\n" + i18n("exception.dns.pollution");
-                }
-                return i18n("install.failed.downloading.detail", uri) + "\n" + i18n("exception.ssl_handshake");
-            } else {
-                return i18n("install.failed.downloading.detail", uri) + "\n" + StringUtils.getStackTrace(exception.getCause());
-            }
-        } else if (exception instanceof ArtifactMalformedException) {
-            return i18n("exception.artifact_malformed");
-        } else if (exception instanceof CancellationException) {
-            return i18n("message.cancelled");
-        }
-        return StringUtils.getStackTrace(exception);
-    }
 }

HMCL/src/main/java/org/jackhuang/hmcl/setting/GameDirectoryManager.java

@@ -17,14 +17,17 @@
  */
 package org.jackhuang.hmcl.setting;
 
-import javafx.beans.property.*;
+import javafx.beans.property.ObjectProperty;
+import javafx.beans.property.ReadOnlyObjectProperty;
+import javafx.beans.property.ReadOnlyObjectWrapper;
+import javafx.beans.property.SimpleObjectProperty;
 import javafx.beans.value.ChangeListener;
 import javafx.collections.FXCollections;
 import javafx.collections.ObservableList;
 import org.jackhuang.hmcl.Metadata;
-import org.jackhuang.hmcl.event.EventBus;
-import org.jackhuang.hmcl.event.RefreshedVersionsEvent;
+import org.jackhuang.hmcl.game.HMCLGameInstance;
 import org.jackhuang.hmcl.game.HMCLGameRepository;
+import org.jackhuang.hmcl.game.HMCLGameRepositorySnapshot;
 import org.jackhuang.hmcl.util.PortablePath;
 import org.jackhuang.hmcl.util.i18n.I18n;
 import org.jackhuang.hmcl.util.i18n.LocalizedText;
@@ -33,17 +36,10 @@ import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.UnknownNullability;
 import org.jetbrains.annotations.UnmodifiableView;
 
-import java.util.ArrayList;
-import java.util.IdentityHashMap;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.Objects;
-import java.util.UUID;
+import java.util.*;
 import java.util.function.Consumer;
 
 import static org.jackhuang.hmcl.setting.SettingsManager.*;
-import static org.jackhuang.hmcl.ui.FXUtils.runInFX;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 
 /// Manages the merged runtime view of local and user game directories.
@@ -140,13 +136,18 @@ public final class GameDirectoryManager {
     /// The selected game repository, or `null` before the fallback game directory is resolved.
     private static final ObjectProperty<@UnknownNullability HMCLGameRepository> selectedRepository = new SimpleObjectProperty<>(GameDirectoryManager.class, "selectedRepository");
 
-    /// The selected instance ID projected from the selected repository.
-    private static final ReadOnlyStringWrapper selectedInstance = new ReadOnlyStringWrapper(GameDirectoryManager.class, "selectedInstance");
+    /// The selected instance projected from the selected repository's current snapshot.
+    private static final ReadOnlyObjectWrapper<@Nullable HMCLGameInstance> selectedInstance =
+            new ReadOnlyObjectWrapper<>(GameDirectoryManager.class, "selectedInstance");
 
     /// Updates [#selectedInstance] when the selected repository changes its selected instance.
-    private static final ChangeListener<String> selectedRepositoryInstanceListener =
+    private static final ChangeListener<@Nullable HMCLGameInstance> selectedRepositoryInstanceListener =
             (observable, oldValue, newValue) -> selectedInstance.set(newValue);
 
+    /// Reacts when the selected repository publishes a new snapshot.
+    private static final ChangeListener<? super HMCLGameRepositorySnapshot> selectedRepositorySnapshotListener =
+            (observable, oldValue, newValue) -> onSelectedRepositorySnapshotChanged();
+
     /// Initializes game directory state from the stores loaded by [SettingsManager].
     ///
     /// This method creates the built-in local and user-home game directories when required, rebuilds
@@ -201,25 +202,32 @@ public final class GameDirectoryManager {
             @Nullable HMCLGameRepository oldRepository = selectedRepository.get();
             if (oldRepository != null) {
                 oldRepository.selectedInstanceProperty().removeListener(selectedRepositoryInstanceListener);
+                oldRepository.snapshotProperty().removeListener(selectedRepositorySnapshotListener);
             }
             HMCLGameRepository repository = getOrCreateRepository(newValue);
             selectedRepository.set(repository);
             selectedInstance.set(repository.getSelectedInstance());
             repository.selectedInstanceProperty().addListener(selectedRepositoryInstanceListener);
-            repository.refreshVersionsAsync().start();
+            repository.snapshotProperty().addListener(selectedRepositorySnapshotListener);
+            if (repository.isLoaded()) {
+                onSelectedRepositorySnapshotChanged();
+            }
+            repository.refreshAsync().start();
         });
         selectedGameDirectory.set(currentGameDirectory != null ? currentGameDirectory : mergedGameDirectories.get(0));
+    }
 
-        EventBus.EVENT_BUS.channel(RefreshedVersionsEvent.class).registerWeak(event -> {
-            runInFX(() -> {
-                @Nullable HMCLGameRepository repository = selectedRepository.get();
-                if (repository != null && repository == event.getSource()) {
-                    repository.refreshSelectedInstance();
-                    for (Consumer<HMCLGameRepository> listener : versionsListeners)
-                        listener.accept(repository);
-                }
-            });
-        });
+    /// Restores selection and notifies consumers after the selected repository publishes a loaded snapshot.
+    private static void onSelectedRepositorySnapshotChanged() {
+        @Nullable HMCLGameRepository repository = selectedRepository.get();
+        if (repository == null || !repository.isLoaded()) {
+            return;
+        }
+
+        repository.refreshSelectedInstance();
+        for (Consumer<HMCLGameRepository> listener : versionsListeners) {
+            listener.accept(repository);
+        }
     }
 
     /// Creates the built-in game directories only when no game directory exists.
@@ -322,6 +330,7 @@ public final class GameDirectoryManager {
         if (source == target) {
             gameDirectory.setName(name);
             gameDirectory.setPath(path);
+            rebuildGameDirectories();
             return;
         }
 
@@ -479,17 +488,26 @@ public final class GameDirectoryManager {
     }
 
     /// Returns the selected instance property projected from the selected repository.
-    public static ReadOnlyStringProperty selectedInstanceProperty() {
+    ///
+    /// The value is `null` when the selected repository has no registered selected instance.
+    ///
+    /// @return the read-only selected-instance property
+    public static ReadOnlyObjectProperty<@Nullable HMCLGameInstance> selectedInstanceProperty() {
         return selectedInstance.getReadOnlyProperty();
     }
 
-    /// Returns the selected instance ID for the selected repository.
-    public static @Nullable String getSelectedInstance() {
+    /// Returns the selected instance from the selected repository's current snapshot.
+    ///
+    /// @return the selected instance, or `null` when none is registered
+    public static @Nullable HMCLGameInstance getSelectedInstance() {
         return getSelectedRepository().getSelectedInstance();
     }
 
-    /// Sets the selected instance ID for the selected repository.
-    public static void setSelectedInstance(@Nullable String instance) {
+    /// Sets the selected instance for the selected repository.
+    ///
+    /// @param instance the instance to select, or `null` to clear the selection
+    /// @throws IllegalArgumentException if `instance` belongs to another repository
+    public static void setSelectedInstance(@Nullable HMCLGameInstance instance) {
         getSelectedRepository().setSelectedInstance(instance);
     }
 

HMCL/src/main/java/org/jackhuang/hmcl/setting/GameInstanceIconType.java

@@ -19,9 +19,11 @@ package org.jackhuang.hmcl.setting;
 
 import javafx.scene.image.Image;
 import org.jackhuang.hmcl.addon.mod.ModLoaderType;
+import org.jackhuang.hmcl.game.GameComponentType;
 import org.jackhuang.hmcl.ui.FXUtils;
+import org.jetbrains.annotations.Nullable;
 
-public enum VersionIconType {
+public enum GameInstanceIconType {
     DEFAULT("/assets/img/grass.png"),
 
     GRASS("/assets/img/grass.png"),
@@ -42,21 +44,38 @@ public enum VersionIconType {
 
     // Please append new items at last
 
-    public static VersionIconType getIconType(ModLoaderType modLoaderType) {
+    public static GameInstanceIconType getIconType(ModLoaderType modLoaderType) {
         return switch (modLoaderType) {
-            case FORGE -> VersionIconType.FORGE;
-            case NEO_FORGE -> VersionIconType.NEO_FORGE;
-            case FABRIC -> VersionIconType.FABRIC;
-            case QUILT -> VersionIconType.QUILT;
-            case LITE_LOADER -> VersionIconType.CHICKEN;
-            case CLEANROOM -> VersionIconType.CLEANROOM;
-            default -> VersionIconType.COMMAND;
+            case FORGE -> GameInstanceIconType.FORGE;
+            case NEO_FORGE -> GameInstanceIconType.NEO_FORGE;
+            case FABRIC -> GameInstanceIconType.FABRIC;
+            case LEGACY_FABRIC -> GameInstanceIconType.LEGACY_FABRIC;
+            case QUILT -> GameInstanceIconType.QUILT;
+            case LITE_LOADER -> GameInstanceIconType.CHICKEN;
+            case CLEANROOM -> GameInstanceIconType.CLEANROOM;
+            default -> GameInstanceIconType.COMMAND;
         };
     }
 
+    public static @Nullable GameInstanceIconType getIconType(GameComponentType componentType) {
+        return switch (componentType) {
+            case GAME -> GameInstanceIconType.GRASS;
+            case FABRIC, FABRIC_API -> GameInstanceIconType.FABRIC;
+            case LEGACY_FABRIC, LEGACY_FABRIC_API -> GameInstanceIconType.LEGACY_FABRIC;
+            case FORGE -> GameInstanceIconType.FORGE;
+            case CLEANROOM -> GameInstanceIconType.CLEANROOM;
+            case LITELOADER -> GameInstanceIconType.CHICKEN;
+            case OPTIFINE -> GameInstanceIconType.OPTIFINE;
+            case QUILT, QUILT_API -> GameInstanceIconType.QUILT;
+            case NEO_FORGE -> GameInstanceIconType.NEO_FORGE;
+            default -> null;
+        };
+    }
+
+
     private final String resourceUrl;
 
-    VersionIconType(String resourceUrl) {
+    GameInstanceIconType(String resourceUrl) {
         this.resourceUrl = resourceUrl;
     }
 

HMCL/src/main/java/org/jackhuang/hmcl/setting/GameSettings.java

@@ -152,10 +152,10 @@ public sealed abstract class GameSettings extends ObservableSetting {
 
         /// The icon of the instance.
         @SerializedName("icon")
-        private final SettingProperty<VersionIconType> icon = newSettingProperty("icon", VersionIconType.DEFAULT);
+        private final SettingProperty<GameInstanceIconType> icon = newSettingProperty("icon", GameInstanceIconType.DEFAULT);
 
         /// Returns the instance icon property.
-        public SettingProperty<VersionIconType> iconProperty() {
+        public SettingProperty<GameInstanceIconType> iconProperty() {
             return icon;
         }
 
@@ -643,6 +643,19 @@ public sealed abstract class GameSettings extends ObservableSetting {
         return vulkanRenderer;
     }
 
+    /// Property name for high performance GPU preference.
+    public static final String PROPERTY_HIGH_PERFORMANCE = "highPerformance";
+
+    /// Whether to launch games with high-performance GPU.
+    @SerializedName(PROPERTY_HIGH_PERFORMANCE)
+    private final InheritableProperty<Boolean> highPerformance =
+            newInheritableProperty(PROPERTY_HIGH_PERFORMANCE, false);
+
+    /// Returns the high performance GPU preference property.
+    public InheritableProperty<Boolean> highPerformanceProperty() {
+        return highPerformance;
+    }
+
     /// Property name for customized environment variables.
     public static final String PROPERTY_ENVIRONMENT_VARIABLES = "environmentVariables";
 
@@ -800,15 +813,15 @@ public sealed abstract class GameSettings extends ObservableSetting {
     }
 
     /// Property name for using native GLFW.
-    public static final String PROPERTY_USE_NATIVE_GLFW = "useNativeGLFW";
+    public static final String PROPERTY_USE_NATIVE_GLFW_OR_SDL = "useNativeGLFW";
 
     /// If `true`, HMCL will use native GLFW.
-    @SerializedName(PROPERTY_USE_NATIVE_GLFW)
-    private final InheritableProperty<Boolean> useNativeGLFW = newInheritableProperty(PROPERTY_USE_NATIVE_GLFW, false);
+    @SerializedName(PROPERTY_USE_NATIVE_GLFW_OR_SDL)
+    private final InheritableProperty<Boolean> useNativeGLFWorSDL = newInheritableProperty(PROPERTY_USE_NATIVE_GLFW_OR_SDL, false);
 
     /// Returns the native GLFW property.
-    public InheritableProperty<Boolean> useNativeGLFWProperty() {
-        return useNativeGLFW;
+    public InheritableProperty<Boolean> useNativeGLFWorSDLProperty() {
+        return useNativeGLFWorSDL;
     }
 
     /// Property name for using native OpenAL.
@@ -916,11 +929,11 @@ public sealed abstract class GameSettings extends ObservableSetting {
         }
 
         /// Finds the effective Java runtime.
-        public @Nullable JavaRuntime getJava(@Nullable GameVersionNumber gameVersion, @Nullable Version version) throws InterruptedException {
+        public @Nullable JavaRuntime getJava(@Nullable GameVersionNumber gameVersion, @Nullable GameInstanceManifest manifest) throws InterruptedException {
             JavaVersionType javaVersionType = getInheritable(GameSettings::javaTypeProperty);
             switch (javaVersionType) {
                 case AUTO:
-                    return JavaManager.findSuitableJava(gameVersion, version);
+                    return JavaManager.findSuitableJava(gameVersion, manifest);
                 case CUSTOM:
                     try {
                         return JavaManager.getJava(Path.of(getInheritable(GameSettings::customJavaPathProperty)));
@@ -930,7 +943,7 @@ public sealed abstract class GameSettings extends ObservableSetting {
                 case VERSION: {
                     String javaVersion = getInheritable(GameSettings::customJavaVersionProperty);
                     if (StringUtils.isBlank(javaVersion)) {
-                        return JavaManager.findSuitableJava(gameVersion, version);
+                        return JavaManager.findSuitableJava(gameVersion, manifest);
                     }
 
                     int majorVersion = -1;
@@ -948,13 +961,13 @@ public sealed abstract class GameSettings extends ObservableSetting {
                     Collection<JavaRuntime> allJava = JavaManager.getAllJava().stream()
                             .filter(it -> it.getParsedVersion() == finalMajorVersion)
                             .collect(Collectors.toList());
-                    return JavaManager.findSuitableJava(allJava, gameVersion, version);
+                    return JavaManager.findSuitableJava(allJava, gameVersion, manifest);
                 }
                 case DETECTED: {
                     DetectedJava detectedJava = getInheritable(GameSettings::detectedJavaProperty);
                     String javaVersion = detectedJava.version();
                     if (StringUtils.isBlank(javaVersion)) {
-                        return JavaManager.findSuitableJava(gameVersion, version);
+                        return JavaManager.findSuitableJava(gameVersion, manifest);
                     }
 
                     if (StringUtils.isNotBlank(detectedJava.pathHash())) {

HMCL/src/main/java/org/jackhuang/hmcl/setting/LauncherSettings.java

@@ -34,6 +34,7 @@ import org.hildan.fxgson.creators.ObservableSetCreator;
 import org.hildan.fxgson.factories.JavaFxPropertyTypeAdapterFactory;
 import org.jackhuang.hmcl.Metadata;
 import org.jackhuang.hmcl.auth.AccountID;
+import org.jackhuang.hmcl.game.GameInstanceID;
 import org.jackhuang.hmcl.java.JavaRuntime;
 import org.jackhuang.hmcl.theme.BackgroundLoadPolicy;
 import org.jackhuang.hmcl.theme.BuiltinBackground;
@@ -623,34 +624,34 @@ public final class LauncherSettings extends ObservableSetting implements JsonSch
     ///
     /// This field is owned by [GameDirectoryManager]. Code outside [GameDirectoryManager] should not modify it directly.
     @SerializedName(PROPERTY_SELECTED_INSTANCE)
-    private final ObservableMap<GameDirectoryID, String> selectedInstance = FXCollections.observableHashMap();
+    private final ObservableMap<GameDirectoryID, GameInstanceID> selectedInstance = FXCollections.observableHashMap();
 
     /// Returns selected instance IDs keyed by game directory ID.
     ///
     /// The map stores persisted selected instance values by game directory ID.
-    public ObservableMap<GameDirectoryID, String> getSelectedInstance() {
+    public ObservableMap<GameDirectoryID, GameInstanceID> getSelectedInstance() {
         return selectedInstance;
     }
 
     /// Returns the selected instance ID for the given game directory ID.
     ///
     /// The value is loaded by the game repository for the matching game directory.
-    public @Nullable String getSelectedInstance(@Nullable GameDirectoryID gameDirectoryId) {
+    public @Nullable GameInstanceID getSelectedInstance(@Nullable GameDirectoryID gameDirectoryId) {
         return gameDirectoryId != null ? selectedInstance.get(gameDirectoryId) : null;
     }
 
     /// Sets the selected instance ID for the given game directory ID.
     ///
     /// Blank values remove the persisted selected instance entry.
-    public void setSelectedInstance(@Nullable GameDirectoryID gameDirectoryId, @Nullable String selectedInstance) {
+    public void setSelectedInstance(@Nullable GameDirectoryID gameDirectoryId, @Nullable GameInstanceID selectedInstance) {
         if (gameDirectoryId == null) {
             return;
         }
 
-        if (StringUtils.isBlank(selectedInstance)) {
-            this.selectedInstance.remove(gameDirectoryId);
-        } else {
+        if (selectedInstance != null) {
             this.selectedInstance.put(gameDirectoryId, selectedInstance);
+        } else {
+            this.selectedInstance.remove(gameDirectoryId);
         }
     }
 

HMCL/src/main/java/org/jackhuang/hmcl/setting/LegacyGameSettingsMigrator.java

@@ -73,22 +73,22 @@ public final class LegacyGameSettingsMigrator {
     }
 
     /// Legacy `VersionIconType` ordinal order used by old local settings.
-    private static final VersionIconType @Unmodifiable [] LEGACY_VERSION_ICON_TYPES = {
-            VersionIconType.DEFAULT,
-            VersionIconType.GRASS,
-            VersionIconType.CHEST,
-            VersionIconType.CHICKEN,
-            VersionIconType.COMMAND,
-            VersionIconType.OPTIFINE,
-            VersionIconType.CRAFT_TABLE,
-            VersionIconType.FABRIC,
-            VersionIconType.FORGE,
-            VersionIconType.NEO_FORGE,
-            VersionIconType.FURNACE,
-            VersionIconType.QUILT,
-            VersionIconType.APRIL_FOOLS,
-            VersionIconType.CLEANROOM,
-            VersionIconType.LEGACY_FABRIC
+    private static final GameInstanceIconType @Unmodifiable [] LEGACY_VERSION_ICON_TYPES = {
+            GameInstanceIconType.DEFAULT,
+            GameInstanceIconType.GRASS,
+            GameInstanceIconType.CHEST,
+            GameInstanceIconType.CHICKEN,
+            GameInstanceIconType.COMMAND,
+            GameInstanceIconType.OPTIFINE,
+            GameInstanceIconType.CRAFT_TABLE,
+            GameInstanceIconType.FABRIC,
+            GameInstanceIconType.FORGE,
+            GameInstanceIconType.NEO_FORGE,
+            GameInstanceIconType.FURNACE,
+            GameInstanceIconType.QUILT,
+            GameInstanceIconType.APRIL_FOOLS,
+            GameInstanceIconType.CLEANROOM,
+            GameInstanceIconType.LEGACY_FABRIC
     };
 
     /// Legacy `JavaVersionType` ordinal order used by old game settings.
@@ -130,14 +130,14 @@ public final class LegacyGameSettingsMigrator {
     /// @return the migrated instance setting, or `null` when no legacy file can be migrated
     public static @Nullable InstanceMigrationResult migrateInstanceGameSettings(
             HMCLGameRepository repository,
-            String instanceId,
+            GameInstanceID instanceId,
             @Nullable GameSettingsPresetID parent) {
-        Path instanceRoot = repository.getVersionRoot(instanceId);
+        Path instanceRoot = repository.getLayout().getInstanceRoot(instanceId);
         Path file = instanceRoot.resolve(LEGACY_INSTANCE_SETTINGS_FILENAME);
         if (!Files.exists(file)) {
             return null;
         }
-        Path receiptLocation = repository.getInstanceStateDirectory(instanceId)
+        Path receiptLocation = repository.getLayout().getInstanceStateDirectory(instanceId)
                 .resolve(LEGACY_INSTANCE_SETTINGS_MIGRATION_RECEIPT_FILENAME);
         if (MigrationReceipt.matches(receiptLocation, file)) {
             LOG.info("Skipping already migrated legacy version setting " + file);
@@ -271,7 +271,7 @@ public final class LegacyGameSettingsMigrator {
                     GameSettings.PROPERTY_NOT_PATCH_NATIVES,
                     GameSettings.PROPERTY_USE_CUSTOM_NATIVES,
                     GameSettings.PROPERTY_NATIVES_DIRECTORY,
-                    GameSettings.PROPERTY_USE_NATIVE_GLFW,
+                    GameSettings.PROPERTY_USE_NATIVE_GLFW_OR_SDL,
                     GameSettings.PROPERTY_USE_NATIVE_OPENAL
             ));
         }
@@ -342,7 +342,7 @@ public final class LegacyGameSettingsMigrator {
         boolean useCustomNatives = isLegacyCustomNativesDirectory(source);
         target.useCustomNativesProperty().setValue(useCustomNatives);
         target.nativesDirectoryProperty().setValue(useCustomNatives ? JsonUtils.getString(source, "nativesDir", "") : "");
-        target.useNativeGLFWProperty().setValue(JsonUtils.getBoolean(source, "useNativeGLFW", false));
+        target.useNativeGLFWorSDLProperty().setValue(JsonUtils.getBoolean(source, "useNativeGLFW", false));
         target.useNativeOpenALProperty().setValue(JsonUtils.getBoolean(source, "useNativeOpenAL", false));
     }
 
@@ -488,10 +488,10 @@ public final class LegacyGameSettingsMigrator {
     }
 
     /// Parses the legacy icon selection with frozen ordinal order.
-    private static VersionIconType parseLegacyVersionIconType(@Nullable JsonObject source) {
+    private static GameInstanceIconType parseLegacyVersionIconType(@Nullable JsonObject source) {
         JsonPrimitive primitive = JsonUtils.getPrimitive(source, "versionIcon");
         if (primitive == null) {
-            return VersionIconType.DEFAULT;
+            return GameInstanceIconType.DEFAULT;
         }
 
         try {
@@ -499,11 +499,11 @@ public final class LegacyGameSettingsMigrator {
                 int index = primitive.getAsInt();
                 return index >= 0 && index < LEGACY_VERSION_ICON_TYPES.length
                         ? LEGACY_VERSION_ICON_TYPES[index]
-                        : VersionIconType.DEFAULT;
+                        : GameInstanceIconType.DEFAULT;
             }
 
             String value = primitive.getAsString();
-            for (VersionIconType iconType : LEGACY_VERSION_ICON_TYPES) {
+            for (GameInstanceIconType iconType : LEGACY_VERSION_ICON_TYPES) {
                 if (iconType.name().equalsIgnoreCase(value)) {
                     return iconType;
                 }
@@ -511,7 +511,7 @@ public final class LegacyGameSettingsMigrator {
         } catch (RuntimeException ignored) {
         }
 
-        return VersionIconType.DEFAULT;
+        return GameInstanceIconType.DEFAULT;
     }
 
     /// Reads an enum property from either ordinal or name.

HMCL/src/main/java/org/jackhuang/hmcl/setting/StyleSheets.java

@@ -153,6 +153,7 @@ public final class StyleSheets {
         addColor(builder, "-monet-primary-seed", scheme.getPrimaryColorSeed());
 
         addColor(builder, scheme, ColorRole.PRIMARY, 0.5);
+        addColor(builder, scheme, ColorRole.PRIMARY, 0.8);
         addColor(builder, scheme, ColorRole.SECONDARY_CONTAINER, 0.5);
         addColor(builder, scheme, ColorRole.SURFACE, 0.5);
         addColor(builder, scheme, ColorRole.SURFACE, 0.8);

HMCL/src/main/java/org/jackhuang/hmcl/terracotta/TerracottaBundle.java

@@ -18,6 +18,7 @@
 package org.jackhuang.hmcl.terracotta;
 
 import kala.compress.archivers.tar.TarArchiveEntry;
+import org.glavo.url.WebURL;
 import org.jackhuang.hmcl.download.ArtifactMalformedException;
 import org.jackhuang.hmcl.task.FetchTask;
 import org.jackhuang.hmcl.task.FileDownloadTask;
@@ -29,13 +30,12 @@ import org.jackhuang.hmcl.util.io.ChecksumMismatchException;
 import org.jackhuang.hmcl.util.io.FileUtils;
 import org.jackhuang.hmcl.util.io.UrlResponseInfo;
 import org.jackhuang.hmcl.util.platform.OperatingSystem;
-import org.jetbrains.annotations.Nullable;
 import org.jackhuang.hmcl.util.tree.TarFileTree;
+import org.jetbrains.annotations.Nullable;
 
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
-import java.net.URI;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.security.DigestInputStream;
@@ -50,13 +50,16 @@ import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 public final class TerracottaBundle {
     private final Path root;
 
-    private final List<URI> links;
+    /// Candidate bundle URLs in attempt order.
+    private final List<WebURL> links;
 
     private final FileDownloadTask.IntegrityCheck hash;
 
     private final Map<String, FileDownloadTask.IntegrityCheck> files;
 
-    public TerracottaBundle(Path root, List<URI> links, FileDownloadTask.IntegrityCheck hash, Map<String, FileDownloadTask.IntegrityCheck> files) {
+    /// Creates a bundle using the supplied download candidates and archive/file integrity metadata.
+    /// The candidate list and file map are retained without copying.
+    public TerracottaBundle(Path root, List<WebURL> links, FileDownloadTask.IntegrityCheck hash, Map<String, FileDownloadTask.IntegrityCheck> files) {
         this.root = root;
         this.links = links;
         this.hash = hash;

HMCL/src/main/java/org/jackhuang/hmcl/terracotta/TerracottaManager.java

@@ -22,6 +22,7 @@ import javafx.application.Platform;
 import javafx.beans.property.ReadOnlyDoubleWrapper;
 import javafx.beans.property.ReadOnlyObjectProperty;
 import javafx.beans.property.ReadOnlyObjectWrapper;
+import org.glavo.url.WebURL;
 import org.jackhuang.hmcl.auth.Account;
 import org.jackhuang.hmcl.setting.Accounts;
 import org.jackhuang.hmcl.task.DownloadException;
@@ -42,7 +43,6 @@ import org.jackhuang.hmcl.util.platform.ManagedProcess;
 import org.jackhuang.hmcl.util.platform.SystemUtils;
 
 import java.io.IOException;
-import java.net.URI;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
@@ -288,7 +288,7 @@ public final class TerracottaManager {
 
     public static Task<String> exportLogs() {
         if (STATE_V.get() instanceof TerracottaState.PortSpecific portSpecific) {
-            return new GetTask(URI.create(String.format("http://127.0.0.1:%d/log?fetch=true", portSpecific.port)))
+            return new GetTask(WebURL.parse(String.format("http://127.0.0.1:%d/log?fetch=true", portSpecific.port)))
                     .setSignificance(Task.TaskSignificance.MINOR);
         }
         return Task.completed(null);
@@ -297,7 +297,7 @@ public final class TerracottaManager {
     public static TerracottaState.Waiting setWaiting() {
         TerracottaState state = STATE_V.get();
         if (state instanceof TerracottaState.PortSpecific portSpecific) {
-            new GetTask(URI.create(String.format("http://127.0.0.1:%d/state/ide", portSpecific.port)))
+            new GetTask(WebURL.parse(String.format("http://127.0.0.1:%d/state/ide", portSpecific.port)))
                     .setSignificance(Task.TaskSignificance.MINOR)
                     .start();
             return new TerracottaState.Waiting(-1, -1, null);
@@ -317,7 +317,7 @@ public final class TerracottaManager {
                     .thenComposeAsync(nodes -> {
                         List<Pair<String, String>> query = new ArrayList<>(nodes.size() + 1);
                         query.add(pair("player", getPlayerName()));
-                        for (URI node : nodes) {
+                        for (WebURL node : nodes) {
                             query.add(pair("public_nodes", node.toString()));
                         }
                         return new GetTask(NetworkUtils.withQuery(
@@ -338,7 +338,7 @@ public final class TerracottaManager {
                         ArrayList<Pair<String, String>> query = new ArrayList<>(nodes.size() + 2);
                         query.add(pair("room", room));
                         query.add(pair("player", getPlayerName()));
-                        for (URI node : nodes) {
+                        for (WebURL node : nodes) {
                             query.add(pair("public_nodes", node.toString()));
                         }
                         return new GetTask(NetworkUtils.withQuery("http://127.0.0.1:%d/state/guesting".formatted(portSpecific.port), query))

HMCL/src/main/java/org/jackhuang/hmcl/terracotta/TerracottaMetadata.java

@@ -18,6 +18,7 @@
 package org.jackhuang.hmcl.terracotta;
 
 import com.google.gson.annotations.SerializedName;
+import org.glavo.url.WebURL;
 import org.jackhuang.hmcl.Metadata;
 import org.jackhuang.hmcl.task.FileDownloadTask;
 import org.jackhuang.hmcl.terracotta.provider.AbstractTerracottaProvider;
@@ -35,10 +36,10 @@ import org.jackhuang.hmcl.util.platform.OperatingSystem;
 import org.jackhuang.hmcl.util.versioning.VersionNumber;
 import org.jackhuang.hmcl.util.versioning.VersionRange;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
 import java.io.IOException;
 import java.io.InputStream;
-import java.net.URI;
 import java.nio.file.DirectoryStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -90,8 +91,8 @@ public final class TerracottaMetadata {
             }
 
             Stream<String> stream = downloads.stream(), streamCN = downloadsCN.stream();
-            List<URI> links = (LocaleUtils.IS_CHINA_MAINLAND ? Stream.concat(streamCN, stream) : Stream.concat(stream, streamCN))
-                    .map(link -> URI.create(options.replace(link)))
+            @Unmodifiable List<WebURL> links = (LocaleUtils.IS_CHINA_MAINLAND ? Stream.concat(streamCN, stream) : Stream.concat(stream, streamCN))
+                    .map(link -> WebURL.parse(options.replace(link)))
                     .toList();
 
             Map<String, FileDownloadTask.IntegrityCheck> files = pkg.files.entrySet().stream().collect(Collectors.toUnmodifiableMap(

HMCL/src/main/java/org/jackhuang/hmcl/terracotta/TerracottaNodeList.java

@@ -18,6 +18,7 @@
 package org.jackhuang.hmcl.terracotta;
 
 import com.google.gson.JsonParseException;
+import org.glavo.url.WebURL;
 import org.jackhuang.hmcl.util.StringUtils;
 import org.jackhuang.hmcl.util.gson.JsonSerializable;
 import org.jackhuang.hmcl.util.gson.JsonUtils;
@@ -26,9 +27,8 @@ import org.jackhuang.hmcl.util.gson.Validation;
 import org.jackhuang.hmcl.util.i18n.LocaleUtils;
 import org.jackhuang.hmcl.util.io.HttpRequest;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
-import java.net.URI;
-import java.net.URISyntaxException;
 import java.util.List;
 
 import static org.jackhuang.hmcl.util.logging.Logger.LOG;
@@ -43,17 +43,19 @@ public final class TerracottaNodeList {
         public void validate() throws JsonParseException, TolerableValidationException {
             Validation.requireNonNull(url, "TerracottaNode.url cannot be null");
             try {
-                new URI(url);
-            } catch (URISyntaxException e) {
+                WebURL.parse(url);
+            } catch (IllegalArgumentException e) {
                 throw new JsonParseException("Invalid URL: " + url, e);
             }
         }
     }
 
-    private static volatile List<URI> list;
+    /// Cached node URLs, or `null` before the first fetch completes.
+    private static volatile @Nullable @Unmodifiable List<WebURL> list;
 
-    public static List<URI> fetch() {
-        List<URI> list = TerracottaNodeList.list;
+    /// Returns the cached unmodifiable node URLs, fetching once and caching an empty list on failure.
+    public static @Unmodifiable List<WebURL> fetch() {
+        @Nullable @Unmodifiable List<WebURL> list = TerracottaNodeList.list;
         if (list != null)
             return list;
 
@@ -84,7 +86,7 @@ public final class TerracottaNodeList {
 
                                 return StringUtils.isBlank(node.region) || LocaleUtils.IS_CHINA_MAINLAND == "CN".equalsIgnoreCase(node.region);
                             })
-                            .map(it -> URI.create(it.url()))
+                            .map(it -> WebURL.parse(it.url()))
                             .toList();
                     LOG.info("Terracotta node list: " + list);
                 }

HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java

@@ -26,6 +26,7 @@ import org.glavo.monetfx.Brightness;
 import org.glavo.monetfx.ColorRole;
 import org.glavo.monetfx.ColorStyle;
 import org.glavo.monetfx.Contrast;
+import org.glavo.url.WebURL;
 import org.jackhuang.hmcl.Metadata;
 import org.jackhuang.hmcl.setting.BackgroundType;
 import org.jackhuang.hmcl.setting.LauncherSettings;
@@ -36,8 +37,8 @@ import org.jackhuang.hmcl.util.MathUtils;
 import org.jackhuang.hmcl.util.StringUtils;
 import org.jackhuang.hmcl.util.gson.JsonUtils;
 import org.jackhuang.hmcl.util.i18n.LocalizedText;
-import org.jackhuang.hmcl.util.io.FileUtils;
 import org.jackhuang.hmcl.util.io.ContentEncoding;
+import org.jackhuang.hmcl.util.io.FileUtils;
 import org.jackhuang.hmcl.util.io.IOUtils;
 import org.jackhuang.hmcl.util.io.NetworkUtils;
 import org.jetbrains.annotations.NotNullByDefault;
@@ -48,7 +49,6 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.net.HttpURLConnection;
-import java.net.URI;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.AtomicMoveNotSupportedException;
 import java.nio.file.Files;
@@ -1497,28 +1497,28 @@ public final class ThemePackManager {
             List<Path> temporaryFiles,
             ResolvedBackground background) throws IOException {
         String url = requireNonBlank(background.networkImageUrl(), "background.url");
-        URI uri = NetworkUtils.toURI(url);
-        if (!NetworkUtils.isHttpUri(uri)) {
+        WebURL webUrl = WebURL.parse(url);
+        if (!NetworkUtils.isHttpUri(webUrl)) {
             throw new IOException("Theme background URL must be HTTP or HTTPS: " + url);
         }
 
-        String entryName = "assets/wallpapers/" + networkBackgroundAssetName(uri);
+        String entryName = "assets/wallpapers/" + networkBackgroundAssetName(webUrl);
         if (background.networkImageCachePolicy() == NetworkBackgroundImageCachePolicy.ENABLED) {
             try {
-                @Nullable Path cachedFile = new CacheFileTask(uri).run();
+                @Nullable Path cachedFile = new CacheFileTask(webUrl).run();
                 if (cachedFile != null && Files.isRegularFile(cachedFile)) {
                     assets.add(new ThemePackAsset(cachedFile, entryName));
                     return new ThemeBackground.Image(entryName);
                 }
             } catch (Exception e) {
-                LOG.warning("Failed to cache theme background, falling back to direct download: " + uri, e);
+                LOG.warning("Failed to cache theme background, falling back to direct download: " + webUrl, e);
             }
         }
 
         Path temporaryFile = Files.createTempFile("hmcl-theme-background-", ".tmp");
         boolean success = false;
         try {
-            downloadNetworkBackground(uri, temporaryFile);
+            downloadNetworkBackground(webUrl, temporaryFile);
             assets.add(new ThemePackAsset(temporaryFile, entryName));
             temporaryFiles.add(temporaryFile);
             success = true;
@@ -1535,12 +1535,12 @@ public final class ThemePackManager {
     }
 
     /// Downloads one network background into a temporary file without installing it into the persistent image cache.
-    private static void downloadNetworkBackground(URI uri, Path outputFile) throws IOException {
-        HttpURLConnection connection = NetworkUtils.resolveConnection(NetworkUtils.createHttpConnection(uri));
+    private static void downloadNetworkBackground(WebURL url, Path outputFile) throws IOException {
+        HttpURLConnection connection = NetworkUtils.resolveConnection(NetworkUtils.createHttpConnection(url));
         try {
             int responseCode = connection.getResponseCode();
             if (responseCode / 100 != 2) {
-                throw new IOException("Failed to download theme background: HTTP " + responseCode + " " + uri);
+                throw new IOException("Failed to download theme background: HTTP " + responseCode + " " + url);
             }
 
             ContentEncoding contentEncoding = ContentEncoding.fromConnection(connection);
@@ -1554,8 +1554,8 @@ public final class ThemePackManager {
     }
 
     /// Returns a safe theme-pack asset file name for a downloaded network background.
-    private static String networkBackgroundAssetName(URI uri) {
-        String path = Objects.toString(uri.getPath(), "");
+    private static String networkBackgroundAssetName(WebURL url) {
+        String path = Objects.toString(url.getPath(), "");
         @Nullable Path fileNamePath = path.isBlank() ? null : Path.of(path).getFileName();
         String fileName = fileNamePath != null ? fileNamePath.toString() : "";
         String sanitized = sanitizePathSegment(fileName);

HMCL/src/main/java/org/jackhuang/hmcl/theme/Themes.java

@@ -24,8 +24,7 @@ import javafx.beans.binding.Bindings;
 import javafx.beans.binding.BooleanBinding;
 import javafx.beans.binding.ObjectBinding;
 import javafx.beans.binding.ObjectExpression;
-import javafx.beans.property.ReadOnlyObjectProperty;
-import javafx.beans.property.ReadOnlyObjectWrapper;
+import javafx.beans.property.*;
 import javafx.beans.value.ChangeListener;
 import javafx.beans.value.ObservableValue;
 import javafx.collections.SetChangeListener;
@@ -80,6 +79,7 @@ import java.nio.file.Files;
 import java.nio.file.Path;
 import java.time.Duration;
 import java.util.*;
+import java.util.function.Supplier;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -91,6 +91,9 @@ import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 /// Provides the current launcher MonetFX theme and derived color bindings.
 @NotNullByDefault
 public final class Themes {
+    /// The stage property retaining the listener for native appearance updates and marking completed registration.
+    private static final String NATIVE_DARK_MODE_LISTENER = "Themes.applyNativeDarkMode.listener";
+
     /// The seed color extracted from the last loaded wallpaper image.
     private static final ReadOnlyObjectWrapper<@Nullable ThemeColor> wallpaperThemeColor = new ReadOnlyObjectWrapper<>();
 
@@ -283,6 +286,9 @@ public final class Themes {
             colorScheme
     );
 
+    /// Whether the current color scheme brightness is inherited from system.
+    private static final ReadOnlyBooleanWrapper autoBrightness = new ReadOnlyBooleanWrapper();
+
     /// The current JavaFX launcher background and its node opacity.
     private static final ReadOnlyObjectWrapper<LauncherBackground> background = new ReadOnlyObjectWrapper<>(
             new LauncherBackground(
@@ -380,6 +386,35 @@ public final class Themes {
     }
 
     static {
+        Supplier<@Nullable Brightness> effectiveBrightnessSupplier = () -> {
+            try {
+                return ThemePackManager.resolveCurrentThemeBrightness(ThemePackManager.currentResolveContext());
+            } catch (IOException | RuntimeException e) {
+                return null;
+            }
+        };
+        InvalidationListener autoBrightnessListener = o -> {
+            boolean auto;
+            if (settings().getThemeAppearanceOverrides().contains(LauncherSettings.THEME_APPEARANCE_BRIGHTNESS_MODE)) {
+                String val = settings().themeBrightnessModeProperty().get();
+                auto = val == null || switch (val.trim().toLowerCase(Locale.ROOT)) {
+                    case "light", "dark" -> false;
+                    default -> true;
+                };
+            } else {
+                auto = effectiveBrightnessSupplier.get() == null;
+            }
+            autoBrightness.set(auto);
+        };
+        settings().selectedThemeProperty().addListener(autoBrightnessListener);
+        settings().getThemeAppearanceOverrides().addListener(autoBrightnessListener);
+        settings().themeBrightnessModeProperty().addListener(autoBrightnessListener);
+        settings().backgroundTypeProperty().addListener(autoBrightnessListener);
+        if (FXUtils.DARK_MODE != null) {
+            FXUtils.DARK_MODE.addListener(autoBrightnessListener);
+        }
+        autoBrightnessListener.invalidated(null);
+
         ChangeListener<ResolvedTheme> listener = (observable, oldValue, newValue) -> {
             if (!Objects.equals(oldValue, newValue)) {
                 colorScheme.set(newValue.toColorScheme());
@@ -433,7 +468,7 @@ public final class Themes {
         }
 
         String themeBrightnessMode = settings().themeBrightnessModeProperty().get();
-        return switch (Objects.toString(themeBrightnessMode, "").toLowerCase(Locale.ROOT).trim()) {
+        return switch (Objects.toString(themeBrightnessMode, "").trim().toLowerCase(Locale.ROOT)) {
             case "light" -> Brightness.LIGHT;
             case "dark" -> Brightness.DARK;
             default -> getAutomaticBrightness();
@@ -444,24 +479,16 @@ public final class Themes {
     ///
     /// @return the effective launcher brightness
     public static Brightness getCurrentBrightness() {
+        Brightness contextBrightness = getThemeConditionBrightness();
         if (!settings().getThemeAppearanceOverrides().contains(LauncherSettings.THEME_APPEARANCE_BRIGHTNESS_MODE)) {
-            Brightness contextBrightness = getThemeConditionBrightness();
             try {
                 return Objects.requireNonNullElse(
                         ThemePackManager.resolveCurrentThemeBrightness(ThemeResolveContext.current(contextBrightness)),
                         contextBrightness);
-            } catch (IOException | RuntimeException e) {
-                return contextBrightness;
+            } catch (IOException | RuntimeException ignored) {
             }
         }
-
-        String themeBrightnessMode = settings().themeBrightnessModeProperty().get();
-        return switch (Objects.toString(themeBrightnessMode, "").toLowerCase(Locale.ROOT).trim()) {
-            case "auto" -> getAutomaticBrightness();
-            case "dark" -> Brightness.DARK;
-            case "light" -> Brightness.LIGHT;
-            default -> getAutomaticBrightness();
-        };
+        return contextBrightness;
     }
 
     /// Returns the brightness requested by the current system or platform settings.
@@ -1119,8 +1146,22 @@ public final class Themes {
         return darkMode;
     }
 
-    /// Applies native dark-mode integration to a JavaFX stage where the platform supports it.
+    /// Returns whether the current color scheme brightness is inherited from system.
+    public static ReadOnlyBooleanProperty autoBrightnessProperty() {
+        return autoBrightness.getReadOnlyProperty();
+    }
+
+    /// Registers native dark-mode integration once per stage where the platform supports it.
+    ///
+    /// Windows updates the stage's native frame; macOS updates the application appearance. The stage retains
+    /// its listener, which observes theme changes weakly. Repeated calls for an already registered stage do
+    /// nothing, including after hiding the stage or replacing its scene.
+    ///
+    /// @param stage the stage retaining the registration, accessed on the JavaFX application thread
     public static void applyNativeDarkMode(Stage stage) {
+        if (stage.getProperties().containsKey(NATIVE_DARK_MODE_LISTENER)) {
+            return;
+        }
         if (OperatingSystem.SYSTEM_VERSION.isAtLeast(OSVersion.WINDOWS_11) && NativeUtils.USE_JNA && Dwmapi.INSTANCE != null) {
             ChangeListener<Boolean> listener = FXUtils.onWeakChange(Themes.darkModeProperty(), darkMode -> {
                 if (stage.isShowing()) {
@@ -1137,7 +1178,7 @@ public final class Themes {
                     });
                 }
             });
-            stage.getProperties().put("Themes.applyNativeDarkMode.listener", listener);
+            stage.getProperties().put(NATIVE_DARK_MODE_LISTENER, listener);
 
             if (stage.isShowing()) {
                 listener.changed(null, false, Themes.darkModeProperty().get());
@@ -1154,7 +1195,7 @@ public final class Themes {
             MacOSNativeUtils.setAppearance(darkModeProperty().get());
 
             ChangeListener<Boolean> listener = FXUtils.onWeakChange(Themes.darkModeProperty(), MacOSNativeUtils::setAppearance);
-            stage.getProperties().put("Themes.applyNativeDarkMode.listener", listener);
+            stage.getProperties().put(NATIVE_DARK_MODE_LISTENER, listener);
         }
     }
 

HMCL/src/main/java/org/jackhuang/hmcl/ui/Controllers.java

@@ -24,46 +24,44 @@ import javafx.animation.KeyFrame;
 import javafx.animation.KeyValue;
 import javafx.animation.Timeline;
 import javafx.application.Platform;
-import javafx.beans.InvalidationListener;
-import javafx.beans.WeakInvalidationListener;
-import javafx.beans.property.DoubleProperty;
-import javafx.beans.property.ReadOnlyDoubleProperty;
-import javafx.beans.property.SimpleDoubleProperty;
-import javafx.geometry.Rectangle2D;
 import javafx.scene.Node;
 import javafx.scene.Scene;
 import javafx.scene.control.ButtonBase;
 import javafx.scene.control.Label;
 import javafx.scene.layout.Region;
-import javafx.scene.paint.Color;
 import javafx.stage.*;
 import javafx.util.Duration;
 import org.jackhuang.hmcl.Launcher;
 import org.jackhuang.hmcl.Metadata;
+import org.jackhuang.hmcl.game.GameInstanceID;
+import org.jackhuang.hmcl.game.HMCLGameRepository;
 import org.jackhuang.hmcl.game.LauncherHelper;
+import org.jackhuang.hmcl.game.ModpackHelper;
 import org.jackhuang.hmcl.java.JavaManager;
 import org.jackhuang.hmcl.java.JavaRuntime;
+import org.jackhuang.hmcl.modpack.Modpack;
 import org.jackhuang.hmcl.setting.*;
+import org.jackhuang.hmcl.task.Schedulers;
 import org.jackhuang.hmcl.task.Task;
 import org.jackhuang.hmcl.task.TaskExecutor;
 import org.jackhuang.hmcl.ui.account.AccountListPage;
-import org.jackhuang.hmcl.ui.animation.AnimationUtils;
 import org.jackhuang.hmcl.ui.animation.ContainerAnimations;
 import org.jackhuang.hmcl.ui.animation.Motion;
 import org.jackhuang.hmcl.ui.construct.*;
 import org.jackhuang.hmcl.ui.construct.MessageDialogPane.MessageType;
-import org.jackhuang.hmcl.ui.decorator.DecoratorController;
+import org.jackhuang.hmcl.ui.decorator.Decorator;
 import org.jackhuang.hmcl.ui.download.DownloadPage;
 import org.jackhuang.hmcl.ui.main.LauncherSettingsPage;
 import org.jackhuang.hmcl.ui.main.RootPage;
 import org.jackhuang.hmcl.ui.terracotta.TerracottaPage;
-import org.jackhuang.hmcl.ui.versions.GameListPage;
-import org.jackhuang.hmcl.ui.versions.VersionPage;
-import org.jackhuang.hmcl.ui.versions.Versions;
+import org.jackhuang.hmcl.ui.instances.GameListPage;
+import org.jackhuang.hmcl.ui.instances.GameInstancePage;
+import org.jackhuang.hmcl.ui.instances.Instances;
 import org.jackhuang.hmcl.upgrade.UpdateChecker;
 import org.jackhuang.hmcl.util.*;
 import org.jackhuang.hmcl.util.i18n.I18n;
 import org.jackhuang.hmcl.util.i18n.SupportedLocale;
+import org.jackhuang.hmcl.util.io.CompressingUtils;
 import org.jackhuang.hmcl.util.io.FileUtils;
 import org.jackhuang.hmcl.util.platform.Architecture;
 import org.jackhuang.hmcl.util.platform.OperatingSystem;
@@ -71,9 +69,13 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.io.IOException;
+import java.net.URI;
+import java.nio.charset.Charset;
+import java.nio.file.Files;
 import java.nio.file.Path;
 import java.time.LocalDate;
 import java.util.List;
+import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 
 import static org.jackhuang.hmcl.setting.SettingsManager.settings;
@@ -89,26 +91,12 @@ public final class Controllers {
     public static final String SOFTWARE_RENDERING = "softwareRendering";
     public static final String APRIL_FOOLS = "aprilFools";
 
-    private static final int CUSTOM_DECORATION_SHADOW_SIZE = 8;
-    private static final int CUSTOM_DECORATION_SHADOW_EXTENT = CUSTOM_DECORATION_SHADOW_SIZE * 2;
-
-    public static final int MIN_CONTENT_WIDTH = 800 + 2; // bg width + border width*2
-    public static final int MIN_CONTENT_HEIGHT = 450 + 2 + 40; // bg height + border width*2 + toolbar height
-    public static final int MIN_WIDTH = MIN_CONTENT_WIDTH + CUSTOM_DECORATION_SHADOW_EXTENT;
-    public static final int MIN_HEIGHT = MIN_CONTENT_HEIGHT + CUSTOM_DECORATION_SHADOW_EXTENT;
-    public static final Rectangle2D PRIMARY_SCREEN_BOUNDS = Screen.getPrimary().getBounds();
-    private static InvalidationListener stageSizeChangeListener;
-    private static final DoubleProperty contentX = new SimpleDoubleProperty();
-    private static final DoubleProperty contentY = new SimpleDoubleProperty();
-    private static final DoubleProperty contentWidth = new SimpleDoubleProperty();
-    private static final DoubleProperty contentHeight = new SimpleDoubleProperty();
-
-    private static Scene scene;
-    private static Stage stage;
-    private static VersionPage versionPage;
+    private static GameInstancePage gameInstancePage;
     private static Lazy<GameListPage> gameListPage = new Lazy<>(GameListPage::new);
     private static Lazy<RootPage> rootPage = new Lazy<>(RootPage::new);
-    private static DecoratorController decorator;
+    /// The coordinator for the main window's scene graph and navigation stack.
+    private static @Nullable Decorator decorator;
+
     private static DownloadPage downloadPage;
     private static Lazy<AccountListPage> accountListPage = new Lazy<>(() -> {
         AccountListPage accountListPage = new AccountListPage();
@@ -132,31 +120,27 @@ public final class Controllers {
         void run() throws Exception;
     }
 
+    /// Returns the stage currently attached to the main-window decorator.
+    ///
+    /// @return the current stage, or `null` before initialization or after detachment
     public static @Nullable Stage getStage() {
-        return stage;
-    }
-
-    public static ReadOnlyDoubleProperty windowWidthProperty() {
-        return contentWidth;
-    }
-
-    public static ReadOnlyDoubleProperty windowHeightProperty() {
-        return contentHeight;
+        @Nullable Decorator currentDecorator = decorator;
+        return currentDecorator == null ? null : currentDecorator.getStage();
     }
 
     @FXThread
-    public static VersionPage getVersionPage() {
-        if (versionPage == null) {
-            versionPage = new VersionPage();
+    public static GameInstancePage getGameInstancePage() {
+        if (gameInstancePage == null) {
+            gameInstancePage = new GameInstancePage();
         }
-        return versionPage;
+        return gameInstancePage;
     }
 
     @FXThread
-    public static void prepareVersionPage() {
-        if (versionPage == null) {
-            LOG.info("Prepare the version page");
-            versionPage = FXUtils.prepareNode(new VersionPage());
+    public static void prepareGameInstancePage() {
+        if (gameInstancePage == null) {
+            LOG.info("Prepare the game instance page");
+            gameInstancePage = FXUtils.prepareNode(new GameInstancePage());
         }
     }
 
@@ -212,15 +196,34 @@ public final class Controllers {
         return terracottaPage.get();
     }
 
+    /// Returns the initialized main-window decorator.
+    ///
+    /// @return the application-wide main-window decorator
     @FXThread
-    public static DecoratorController getDecorator() {
-        return decorator;
+    public static Decorator getDecorator() {
+        return Objects.requireNonNull(decorator, "Main window is not initialized");
     }
 
+    /// Releases stage-specific listeners and retained window ownership before application shutdown.
     public static void onApplicationStop() {
-        stageSizeChangeListener = null;
+        if (decorator != null) {
+            decorator.detachStage();
+        }
     }
 
+    /// Configures the main stage's application identity, shutdown action, and taskbar relaunch information.
+    ///
+    /// @param stage the unshown main stage
+    private static void configureMainStage(Stage stage) {
+        stage.setOnCloseRequest(event -> Launcher.stopApplication());
+        FXUtils.setIcon(stage);
+        stage.setTitle(Metadata.FULL_TITLE);
+        WindowsNativeUtils.installWindowsAppUserModelRelaunchProperties(stage);
+    }
+
+    /// Initializes the main application stage, scene graph, and background services.
+    ///
+    /// @param stage the primary application stage, which must not have been shown
     public static void initialize(Stage stage) {
         LOG.info("Start initializing application");
 
@@ -238,99 +241,10 @@ public final class Controllers {
             }
         }
 
-        Controllers.stage = stage;
+        configureMainStage(stage);
 
-        double initContentWidth = Math.max(MIN_CONTENT_WIDTH, state().getWidth());
-        double initContentHeight = Math.max(MIN_CONTENT_HEIGHT, state().getHeight());
-        double initWidth = initContentWidth + CUSTOM_DECORATION_SHADOW_EXTENT;
-        double initHeight = initContentHeight + CUSTOM_DECORATION_SHADOW_EXTENT;
-
-        {
-            double initContentX = state().getX() * PRIMARY_SCREEN_BOUNDS.getWidth();
-            double initContentY = state().getY() * PRIMARY_SCREEN_BOUNDS.getHeight();
-
-            boolean invalid = true;
-            double border = 20D;
-            for (Screen screen : Screen.getScreens()) {
-                Rectangle2D bound = screen.getBounds();
-
-                if (bound.getMinX() + border <= initContentX + initContentWidth
-                        && initContentX <= bound.getMaxX() - border
-                        && bound.getMinY() + border <= initContentY
-                        && initContentY <= bound.getMaxY() - border) {
-                    invalid = false;
-                    break;
-                }
-            }
-
-            if (invalid) {
-                initContentX = (0.5D - initContentWidth / PRIMARY_SCREEN_BOUNDS.getWidth() / 2)
-                        * PRIMARY_SCREEN_BOUNDS.getWidth();
-                initContentY = (0.5D - initContentHeight / PRIMARY_SCREEN_BOUNDS.getHeight() / 2)
-                        * PRIMARY_SCREEN_BOUNDS.getHeight();
-            }
-
-            double initX = initContentX - CUSTOM_DECORATION_SHADOW_SIZE;
-            double initY = initContentY - CUSTOM_DECORATION_SHADOW_SIZE;
-            stage.setX(initX);
-            stage.setY(initY);
-            contentX.set(initContentX);
-            contentY.set(initContentY);
-        }
-
-        stage.setHeight(initHeight);
-        stage.setWidth(initWidth);
-        contentHeight.set(initContentHeight);
-        contentWidth.set(initContentWidth);
-
-        stageSizeChangeListener = o -> {
-            ReadOnlyDoubleProperty property = (ReadOnlyDoubleProperty) o;
-            Stage currentStage = property.getBean() instanceof Stage s ? s : null;
-            if (currentStage == null)
-                return;
-
-            boolean saveState = !currentStage.isIconified()
-                    // https://github.com/HMCL-dev/HMCL/issues/4290
-                    && (OperatingSystem.CURRENT_OS == OperatingSystem.MACOS
-                    || !currentStage.isFullScreen() && !currentStage.isMaximized());
-
-            switch (property.getName()) {
-                case "x" -> {
-                    double value = property.get() + CUSTOM_DECORATION_SHADOW_SIZE;
-                    contentX.set(value);
-                    if (saveState)
-                        state().setX(value / PRIMARY_SCREEN_BOUNDS.getWidth());
-                }
-                case "y" -> {
-                    double value = property.get() + CUSTOM_DECORATION_SHADOW_SIZE;
-                    contentY.set(value);
-                    if (saveState)
-                        state().setY(value / PRIMARY_SCREEN_BOUNDS.getHeight());
-                }
-                case "width" -> {
-                    double value = Math.max(MIN_CONTENT_WIDTH, property.get() - CUSTOM_DECORATION_SHADOW_EXTENT);
-                    contentWidth.set(value);
-                    if (saveState)
-                        state().setWidth(value);
-                }
-                case "height" -> {
-                    double value = Math.max(MIN_CONTENT_HEIGHT, property.get() - CUSTOM_DECORATION_SHADOW_EXTENT);
-                    contentHeight.set(value);
-                    if (saveState)
-                        state().setHeight(value);
-                }
-            }
-        };
-
-        WeakInvalidationListener weakListener = new WeakInvalidationListener(stageSizeChangeListener);
-        stage.xProperty().addListener(weakListener);
-        stage.yProperty().addListener(weakListener);
-        stage.heightProperty().addListener(weakListener);
-        stage.widthProperty().addListener(weakListener);
-
-        stage.setOnCloseRequest(e -> Launcher.stopApplication());
-
-        decorator = new DecoratorController(stage, getRootPage());
+        decorator = new Decorator(getRootPage(), Controllers::configureMainStage);
+        Scene mainScene = decorator.attachStage(stage);
         getRootPage().getMainPage().showUpdateProperty().bind(UpdateChecker.checkingUpdateProperty().not().and(UpdateChecker.outdatedProperty()));
         getRootPage().getMainPage().showUpdateDialogProperty().bind(
                 decorator.backableProperty().not()
@@ -346,36 +260,7 @@ public final class Controllers {
 
         Lang.thread(JavaManager::initialize, "Search Java", true);
 
-        scene = new Scene(decorator.getDecorator());
-        scene.setFill(Color.TRANSPARENT);
-        stage.setMinWidth(MIN_WIDTH);
-        stage.setMinHeight(MIN_HEIGHT);
-        decorator.getDecorator().prefWidthProperty().bind(scene.widthProperty());
-        decorator.getDecorator().prefHeightProperty().bind(scene.heightProperty());
-        StyleSheets.init(scene);
-
-        FXUtils.setIcon(stage);
-        stage.setTitle(Metadata.FULL_TITLE);
-        stage.initStyle(StageStyle.TRANSPARENT);
-        stage.setScene(scene);
-
-        if (AnimationUtils.playWindowAnimation()) {
-            Timeline timeline = new Timeline(
-                    new KeyFrame(Duration.millis(0),
-                            new KeyValue(decorator.getDecorator().opacityProperty(), 0, Motion.EASE),
-                            new KeyValue(decorator.getDecorator().scaleXProperty(), 0.8, Motion.EASE),
-                            new KeyValue(decorator.getDecorator().scaleYProperty(), 0.8, Motion.EASE),
-                            new KeyValue(decorator.getDecorator().scaleZProperty(), 0.8, Motion.EASE)
-                    ),
-                    new KeyFrame(Duration.millis(600),
-                            new KeyValue(decorator.getDecorator().opacityProperty(), 1, Motion.EASE),
-                            new KeyValue(decorator.getDecorator().scaleXProperty(), 1, Motion.EASE),
-                            new KeyValue(decorator.getDecorator().scaleYProperty(), 1, Motion.EASE),
-                            new KeyValue(decorator.getDecorator().scaleZProperty(), 1, Motion.EASE)
-                    )
-            );
-            timeline.play();
-        }
+        StyleSheets.init(mainScene);
 
         if (!Architecture.SYSTEM_ARCH.isX86() && SettingsManager.userState().platformPromptVersionProperty().get() < 1) {
             Runnable continueAction = () -> {
@@ -502,6 +387,42 @@ public final class Controllers {
                         }, updateShowTips);
                     }, updateShowTips);
         }
+
+        tryInstallBundledModpack(GameDirectoryManager.getSelectedRepository());
+    }
+
+    /// Offers automatic install when a package exists under `.hmcl/modpack/`.
+    ///
+    /// Called from [Controllers#initialize] after the UI is ready. Install does not wait for repository
+    /// refresh: instance paths come from the selected repository layout. The package file itself is the
+    /// install signal; it is deleted after a successful install so later startups do not re-prompt.
+    private static void tryInstallBundledModpack(HMCLGameRepository repository) {
+        @Nullable Path modpackFile = Metadata.findBundledModpackFile();
+        if (modpackFile == null) {
+            return;
+        }
+
+        LOG.info("Found bundled modpack at " + modpackFile + "; starting automatic install");
+
+        Controllers.taskDialog(
+                Task.composeAsync(Schedulers.io(), () -> {
+                            Charset encoding = CompressingUtils.findSuitableEncoding(modpackFile);
+                            Modpack modpack = ModpackHelper.readModpackManifest(modpackFile, encoding);
+                            return ModpackHelper.getInstallTask(
+                                    repository, modpackFile, new GameInstanceID(modpack.getName()), modpack, null);
+                        })
+                        .whenComplete(Schedulers.javafx(), (ignored, exception) -> {
+                            if (exception != null) {
+                                LOG.warning("Failed to install bundled modpack", exception);
+                                return;
+                            }
+                            try {
+                                Files.deleteIfExists(modpackFile);
+                            } catch (IOException e) {
+                                LOG.warning("Failed to delete bundled modpack: " + modpackFile, e);
+                            }
+                        }), i18n("modpack.installing"), TaskCancellationAction.NO_CANCEL
+        );
     }
 
     public static void dialog(Region content) {
@@ -644,20 +565,36 @@ public final class Controllers {
         decorator.showToast(content);
     }
 
+    /// Shows `directoryChooser` with the current main window as its owner.
+    ///
+    /// @param directoryChooser the chooser to show
+    /// @return the selected directory, or `null` if the chooser is cancelled
     public static @Nullable Path showDialog(DirectoryChooser directoryChooser) {
-        return FileUtils.toPath(directoryChooser.showDialog(stage));
+        return FileUtils.toPath(directoryChooser.showDialog(getStage()));
     }
 
+    /// Shows `fileChooser` for opening one file with the current main window as its owner.
+    ///
+    /// @param fileChooser the chooser to show
+    /// @return the selected file, or `null` if the chooser is cancelled
     public static @Nullable Path showOpenDialog(FileChooser fileChooser) {
-        return FileUtils.toPath(fileChooser.showOpenDialog(stage));
+        return FileUtils.toPath(fileChooser.showOpenDialog(getStage()));
     }
 
+    /// Shows `fileChooser` for saving one file with the current main window as its owner.
+    ///
+    /// @param fileChooser the chooser to show
+    /// @return the selected file, or `null` if the chooser is cancelled
     public static @Nullable Path showSaveDialog(FileChooser fileChooser) {
-        return FileUtils.toPath(fileChooser.showSaveDialog(stage));
+        return FileUtils.toPath(fileChooser.showSaveDialog(getStage()));
     }
 
+    /// Shows `fileChooser` for opening multiple files with the current main window as its owner.
+    ///
+    /// @param fileChooser the chooser to show
+    /// @return the selected files, or `null` if the chooser is cancelled
     public static @Nullable List<Path> showOpenMultipleDialog(FileChooser fileChooser) {
-        return FileUtils.toPaths(fileChooser.showOpenMultipleDialog(stage));
+        return FileUtils.toPaths(fileChooser.showOpenMultipleDialog(getStage()));
     }
 
     public static void onHyperlinkAction(String href) {
@@ -669,7 +606,7 @@ public final class Controllers {
                     break;
                 case "hmcl://game/launch":
                     var repository = GameDirectoryManager.getSelectedRepository();
-                    Versions.launch(repository, repository.getSelectedInstance(), LauncherHelper::setKeep);
+                    Instances.launch(repository.getSelectedInstance(), LauncherHelper::setKeep);
                     break;
             }
         } else {
@@ -677,23 +614,48 @@ public final class Controllers {
         }
     }
 
+    public static void openUriOrCopy(@Nullable URI url) {
+        if (url == null) return;
+        openUriOrCopy(url.toString());
+    }
+
+    public static void openUriOrCopy(@Nullable String url) {
+        if (url == null) return;
+        var dialog = new MessageDialogPane.Builder(
+                i18n("web.open_in_browser", url),
+                i18n("message.confirm"),
+                MessageDialogPane.MessageType.QUESTION
+        )
+                .addAction(i18n("button.copy"), () -> FXUtils.copyText(url))
+                .yesOrNo(() -> FXUtils.openLink(url), null)
+                .build();
+        dialog(dialog);
+    }
+
     public static boolean isStopped() {
         return decorator == null;
     }
 
+    /// Releases controller-owned pages, window state, and JavaFX helper resources.
     public static void shutdown() {
+        onApplicationStop();
         rootPage = null;
-        versionPage = null;
+        gameInstancePage = null;
         gameListPage = null;
         downloadPage = null;
         accountListPage = null;
         settingsPage = null;
         terracottaPage = null;
         decorator = null;
-        stage = null;
-        scene = null;
-        onApplicationStop();
 
         FXUtils.shutdown();
     }
+
+    public static final boolean AUTO_TRIM_HEAP = !"false".equalsIgnoreCase(System.getenv("HMCL_AUTO_TRIM_HEAP"));
+
+    public static void trimHeap() {
+        if (AUTO_TRIM_HEAP) {
+            System.gc();
+        }
+    }
 }

HMCL/src/main/java/org/jackhuang/hmcl/ui/CrashWindow.java

@@ -72,6 +72,8 @@ public class CrashWindow extends Stage {
         FXUtils.setIcon(this);
         setTitle(i18n("message.error"));
 
+        FXUtils.addMacOSCloseWindowHandler(this, null);
+
         setOnCloseRequest(e -> javafx.application.Platform.exit());
     }
 

HMCL/src/main/java/org/jackhuang/hmcl/ui/DialogUtils.java

@@ -49,17 +49,31 @@ public final class DialogUtils {
 
     public static final String PROPERTY_DIALOG_SHOW_LATER = DialogUtils.class.getName() + ".dialog.showLater";
 
+    /// Shows content in the main-window dialog stack owned by `decorator`.
+    ///
+    /// @param decorator the main-window decorator
+    /// @param content   the dialog content
     public static void show(Decorator decorator, Node content) {
-        if (decorator.getDrawerWrapper() == null) {
-            Platform.runLater(() -> show(decorator, content));
+        StackPane dialogContainer = decorator.getDialogContainer();
+        if (decorator.getRoot().getScene() == null) {
+            Platform.runLater(() -> showInDecorator(decorator, dialogContainer, content));
             return;
         }
 
-        show(decorator.getDrawerWrapper(), content, (dialog) -> {
+        showInDecorator(decorator, dialogContainer, content);
+    }
+
+    /// Shows content in a decorator's resolved dialog container.
+    ///
+    /// @param decorator     the main-window decorator
+    /// @param dialogContainer the container resolved before any deferred execution
+    /// @param content       the dialog content
+    private static void showInDecorator(Decorator decorator, StackPane dialogContainer, Node content) {
+        show(dialogContainer, content, dialog -> {
             JFXDialogPane pane = (JFXDialogPane) dialog.getContent();
-            decorator.capableDraggingWindow(dialog);
+            decorator.capableDraggingOverlay(dialog);
             decorator.forbidDraggingWindow(pane);
-            dialog.setDialogContainer(decorator.getDrawerWrapper());
+            dialog.setDialogContainer(dialogContainer);
         });
     }
 
@@ -125,12 +139,18 @@ public final class DialogUtils {
         }
     }
 
+    /// Queues content in the main-window dialog stack owned by `decorator`.
+    ///
+    /// @param decorator the main-window decorator
+    /// @param content   the dialog content
     public static void showLater(Decorator decorator, Node content) {
-        if (decorator.getDrawerWrapper() == null) {
-            Platform.runLater(() -> showLater(decorator, content));
+        StackPane dialogContainer = decorator.getDialogContainer();
+        Runnable showDialogAction = () -> showInDecorator(decorator, dialogContainer, content);
+        if (decorator.getRoot().getScene() == null) {
+            Platform.runLater(() -> showLater(dialogContainer, showDialogAction));
             return;
         }
-        showLater(decorator.getDrawerWrapper(), () -> show(decorator, content));
+        showLater(dialogContainer, showDialogAction);
     }
 
     @SuppressWarnings("unchecked")

HMCL/src/main/java/org/jackhuang/hmcl/ui/FXUtils.java

@@ -32,6 +32,7 @@ import javafx.beans.value.ChangeListener;
 import javafx.beans.value.ObservableBooleanValue;
 import javafx.beans.value.ObservableValue;
 import javafx.beans.value.WeakChangeListener;
+import javafx.collections.ObservableList;
 import javafx.collections.ObservableMap;
 import javafx.event.Event;
 import javafx.event.EventDispatcher;
@@ -44,6 +45,7 @@ import javafx.scene.Node;
 import javafx.scene.Parent;
 import javafx.scene.Scene;
 import javafx.scene.control.*;
+import javafx.scene.control.skin.TableViewSkin;
 import javafx.scene.control.skin.VirtualFlow;
 import javafx.scene.image.Image;
 import javafx.scene.image.ImageView;
@@ -56,13 +58,11 @@ import javafx.scene.paint.Paint;
 import javafx.scene.shape.Rectangle;
 import javafx.scene.text.Text;
 import javafx.scene.text.TextFlow;
-import javafx.stage.FileChooser;
-import javafx.stage.Screen;
-import javafx.stage.Stage;
-import javafx.util.Callback;
+import javafx.stage.*;
 import javafx.util.Duration;
 import javafx.util.StringConverter;
 import org.glavo.url.WebURL;
+import org.jackhuang.hmcl.download.DownloadCandidates;
 import org.jackhuang.hmcl.setting.StyleSheets;
 import org.jackhuang.hmcl.task.CacheFileTask;
 import org.jackhuang.hmcl.task.Schedulers;
@@ -74,15 +74,16 @@ import org.jackhuang.hmcl.ui.construct.MenuSeparator;
 import org.jackhuang.hmcl.ui.construct.PopupMenu;
 import org.jackhuang.hmcl.ui.image.ImageLoader;
 import org.jackhuang.hmcl.ui.image.ImageUtils;
+import org.jackhuang.hmcl.util.FXThread;
 import org.jackhuang.hmcl.util.Lang;
 import org.jackhuang.hmcl.util.ResourceNotFoundError;
 import org.jackhuang.hmcl.util.io.FileUtils;
 import org.jackhuang.hmcl.util.io.NetworkUtils;
-import org.jackhuang.hmcl.util.javafx.ExtendedProperties;
 import org.jackhuang.hmcl.util.javafx.SafeStringConverter;
 import org.jackhuang.hmcl.util.platform.OperatingSystem;
 import org.jackhuang.hmcl.util.platform.SystemUtils;
 import org.jetbrains.annotations.Nullable;
+import org.jsoup.Jsoup;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import org.w3c.dom.NodeList;
@@ -107,10 +108,7 @@ import java.nio.file.Path;
 import java.nio.file.PathMatcher;
 import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
-import java.util.function.Consumer;
-import java.util.function.Function;
-import java.util.function.Predicate;
-import java.util.function.ToIntFunction;
+import java.util.function.*;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
@@ -467,25 +465,31 @@ public final class FXUtils {
     private static final Duration TOOLTIP_SLOW_SHOW_DELAY = Duration.millis(500);
     private static final Duration TOOLTIP_SHOW_DURATION = Duration.millis(5000);
 
+    @FXThread
     public static void installTooltip(Node node, Duration showDelay, Duration showDuration, Duration hideDelay, Tooltip tooltip) {
+        checkFxUserThread();
         tooltip.setShowDelay(showDelay);
         tooltip.setShowDuration(showDuration);
         tooltip.setHideDelay(hideDelay);
         Tooltip.install(node, tooltip);
     }
 
+    @FXThread
     public static void installFastTooltip(Node node, Tooltip tooltip) {
-        runInFX(() -> installTooltip(node, TOOLTIP_FAST_SHOW_DELAY, TOOLTIP_SHOW_DURATION, Duration.ZERO, tooltip));
+        installTooltip(node, TOOLTIP_FAST_SHOW_DELAY, TOOLTIP_SHOW_DURATION, Duration.ZERO, tooltip);
     }
 
+    @FXThread
     public static void installFastTooltip(Node node, String tooltip) {
         installFastTooltip(node, new Tooltip(tooltip));
     }
 
+    @FXThread
     public static void installSlowTooltip(Node node, Tooltip tooltip) {
-        runInFX(() -> installTooltip(node, TOOLTIP_SLOW_SHOW_DELAY, TOOLTIP_SHOW_DURATION, Duration.ZERO, tooltip));
+        installTooltip(node, TOOLTIP_SLOW_SHOW_DELAY, TOOLTIP_SHOW_DURATION, Duration.ZERO, tooltip);
     }
 
+    @FXThread
     public static void installSlowTooltip(Node node, String tooltip) {
         installSlowTooltip(node, new Tooltip(tooltip));
     }
@@ -610,21 +614,21 @@ public final class FXUtils {
         if (link == null)
             return;
 
-        String uri = NetworkUtils.encodeLocation(link);
+        String url = NetworkUtils.encodeLocation(link);
         thread(() -> {
             try {
                 if (OperatingSystem.CURRENT_OS == OperatingSystem.WINDOWS) {
-                    Runtime.getRuntime().exec(new String[]{"rundll32.exe", "url.dll,FileProtocolHandler", uri});
+                    Runtime.getRuntime().exec(new String[]{"rundll32.exe", "url.dll,FileProtocolHandler", url});
                     return;
                 } else if (OperatingSystem.CURRENT_OS == OperatingSystem.MACOS) {
-                    Runtime.getRuntime().exec(new String[]{"open", uri});
+                    Runtime.getRuntime().exec(new String[]{"open", url});
                     return;
                 } else {
                     for (String browser : linuxBrowsers) {
                         Path path = SystemUtils.which(browser);
                         if (path != null) {
                             try {
-                                Runtime.getRuntime().exec(new String[]{path.toString(), uri});
+                                Runtime.getRuntime().exec(new String[]{path.toString(), url});
                                 return;
                             } catch (Throwable ignored) {
                             }
@@ -637,7 +641,7 @@ public final class FXUtils {
             }
 
             try {
-                java.awt.Desktop.getDesktop().browse(new URI(uri));
+                java.awt.Desktop.getDesktop().browse(new URI(url));
             } catch (Throwable e) {
                 LOG.warning("Failed to open link: " + link, e);
             }
@@ -725,116 +729,6 @@ public final class FXUtils {
         }
     }
 
-    private static final class EnumBidirectionalBinding<E extends Enum<E>> implements InvalidationListener, WeakListener {
-        private final WeakReference<JFXComboBox<E>> comboBoxRef;
-        private final WeakReference<Property<E>> propertyRef;
-        private final int hashCode;
-
-        private boolean updating = false;
-
-        private EnumBidirectionalBinding(JFXComboBox<E> comboBox, Property<E> property) {
-            this.comboBoxRef = new WeakReference<>(comboBox);
-            this.propertyRef = new WeakReference<>(property);
-            this.hashCode = System.identityHashCode(comboBox) ^ System.identityHashCode(property);
-        }
-
-        @Override
-        public void invalidated(Observable sourceProperty) {
-            if (!updating) {
-                final JFXComboBox<E> comboBox = comboBoxRef.get();
-                final Property<E> property = propertyRef.get();
-
-                if (comboBox == null || property == null) {
-                    if (comboBox != null) {
-                        comboBox.getSelectionModel().selectedItemProperty().removeListener(this);
-                    }
-
-                    if (property != null) {
-                        property.removeListener(this);
-                    }
-                } else {
-                    updating = true;
-                    try {
-                        if (property == sourceProperty) {
-                            E newValue = property.getValue();
-                            comboBox.getSelectionModel().select(newValue);
-                        } else {
-                            E newValue = comboBox.getSelectionModel().getSelectedItem();
-                            property.setValue(newValue);
-                        }
-                    } finally {
-                        updating = false;
-                    }
-                }
-            }
-        }
-
-        @Override
-        public boolean wasGarbageCollected() {
-            return comboBoxRef.get() == null || propertyRef.get() == null;
-        }
-
-        @Override
-        public int hashCode() {
-            return hashCode;
-        }
-
-        @Override
-        public boolean equals(Object o) {
-            if (this == o)
-                return true;
-            if (!(o instanceof EnumBidirectionalBinding))
-                return false;
-
-            EnumBidirectionalBinding<?> that = (EnumBidirectionalBinding<?>) o;
-
-            final JFXComboBox<E> comboBox = this.comboBoxRef.get();
-            final Property<E> property = this.propertyRef.get();
-
-            final JFXComboBox<?> thatComboBox = that.comboBoxRef.get();
-            final Property<?> thatProperty = that.propertyRef.get();
-
-            if (comboBox == null || property == null || thatComboBox == null || thatProperty == null)
-                return false;
-
-            return comboBox == thatComboBox && property == thatProperty;
-        }
-    }
-
-    /**
-     * Bind combo box selection with given enum property bidirectionally.
-     * You should <b>only and always</b> use {@code bindEnum} as well as {@code unbindEnum} at the same time.
-     *
-     * @param comboBox the combo box being bound with {@code property}.
-     * @param property the property being bound with {@code combo box}.
-     * @see #unbindEnum(JFXComboBox, Property)
-     * @see ExtendedProperties#selectedItemPropertyFor(ComboBox)
-     */
-    public static <T extends Enum<T>> void bindEnum(JFXComboBox<T> comboBox, Property<T> property) {
-        EnumBidirectionalBinding<T> binding = new EnumBidirectionalBinding<>(comboBox, property);
-
-        comboBox.getSelectionModel().selectedItemProperty().removeListener(binding);
-        property.removeListener(binding);
-
-        comboBox.getSelectionModel().select(property.getValue());
-        comboBox.getSelectionModel().selectedItemProperty().addListener(binding);
-        property.addListener(binding);
-    }
-
-    /**
-     * Unbind combo box selection with given enum property bidirectionally.
-     * You should <b>only and always</b> use {@code bindEnum} as well as {@code unbindEnum} at the same time.
-     *
-     * @param comboBox the combo box being bound with the property which can be inferred by {@code bindEnum}.
-     * @see #bindEnum(JFXComboBox, Property)
-     * @see ExtendedProperties#selectedItemPropertyFor(ComboBox)
-     */
-    public static <T extends Enum<T>> void unbindEnum(JFXComboBox<T> comboBox, Property<T> property) {
-        EnumBidirectionalBinding<T> binding = new EnumBidirectionalBinding<>(comboBox, property);
-        comboBox.getSelectionModel().selectedItemProperty().removeListener(binding);
-        property.removeListener(binding);
-    }
-
     private static final class PaintBidirectionalBinding implements InvalidationListener, WeakListener {
         private final WeakReference<ColorPicker> colorPickerRef;
         private final WeakReference<Property<Paint>> propertyRef;
@@ -929,146 +823,6 @@ public final class FXUtils {
         property.addListener(binding);
     }
 
-    private static final class WindowsSizeBidirectionalBinding implements InvalidationListener, WeakListener {
-        private final WeakReference<JFXComboBox<String>> comboBoxRef;
-        private final WeakReference<IntegerProperty> widthPropertyRef;
-        private final WeakReference<IntegerProperty> heightPropertyRef;
-
-        private final int hashCode;
-
-        private boolean updating = false;
-
-        private WindowsSizeBidirectionalBinding(JFXComboBox<String> comboBox,
-                                                IntegerProperty widthProperty,
-                                                IntegerProperty heightProperty) {
-            this.comboBoxRef = new WeakReference<>(comboBox);
-            this.widthPropertyRef = new WeakReference<>(widthProperty);
-            this.heightPropertyRef = new WeakReference<>(heightProperty);
-            this.hashCode = System.identityHashCode(comboBox)
-                    ^ System.identityHashCode(widthProperty)
-                    ^ System.identityHashCode(heightProperty);
-        }
-
-        @Override
-        public void invalidated(Observable observable) {
-            if (!updating) {
-                var comboBox = this.comboBoxRef.get();
-                var widthProperty = this.widthPropertyRef.get();
-                var heightProperty = this.heightPropertyRef.get();
-
-                if (comboBox == null || widthProperty == null || heightProperty == null) {
-                    if (comboBox != null) {
-                        comboBox.focusedProperty().removeListener(this);
-                        comboBox.sceneProperty().removeListener(this);
-                    }
-                    if (widthProperty != null)
-                        widthProperty.removeListener(this);
-                    if (heightProperty != null)
-                        heightProperty.removeListener(this);
-                } else {
-                    updating = true;
-                    try {
-                        int width = widthProperty.get();
-                        int height = heightProperty.get();
-
-                        if (observable instanceof ReadOnlyProperty<?>
-                                && ((ReadOnlyProperty<?>) observable).getBean() == comboBox) {
-                            String value = comboBox.valueProperty().get();
-                            if (value == null)
-                                value = "";
-                            int idx = value.indexOf('x');
-                            if (idx < 0)
-                                idx = value.indexOf('*');
-
-                            if (idx < 0) {
-                                LOG.warning("Bad window size: " + value);
-                                comboBox.setValue(width + "x" + height);
-                                return;
-                            }
-
-                            String widthStr = value.substring(0, idx).trim();
-                            String heightStr = value.substring(idx + 1).trim();
-
-                            int newWidth;
-                            int newHeight;
-                            try {
-                                newWidth = Integer.parseInt(widthStr);
-                                newHeight = Integer.parseInt(heightStr);
-                            } catch (NumberFormatException e) {
-                                LOG.warning("Bad window size: " + value);
-                                comboBox.setValue(width + "x" + height);
-                                return;
-                            }
-
-                            widthProperty.set(newWidth);
-                            heightProperty.set(newHeight);
-                        } else {
-                            comboBox.setValue(width + "x" + height);
-                        }
-                    } finally {
-                        updating = false;
-                    }
-                }
-            }
-        }
-
-        @Override
-        public boolean wasGarbageCollected() {
-            return this.comboBoxRef.get() == null
-                    || this.widthPropertyRef.get() == null
-                    || this.heightPropertyRef.get() == null;
-        }
-
-        @Override
-        public int hashCode() {
-            return hashCode;
-        }
-
-        @Override
-        public boolean equals(Object obj) {
-            if (this == obj)
-                return true;
-            if (!(obj instanceof WindowsSizeBidirectionalBinding))
-                return false;
-
-            var that = (WindowsSizeBidirectionalBinding) obj;
-
-            var comboBox = this.comboBoxRef.get();
-            var widthProperty = this.widthPropertyRef.get();
-            var heightProperty = this.heightPropertyRef.get();
-
-            var thatComboBox = that.comboBoxRef.get();
-            var thatWidthProperty = that.widthPropertyRef.get();
-            var thatHeightProperty = that.heightPropertyRef.get();
-
-            if (comboBox == null || widthProperty == null || heightProperty == null
-                    || thatComboBox == null || thatWidthProperty == null || thatHeightProperty == null) {
-                return false;
-            }
-
-            return comboBox == thatComboBox
-                    && widthProperty == thatWidthProperty
-                    && heightProperty == thatHeightProperty;
-        }
-    }
-
-    public static void bindWindowsSize(JFXComboBox<String> comboBox, IntegerProperty widthProperty, IntegerProperty heightProperty) {
-        comboBox.setValue(widthProperty.get() + "x" + heightProperty.get());
-        var binding = new WindowsSizeBidirectionalBinding(comboBox, widthProperty, heightProperty);
-        comboBox.focusedProperty().addListener(binding);
-        comboBox.sceneProperty().addListener(binding);
-        widthProperty.addListener(binding);
-        heightProperty.addListener(binding);
-    }
-
-    public static void unbindWindowsSize(JFXComboBox<String> comboBox, IntegerProperty widthProperty, IntegerProperty heightProperty) {
-        var binding = new WindowsSizeBidirectionalBinding(comboBox, widthProperty, heightProperty);
-        comboBox.focusedProperty().removeListener(binding);
-        comboBox.sceneProperty().removeListener(binding);
-        widthProperty.removeListener(binding);
-        heightProperty.removeListener(binding);
-    }
-
     public static void bindAllEnabled(BooleanProperty allEnabled, BooleanProperty... children) {
         int itemCount = children.length;
         int childSelectedCount = 0;
@@ -1248,8 +1002,9 @@ public final class FXUtils {
                 .setSignificance(Task.TaskSignificance.MINOR);
     }
 
-    public static Task<Image> getRemoteImageTask(List<URI> uris, int requestedWidth, int requestedHeight, boolean preserveRatio, boolean smooth) {
-        return new CacheFileTask(uris)
+    /// Creates a task that caches an image from HTTP(S) candidates and loads it with the requested sizing options.
+    public static Task<Image> getRemoteImageTask(DownloadCandidates candidates, int requestedWidth, int requestedHeight, boolean preserveRatio, boolean smooth) {
+        return new CacheFileTask(candidates)
                 .setSignificance(Task.TaskSignificance.MINOR)
                 .thenApplyAsync(file -> loadImage(file, requestedWidth, requestedHeight, preserveRatio, smooth))
                 .setSignificance(Task.TaskSignificance.MINOR);
@@ -1390,20 +1145,6 @@ public final class FXUtils {
         };
     }
 
-    public static <T> Callback<ListView<T>, ListCell<T>> jfxListCellFactory(Function<T, Node> graphicBuilder) {
-        return view -> new JFXListCell<T>() {
-            @Override
-            public void updateItem(T item, boolean empty) {
-                super.updateItem(item, empty);
-
-                if (!empty) {
-                    setContentDisplay(ContentDisplay.GRAPHIC_ONLY);
-                    setGraphic(graphicBuilder.apply(item));
-                }
-            }
-        };
-    }
-
     public static ColumnConstraints getColumnFillingWidth() {
         ColumnConstraints constraint = new ColumnConstraints();
         constraint.setFillWidth(true);
@@ -1456,6 +1197,18 @@ public final class FXUtils {
         });
     }
 
+    public static void addMacOSCloseWindowHandler(Window window, @Nullable Supplier<Boolean> restriction) {
+        window.addEventHandler(KeyEvent.KEY_PRESSED, event -> {
+            if (OperatingSystem.CURRENT_OS == OperatingSystem.MACOS
+                    && event.isMetaDown()
+                    && event.getCode() == KeyCode.W
+                    && (restriction == null || restriction.get())) {
+                window.fireEvent(new WindowEvent(window, WindowEvent.WINDOW_CLOSE_REQUEST));
+                event.consume();
+            }
+        });
+    }
+
     public static <N extends Parent> N prepareNode(N node) {
         Scene dummyScene = new Scene(node);
         StyleSheets.init(dummyScene);
@@ -1713,4 +1466,62 @@ public final class FXUtils {
             e.consume();
         });
     }
+
+    public static TextFlow renderAddonChangelog(String changelogHtml, String baseUri) {
+        var textFlow = new HTMLRenderer(Controllers::openUriOrCopy).appendNode(Jsoup.parse(changelogHtml, baseUri)).mergeLineBreaks().render();
+        textFlow.getStyleClass().add("addon-changelog");
+        return textFlow;
+    }
+
+    /// Be cautious when dealing with large amounts of data
+    public static <S> TableView<S> newAutoHeightTable(ObservableList<S> items) {
+        return new AutoHeightTableView<>(items);
+    }
+
+    private static final class AutoHeightTableView<S> extends TableView<S> {
+
+        public AutoHeightTableView() {
+            super();
+        }
+
+        public AutoHeightTableView(ObservableList<S> items) {
+            super(items);
+        }
+
+        @Override
+        protected Skin<?> createDefaultSkin() {
+            return new AutoSizeSkin<>(this);
+        }
+
+        private static final class AutoSizeSkin<S> extends TableViewSkin<S> {
+
+            private final VirtualFlow<TableRow<S>> flow;
+
+            public AutoSizeSkin(TableView<S> control) {
+                super(control);
+                this.flow = getVirtualFlow();
+            }
+
+            @Override
+            protected double computePrefHeight(double width, double topInset, double rightInset, double bottomInset, double leftInset) {
+                double fixedCellSize = getSkinnable().getFixedCellSize();
+                double w = width - rightInset - leftInset;
+                int itemCount = getItemCount();
+                double headerHeight = getTableHeaderRow().prefHeight(w);
+
+                double prefHeight = topInset + bottomInset + headerHeight;
+                if (fixedCellSize > 0 || itemCount == 0) return prefHeight + fixedCellSize * itemCount;
+                int i = 0;
+                TableRow<S> r;
+                while (i < itemCount && !(r = flow.getCell(i)).isEmpty() && r.getItem() != null) {
+                    prefHeight += r.prefHeight(w);
+                    i++;
+                }
+                return prefHeight;
+            }
+
+        }
+
+    }
+
 }

HMCL/src/main/java/org/jackhuang/hmcl/ui/GameCrashWindow.java

@@ -33,9 +33,7 @@ import javafx.scene.layout.VBox;
 import javafx.scene.text.Text;
 import javafx.scene.text.TextFlow;
 import javafx.stage.Stage;
-import kala.encdet.EncodingDetector;
 import org.jackhuang.hmcl.Metadata;
-import org.jackhuang.hmcl.download.LibraryAnalyzer;
 import org.jackhuang.hmcl.game.*;
 import org.jackhuang.hmcl.launch.ProcessListener;
 import org.jackhuang.hmcl.setting.StyleSheets;
@@ -45,10 +43,10 @@ import org.jackhuang.hmcl.theme.Themes;
 import org.jackhuang.hmcl.ui.construct.MessageDialogPane;
 import org.jackhuang.hmcl.ui.construct.SpinnerPane;
 import org.jackhuang.hmcl.ui.construct.TwoLineListItem;
-import org.jackhuang.hmcl.util.Lang;
 import org.jackhuang.hmcl.util.Log4jLevel;
 import org.jackhuang.hmcl.util.Pair;
 import org.jackhuang.hmcl.util.StringUtils;
+import org.jackhuang.hmcl.util.io.FileUtils;
 import org.jackhuang.hmcl.util.logging.Logger;
 import org.jackhuang.hmcl.util.platform.*;
 
@@ -73,17 +71,15 @@ import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 
 public class GameCrashWindow extends Stage {
-    private final Version version;
+    private final HMCLGameInstance gameInstance;
     private final String memory;
     private final String total_memory;
     private final String java;
-    private final LibraryAnalyzer analyzer;
     private final TextFlow reasonTextFlow = new TextFlow(new Text(i18n("game.crash.reason.unknown")));
     private final BooleanProperty loading = new SimpleBooleanProperty();
     private final TextFlow feedbackTextFlow = new TextFlow();
 
     private final ManagedProcess managedProcess;
-    private final DefaultGameRepository repository;
     private final ProcessListener.ExitType exitType;
     private final LaunchOptions launchOptions;
     private final View view;
@@ -91,16 +87,14 @@ public class GameCrashWindow extends Stage {
 
     private final List<Log> logs;
 
-    public GameCrashWindow(ManagedProcess managedProcess, ProcessListener.ExitType exitType, DefaultGameRepository repository, Version version, LaunchOptions launchOptions, List<Log> logs) {
+    public GameCrashWindow(ManagedProcess managedProcess, ProcessListener.ExitType exitType, HMCLGameInstance gameInstance, LaunchOptions launchOptions, List<Log> logs) {
         Themes.applyNativeDarkMode(this);
 
         this.managedProcess = managedProcess;
         this.exitType = exitType;
-        this.repository = repository;
-        this.version = version;
+        this.gameInstance = gameInstance;
         this.launchOptions = launchOptions;
         this.logs = logs;
-        this.analyzer = LibraryAnalyzer.analyze(version, repository.getGameVersion(version).orElse(null));
 
         memory = Optional.ofNullable(launchOptions.getMaxMemory()).map(i -> i + " " + i18n("settings.memory.unit.mib")).orElse("-");
 
@@ -120,6 +114,8 @@ public class GameCrashWindow extends Stage {
         setTitle(i18n("game.crash.title"));
         FXUtils.setIcon(this);
 
+        FXUtils.addMacOSCloseWindowHandler(this, null);
+
         analyzeCrashReport();
     }
 
@@ -142,14 +138,15 @@ public class GameCrashWindow extends Stage {
 
             return pair(CrashReportAnalyzer.analyze(rawLog), crashReport != null ? CrashReportAnalyzer.findKeywordsFromCrashReport(crashReport) : new HashSet<>());
         }), Task.supplyAsync(() -> {
-            Path latestLog = repository.getRunDirectory(version.getId()).resolve("logs/latest.log");
+            Path runDirectory = gameInstance.getRunDirectory();
+            Path latestLog = runDirectory.resolve("logs/latest.log");
             if (!Files.isReadable(latestLog)) {
                 return pair(new HashSet<CrashReportAnalyzer.Result>(), new HashSet<String>());
             }
 
             String log;
             try {
-                log = EncodingDetector.MODERN_WEB.readString(latestLog);
+                log = FileUtils.readTextMaybeNativeEncoding(latestLog);
             } catch (IOException e) {
                 LOG.warning("Failed to read logs/latest.log", e);
                 return pair(new HashSet<CrashReportAnalyzer.Result>(), new HashSet<String>());
@@ -291,7 +288,7 @@ public class GameCrashWindow extends Stage {
                                 }
                             });
 
-                    return LogExporter.exportLogs(logFile, repository, launchOptions.getVersionName(), logs,
+                    return LogExporter.exportLogs(logFile, gameInstance, launchOptions, logs,
                             new CommandBuilder().addAll(managedProcess.getCommands()).toString(),
                             path -> {
                                 try {
@@ -342,10 +339,10 @@ public class GameCrashWindow extends Stage {
                 launcher.setTitle(i18n("launcher"));
                 launcher.setSubtitle(Metadata.VERSION);
 
-                TwoLineListItem version = new TwoLineListItem();
-                version.getStyleClass().setAll("two-line-item-second-large");
-                version.setTitle(i18n("game.version"));
-                version.setSubtitle(GameCrashWindow.this.version.getId());
+                TwoLineListItem instance = new TwoLineListItem();
+                instance.getStyleClass().setAll("two-line-item-second-large");
+                instance.setTitle(i18n("game.version"));
+                instance.setSubtitle(GameCrashWindow.this.gameInstance.getId().toString());
 
                 TwoLineListItem total_memory = new TwoLineListItem();
                 total_memory.getStyleClass().setAll("two-line-item-second-large");
@@ -365,14 +362,14 @@ public class GameCrashWindow extends Stage {
                 TwoLineListItem os = new TwoLineListItem();
                 os.getStyleClass().setAll("two-line-item-second-large");
                 os.setTitle(i18n("system.operating_system"));
-                os.setSubtitle(Lang.requireNonNullElse(OperatingSystem.OS_RELEASE_NAME, OperatingSystem.SYSTEM_NAME));
+                os.setSubtitle(Objects.requireNonNullElse(OperatingSystem.OS_RELEASE_NAME, OperatingSystem.SYSTEM_NAME));
 
                 TwoLineListItem arch = new TwoLineListItem();
                 arch.getStyleClass().setAll("two-line-item-second-large");
                 arch.setTitle(i18n("system.architecture"));
                 arch.setSubtitle(Architecture.SYSTEM_ARCH.getDisplayName());
 
-                infoPane.getChildren().setAll(launcher, version, total_memory, memory, java, os, arch);
+                infoPane.getChildren().setAll(launcher, instance, total_memory, memory, java, os, arch);
             }
 
             HBox moddedPane = new HBox(8);
@@ -380,15 +377,13 @@ public class GameCrashWindow extends Stage {
                 moddedPane.setPadding(new Insets(8));
                 moddedPane.setAlignment(Pos.CENTER_LEFT);
 
-                for (LibraryAnalyzer.LibraryType type : LibraryAnalyzer.LibraryType.values()) {
-                    if (!type.getPatchId().isEmpty()) {
-                        analyzer.getVersion(type).ifPresent(ver -> {
-                            TwoLineListItem item = new TwoLineListItem();
-                            item.getStyleClass().setAll("two-line-item-second-large");
-                            item.setTitle(i18n("install.installer." + type.getPatchId()));
-                            item.setSubtitle(ver);
-                            moddedPane.getChildren().add(item);
-                        });
+                for (GameComponentAnalyzer.Mark mark : gameInstance.getAnalyzer()) {
+                    if (mark.version() != null) {
+                        TwoLineListItem item = new TwoLineListItem();
+                        item.getStyleClass().setAll("two-line-item-second-large");
+                        item.setTitle(i18n("install.installer." + mark.componentType().getPatchId()));
+                        item.setSubtitle(mark.version());
+                        moddedPane.getChildren().add(item);
                     }
                 }
             }

HMCL/src/main/java/org/jackhuang/hmcl/ui/HTMLRenderer.java

@@ -17,27 +17,41 @@
  */
 package org.jackhuang.hmcl.ui;
 
+import javafx.beans.InvalidationListener;
+import javafx.beans.property.SimpleObjectProperty;
+import javafx.collections.FXCollections;
+import javafx.geometry.Pos;
 import javafx.scene.Cursor;
-import javafx.scene.image.Image;
+import javafx.scene.control.Separator;
+import javafx.scene.control.TableCell;
+import javafx.scene.control.TableColumn;
+import javafx.scene.control.TableView;
 import javafx.scene.image.ImageView;
+import javafx.scene.layout.Pane;
+import javafx.scene.layout.StackPane;
+import javafx.scene.layout.VBox;
 import javafx.scene.text.Text;
 import javafx.scene.text.TextFlow;
+import org.jackhuang.hmcl.util.Lang;
 import org.jackhuang.hmcl.util.StringUtils;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+import org.jsoup.nodes.Element;
 import org.jsoup.nodes.Node;
 import org.jsoup.nodes.TextNode;
 
 import java.net.URI;
-import java.util.ArrayList;
-import java.util.List;
+import java.util.*;
 import java.util.function.Consumer;
 
+import static org.jackhuang.hmcl.setting.SettingsManager.settings;
 import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 
 /**
  * @author Glavo
  */
 public final class HTMLRenderer {
-    private static final String INDENT = "  ";
+
     private static URI resolveLink(Node linkNode) {
         String href = linkNode.absUrl("href");
         if (href.isEmpty())
@@ -50,6 +64,42 @@ public final class HTMLRenderer {
         }
     }
 
+    /// @see org.jsoup.internal.StringUtil#isWhitespace(int)
+    public static boolean isWhitespace(int c) {
+        return c == ' ' || c == '\t' || c == '\n' || c == '\f' || c == '\r';
+    }
+
+    /// @see org.jsoup.internal.StringUtil#isInvisibleChar(int)
+    public static boolean isInvisibleChar(int c) {
+        return c == 8203 || c == 173; // zero width sp, soft hyphen
+        // previously also included zw non join, zw join - but removing those breaks semantic meaning of text
+    }
+
+    /// @see org.jsoup.internal.StringUtil#normaliseWhitespace(String)
+    /// @see org.jsoup.internal.StringUtil#isActuallyWhitespace(int)
+    public static String normaliseWhitespace(String str) {
+        var accum = new StringBuilder();
+        boolean lastWasWhite = false;
+        int len = str.length();
+        int i = 0;
+        while (i < len) {
+            int c = str.codePointAt(i);
+            if (isWhitespace(c)) { // Ignore &nbsp;
+                if (lastWasWhite) {
+                    i += Character.charCount(c);
+                    continue;
+                }
+                accum.append(' ');
+                lastWasWhite = true;
+            } else if (!isInvisibleChar(c)) {
+                accum.appendCodePoint(c);
+                lastWasWhite = false;
+            }
+            i += Character.charCount(c);
+        }
+        return accum.toString();
+    }
+
     private final List<javafx.scene.Node> children = new ArrayList<>();
     private final List<Node> stack = new ArrayList<>();
 
@@ -58,12 +108,17 @@ public final class HTMLRenderer {
     private boolean underline;
     private boolean strike;
     private boolean highlight;
-    private int indentLevel;
+    private boolean preformatted;
+    private boolean code;
+    private int listDepth;
     private String headerLevel;
     private Node hyperlink;
+    private String fxStyle;
 
     private final Consumer<URI> onClickHyperlink;
 
+    private boolean rendered;
+
     public HTMLRenderer(Consumer<URI> onClickHyperlink) {
         this.onClickHyperlink = onClickHyperlink;
     }
@@ -74,42 +129,32 @@ public final class HTMLRenderer {
         underline = false;
         strike = false;
         highlight = false;
+        preformatted = false;
+        code = false;
+        listDepth = 0;
         headerLevel = null;
         hyperlink = null;
+        fxStyle = null;
 
+        var declarations = new SimpleCssDeclarations();
         for (Node node : stack) {
             String nodeName = node.nodeName();
             switch (nodeName) {
-                case "b":
-                case "strong":
-                    bold = true;
-                    break;
-                case "i":
-                case "em":
-                    italic = true;
-                    break;
-                case "ins":
-                    underline = true;
-                    break;
-                case "del":
-                    strike = true;
-                    break;
-                case "mark":
-                    highlight = true;
-                    break;
-                case "a":
-                    hyperlink = node;
-                    break;
-                case "h1":
-                case "h2":
-                case "h3":
-                case "h4":
-                case "h5":
-                case "h6":
-                    headerLevel = nodeName;
-                    break;
+                case "b", "strong" -> bold = true;
+                case "i", "em" -> italic = true;
+                case "ins" -> underline = true;
+                case "del" -> strike = true;
+                case "mark" -> highlight = true;
+                case "pre" -> preformatted = true;
+                case "code" -> code = true;
+                case "a" -> hyperlink = node;
+                case "h1", "h2", "h3", "h4", "h5", "h6" -> headerLevel = nodeName;
+                case "li" -> listDepth++;
             }
+
+            declarations.add(node.attr("style"));
         }
+        fxStyle = declarations.asString();
     }
 
     private void pushNode(Node node) {
@@ -123,6 +168,14 @@ public final class HTMLRenderer {
     }
 
     private void applyStyle(Text text) {
+        if (code) {
+            text.getStyleClass().add("html-code");
+            text.setStyle("-fx-font-family: \"%s\";".formatted(Objects.requireNonNullElse(settings().logFontFamilyProperty().get(), FXUtils.DEFAULT_MONOSPACE_FONT)));
+            return;
+        }
+
+        var styleBuilder = new StringBuilder();
+
         if (hyperlink != null) {
             URI target = resolveLink(hyperlink);
             if (target != null) {
@@ -146,12 +199,22 @@ public final class HTMLRenderer {
 
         if (headerLevel != null)
             text.getStyleClass().add("html-" + headerLevel);
+
+        if (fxStyle != null)
+            styleBuilder.append(fxStyle);
+        text.setStyle(styleBuilder.toString());
     }
 
     private void appendText(String text) {
         Text textNode = new Text(text);
         applyStyle(textNode);
-        children.add(textNode);
+        if (code) {
+            var codeFlow = new CodeFlow(textNode);
+            codeFlow.getStyleClass().add("html-code-block");
+            children.add(codeFlow);
+        } else {
+            children.add(textNode);
+        }
     }
 
     private void appendAutoLineBreak(String text) {
@@ -185,20 +248,22 @@ public final class HTMLRenderer {
             }
 
             try {
-                Image image = FXUtils.getRemoteImageTask(src, width, height, true, true)
-                        .run();
-                if (image == null)
-                    throw new AssertionError("Image loading task returned null");
+                ImageView imageView = new ImageView();
+
+                imageView.imageProperty().bind(FXUtils.newRemoteImage(src, width, height, true, true));
+                imageView.setPreserveRatio(true);
+
+                ImagePane imagePane = new ImagePane(imageView, alt);
 
-                ImageView imageView = new ImageView(image);
                 if (hyperlink != null) {
                     URI target = resolveLink(hyperlink);
                     if (target != null) {
-                        FXUtils.onClicked(imageView, () -> onClickHyperlink.accept(target));
-                        imageView.setCursor(Cursor.HAND);
+                        FXUtils.onClicked(imagePane, () -> onClickHyperlink.accept(target));
+                        imagePane.setCursor(Cursor.HAND);
                     }
                 }
-                children.add(imageView);
+
+                children.add(imagePane);
                 return;
             } catch (Throwable e) {
                 LOG.warning("Failed to load image: " + src, e);
@@ -209,59 +274,203 @@ public final class HTMLRenderer {
             appendText(alt);
     }
 
-    public void appendNode(Node node) {
-        if (node instanceof TextNode) {
-            appendText(((TextNode) node).text());
+    private void appendTable(Node table) {
+        var childElements = ((Element) table).children();
+        List<Element> captions = new ArrayList<>();
+
+        List<Element> head = new ArrayList<>();
+        List<List<Element>> body = new ArrayList<>();
+        List<Element> foot = new ArrayList<>();
+
+        boolean hasHead = false;
+        boolean hasBody = childElements.stream().map(Element::nodeName).anyMatch("tbody"::equals);
+        boolean hasFoot = false;
+        int columnCount = 0;
+        for (Element child : childElements) {
+            switch (child.nodeName()) {
+                case "caption" -> captions.add(child);
+                case "thead" -> {
+                    if (hasHead) continue;
+                    hasHead = true;
+                    for (Element e : child.children()) {
+                        if (e.nameIs("tr")) {
+                            head.clear();
+                            head.addAll(
+                                    e.children().stream()
+                                            .filter(n -> n.nameIs("th") || n.nameIs("td"))
+                                            .toList()
+                            );
+                            break;
+                        }
+                        if (e.nameIs("th") || e.nameIs("td")) {
+                            head.add(e);
+                        }
+                    }
+                    columnCount = Math.max(columnCount, head.size());
+                }
+                case "tbody" -> {
+                    var rows = child.children().stream()
+                            .filter(e -> e.nameIs("tr"))
+                            .map(e ->
+                                    e.children().stream().filter(n -> n.nameIs("th") || n.nameIs("td")).toList())
+                            .filter(row -> !row.isEmpty())
+                            .toList();
+                    body.addAll(rows);
+                    columnCount = Math.max(columnCount, rows.stream().mapToInt(List::size).max().orElse(0));
+                }
+                case "tfoot" -> {
+                    if (hasFoot) continue;
+                    hasFoot = true;
+                    for (Element e : child.children()) {
+                        if (e.nameIs("tr")) {
+                            foot.clear();
+                            foot.addAll(
+                                    e.children().stream()
+                                            .filter(n -> n.nameIs("th") || n.nameIs("td"))
+                                            .toList()
+                            );
+                            break;
+                        }
+                        if (e.nameIs("th") || e.nameIs("td")) {
+                            foot.add(e);
+                        }
+                    }
+                    columnCount = Math.max(columnCount, foot.size());
+                }
+                case "tr" -> {
+                    if (hasBody) continue;
+                    List<Element> row = child.children().stream()
+                            .filter(n -> n.nameIs("th") || n.nameIs("td"))
+                            .toList();
+                    if (!row.isEmpty()) {
+                        body.add(row);
+                        columnCount = Math.max(columnCount, row.size());
+                    }
+                }
+            }
+        }
+
+        head = Lang.copyWithSize(head, columnCount, null);
+
+        List<List<Element>> rows = new ArrayList<>(hasFoot ? body.size() + 1 : body.size());
+        for (List<Element> row : body)
+            rows.add(Lang.copyWithSize(row, columnCount, null));
+        if (hasFoot)
+            rows.add(Lang.copyWithSize(foot, columnCount, null));
+
+        TableView<List<Element>> tableView = FXUtils.newAutoHeightTable(FXCollections.observableList(rows));
+        tableView.setColumnResizePolicy(TableView.CONSTRAINED_RESIZE_POLICY);
+        for (int i = 0; i < columnCount; i++) {
+            int finalI = i;
+            TableColumn<List<Element>, Element> c = new TableColumn<>();
+            Element e = head.get(i);
+            if (e != null) {
+                var box = new VBox(new HTMLRenderer(onClickHyperlink).appendNode(e).mergeLineBreaks().render());
+                box.setAlignment(Pos.CENTER_LEFT);
+                c.setGraphic(box);
+            }
+            c.setCellFactory(param -> new TableCell<>() {
+                @Override
+                protected void updateItem(Element item, boolean empty) {
+                    if (item == getItem()) return;
+                    super.updateItem(item, empty);
+                    if (item == null) {
+                        setGraphic(null);
+                    } else {
+                        setGraphic(new Pane(new HTMLRenderer(onClickHyperlink).appendNode(item).mergeLineBreaks().render()));
+                    }
+                }
+            });
+            c.setCellValueFactory(param -> new SimpleObjectProperty<>(param.getValue().get(finalI)));
+            tableView.getColumns().add(c);
+        }
+
+        for (Element caption : captions) {
+            appendAutoLineBreak("\n\n");
+            appendChildren(caption);
+            appendAutoLineBreak("\n");
+        }
+
+        children.add(tableView);
+    }
+
+    private void appendOrderedList(Node node) {
+        pushNode(node);
+        int ordinal = StringUtils.toInt(node.attr("start")).orElse(1);
+        for (Node childNode : node.childNodes()) {
+            if (childNode.nameIs("li")) {
+                ordinal = StringUtils.toInt(childNode.attr("value")).orElse(ordinal);
+                appendAutoLineBreak("\n");
+                appendText(" " + "  ".repeat(listDepth) + ordinal++ + ". ");
+                appendChildren(childNode);
+                continue;
+            }
+            appendNode(childNode);
+        }
+        popNode();
+    }
+
+    private void appendChildren(Node node) {
+        if (node.childNodeSize() > 0) {
+            if (node.nameIs("table")) {
+                appendTable(node);
+            } else if (node.nameIs("ol")) {
+                appendOrderedList(node);
+            } else {
+                pushNode(node);
+                for (Node childNode : node.childNodes()) {
+                    appendNode(childNode);
+                }
+                popNode();
+            }
+        }
+    }
+
+    public HTMLRenderer appendNode(Node node) {
+        if (node instanceof TextNode n) {
+            appendText(preformatted ? n.getWholeText() : normaliseWhitespace(n.getWholeText()));
         }
 
         String name = node.nodeName();
         switch (name) {
-            case "img":
+            case "img" -> {
+                if (!children.isEmpty())
+                    appendAutoLineBreak("\n");
                 appendImage(node);
-                break;
-            case "li":
-                appendText("\n" + INDENT.repeat(indentLevel) + " \u2022 ");
-                break;
-            case "dt":
-                appendText(" ");
-                break;
-            case "p":
-            case "h1":
-            case "h2":
-            case "h3":
-            case "h4":
-            case "h5":
-            case "h6":
-            case "tr":
+                appendAutoLineBreak("\n");
+            }
+            case "li" -> {
+                appendAutoLineBreak("\n");
+                appendText(" " + "  ".repeat(listDepth) + "\u2022 ");
+            }
+            case "dt" -> appendText(" ");
+            case "p" -> {
+                var n = node.parent();
+                if (!children.isEmpty() && (n == null || !n.nameIs("li")))
+                    appendAutoLineBreak("\n\n");
+            }
+            case "h1", "h2", "h3", "h4", "h5", "h6" -> {
                 if (!children.isEmpty())
                     appendAutoLineBreak("\n\n");
-                break;
+            }
+            case "hr" -> {
+                appendAutoLineBreak("\n\n");
+                this.children.add(new Separator());
+            }
         }
 
-        if (node.childNodeSize() > 0) {
-            boolean isLiNode = "li".equals(name);
-            if (isLiNode) indentLevel++;
-            pushNode(node);
-            for (Node childNode : node.childNodes()) {
-                appendNode(childNode);
-            }
-            popNode();
-            if (isLiNode) indentLevel--;
-        }
+        appendChildren(node);
 
         switch (name) {
-            case "br":
-            case "dd":
-            case "p":
-            case "h1":
-            case "h2":
-            case "h3":
-            case "h4":
-            case "h5":
-            case "h6":
-                appendAutoLineBreak("\n");
-                break;
+            case "br", "dd", "h1", "h2", "h3", "h4", "h5", "h6" -> appendAutoLineBreak("\n");
+            case "p" -> {
+                var n = node.parent();
+                if (n == null || !n.nameIs("li"))
+                    appendAutoLineBreak("\n");
+            }
         }
+
+        return this;
     }
 
     private static boolean isSpacing(String text) {
@@ -276,7 +485,7 @@ public final class HTMLRenderer {
         return true;
     }
 
-    public void mergeLineBreaks() {
+    public HTMLRenderer mergeLineBreaks() {
         for (int i = 0; i < this.children.size(); i++) {
             javafx.scene.Node child = this.children.get(i);
             if (child instanceof AutoLineBreak) {
@@ -287,7 +496,7 @@ public final class HTMLRenderer {
 
                     if (otherChild instanceof AutoLineBreak) {
                         lastAutoLineBreak = j;
-                    } else if (otherChild instanceof Text && isSpacing(((Text) otherChild).getText())) {
+                    } else if (otherChild instanceof Text txt && isSpacing(txt.getText())) {
                         // do nothing
                     } else {
                         break;
@@ -303,12 +512,58 @@ public final class HTMLRenderer {
                 }
             }
         }
+
+        {
+            // Remove empty lines at the beginning
+            int size = children.size();
+            for (int i = 0; i < size; i++) {
+                var child = children.get(i);
+                if (child instanceof AutoLineBreak || child instanceof Text txt && isSpacing(txt.getText())) {
+                    // NO-OP
+                } else {
+                    this.children.subList(0, i).clear();
+                    break;
+                }
+            }
+        }
+        {
+            // Remove empty lines and spaces at the end
+            int size = children.size();
+            for (int i = size - 1; i > -1; i--) {
+                var child = children.get(i);
+                if (child instanceof AutoLineBreak || child instanceof Text txt && isSpacing(txt.getText())) {
+                    // NO-OP
+                } else {
+                    this.children.subList(i + 1, size).clear();
+                    break;
+                }
+            }
+        }
+
+        return this;
     }
 
     public TextFlow render() {
+        if (rendered) throw new IllegalStateException("Should not render twice");
+        rendered = true;
         TextFlow textFlow = new TextFlow();
         textFlow.getStyleClass().add("html");
         textFlow.getChildren().setAll(children);
+        for (javafx.scene.Node node : children) {
+            if (node instanceof ImagePane imgPane) {
+                ImageView img = imgPane.imageView;
+                InvalidationListener listener = __ -> img.setFitWidth(Math.min(textFlow.getWidth() * 0.9, img.getImage() == null ? 0D : img.getImage().getWidth()));
+                textFlow.widthProperty().addListener(listener);
+                img.imageProperty().addListener(listener);
+                listener.invalidated(null);
+            } else if (node instanceof TableView<?> table) {
+                table.prefWidthProperty().bind(textFlow.widthProperty().multiply(0.8));
+            } else if (node instanceof CodeFlow codeFlow) {
+                codeFlow.maxWidthProperty().bind(textFlow.widthProperty().multiply(0.8));
+            } else if (node instanceof Separator separator) {
+                separator.prefWidthProperty().bind(textFlow.widthProperty().subtract(24));
+            }
+        }
         return textFlow;
     }
 
@@ -317,4 +572,62 @@ public final class HTMLRenderer {
             super(text);
         }
     }
+
+    private static final class ImagePane extends StackPane {
+
+        public final ImageView imageView;
+
+        public ImagePane(ImageView imageView, @Nullable String alt) {
+            super();
+            this.imageView = imageView;
+
+            var txt = new Text(alt);
+            if (StringUtils.isNotBlank(alt)) getChildren().add(txt);
+            getChildren().add(imageView);
+            FXUtils.onChangeAndOperate(imageView.imageProperty(), img -> {
+                if (img != null) getChildren().remove(txt);
+            });
+        }
+
+    }
+
+    private static final class CodeFlow extends TextFlow {
+
+        public CodeFlow(Text text) {
+            super(text);
+        }
+
+    }
+
+    private static final class SimpleCssDeclarations {
+
+        @Unmodifiable
+        private static final Map<String, String> cssPropertyMapping = Map.of(
+                "color", "-fx-fill",
+                "font-size", "-fx-font-size"
+        );
+
+        private final Map<String, String> declarations = new HashMap<>();
+
+        public void add(String inlineCss) {
+            if (StringUtils.isBlank(inlineCss)) return;
+            Arrays.stream(inlineCss.split(";")).filter(StringUtils::isNotBlank).forEach(s -> {
+                String[] declaration = s.split(":", 2);
+                if (declaration.length != 2) return;
+                declaration[0] = declaration[0].trim();
+                declaration[1] = declaration[1].trim();
+                String mappedKey = cssPropertyMapping.get(declaration[0].toLowerCase(Locale.ROOT));
+                if (mappedKey != null) {
+                    declarations.put(mappedKey, declaration[1]);
+                } // Ignore unsupported fields
+            });
+        }
+
+        public String asString() {
+            StringBuilder sb = new StringBuilder();
+            declarations.forEach((property, value) -> sb.append(property).append(": ").append(value).append(";"));
+            return sb.toString();
+        }
+
+    }
 }

HMCL/src/main/java/org/jackhuang/hmcl/ui/InstallerItem.java

@@ -34,27 +34,23 @@ import javafx.scene.control.Skin;
 import javafx.scene.control.SkinBase;
 import javafx.scene.input.MouseButton;
 import javafx.scene.layout.*;
-import org.jackhuang.hmcl.download.LibraryAnalyzer;
-import org.jackhuang.hmcl.setting.VersionIconType;
+import org.jackhuang.hmcl.game.GameComponentType;
+import org.jackhuang.hmcl.setting.GameInstanceIconType;
 import org.jackhuang.hmcl.ui.construct.ImageContainer;
 import org.jackhuang.hmcl.ui.construct.RipplerContainer;
 import org.jackhuang.hmcl.util.i18n.I18n;
 import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
 
-import java.util.HashMap;
-import java.util.HashSet;
-import java.util.Map;
-import java.util.Set;
+import java.util.*;
 
-import static org.jackhuang.hmcl.download.LibraryAnalyzer.LibraryType.*;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 
 /**
  * @author huangyuhui
  */
 public class InstallerItem extends Control {
-    private final String id;
-    private final VersionIconType iconType;
+    private final GameComponentType type;
+    private final GameInstanceIconType iconType;
     private final Style style;
     private final ObjectProperty<InstalledState> versionProperty = new SimpleObjectProperty<>(this, "version", null);
     private final ObjectProperty<State> resolvedStateProperty = new SimpleObjectProperty<>(this, "resolvedState", InstallableState.INSTANCE);
@@ -83,30 +79,14 @@ public class InstallerItem extends Control {
         CARD,
     }
 
-    public InstallerItem(LibraryAnalyzer.LibraryType id, Style style) {
-        this(id.getPatchId(), style);
-    }
-
-    public InstallerItem(String id, Style style) {
-        this.id = id;
+    public InstallerItem(GameComponentType type, Style style) {
+        this.type = type;
         this.style = style;
-
-        iconType = switch (id) {
-            case "game" -> VersionIconType.GRASS;
-            case "fabric", "fabric-api" -> VersionIconType.FABRIC;
-            case "legacyfabric", "legacyfabric-api" -> VersionIconType.LEGACY_FABRIC;
-            case "forge" -> VersionIconType.FORGE;
-            case "cleanroom" -> VersionIconType.CLEANROOM;
-            case "liteloader" -> VersionIconType.CHICKEN;
-            case "optifine" -> VersionIconType.OPTIFINE;
-            case "quilt", "quilt-api" -> VersionIconType.QUILT;
-            case "neoforge" -> VersionIconType.NEO_FORGE;
-            default -> null;
-        };
+        this.iconType = GameInstanceIconType.getIconType(type);
     }
 
-    public String getLibraryId() {
-        return id;
+    public GameComponentType getComponentType() {
+        return type;
     }
 
     public ObjectProperty<InstalledState> versionProperty() {
@@ -149,7 +129,7 @@ public class InstallerItem extends Control {
     public final static class InstallerItemGroup {
         private final InstallerItem game;
 
-        private final InstallerItem[] libraries;
+        private final InstallerItem[] components;
 
         private Set<InstallerItem> getIncompatibles(Map<InstallerItem, Set<InstallerItem>> incompatibleMap, InstallerItem item) {
             return incompatibleMap.computeIfAbsent(item, it -> new HashSet<>());
@@ -175,19 +155,19 @@ public class InstallerItem extends Control {
             }
         }
 
-        public InstallerItemGroup(String gameVersion, Style style) {
-            game = new InstallerItem(MINECRAFT, style);
-            InstallerItem fabric = new InstallerItem(FABRIC, style);
-            InstallerItem fabricApi = new InstallerItem(FABRIC_API, style);
-            InstallerItem forge = new InstallerItem(FORGE, style);
-            InstallerItem cleanroom = new InstallerItem(CLEANROOM, style);
-            InstallerItem legacyfabric = new InstallerItem(LEGACY_FABRIC, style);
-            InstallerItem legacyfabricApi = new InstallerItem(LEGACY_FABRIC_API, style);
-            InstallerItem neoForge = new InstallerItem(NEO_FORGE, style);
-            InstallerItem liteLoader = new InstallerItem(LITELOADER, style);
-            InstallerItem optiFine = new InstallerItem(OPTIFINE, style);
-            InstallerItem quilt = new InstallerItem(QUILT, style);
-            InstallerItem quiltApi = new InstallerItem(QUILT_API, style);
+        public InstallerItemGroup(GameVersionNumber gameVersion, Style style) {
+            game = new InstallerItem(GameComponentType.GAME, style);
+            InstallerItem fabric = new InstallerItem(GameComponentType.FABRIC, style);
+            InstallerItem fabricApi = new InstallerItem(GameComponentType.FABRIC_API, style);
+            InstallerItem forge = new InstallerItem(GameComponentType.FORGE, style);
+            InstallerItem cleanroom = new InstallerItem(GameComponentType.CLEANROOM, style);
+            InstallerItem legacyfabric = new InstallerItem(GameComponentType.LEGACY_FABRIC, style);
+            InstallerItem legacyfabricApi = new InstallerItem(GameComponentType.LEGACY_FABRIC_API, style);
+            InstallerItem neoForge = new InstallerItem(GameComponentType.NEO_FORGE, style);
+            InstallerItem liteLoader = new InstallerItem(GameComponentType.LITELOADER, style);
+            InstallerItem optiFine = new InstallerItem(GameComponentType.OPTIFINE, style);
+            InstallerItem quilt = new InstallerItem(GameComponentType.QUILT, style);
+            InstallerItem quiltApi = new InstallerItem(GameComponentType.QUILT_API, style);
 
             Map<InstallerItem, Set<InstallerItem>> incompatibleMap = new HashMap<>();
             mutualIncompatible(incompatibleMap, forge, fabric, quilt, neoForge, cleanroom, legacyfabric);
@@ -217,7 +197,7 @@ public class InstallerItem extends Control {
                     for (InstallerItem other : incompatibleItems) {
                         InstalledState otherVersion = other.versionProperty.get();
                         if (otherVersion != null) {
-                            return new IncompatibleState(other.id, otherVersion.version);
+                            return new IncompatibleState(other.type.getPatchId(), otherVersion.version);
                         }
                     }
 
@@ -226,7 +206,7 @@ public class InstallerItem extends Control {
             }
 
             if (gameVersion != null) {
-                game.versionProperty.set(new InstalledState(gameVersion, false, false));
+                game.versionProperty.set(new InstalledState(gameVersion.toString(), false, false));
             }
 
             InstallerItem[] all = {game, forge, neoForge, liteLoader, optiFine, fabric, fabricApi, quilt, quiltApi, legacyfabric, legacyfabricApi, cleanroom};
@@ -235,22 +215,19 @@ public class InstallerItem extends Control {
                 if (!item.resolvedStateProperty.isBound()) {
                     item.resolvedStateProperty.bind(Bindings.createObjectBinding(() -> {
                         InstalledState itemVersion = item.versionProperty.get();
-                        if (itemVersion != null) {
-                            return itemVersion;
-                        }
-                        return InstallableState.INSTANCE;
+                        return Objects.requireNonNullElse(itemVersion, InstallableState.INSTANCE);
                     }, item.versionProperty));
                 }
             }
 
             if (gameVersion == null) {
-                this.libraries = all;
-            } else if (gameVersion.equals("1.12.2")) {
-                this.libraries = new InstallerItem[]{game, forge, cleanroom, liteLoader, legacyfabric, legacyfabricApi, optiFine};
-            } else if (GameVersionNumber.compare(gameVersion, "1.13.2") <= 0) {
-                this.libraries = new InstallerItem[]{game, forge, liteLoader, optiFine, legacyfabric, legacyfabricApi};
+                this.components = all;
+            } else if (gameVersion.compareTo("1.12.2") == 0) {
+                this.components = new InstallerItem[]{game, forge, cleanroom, liteLoader, legacyfabric, legacyfabricApi, optiFine};
+            } else if (gameVersion.compareTo("1.13.2") <= 0) {
+                this.components = new InstallerItem[]{game, forge, liteLoader, optiFine, legacyfabric, legacyfabricApi};
             } else {
-                this.libraries = new InstallerItem[]{game, forge, neoForge, optiFine, fabric, fabricApi, quilt, quiltApi};
+                this.components = new InstallerItem[]{game, forge, neoForge, optiFine, fabric, fabricApi, quilt, quiltApi};
             }
         }
 
@@ -258,8 +235,8 @@ public class InstallerItem extends Control {
             return game;
         }
 
-        public InstallerItem[] getLibraries() {
-            return libraries;
+        public InstallerItem[] getComponents() {
+            return components;
         }
     }
 
@@ -309,7 +286,7 @@ public class InstallerItem extends Control {
             nameLabel.getStyleClass().add("installer-item-name");
             nameLabel.setMouseTransparent(true);
             pane.getChildren().add(nameLabel);
-            nameLabel.textProperty().set(I18n.hasKey("install.installer." + control.id) ? i18n("install.installer." + control.id) : control.id);
+            nameLabel.textProperty().set(I18n.hasKey("install.installer." + control.type.getPatchId()) ? i18n("install.installer." + control.type.getPatchId()) : control.type.getPatchId());
             HBox.setMargin(nameLabel, new Insets(0, 4, 0, 4));
 
             Label statusLabel = new Label();
@@ -355,7 +332,7 @@ public class InstallerItem extends Control {
             pane.getChildren().add(buttonsContainer);
 
             JFXButton removeButton = FXUtils.newToggleButton4(SVG.CLOSE);
-            if (control.id.equals(MINECRAFT.getPatchId())) {
+            if (control.type == GameComponentType.GAME) {
                 removeButton.setVisible(false);
             } else {
                 removeButton.visibleProperty().bind(Bindings.createBooleanBinding(() -> {

HMCL/src/main/java/org/jackhuang/hmcl/ui/LogWindow.java

@@ -40,7 +40,6 @@ import org.jackhuang.hmcl.theme.Themes;
 import org.jackhuang.hmcl.ui.construct.MessageDialogPane;
 import org.jackhuang.hmcl.ui.construct.SpinnerPane;
 import org.jackhuang.hmcl.util.CircularArrayList;
-import org.jackhuang.hmcl.util.Lang;
 import org.jackhuang.hmcl.util.Log4jLevel;
 import org.jackhuang.hmcl.util.StringUtils;
 import org.jackhuang.hmcl.util.platform.ManagedProcess;
@@ -52,10 +51,7 @@ import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.time.LocalDateTime;
 import java.time.format.DateTimeFormatter;
-import java.util.EnumMap;
-import java.util.List;
-import java.util.Locale;
-import java.util.Map;
+import java.util.*;
 import java.util.stream.Collectors;
 
 import static org.jackhuang.hmcl.setting.SettingsManager.settings;
@@ -104,6 +100,8 @@ public final class LogWindow extends Stage {
         }
 
         this.gameProcess = gameProcess;
+
+        FXUtils.addMacOSCloseWindowHandler(this, () -> !gameProcess.isRunning());
     }
 
     public void logLine(Log log) {
@@ -324,7 +322,7 @@ public final class LogWindow extends Stage {
                         listView.scrollTo(listView.getItems().size() - 1);
                 });
 
-                listView.setStyle("-fx-font-family: \"" + Lang.requireNonNullElse(settings().logFontFamilyProperty().get(), FXUtils.DEFAULT_MONOSPACE_FONT)
+                listView.setStyle("-fx-font-family: \"" + Objects.requireNonNullElse(settings().logFontFamilyProperty().get(), FXUtils.DEFAULT_MONOSPACE_FONT)
                         + "\"; -fx-font-size: " + settings().logFontSizeProperty().get() + "px;");
                 listView.setCellFactory(x -> new ListCell<>() {
                     {

HMCL/src/main/java/org/jackhuang/hmcl/ui/MacOSNativeUtils.java

@@ -18,6 +18,8 @@
 package org.jackhuang.hmcl.ui;
 
 import com.sun.jna.Pointer;
+import javafx.beans.property.ReadOnlyBooleanProperty;
+import org.jackhuang.hmcl.theme.Themes;
 import org.jackhuang.hmcl.util.platform.macos.ObjectiveCRuntime;
 import org.jetbrains.annotations.Nullable;
 
@@ -56,8 +58,30 @@ public final class MacOSNativeUtils {
         return pointer == null || Pointer.nativeValue(pointer) == 0;
     }
 
+    private static final ReadOnlyBooleanProperty autoBrightness = Themes.autoBrightnessProperty();
+
+    static {
+        FXUtils.onChange(autoBrightness, b -> setAppearance(Themes.darkModeProperty().get()));
+    }
+
     public static void setAppearance(boolean dark) {
-        setAppearance(dark, false);
+        if (autoBrightness.get()) {
+            clearAppearance();
+        } else {
+            setAppearance(dark, false);
+        }
+    }
+
+    public static void clearAppearance() {
+        if (nsApp == null) return;
+
+        try {
+            var objc = ObjectiveCRuntime.INSTANCE;
+            Pointer setSel = objc.sel_registerName("setAppearance:");
+            objc.objc_msgSend(nsApp, setSel, Pointer.NULL);
+        } catch (Throwable t) {
+            LOG.warning("Failed to set macOS appearance", t);
+        }
     }
 
     public static void setAppearance(boolean dark, boolean highContrast) {

HMCL/src/main/java/org/jackhuang/hmcl/ui/SVGContainer.java

@@ -23,6 +23,7 @@ import javafx.animation.Timeline;
 import javafx.scene.Parent;
 import javafx.scene.shape.SVGPath;
 import javafx.util.Duration;
+import org.jackhuang.hmcl.ui.animation.AnimationUtils;
 import org.jackhuang.hmcl.ui.animation.Motion;
 
 /// A lightweight wrapper for displaying [SVG] icons.
@@ -108,7 +109,7 @@ public final class SVGContainer extends Parent {
         SVG oldIcon = this.icon;
         this.icon = newIcon;
 
-        if (animationDuration.equals(Duration.ZERO)) {
+        if (animationDuration.equals(Duration.ZERO) || !AnimationUtils.isAnimationEnabled()) {
             path.setContent(newIcon.getPath());
             path.setOpacity(1);
             if (getChildren().size() != 1)

HMCL/src/main/java/org/jackhuang/hmcl/ui/UpgradeDialog.java

@@ -44,8 +44,8 @@ import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 public final class UpgradeDialog extends JFXDialogLayout {
 
     public UpgradeDialog(RemoteVersion remoteVersion, Runnable updateRunnable) {
-        maxWidthProperty().bind(Controllers.windowWidthProperty().multiply(0.7));
-        maxHeightProperty().bind(Controllers.windowHeightProperty().multiply(0.7));
+        maxWidthProperty().bind(Controllers.getDecorator().contentWidthProperty().multiply(0.7));
+        maxHeightProperty().bind(Controllers.getDecorator().contentHeightProperty().multiply(0.7));
 
         setHeading(new Label(i18n("update.changelog")));
         setBody(new JFXSpinner());

HMCL/src/main/java/org/jackhuang/hmcl/ui/WebPage.java

@@ -47,11 +47,7 @@ public final class WebPage extends SpinnerPane implements DecoratorPage {
 
         Task.supplyAsync(() -> {
             Document document = Jsoup.parseBodyFragment(content);
-            HTMLRenderer renderer = new HTMLRenderer(uri -> {
-                Controllers.confirm(i18n("web.open_in_browser", uri), i18n("message.confirm"), () -> {
-                    FXUtils.openLink(uri.toString());
-                }, null);
-            });
+            HTMLRenderer renderer = new HTMLRenderer(Controllers::openUriOrCopy);
             renderer.appendNode(document);
             renderer.mergeLineBreaks();
             return renderer.render();

HMCL/src/main/java/org/jackhuang/hmcl/ui/WindowsNativeUtils.java

@@ -19,10 +19,22 @@ package org.jackhuang.hmcl.ui;
 
 import javafx.stage.Stage;
 import javafx.stage.Window;
+import javafx.stage.WindowEvent;
+import org.jackhuang.hmcl.Metadata;
+import org.jackhuang.hmcl.util.io.FileUtils;
+import org.jackhuang.hmcl.util.io.JarUtils;
+import org.jackhuang.hmcl.util.platform.NativeUtils;
+import org.jackhuang.hmcl.util.platform.OperatingSystem;
+import org.jackhuang.hmcl.util.platform.windows.IPropertyStore;
+import org.jackhuang.hmcl.util.platform.windows.Shell32;
+import org.jackhuang.hmcl.util.platform.windows.WinTypes;
+import org.jetbrains.annotations.Nullable;
 
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodHandles;
 import java.lang.invoke.MethodType;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.OptionalLong;
 
 import static org.jackhuang.hmcl.util.logging.Logger.LOG;
@@ -55,6 +67,145 @@ public final class WindowsNativeUtils {
         }
     }
 
+    /// Installs permanent window listeners that keep AppUserModel relaunch properties in sync
+    /// with the stage's native HWND lifecycle.
+    ///
+    /// JavaFX may destroy and recreate the HWND across `hide()` / `show()` (for example with
+    /// `HIDE_AND_REOPEN`). Properties are therefore applied on every [`WindowEvent#WINDOW_SHOWN`]
+    /// and removed with `VT_EMPTY` on every [`WindowEvent#WINDOW_HIDING`], as required by
+    /// [`SHGetPropertyStoreForWindow`](https://learn.microsoft.com/windows/win32/api/shellapi/nf-shellapi-shgetpropertystoreforwindow).
+    ///
+    /// Handlers must run on the JavaFX application thread: `IPropertyStore` is a COM interface,
+    /// and the FX thread is already initialized for COM on Windows.
+    ///
+    /// @param stage the primary launcher stage
+    public static void installWindowsAppUserModelRelaunchProperties(Stage stage) {
+        if (OperatingSystem.CURRENT_OS != OperatingSystem.WINDOWS)
+            return;
+        if (!NativeUtils.USE_JNA || Shell32.INSTANCE == null)
+            return;
+
+        @Nullable Path thisJar = JarUtils.thisJarPath();
+        if (thisJar == null || !Files.isRegularFile(thisJar) || !"exe".equalsIgnoreCase(FileUtils.getExtension(thisJar)))
+            return;
+
+        String exePath = FileUtils.getAbsolutePath(thisJar);
+        String iconResource = exePath + ",0";
+        String relaunchCommand = '"' + exePath + '"';
+
+        stage.addEventFilter(WindowEvent.WINDOW_SHOWN, event -> {
+            try {
+                applyWindowsAppUserModelRelaunchProperties(stage, relaunchCommand, iconResource);
+            } catch (Throwable e) {
+                LOG.warning("Failed to set AppUserModel relaunch properties", e);
+            }
+        });
+        stage.addEventFilter(WindowEvent.WINDOW_HIDING, event -> {
+            try {
+                clearWindowsAppUserModelRelaunchProperties(stage);
+            } catch (Throwable e) {
+                LOG.warning("Failed to clear AppUserModel relaunch properties", e);
+            }
+        });
+    }
+
+    /// Writes AppUserModel relaunch properties for the current native window of `stage`.
+    ///
+    /// Successful [`IPropertyStore#SetValue`] calls on a window property store take effect
+    /// immediately; no `Commit` is required or useful.
+    ///
+    /// @param stage the stage whose native window receives the properties
+    /// @param relaunchCommand the `PKEY_AppUserModel_RelaunchCommand` value
+    /// @param iconResource the `PKEY_AppUserModel_RelaunchIconResource` value
+    private static void applyWindowsAppUserModelRelaunchProperties(Stage stage, String relaunchCommand, String iconResource) {
+        Shell32 shell32 = Shell32.INSTANCE;
+        if (shell32 == null)
+            return;
+
+        OptionalLong handle = WindowsNativeUtils.getWindowHandle(stage);
+        if (handle.isEmpty() || handle.getAsLong() == WinTypes.HANDLE.INVALID_VALUE) {
+            LOG.warning("Failed to get window handle for AppUserModel relaunch properties");
+            return;
+        }
+
+        try (IPropertyStore store = IPropertyStore.forWindow(shell32, handle.getAsLong())) {
+            if (store == null) {
+                LOG.warning("Failed to call SHGetPropertyStoreForWindow");
+                return;
+            }
+
+            // Set Relaunch* first, then AppUserModel.ID last. Window property store values take
+            // effect immediately on SetValue; assigning the ID first can let the shell register the
+            // window before relaunch metadata is complete.
+            if (!setWindowsPropertyStoreString(store, WinTypes.PROPERTYKEY.PKEY_AppUserModel_RelaunchCommand, relaunchCommand)
+                    || !setWindowsPropertyStoreString(store, WinTypes.PROPERTYKEY.PKEY_AppUserModel_RelaunchIconResource, iconResource)
+                    || !setWindowsPropertyStoreString(store, WinTypes.PROPERTYKEY.PKEY_AppUserModel_RelaunchDisplayNameResource, Metadata.FULL_NAME)
+                    || !setWindowsPropertyStoreString(store, WinTypes.PROPERTYKEY.PKEY_AppUserModel_ID, Metadata.WINDOWS_APP_USER_MODEL_ID)) {
+                return;
+            }
+
+            LOG.info("Set AppUserModel relaunch properties for HWND " + Long.toHexString(handle.getAsLong()));
+        }
+    }
+
+    /// Removes AppUserModel relaunch properties from the current native window before it is hidden.
+    ///
+    /// @param stage the stage whose native window is about to be destroyed or hidden
+    private static void clearWindowsAppUserModelRelaunchProperties(Stage stage) {
+        Shell32 shell32 = Shell32.INSTANCE;
+        if (shell32 == null)
+            return;
+
+        OptionalLong handle = WindowsNativeUtils.getWindowHandle(stage);
+        if (handle.isEmpty() || handle.getAsLong() == WinTypes.HANDLE.INVALID_VALUE) {
+            return;
+        }
+
+        try (IPropertyStore store = IPropertyStore.forWindow(shell32, handle.getAsLong())) {
+            if (store == null) {
+                LOG.warning("Failed to call SHGetPropertyStoreForWindow while clearing properties");
+                return;
+            }
+
+            WinTypes.PROPVARIANT empty = new WinTypes.PROPVARIANT();
+            empty.setEmpty();
+            // Clear in reverse of apply order so ID is removed before relaunch metadata when possible.
+            clearWindowsPropertyStoreValue(store, WinTypes.PROPERTYKEY.PKEY_AppUserModel_ID, empty);
+            clearWindowsPropertyStoreValue(store, WinTypes.PROPERTYKEY.PKEY_AppUserModel_RelaunchDisplayNameResource, empty);
+            clearWindowsPropertyStoreValue(store, WinTypes.PROPERTYKEY.PKEY_AppUserModel_RelaunchIconResource, empty);
+            clearWindowsPropertyStoreValue(store, WinTypes.PROPERTYKEY.PKEY_AppUserModel_RelaunchCommand, empty);
+        }
+    }
+
+    /// Sets a string property on an [`IPropertyStore`].
+    ///
+    /// @param store the property store
+    /// @param key the property key
+    /// @param value the string value
+    /// @return `true` if [`IPropertyStore#SetValue`] succeeds
+    private static boolean setWindowsPropertyStoreString(IPropertyStore store, WinTypes.PROPERTYKEY key, String value) {
+        WinTypes.PROPVARIANT propvar = new WinTypes.PROPVARIANT();
+        propvar.setStringValue(value);
+        int hr = store.SetValue(key, propvar);
+        if (hr < 0) {
+            LOG.warning("Failed to set property pid=" + key.pid + " on IPropertyStore, HRESULT=0x" + Integer.toHexString(hr));
+            return false;
+        }
+        return true;
+    }
+
+    /// Removes a property by writing `VT_EMPTY`.
+    ///
+    /// @param store the property store
+    /// @param key the property key to clear
+    /// @param empty a `VT_EMPTY` value
+    private static void clearWindowsPropertyStoreValue(IPropertyStore store, WinTypes.PROPERTYKEY key, WinTypes.PROPVARIANT empty) {
+        int hr = store.SetValue(key, empty);
+        if (hr < 0) {
+            LOG.warning("Failed to clear property pid=" + key.pid + " on IPropertyStore, HRESULT=0x" + Integer.toHexString(hr));
+        }
+    }
+
     private WindowsNativeUtils() {
     }
 }

HMCL/src/main/java/org/jackhuang/hmcl/ui/account/AccountListPage.java

@@ -18,13 +18,7 @@
 package org.jackhuang.hmcl.ui.account;
 
 import javafx.beans.binding.Bindings;
-import javafx.beans.property.BooleanProperty;
-import javafx.beans.property.ListProperty;
-import javafx.beans.property.ObjectProperty;
-import javafx.beans.property.ReadOnlyObjectProperty;
-import javafx.beans.property.ReadOnlyObjectWrapper;
-import javafx.beans.property.SimpleBooleanProperty;
-import javafx.beans.property.SimpleListProperty;
+import javafx.beans.property.*;
 import javafx.beans.value.ChangeListener;
 import javafx.beans.value.ObservableValue;
 import javafx.collections.FXCollections;
@@ -47,7 +41,6 @@ import org.jackhuang.hmcl.ui.construct.ClassTitle;
 import org.jackhuang.hmcl.ui.decorator.DecoratorAnimatedPage;
 import org.jackhuang.hmcl.ui.decorator.DecoratorPage;
 import org.jackhuang.hmcl.util.i18n.LocaleUtils;
-import org.jackhuang.hmcl.util.io.NetworkUtils;
 import org.jackhuang.hmcl.util.javafx.BindingMapping;
 import org.jackhuang.hmcl.util.javafx.MappedObservableList;
 
@@ -56,7 +49,6 @@ import java.util.Locale;
 import static org.jackhuang.hmcl.setting.SettingsManager.userSettings;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 import static org.jackhuang.hmcl.util.javafx.ExtendedProperties.createSelectedItemPropertyFor;
-import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 
 public final class AccountListPage extends DecoratorAnimatedPage implements DecoratorPage {
     static final BooleanProperty RESTRICTED = new SimpleBooleanProperty(true);
@@ -173,13 +165,7 @@ public final class AccountListPage extends DecoratorAnimatedPage implements Deco
 
                         ObservableValue<String> title = BindingMapping.of(server, AuthlibInjectorServer::getName);
                         item.titleProperty().bind(title);
-                        String host = "";
-                        try {
-                            host = NetworkUtils.toURI(server.getUrl()).getHost();
-                        } catch (IllegalArgumentException e) {
-                            LOG.warning("Unparsable authlib-injector server url " + server.getUrl(), e);
-                        }
-                        item.subtitleProperty().set(host);
+                        item.setSubtitle(server.getDisplayHostUrl());
                         Tooltip tooltip = new Tooltip();
                         tooltip.textProperty().bind(Bindings.format("%s (%s)", title, server.getUrl()));
                         FXUtils.installFastTooltip(item, tooltip);

HMCL/src/main/java/org/jackhuang/hmcl/ui/account/CreateAccountPane.java

@@ -67,11 +67,10 @@ import static java.util.Collections.emptyList;
 import static java.util.Collections.unmodifiableList;
 import static javafx.beans.binding.Bindings.bindContent;
 import static javafx.beans.binding.Bindings.createBooleanBinding;
-import static org.jackhuang.hmcl.setting.SettingsManager.settings;
 import static org.jackhuang.hmcl.setting.SettingsManager.getAuthlibInjectorServers;
+import static org.jackhuang.hmcl.setting.SettingsManager.settings;
 import static org.jackhuang.hmcl.ui.FXUtils.*;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
-import static org.jackhuang.hmcl.util.javafx.ExtendedProperties.classPropertyFor;
 
 public class CreateAccountPane extends JFXDialogLayout implements DialogAware {
     private static final Pattern USERNAME_CHECKER_PATTERN = Pattern.compile("^[A-Za-z0-9_]+$");
@@ -388,20 +387,22 @@ public class CreateAccountPane extends JFXDialogLayout implements DialogAware {
                 add(lblServers, 0, rowIndex);
 
                 cboServers = new JFXComboBox<>();
-                cboServers.setCellFactory(jfxListCellFactory(server -> new TwoLineListItem(server.getName(), server.getUrl())));
-                cboServers.setConverter(stringConverter(AuthlibInjectorServer::getName));
+                cboServers.setConverter(stringConverter(it -> String.format("%s (%s)", it.getName(), it.getDisplayHostUrl())));
                 bindContent(cboServers.getItems(), getAuthlibInjectorServers());
                 cboServers.getItems().addListener(onInvalidating(
                         () -> Platform.runLater( // the selection will not be updated as expected if we call it immediately
                                 cboServers.getSelectionModel()::selectFirst)));
                 cboServers.getSelectionModel().selectFirst();
-                cboServers.setPromptText(i18n("account.injector.empty"));
+
+                Label noServersLabel = new Label(i18n("account.injector.empty"));
                 BooleanBinding noServers = createBooleanBinding(cboServers.getItems()::isEmpty, cboServers.getItems());
-                classPropertyFor(cboServers, "jfx-combo-box-warning").bind(noServers);
-                classPropertyFor(cboServers, "jfx-combo-box").bind(noServers.not());
+
                 HBox.setHgrow(cboServers, Priority.ALWAYS);
                 HBox.setMargin(cboServers, new Insets(0, 10, 0, 0));
                 cboServers.setMaxWidth(Double.MAX_VALUE);
+                HBox.setHgrow(noServersLabel, Priority.ALWAYS);
+                HBox.setMargin(noServersLabel, new Insets(0, 10, 0, 0));
+                noServersLabel.setMaxWidth(Double.MAX_VALUE);
 
                 HBox linksContainer = new HBox();
                 linksContainer.setAlignment(Pos.CENTER);
@@ -419,7 +420,13 @@ public class CreateAccountPane extends JFXDialogLayout implements DialogAware {
                     Controllers.dialog(new AddAuthlibInjectorServerPane());
                 });
 
-                HBox boxServers = new HBox(cboServers, linksContainer, btnAddServer);
+                noServersLabel.visibleProperty().bind(noServers);
+                noServersLabel.managedProperty().bind(noServers);
+                cboServers.visibleProperty().bind(noServers.not());
+                cboServers.managedProperty().bind(noServers.not());
+
+                HBox boxServers = new HBox(cboServers, noServersLabel, linksContainer, btnAddServer);
+                boxServers.setAlignment(Pos.CENTER_LEFT);
                 add(boxServers, 1, rowIndex);
 
                 rowIndex++;

HMCL/src/main/java/org/jackhuang/hmcl/ui/account/MicrosoftAccountLoginPane.java

@@ -29,9 +29,7 @@ import javafx.geometry.Pos;
 import javafx.scene.Cursor;
 import javafx.scene.Group;
 import javafx.scene.control.Label;
-import javafx.scene.layout.FlowPane;
-import javafx.scene.layout.StackPane;
-import javafx.scene.layout.VBox;
+import javafx.scene.layout.*;
 import javafx.scene.shape.SVGPath;
 import org.jackhuang.hmcl.auth.Account;
 import org.jackhuang.hmcl.auth.AuthInfo;
@@ -49,10 +47,10 @@ import org.jackhuang.hmcl.ui.FXUtils;
 import org.jackhuang.hmcl.ui.WeakListenerHolder;
 import org.jackhuang.hmcl.ui.construct.*;
 import org.jackhuang.hmcl.upgrade.IntegrityChecker;
-import org.jackhuang.hmcl.util.Lang;
 import org.jackhuang.hmcl.util.QrCodeUtils;
 import org.jackhuang.hmcl.util.StringUtils;
 
+import java.util.Objects;
 import java.util.concurrent.CancellationException;
 import java.util.function.Consumer;
 
@@ -141,20 +139,22 @@ public class MicrosoftAccountLoginPane extends JFXDialogLayout implements Dialog
         setBody(rootContainer);
         rootContainer.setAlignment(Pos.TOP_CENTER);
 
-        if (Accounts.OAUTH_CALLBACK.getClientId().isEmpty()) {
-            var snapshotHint = new HintPane(MessageDialogPane.MessageType.WARNING);
+        StackPane warningPane = new StackPane();
+
+        if (!IntegrityChecker.isOfficial()) {
+            var unofficialHintPane = new HintPane(MessageDialogPane.MessageType.WARNING);
+            unofficialHintPane.setSegment(i18n("unofficial.hint"));
+            warningPane.getChildren().add(unofficialHintPane);
+        } else if (Accounts.OAUTH_CALLBACK.getClientId().isEmpty()) {
+            HintPane snapshotHint = new HintPane(MessageDialogPane.MessageType.WARNING);
             snapshotHint.setSegment(i18n("account.methods.microsoft.snapshot"));
-            rootContainer.getChildren().add(snapshotHint);
+            warningPane.getChildren().add(snapshotHint);
             btnLogin.setDisable(true);
             loginButtonSpinner.setLoading(false);
             return;
         }
 
-        if (!IntegrityChecker.isOfficial()) {
-            var unofficialHintPane = new HintPane(MessageDialogPane.MessageType.WARNING);
-            unofficialHintPane.setSegment(i18n("unofficial.hint"));
-            rootContainer.getChildren().add(unofficialHintPane);
-        }
+        rootContainer.getChildren().add(warningPane);
 
         if (currentStep instanceof Step.Init) {
             btnLogin.setOnAction(e -> this.step.set(new Step.StartAuthorizationCodeLogin()));
@@ -198,6 +198,20 @@ public class MicrosoftAccountLoginPane extends JFXDialogLayout implements Dialog
         } else if (currentStep instanceof Step.WaitForScanQrCode wait) {
             loginButtonSpinner.setLoading(true);
 
+            VBox leftVBox = new VBox(6);
+            leftVBox.setAlignment(Pos.CENTER);
+            VBox rightVBox = new VBox(6);
+
+            HBox hbox = new HBox(leftVBox, rightVBox);
+
+            leftVBox.prefWidthProperty().bind(hbox.widthProperty().divide(2));
+            rightVBox.prefWidthProperty().bind(hbox.widthProperty().divide(2));
+            leftVBox.setMaxWidth(Double.MAX_VALUE);
+            rightVBox.setMaxWidth(Double.MAX_VALUE);
+
+            HBox.setHgrow(leftVBox, Priority.ALWAYS);
+            HBox.setHgrow(rightVBox, Priority.ALWAYS);
+
             String scanUri = "https://www.microsoft.com/link".equals(wait.verificationUri())
                     ? "https://www.microsoft.com/link?otc=" + wait.userCode()
                     : wait.verificationUri();
@@ -217,7 +231,7 @@ public class MicrosoftAccountLoginPane extends JFXDialogLayout implements Dialog
 
             var lblCode = new Label(wait.userCode());
             lblCode.getStyleClass().add("code-label");
-            lblCode.setStyle("-fx-font-family: \"" + Lang.requireNonNullElse(settings().logFontFamilyProperty().get(), FXUtils.DEFAULT_MONOSPACE_FONT) + "\";");
+            lblCode.setStyle("-fx-font-family: \"" + Objects.requireNonNullElse(settings().logFontFamilyProperty().get(), FXUtils.DEFAULT_MONOSPACE_FONT) + "\";");
 
             var codeBox = new StackPane(lblCode);
             codeBox.getStyleClass().add("code-box");
@@ -225,7 +239,10 @@ public class MicrosoftAccountLoginPane extends JFXDialogLayout implements Dialog
             FXUtils.onClicked(codeBox, () -> FXUtils.copyText(wait.userCode()));
             codeBox.setMaxWidth(USE_PREF_SIZE);
 
-            rootContainer.getChildren().addAll(deviceHint, new Group(qrCode), codeBox);
+            leftVBox.getChildren().setAll(new Group(qrCode), codeBox);
+            rightVBox.getChildren().setAll(warningPane, deviceHint);
+
+            rootContainer.getChildren().setAll(hbox);
         } else if (currentStep instanceof Step.DeviceLoginCompleted) {
             loginButtonSpinner.setLoading(true);
 

HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/DialogPane.java

@@ -19,15 +19,11 @@ package org.jackhuang.hmcl.ui.construct;
 
 import com.jfoenix.controls.JFXButton;
 import com.jfoenix.controls.JFXDialogLayout;
-import com.jfoenix.controls.JFXProgressBar;
 import javafx.beans.property.BooleanProperty;
 import javafx.beans.property.SimpleBooleanProperty;
 import javafx.beans.property.SimpleStringProperty;
 import javafx.beans.property.StringProperty;
-import javafx.geometry.Insets;
-import javafx.geometry.Pos;
 import javafx.scene.control.Label;
-import javafx.scene.layout.StackPane;
 
 import static org.jackhuang.hmcl.ui.FXUtils.onEscPressed;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
@@ -38,18 +34,11 @@ public class DialogPane extends JFXDialogLayout {
     protected final SpinnerPane acceptPane = new SpinnerPane();
     protected final JFXButton cancelButton = new JFXButton();
     protected final Label warningLabel = new Label();
-    private final JFXProgressBar progressBar = new JFXProgressBar();
 
     public DialogPane() {
         Label titleLabel = new Label();
         titleLabel.textProperty().bind(title);
         setHeading(titleLabel);
-        getChildren().add(progressBar);
-
-        progressBar.setVisible(false);
-        StackPane.setMargin(progressBar, new Insets(-24.0D, -24.0D, -16.0D, -24.0D));
-        StackPane.setAlignment(progressBar, Pos.TOP_CENTER);
-        progressBar.setMaxWidth(Double.MAX_VALUE);
 
         JFXButton acceptButton = new JFXButton(i18n("button.ok"));
         acceptButton.setOnAction(e -> onAccept());
@@ -66,10 +55,6 @@ public class DialogPane extends JFXDialogLayout {
         setActions(warningLabel, acceptPane, cancelButton);
     }
 
-    protected JFXProgressBar getProgressBar() {
-        return progressBar;
-    }
-
     public String getTitle() {
         return title.get();
     }

HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/FontComboBox.java

@@ -39,7 +39,7 @@ public final class FontComboBox extends JFXComboBox<String> {
 
         styleProperty().bind(Bindings.concat("-fx-font-family: \"", valueProperty(), "\""));
 
-        setCellFactory(listView -> new JFXListCell<String>() {
+        setCellFactory(listView -> new JFXListCell<>() {
             @Override
             public void updateItem(String item, boolean empty) {
                 super.updateItem(item, empty);

HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/MDListCell.java

@@ -21,15 +21,18 @@ import com.jfoenix.controls.JFXListView;
 import javafx.beans.binding.DoubleBinding;
 import javafx.css.PseudoClass;
 import javafx.scene.control.ListCell;
+import javafx.scene.control.ListView;
 import javafx.scene.layout.Region;
 import javafx.scene.layout.StackPane;
 import org.jackhuang.hmcl.ui.FXUtils;
 
 public abstract class MDListCell<T> extends ListCell<T> {
     private static final PseudoClass SELECTED = PseudoClass.getPseudoClass("selected");
+    private static final PseudoClass LAST = PseudoClass.getPseudoClass("last");
 
     private final StackPane container = new StackPane();
     private final StackPane root = new StackPane();
+    private final RipplerContainer ripplerContainer = new RipplerContainer(container);
 
     public MDListCell(JFXListView<T> listView) {
 
@@ -37,7 +40,6 @@ public abstract class MDListCell<T> extends ListCell<T> {
         setGraphic(null);
 
         root.getStyleClass().add("md-list-cell");
-        RipplerContainer ripplerContainer = new RipplerContainer(container);
         root.getChildren().setAll(ripplerContainer);
 
         Region clippedContainer = (Region) listView.lookup(".clipped-container");
@@ -58,14 +60,32 @@ public abstract class MDListCell<T> extends ListCell<T> {
 
         super.updateItem(item, empty);
 
-        if (oldItem == item && oldEmpty == empty) return;
+        if (oldItem == item && oldEmpty == empty) {
+            updateLastPseudoClass(empty);
+            return;
+        }
+
+        ripplerContainer.releaseRippleImmediately();
 
         updateControl(item, empty);
-        if (empty) {
+        if (empty || item == null) {
             setGraphic(null);
         } else {
             setGraphic(root);
         }
+        updateLastPseudoClass(empty || item == null);
+    }
+
+    /// Updates the `:last` pseudo-class so the trailing divider can be suppressed in CSS.
+    ///
+    /// @param empty whether this cell is empty
+    private void updateLastPseudoClass(boolean empty) {
+        ListView<T> listView = getListView();
+        boolean last = !empty
+                && listView != null
+                && getIndex() >= 0
+                && getIndex() == listView.getItems().size() - 1;
+        root.pseudoClassStateChanged(LAST, last);
     }
 
     protected StackPane getContainer() {
@@ -78,5 +98,9 @@ public abstract class MDListCell<T> extends ListCell<T> {
         });
     }
 
+    protected void onClicked(Runnable action) {
+        FXUtils.onClicked(ripplerContainer, action);
+    }
+
     protected abstract void updateControl(T item, boolean empty);
 }

HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/RipplerContainer.java

@@ -205,6 +205,10 @@ public class RipplerContainer extends StackPane {
         ripplerFillProperty().set(ripplerFill);
     }
 
+    public void releaseRippleImmediately() {
+        buttonRippler.releaseRippleImmediately();
+    }
+
     @Override
     public List<CssMetaData<? extends Styleable, ?>> getCssMetaData() {
         return getClassCssMetaData();

HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/TaskExecutorDialogPane.java

@@ -27,6 +27,7 @@ import javafx.scene.layout.*;
 import org.jackhuang.hmcl.task.FetchTask;
 import org.jackhuang.hmcl.task.TaskExecutor;
 import org.jackhuang.hmcl.task.TaskListener;
+import org.jackhuang.hmcl.ui.Controllers;
 import org.jackhuang.hmcl.ui.FXUtils;
 import org.jackhuang.hmcl.util.TaskCancellationAction;
 import org.jackhuang.hmcl.util.i18n.I18n;
@@ -113,7 +114,15 @@ public class TaskExecutorDialogPane extends BorderPane {
                 executor.addTaskListener(new TaskListener() {
                     @Override
                     public void onStop(boolean success, TaskExecutor executor) {
-                        Platform.runLater(() -> fireEvent(new DialogCloseEvent()));
+                        Platform.runLater(() -> {
+                            fireEvent(new DialogCloseEvent());
+
+                            if (Controllers.AUTO_TRIM_HEAP) {
+                                // Trim heap memory when tasks finish, allowing GC to return memory to the OS faster,
+                                // prevent excessive peak memory from consuming system resources.
+                                Platform.runLater(Controllers::trimHeap);
+                            }
+                        });
                     }
                 });
         }

HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/TaskListPane.java

@@ -33,45 +33,16 @@ import javafx.scene.control.ListCell;
 import javafx.scene.control.ProgressIndicator;
 import javafx.scene.layout.BorderPane;
 import javafx.scene.layout.StackPane;
-import org.jackhuang.hmcl.download.cleanroom.CleanroomInstallTask;
-import org.jackhuang.hmcl.download.fabric.FabricAPIInstallTask;
-import org.jackhuang.hmcl.download.fabric.FabricInstallTask;
-import org.jackhuang.hmcl.download.forge.ForgeNewInstallTask;
-import org.jackhuang.hmcl.download.forge.ForgeOldInstallTask;
-import org.jackhuang.hmcl.download.game.GameAssetDownloadTask;
 import org.jackhuang.hmcl.download.game.GameInstallTask;
-import org.jackhuang.hmcl.download.java.mojang.MojangJavaDownloadTask;
-import org.jackhuang.hmcl.download.legacyfabric.LegacyFabricInstallTask;
-import org.jackhuang.hmcl.download.liteloader.LiteLoaderInstallTask;
-import org.jackhuang.hmcl.download.neoforge.NeoForgeInstallTask;
-import org.jackhuang.hmcl.download.neoforge.NeoForgeOldInstallTask;
-import org.jackhuang.hmcl.download.optifine.OptiFineInstallTask;
-import org.jackhuang.hmcl.download.quilt.QuiltAPIInstallTask;
-import org.jackhuang.hmcl.download.quilt.QuiltInstallTask;
-import org.jackhuang.hmcl.game.HMCLModpackInstallTask;
-import org.jackhuang.hmcl.java.JavaInstallTask;
-import org.jackhuang.hmcl.modpack.MinecraftInstanceTask;
-import org.jackhuang.hmcl.modpack.ModpackInstallTask;
-import org.jackhuang.hmcl.modpack.ModpackUpdateTask;
-import org.jackhuang.hmcl.modpack.curse.CurseCompletionTask;
-import org.jackhuang.hmcl.modpack.curse.CurseInstallTask;
-import org.jackhuang.hmcl.modpack.mcbbs.McbbsModpackCompletionTask;
-import org.jackhuang.hmcl.modpack.mcbbs.McbbsModpackExportTask;
-import org.jackhuang.hmcl.modpack.modrinth.ModrinthCompletionTask;
-import org.jackhuang.hmcl.modpack.modrinth.ModrinthInstallTask;
-import org.jackhuang.hmcl.modpack.modrinth.ModrinthModpackExportTask;
-import org.jackhuang.hmcl.modpack.multimc.MultiMCModpackExportTask;
-import org.jackhuang.hmcl.modpack.multimc.MultiMCModpackInstallTask;
-import org.jackhuang.hmcl.modpack.server.ServerModpackCompletionTask;
-import org.jackhuang.hmcl.modpack.server.ServerModpackExportTask;
-import org.jackhuang.hmcl.modpack.server.ServerModpackLocalInstallTask;
 import org.jackhuang.hmcl.task.Task;
 import org.jackhuang.hmcl.task.TaskExecutor;
 import org.jackhuang.hmcl.task.TaskListener;
 import org.jackhuang.hmcl.ui.FXUtils;
 import org.jackhuang.hmcl.ui.SVG;
 import org.jackhuang.hmcl.util.FXThread;
+import org.jackhuang.hmcl.util.i18n.I18n;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.lang.ref.WeakReference;
 import java.util.Collection;
@@ -162,58 +133,16 @@ public final class TaskListPane extends StackPane {
                 if (!task.getSignificance().shouldShow() || task.getName() == null)
                     return;
 
-                if (task instanceof GameAssetDownloadTask) {
-                    task.setName(i18n("assets.download_all"));
-                } else if (task instanceof GameInstallTask) {
-                    if (task.getInheritedStage() != null && task.getInheritedStage().startsWith("hmcl.install.game"))
-                        return;
-                    task.setName(i18n("install.installer.install", i18n("install.installer.game")));
-                } else if (task instanceof CleanroomInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.cleanroom")));
-                } else if (task instanceof LegacyFabricInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.legacyfabric")));
-                } else if (task instanceof ForgeNewInstallTask || task instanceof ForgeOldInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.forge")));
-                } else if (task instanceof NeoForgeInstallTask || task instanceof NeoForgeOldInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.neoforge")));
-                } else if (task instanceof LiteLoaderInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.liteloader")));
-                } else if (task instanceof OptiFineInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.optifine")));
-                } else if (task instanceof FabricInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.fabric")));
-                } else if (task instanceof FabricAPIInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.fabric-api")));
-                } else if (task instanceof QuiltInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.quilt")));
-                } else if (task instanceof QuiltAPIInstallTask) {
-                    task.setName(i18n("install.installer.install", i18n("install.installer.quilt-api")));
-                } else if (task instanceof CurseCompletionTask || task instanceof ModrinthCompletionTask || task instanceof ServerModpackCompletionTask || task instanceof McbbsModpackCompletionTask) {
-                    task.setName(i18n("modpack.completion"));
-                } else if (task instanceof ModpackInstallTask) {
-                    task.setName(i18n("modpack.installing"));
-                } else if (task instanceof ModpackUpdateTask) {
-                    task.setName(i18n("modpack.update"));
-                } else if (task instanceof CurseInstallTask) {
-                    task.setName(i18n("modpack.installing.given", i18n("modpack.type.curse")));
-                } else if (task instanceof MultiMCModpackInstallTask) {
-                    task.setName(i18n("modpack.installing.given", i18n("modpack.type.multimc")));
-                } else if (task instanceof ModrinthInstallTask) {
-                    task.setName(i18n("modpack.installing.given", i18n("modpack.type.modrinth")));
-                } else if (task instanceof ServerModpackLocalInstallTask) {
-                    task.setName(i18n("install.installing") + ": " + i18n("modpack.type.server"));
-                } else if (task instanceof HMCLModpackInstallTask) {
-                    task.setName(i18n("modpack.installing.given", i18n("modpack.type.hmcl")));
-                } else if (task instanceof McbbsModpackExportTask || task instanceof MultiMCModpackExportTask || task instanceof ServerModpackExportTask || task instanceof ModrinthModpackExportTask) {
-                    task.setName(i18n("modpack.export"));
-                } else if (task instanceof MinecraftInstanceTask) {
-                    task.setName(i18n("modpack.scan"));
-                } else if (task instanceof MojangJavaDownloadTask) {
-                    task.setName(i18n("download.java"));
-                } else if (task instanceof JavaInstallTask) {
-                    task.setName(i18n("java.installing"));
+                if (task instanceof GameInstallTask
+                        && task.getInheritedStage() != null
+                        && task.getInheritedStage().startsWith("hmcl.install.game")) {
+                    return;
                 }
 
+                @Nullable String localizedName = I18n.translateTaskName(task);
+                if (localizedName != null)
+                    task.setName(localizedName);
+
                 Platform.runLater(() -> {
                     ProgressListNode node = new ProgressListNode(task);
                     nodes.put(task, node);

HMCL/src/main/java/org/jackhuang/hmcl/ui/construct/TwoLineListItem.java

@@ -24,12 +24,21 @@ import javafx.collections.FXCollections;
 import javafx.collections.ObservableList;
 import javafx.css.PseudoClass;
 import javafx.geometry.Pos;
+import javafx.scene.Node;
 import javafx.scene.control.Label;
+import javafx.scene.control.OverrunStyle;
 import javafx.scene.layout.HBox;
 import javafx.scene.layout.Priority;
 import javafx.scene.layout.VBox;
 import org.jackhuang.hmcl.ui.FXUtils;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
 
+import java.util.Collection;
+import java.util.LinkedHashSet;
+import java.util.stream.Collectors;
+
+/// Displays a title with optional tags and a subtitle.
 public class TwoLineListItem extends VBox {
     private static final String DEFAULT_STYLE_CLASS = "two-line-list-item";
 
@@ -39,14 +48,28 @@ public class TwoLineListItem extends VBox {
     private final Label lblTitle;
     private Label lblSubtitle;
 
+    /// Creates an empty item whose children do not receive mouse events.
     public TwoLineListItem() {
         getStyleClass().add(DEFAULT_STYLE_CLASS);
         setMouseTransparent(true);
 
         lblTitle = new Label();
         lblTitle.getStyleClass().add("title");
+        lblTitle.setTextOverrun(OverrunStyle.ELLIPSIS);
 
-        this.firstLine = new HBox(lblTitle);
+        this.firstLine = new HBox(lblTitle) {
+            /// Includes the tags' natural width when requesting space from the parent.
+            @Override
+            protected double computePrefWidth(double height) {
+                double width = super.computePrefWidth(height);
+                for (Node child : getManagedChildren()) {
+                    if (child instanceof TagsBox tagsBox) {
+                        width += snapSizeX(tagsBox.computeNaturalPrefWidth(height));
+                    }
+                }
+                return width;
+            }
+        };
         firstLine.getStyleClass().add("first-line");
         firstLine.setAlignment(Pos.CENTER_LEFT);
 
@@ -158,17 +181,29 @@ public class TwoLineListItem extends VBox {
         return lblSubtitle;
     }
 
-    private ObservableList<Label> tags;
+    private static Label createTag(String tag, PseudoClass pseudoClass) {
+        var tagLabel = new Label(tag);
+        tagLabel.getStyleClass().add("tag");
+        tagLabel.setMinWidth(Label.USE_PREF_SIZE);
+        if (pseudoClass != null)
+            tagLabel.pseudoClassStateChanged(pseudoClass, true);
+        return tagLabel;
+    }
 
+    /// Stores the mutable tag list once tag support has been initialized.
+    private @Nullable ObservableList<Label> tags;
+
+    /// Returns the mutable list of tags displayed after the title.
     public ObservableList<Label> getTags() {
         if (tags == null) {
             tags = FXCollections.observableArrayList();
 
-            var tagsBox = new HBox(8);
+            var tagsBox = new TagsBox();
             tagsBox.getStyleClass().add("tags");
             tagsBox.setAlignment(Pos.CENTER_LEFT);
-            tagsBox.setMinWidth(0);
-            HBox.setHgrow(tagsBox, Priority.ALWAYS);
+
+            HBox.setHgrow(tagsBox, Priority.SOMETIMES);
+
             Bindings.bindContent(tagsBox.getChildren(), tags);
             var isNotEmpty = Bindings.isNotEmpty(tags);
             tagsBox.managedProperty().bind(isNotEmpty);
@@ -176,25 +211,53 @@ public class TwoLineListItem extends VBox {
 
             FXUtils.setOverflowHidden(tagsBox);
 
-            lblTitle.setMinWidth(Label.USE_PREF_SIZE);
+            HBox.setHgrow(lblTitle, Priority.ALWAYS);
+            lblTitle.setMinWidth(0);
             firstLine.getChildren().setAll(lblTitle, tagsBox);
         }
         return tags;
     }
 
+    /// Reports its natural width separately from the width used to allocate space within the title row.
+    @NotNullByDefault
+    private static final class TagsBox extends HBox {
+
+        /// Creates a tag container with zero minimum and preferred allocation widths.
+        private TagsBox() {
+            super(8);
+            // Start at zero during HBox allocation so tags do not compete with the title for space.
+            setPrefWidth(0);
+            setMinWidth(0);
+        }
+
+        /// Returns the computed preferred width without applying the zero preferred-width override.
+        ///
+        /// @param height the available height, or -1 if unspecified
+        /// @return the natural preferred width of the tags and their container
+        private double computeNaturalPrefWidth(double height) {
+            return super.computePrefWidth(height);
+        }
+    }
+
     public void addTag(String tag, PseudoClass pseudoClass) {
-        var tagLabel = new Label(tag);
-        tagLabel.getStyleClass().add("tag");
-        tagLabel.setMinWidth(Label.USE_PREF_SIZE);
-        if (pseudoClass != null)
-            tagLabel.pseudoClassStateChanged(pseudoClass, true);
-        getTags().add(tagLabel);
+        getTags().add(createTag(tag, pseudoClass));
     }
 
     public void addTag(String tag) {
         addTag(tag, null);
     }
 
+    public void addTags(Collection<String> tags) {
+        getTags().addAll(tags.stream().map(tag -> createTag(tag, null)).toList());
+    }
+
+    public void addTagsIfNotExist(Collection<String> tags) {
+        var current = getTags().stream().map(Label::getText).collect(Collectors.toSet());
+        var target = new LinkedHashSet<>(tags);
+        target.removeAll(current);
+        addTags(target);
+    }
+
     private static final PseudoClass WARNING_PSEUDO_CLASS = PseudoClass.getPseudoClass("warning");
 
     public void addTagWarning(String tag) {

HMCL/src/main/java/org/jackhuang/hmcl/ui/decorator/DecoratorController.java

@@ -1,253 +0,0 @@
-/*
- * Hello Minecraft! Launcher
- * Copyright (C) 2021  huangyuhui <huanghongxun2008@126.com> and contributors
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-package org.jackhuang.hmcl.ui.decorator;
-
-import com.jfoenix.controls.JFXSnackbar;
-import com.jfoenix.controls.JFXSnackbarLayout;
-import javafx.animation.Interpolator;
-import javafx.beans.property.BooleanProperty;
-import javafx.scene.Node;
-import javafx.scene.input.*;
-import javafx.scene.layout.*;
-import javafx.stage.Stage;
-import javafx.util.Duration;
-import org.jackhuang.hmcl.auth.authlibinjector.AuthlibInjectorDnD;
-import org.jackhuang.hmcl.theme.Themes;
-import org.jackhuang.hmcl.ui.Controllers;
-import org.jackhuang.hmcl.ui.DialogUtils;
-import org.jackhuang.hmcl.ui.FXUtils;
-import org.jackhuang.hmcl.ui.account.AddAuthlibInjectorServerPane;
-import org.jackhuang.hmcl.ui.animation.ContainerAnimations;
-import org.jackhuang.hmcl.ui.animation.Motion;
-import org.jackhuang.hmcl.ui.animation.TransitionPane.AnimationProducer;
-import org.jackhuang.hmcl.ui.construct.JFXDialogPane;
-import org.jackhuang.hmcl.ui.construct.Navigator;
-import org.jackhuang.hmcl.ui.wizard.Refreshable;
-import org.jackhuang.hmcl.ui.wizard.WizardProvider;
-import org.jackhuang.hmcl.util.platform.OperatingSystem;
-
-import static org.jackhuang.hmcl.ui.FXUtils.onEscPressed;
-
-public class DecoratorController {
-    private final Decorator decorator;
-    private final Navigator navigator;
-
-    public DecoratorController(Stage stage, Node mainPage) {
-        decorator = new Decorator(stage);
-        decorator.titleTransparentProperty().bind(Themes.titleBarTransparentProperty());
-
-        navigator = new Navigator();
-        navigator.setOnNavigated(this::onNavigated);
-        navigator.init(mainPage);
-
-        decorator.getContent().setAll(navigator);
-        decorator.onCloseNavButtonActionProperty().set(e -> close());
-        decorator.onBackNavButtonActionProperty().set(e -> back());
-        decorator.onRefreshNavButtonActionProperty().set(e -> refresh());
-
-        setupAuthlibInjectorDnD();
-
-        decorator.contentBackgroundProperty().bind(Themes.backgroundProperty());
-
-        // pass key events to current dialog / current page
-        decorator.addEventFilter(KeyEvent.ANY, e -> {
-            if (!(e.getTarget() instanceof Node t)) {
-                return;
-            }
-
-            Node newTarget;
-
-            JFXDialogPane currentDialogPane = null;
-            if (decorator.getDrawerWrapper() != null) {
-                currentDialogPane = (JFXDialogPane) decorator.getDrawerWrapper().getProperties().get(DialogUtils.PROPERTY_DIALOG_PANE_INSTANCE);
-            }
-
-            if (currentDialogPane != null && currentDialogPane.peek().isPresent()) {
-                newTarget = currentDialogPane.peek().get();
-            } else {
-                newTarget = navigator.getCurrentPage();
-            }
-            boolean needsRedirect = true;
-
-            while (t != null) {
-                if (t == newTarget) {
-                    // current event target is in newTarget
-                    needsRedirect = false;
-                    break;
-                }
-                t = t.getParent();
-            }
-            if (!needsRedirect) {
-                return;
-            }
-
-            e.consume();
-            newTarget.fireEvent(e.copyFor(e.getSource(), newTarget));
-        });
-
-        // press ESC to go back
-        onEscPressed(navigator, this::back);
-
-        // https://github.com/HMCL-dev/HMCL/issues/4290
-        if (OperatingSystem.CURRENT_OS != OperatingSystem.MACOS) {
-            // press F11 to toggle full screen
-            navigator.addEventHandler(KeyEvent.KEY_PRESSED, e -> {
-                if (e.getCode() == KeyCode.F11) {
-                    stage.setFullScreen(!stage.isFullScreen());
-                    e.consume();
-                }
-            });
-        }
-
-        navigator.addEventFilter(MouseEvent.MOUSE_CLICKED, e -> {
-            if (e.getButton() == MouseButton.BACK) {
-                back();
-                e.consume();
-            }
-        });
-    }
-
-    public Decorator getDecorator() {
-        return decorator;
-    }
-
-    // ==== Navigation ====
-
-    public void navigate(Node node, AnimationProducer animationProducer, Duration duration, Interpolator interpolator) {
-        navigator.navigate(node, animationProducer, duration, interpolator);
-    }
-
-    public BooleanProperty backableProperty() {
-        return navigator.backableProperty();
-    }
-
-    private void close() {
-        if (navigator.getCurrentPage() instanceof DecoratorPage) {
-            DecoratorPage page = (DecoratorPage) navigator.getCurrentPage();
-
-            if (page.isPageCloseable()) {
-                page.closePage();
-                return;
-            }
-        }
-        navigator.clear();
-    }
-
-    private void back() {
-        if (navigator.getCurrentPage() instanceof DecoratorPage) {
-            DecoratorPage page = (DecoratorPage) navigator.getCurrentPage();
-
-            if (page.back()) {
-                if (navigator.canGoBack()) {
-                    navigator.close();
-                }
-            }
-        } else {
-            if (navigator.canGoBack()) {
-                navigator.close();
-            }
-        }
-    }
-
-    private void refresh() {
-        if (navigator.getCurrentPage() instanceof Refreshable) {
-            Refreshable refreshable = (Refreshable) navigator.getCurrentPage();
-
-            if (refreshable.refreshableProperty().get())
-                refreshable.refresh();
-        }
-    }
-
-    private void onNavigated(Navigator.NavigationEvent event) {
-        if (event.getSource() != this.navigator) return;
-        Node to = event.getNode();
-
-        if (to instanceof Refreshable) {
-            decorator.canRefreshProperty().bind(((Refreshable) to).refreshableProperty());
-        } else {
-            decorator.canRefreshProperty().unbind();
-            decorator.canRefreshProperty().set(false);
-        }
-
-        decorator.canCloseProperty().set(navigator.size() > 2);
-
-        if (to instanceof DecoratorPage) {
-            decorator.showCloseAsHomeProperty().set(!((DecoratorPage) to).isPageCloseable());
-        } else {
-            decorator.showCloseAsHomeProperty().set(true);
-        }
-
-        decorator.setNavigationDirection(event.getDirection());
-
-        // state property should be updated at last.
-        if (to instanceof DecoratorPage) {
-            decorator.stateProperty().bind(((DecoratorPage) to).stateProperty());
-        } else {
-            decorator.stateProperty().unbind();
-            decorator.stateProperty().set(new DecoratorPage.State("", null, navigator.canGoBack(), false, true));
-        }
-
-        if (to instanceof Region) {
-            Region region = (Region) to;
-            // Let root pane fix window size.
-            StackPane parent = (StackPane) region.getParent();
-            region.prefWidthProperty().bind(parent.widthProperty());
-            region.prefHeightProperty().bind(parent.heightProperty());
-        }
-    }
-
-    // ==== Dialog ====
-    public void showDialog(Node node) {
-        DialogUtils.show(decorator, node);
-    }
-
-    private void closeDialog(Node node) {
-        DialogUtils.close(node);
-    }
-
-    public void showDialogLater(Node node) {
-        DialogUtils.showLater(decorator, node);
-    }
-
-    // ==== Toast ====
-
-    public void showToast(String content) {
-        decorator.getSnackbar().fireEvent(new JFXSnackbar.SnackbarEvent(new JFXSnackbarLayout(content)));
-    }
-
-    // ==== Wizard ====
-
-    public void startWizard(WizardProvider wizardProvider) {
-        startWizard(wizardProvider, null);
-    }
-
-    public void startWizard(WizardProvider wizardProvider, String category) {
-        FXUtils.checkFxUserThread();
-
-        navigator.navigate(new DecoratorWizardDisplayer(wizardProvider, category),
-                ContainerAnimations.FORWARD, Motion.SHORT4, Motion.EASE);
-    }
-
-    // ==== Authlib Injector DnD ====
-
-    private void setupAuthlibInjectorDnD() {
-        decorator.addEventFilter(DragEvent.DRAG_OVER, AuthlibInjectorDnD.dragOverHandler());
-        decorator.addEventFilter(DragEvent.DRAG_DROPPED, AuthlibInjectorDnD.dragDroppedHandler(
-                url -> Controllers.dialog(new AddAuthlibInjectorServerPane(url))));
-    }
-}

HMCL/src/main/java/org/jackhuang/hmcl/ui/decorator/DecoratorSkin.java

@@ -1,602 +0,0 @@
-/*
- * Hello Minecraft! Launcher
- * Copyright (C) 2020  huangyuhui <huanghongxun2008@126.com> and contributors
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-package org.jackhuang.hmcl.ui.decorator;
-
-import com.jfoenix.controls.JFXButton;
-import javafx.animation.Interpolator;
-import javafx.animation.KeyFrame;
-import javafx.animation.KeyValue;
-import javafx.animation.Timeline;
-import javafx.beans.InvalidationListener;
-import javafx.beans.WeakInvalidationListener;
-import javafx.beans.binding.Bindings;
-import javafx.collections.ListChangeListener;
-import javafx.event.EventHandler;
-import javafx.geometry.Bounds;
-import javafx.geometry.Insets;
-import javafx.geometry.Pos;
-import javafx.scene.Cursor;
-import javafx.scene.Node;
-import javafx.scene.control.Label;
-import javafx.scene.control.SkinBase;
-import javafx.scene.effect.BlurType;
-import javafx.scene.effect.DropShadow;
-import javafx.scene.input.MouseButton;
-import javafx.scene.input.MouseEvent;
-import javafx.scene.layout.*;
-import javafx.scene.paint.Color;
-import javafx.scene.shape.Rectangle;
-import javafx.stage.Stage;
-
-import javafx.util.Duration;
-import org.glavo.monetfx.ColorRole;
-import org.jackhuang.hmcl.Metadata;
-import org.jackhuang.hmcl.theme.Themes;
-import org.jackhuang.hmcl.ui.FXUtils;
-import org.jackhuang.hmcl.ui.SVG;
-import org.jackhuang.hmcl.ui.animation.ContainerAnimations;
-import org.jackhuang.hmcl.ui.animation.Motion;
-import org.jackhuang.hmcl.ui.animation.TransitionPane;
-import org.jackhuang.hmcl.ui.wizard.Navigation;
-import org.jackhuang.hmcl.util.platform.OperatingSystem;
-
-public class DecoratorSkin extends SkinBase<Decorator> {
-    private final StackPane root, parent;
-    private final StackPane titleContainer;
-    private final Stage primaryStage;
-    private final TransitionPane navBarPane;
-
-    @SuppressWarnings("FieldCanBeLocal")
-    private final InvalidationListener onWindowsStatusChange;
-    private final EventHandler<MouseEvent> onTitleBarDoubleClick;
-
-    private double mouseInitX, mouseInitY, stageInitX, stageInitY, stageInitWidth, stageInitHeight;
-
-    /**
-     * Constructor for all SkinBase instances.
-     *
-     * @param control The control for which this Skin should attach to.
-     */
-    public DecoratorSkin(Decorator control) {
-        super(control);
-
-        primaryStage = control.getPrimaryStage();
-
-        Decorator skinnable = getSkinnable();
-        root = new StackPane();
-        root.getStyleClass().add("window");
-
-        StackPane shadowContainer = new StackPane();
-        shadowContainer.getStyleClass().add("body");
-        shadowContainer.setEffect(new DropShadow(BlurType.ONE_PASS_BOX, Color.rgb(0, 0, 0, 0.4), 10, 0.3, 0.0, 0.0));
-
-        parent = new StackPane();
-        Rectangle clip = new Rectangle();
-        clip.widthProperty().bind(parent.widthProperty());
-        clip.heightProperty().bind(parent.heightProperty());
-        clip.setArcWidth(8);
-        clip.setArcHeight(8);
-        parent.setClip(clip);
-
-        skinnable.getSnackbar().registerSnackbarContainer(parent);
-
-        EventHandler<MouseEvent> onMouseReleased = this::onMouseReleased;
-        EventHandler<MouseEvent> onMouseDragged = this::onMouseDragged;
-        EventHandler<MouseEvent> onMouseMoved = this::onMouseMoved;
-
-        // https://github.com/HMCL-dev/HMCL/issues/4290
-        if (OperatingSystem.CURRENT_OS != OperatingSystem.MACOS) {
-            onWindowsStatusChange = observable -> {
-                if (primaryStage.isIconified() || primaryStage.isFullScreen() || primaryStage.isMaximized()) {
-                    root.removeEventFilter(MouseEvent.MOUSE_RELEASED, onMouseReleased);
-                    root.removeEventFilter(MouseEvent.MOUSE_DRAGGED, onMouseDragged);
-                    root.removeEventFilter(MouseEvent.MOUSE_MOVED, onMouseMoved);
-                } else {
-                    root.addEventFilter(MouseEvent.MOUSE_RELEASED, onMouseReleased);
-                    root.addEventFilter(MouseEvent.MOUSE_DRAGGED, onMouseDragged);
-                    root.addEventFilter(MouseEvent.MOUSE_MOVED, onMouseMoved);
-                }
-            };
-            onTitleBarDoubleClick = event -> {
-                if (event.getButton() == MouseButton.PRIMARY && event.getClickCount() == 2) {
-                    primaryStage.setMaximized(!primaryStage.isMaximized());
-                    event.consume();
-                }
-            };
-            WeakInvalidationListener weakOnWindowsStatusChange = new WeakInvalidationListener(onWindowsStatusChange);
-            primaryStage.iconifiedProperty().addListener(weakOnWindowsStatusChange);
-            primaryStage.maximizedProperty().addListener(weakOnWindowsStatusChange);
-            primaryStage.fullScreenProperty().addListener(weakOnWindowsStatusChange);
-            onWindowsStatusChange.invalidated(null);
-        } else {
-            onWindowsStatusChange = null;
-            onTitleBarDoubleClick = null;
-            root.addEventFilter(MouseEvent.MOUSE_RELEASED, onMouseReleased);
-            root.addEventFilter(MouseEvent.MOUSE_DRAGGED, onMouseDragged);
-            root.addEventFilter(MouseEvent.MOUSE_MOVED, onMouseMoved);
-        }
-
-        shadowContainer.getChildren().setAll(parent);
-        root.getChildren().setAll(shadowContainer);
-
-        StackPane wrapper = new StackPane();
-        wrapper.backgroundProperty().bind(Bindings.createObjectBinding(
-                () -> Themes.windowTransparentProperty().get()
-                        ? null
-                        : new Background(new BackgroundFill(
-                                Themes.getColorScheme().getColor(ColorRole.SURFACE_CONTAINER),
-                                CornerRadii.EMPTY,
-                                Insets.EMPTY)),
-                Themes.windowTransparentProperty(),
-                Themes.colorSchemeProperty()));
-
-        Region backgroundNode = new Region();
-        backgroundNode.setMouseTransparent(true);
-        backgroundNode.backgroundProperty().bind(Bindings.createObjectBinding(
-                () -> skinnable.getContentBackground() == null
-                        ? null
-                        : skinnable.getContentBackground().background(),
-                skinnable.contentBackgroundProperty()));
-        backgroundNode.opacityProperty().bind(Bindings.createDoubleBinding(
-                () -> skinnable.getContentBackground() == null
-                        ? 1.0
-                        : skinnable.getContentBackground().opacity(),
-                skinnable.contentBackgroundProperty()));
-        StackPane.setAlignment(backgroundNode, Pos.BOTTOM_CENTER);
-
-        BorderPane frame = new BorderPane();
-        frame.getStyleClass().addAll("jfx-decorator");
-        wrapper.getChildren().setAll(backgroundNode, frame);
-        skinnable.setDrawerWrapper(wrapper);
-
-        parent.getChildren().add(wrapper);
-
-        // center node with an animation layer at bottom, a container layer at middle and a "welcome" layer at top.
-        StackPane container = new StackPane();
-        FXUtils.setOverflowHidden(container);
-
-        // content layer at middle
-        {
-            StackPane contentPlaceHolder = new StackPane();
-            contentPlaceHolder.getStyleClass().add("jfx-decorator-content-container");
-            Bindings.bindContent(contentPlaceHolder.getChildren(), skinnable.contentProperty());
-
-            container.getChildren().add(contentPlaceHolder);
-        }
-
-        // welcome and hint layer at top
-        {
-            StackPane floatLayer = new StackPane();
-            Bindings.bindContent(floatLayer.getChildren(), skinnable.containerProperty());
-            ListChangeListener<Node> listener = c -> {
-                if (skinnable.getContainer().isEmpty()) {
-                    floatLayer.setMouseTransparent(true);
-                    floatLayer.setVisible(false);
-                } else {
-                    floatLayer.setMouseTransparent(false);
-                    floatLayer.setVisible(true);
-                }
-            };
-            skinnable.containerProperty().addListener(listener);
-            listener.onChanged(null);
-
-            container.getChildren().add(floatLayer);
-        }
-
-        frame.setCenter(container);
-
-        titleContainer = new StackPane();
-        titleContainer.setPickOnBounds(false);
-        titleContainer.getStyleClass().addAll("jfx-tool-bar");
-        backgroundNode.maxHeightProperty().bind(Bindings.createDoubleBinding(
-                () -> Math.max(0.0, wrapper.getHeight()
-                        - (skinnable.isTitleTransparent() ? 0.0 : titleContainer.getHeight())),
-                wrapper.heightProperty(),
-                skinnable.titleTransparentProperty(),
-                titleContainer.heightProperty()));
-
-        // Maybe, we can automatically identify whether the top part of the picture is light-coloured or dark when the title is transparent,
-        // and decide whether the whole top bar should be rendered in white or black. TODO
-        FXUtils.onChangeAndOperate(skinnable.titleTransparentProperty(), titleTransparent -> {
-            if (titleTransparent) {
-                titleContainer.getStyleClass().remove("background");
-                titleContainer.getStyleClass().add("gray-background");
-            } else {
-                titleContainer.getStyleClass().add("background");
-                titleContainer.getStyleClass().remove("gray-background");
-            }
-        });
-
-        control.capableDraggingWindow(titleContainer);
-
-        BorderPane titleBar = new BorderPane();
-        titleContainer.getChildren().add(titleBar);
-
-        Rectangle buttonsContainerPlaceHolder = new Rectangle();
-        {
-            navBarPane = new TransitionPane();
-            navBarPane.setId("decoratorTitleTransitionPane");
-            FXUtils.onChangeAndOperate(skinnable.stateProperty(), s -> {
-                if (s == null) return;
-                Node node = createNavBar(skinnable, s.leftPaneWidth(), s.backable(), skinnable.canCloseProperty().get(), skinnable.showCloseAsHomeProperty().get(), s.refreshable(), s.title(), s.titleNode());
-                if (s.animate()) {
-                    TransitionPane.AnimationProducer animation = switch (skinnable.getNavigationDirection()) {
-                        case NEXT -> NavBarAnimations.NEXT;
-                        case PREVIOUS -> NavBarAnimations.PREVIOUS;
-                        default -> ContainerAnimations.FADE;
-                    };
-                    skinnable.setNavigationDirection(Navigation.NavigationDirection.START);
-                    navBarPane.setContent(node, animation, Motion.SHORT4);
-                } else {
-                    navBarPane.getChildren().setAll(node);
-                }
-            });
-            titleBar.setCenter(navBarPane);
-            titleBar.setRight(buttonsContainerPlaceHolder);
-        }
-        frame.setTop(titleContainer);
-
-        {
-            HBox buttonsContainer = new HBox();
-            buttonsContainer.setAlignment(Pos.TOP_RIGHT);
-            buttonsContainer.setMaxHeight(40);
-            {
-                JFXButton btnHelp = new JFXButton();
-                btnHelp.setFocusTraversable(false);
-                btnHelp.setGraphic(SVG.HELP.createIcon(Themes.titleFillProperty()));
-                btnHelp.getStyleClass().add("jfx-decorator-button");
-                btnHelp.setOnAction(e -> FXUtils.openLink(Metadata.CONTACT_URL));
-
-                JFXButton btnMin = new JFXButton();
-                btnMin.setFocusTraversable(false);
-                btnMin.setGraphic(SVG.MINIMIZE_CENTER.createIcon(Themes.titleFillProperty()));
-                btnMin.getStyleClass().add("jfx-decorator-button");
-                btnMin.setOnAction(e -> skinnable.minimize());
-
-                JFXButton btnClose = new JFXButton();
-                btnClose.setFocusTraversable(false);
-                btnClose.setGraphic(SVG.CLOSE.createIcon(Themes.titleFillProperty()));
-                btnClose.getStyleClass().add("jfx-decorator-button");
-                btnClose.setOnAction(e -> skinnable.close());
-
-                buttonsContainer.getChildren().setAll(btnHelp, btnMin, btnClose);
-            }
-            AnchorPane layer = new AnchorPane();
-            layer.setPickOnBounds(false);
-            layer.getChildren().add(buttonsContainer);
-            AnchorPane.setTopAnchor(buttonsContainer, 0.0);
-            AnchorPane.setRightAnchor(buttonsContainer, 0.0);
-            buttonsContainerPlaceHolder.widthProperty().bind(buttonsContainer.widthProperty());
-            parent.getChildren().add(layer);
-        }
-
-        getChildren().add(root);
-    }
-
-    private Node createNavBar(Decorator skinnable, double leftPaneWidth, boolean canBack, boolean canClose, boolean showCloseAsHome, boolean canRefresh, String title, Node titleNode) {
-        BorderPane navBar = new BorderPane();
-        navBar.getStyleClass().add("navigation-bar");
-
-        {
-            HBox navLeft = new HBox();
-            navLeft.setAlignment(Pos.CENTER_LEFT);
-            navLeft.setPadding(new Insets(0, 5, 0, 5));
-
-            if (canBack) {
-                JFXButton backNavButton = new JFXButton();
-                skinnable.forbidDraggingWindow(backNavButton);
-                backNavButton.setFocusTraversable(false);
-                backNavButton.setGraphic(SVG.ARROW_BACK.createIcon(Themes.titleFillProperty()));
-                backNavButton.getStyleClass().add("jfx-decorator-button");
-                backNavButton.onActionProperty().bind(skinnable.onBackNavButtonActionProperty());
-                backNavButton.visibleProperty().set(canBack);
-
-                navLeft.getChildren().add(backNavButton);
-            }
-
-            if (canClose) {
-                JFXButton closeNavButton = new JFXButton();
-                skinnable.forbidDraggingWindow(closeNavButton);
-                closeNavButton.setFocusTraversable(false);
-                closeNavButton.setGraphic(SVG.CLOSE.createIcon(Themes.titleFillProperty()));
-                closeNavButton.getStyleClass().add("jfx-decorator-button");
-                closeNavButton.onActionProperty().bind(skinnable.onCloseNavButtonActionProperty());
-                if (showCloseAsHome)
-                    closeNavButton.setGraphic(SVG.HOME.createIcon(Themes.titleFillProperty()));
-                else
-                    closeNavButton.setGraphic(SVG.CLOSE.createIcon(Themes.titleFillProperty()));
-
-                navLeft.getChildren().add(closeNavButton);
-            }
-
-            if (canBack || canClose) {
-                navBar.setLeft(navLeft);
-            }
-
-            BorderPane center = new BorderPane();
-            if (title != null) {
-                Label titleLabel = new Label();
-                titleLabel.textFillProperty().bind(Themes.titleFillProperty());
-                BorderPane.setAlignment(titleLabel, Pos.CENTER_LEFT);
-                titleLabel.getStyleClass().add("jfx-decorator-title");
-                if (titleNode == null) {
-                    titleLabel.maxWidthProperty().bind(Bindings.createDoubleBinding(
-                            () -> skinnable.getWidth() - 150 - navLeft.getWidth(),
-                            skinnable.widthProperty(), navLeft.widthProperty()));
-                } else {
-                    titleLabel.prefWidthProperty().bind(Bindings.createDoubleBinding(() -> {
-                        // 8 (margin-left)
-                        return leftPaneWidth - 8 - navLeft.getWidth();
-                    }, navLeft.widthProperty()));
-                }
-                titleLabel.setText(title);
-                center.setLeft(titleLabel);
-                BorderPane.setAlignment(titleLabel, Pos.CENTER_LEFT);
-            }
-            if (titleNode != null) {
-                center.setCenter(titleNode);
-                BorderPane.setAlignment(titleNode, Pos.CENTER_LEFT);
-                BorderPane.setMargin(titleNode, new Insets(0, 0, 0, 8));
-            }
-            if (onTitleBarDoubleClick != null)
-                center.setOnMouseClicked(onTitleBarDoubleClick);
-            center.setOnMouseDragged(mouseEvent -> {
-                if (!getSkinnable().isDragging() && primaryStage.isMaximized()) {
-                    getSkinnable().setDragging(true);
-                    mouseInitX = mouseEvent.getScreenX();
-                    mouseInitY = mouseEvent.getScreenY();
-                    primaryStage.setMaximized(false);
-                    stageInitWidth = primaryStage.getWidth();
-                    stageInitHeight = primaryStage.getHeight();
-                    primaryStage.setY(stageInitY = 0);
-                    primaryStage.setX(stageInitX = mouseInitX - stageInitWidth / 2);
-                }
-            });
-            navBar.setCenter(center);
-
-            if (canRefresh) {
-                HBox navRight = new HBox();
-                navRight.setAlignment(Pos.CENTER_RIGHT);
-                JFXButton refreshNavButton = new JFXButton();
-                refreshNavButton.setGraphic(SVG.REFRESH.createIcon(Themes.titleFillProperty()));
-                refreshNavButton.getStyleClass().add("jfx-decorator-button");
-                refreshNavButton.onActionProperty().bind(skinnable.onRefreshNavButtonActionProperty());
-                skinnable.forbidDraggingWindow(refreshNavButton);
-
-                navRight.getChildren().setAll(refreshNavButton);
-                navBar.setRight(navRight);
-            }
-        }
-        return navBar;
-    }
-
-    private boolean isRightEdge(double x, double y, Bounds boundsInParent) {
-        return x < root.getWidth() && x >= root.getWidth() - root.snappedLeftInset();
-    }
-
-    private boolean isTopEdge(double x, double y, Bounds boundsInParent) {
-        return y >= 0 && y <= root.snappedTopInset();
-    }
-
-    private boolean isBottomEdge(double x, double y, Bounds boundsInParent) {
-        return y < root.getHeight() && y >= root.getHeight() - root.snappedLeftInset();
-    }
-
-    private boolean isLeftEdge(double x, double y, Bounds boundsInParent) {
-        return x >= 0 && x <= root.snappedLeftInset();
-    }
-
-    private void resizeStage(double newWidth, double newHeight) {
-        if (newWidth < 0)
-            newWidth = primaryStage.getWidth();
-        if (newWidth < primaryStage.getMinWidth())
-            newWidth = primaryStage.getMinWidth();
-        if (newWidth < titleContainer.getMinWidth())
-            newWidth = titleContainer.getMinWidth();
-
-        if (newHeight < 0)
-            newHeight = primaryStage.getHeight();
-        if (newHeight < primaryStage.getMinHeight())
-            newHeight = primaryStage.getMinHeight();
-        if (newHeight < titleContainer.getMinHeight())
-            newHeight = titleContainer.getMinHeight();
-
-        // Width and height must be set simultaneously to avoid JDK-8344372 (https://github.com/openjdk/jfx/pull/1654)
-        primaryStage.setWidth(newWidth);
-        primaryStage.setHeight(newHeight);
-    }
-
-    private void onMouseMoved(MouseEvent mouseEvent) {
-        if (!primaryStage.isFullScreen() && primaryStage.isResizable()) {
-            double x = mouseEvent.getX(), y = mouseEvent.getY();
-            Bounds boundsInParent = root.getBoundsInParent();
-            double diagonalSize = root.snappedLeftInset() + 10;
-            if (this.isRightEdge(x, y, boundsInParent)) {
-                if (y < diagonalSize) {
-                    root.setCursor(Cursor.NE_RESIZE);
-                } else if (y > root.getHeight() - diagonalSize) {
-                    root.setCursor(Cursor.SE_RESIZE);
-                } else {
-                    root.setCursor(Cursor.E_RESIZE);
-                }
-            } else if (this.isLeftEdge(x, y, boundsInParent)) {
-                if (y < diagonalSize) {
-                    root.setCursor(Cursor.NW_RESIZE);
-                } else if (y > root.getHeight() - diagonalSize) {
-                    root.setCursor(Cursor.SW_RESIZE);
-                } else {
-                    root.setCursor(Cursor.W_RESIZE);
-                }
-            } else if (this.isTopEdge(x, y, boundsInParent)) {
-                if (x < diagonalSize) {
-                    root.setCursor(Cursor.NW_RESIZE);
-                } else if (x > root.getWidth() - diagonalSize) {
-                    root.setCursor(Cursor.NE_RESIZE);
-                } else {
-                    root.setCursor(Cursor.N_RESIZE);
-                }
-            } else if (this.isBottomEdge(x, y, boundsInParent)) {
-                if (x < diagonalSize) {
-                    root.setCursor(Cursor.SW_RESIZE);
-                } else if (x > root.getWidth() - diagonalSize) {
-                    root.setCursor(Cursor.SE_RESIZE);
-                } else {
-                    root.setCursor(Cursor.S_RESIZE);
-                }
-            } else {
-                root.setCursor(Cursor.DEFAULT);
-            }
-        } else {
-            root.setCursor(Cursor.DEFAULT);
-        }
-    }
-
-    private void onMouseReleased(MouseEvent mouseEvent) {
-        getSkinnable().setDragging(false);
-    }
-
-    private void onMouseDragged(MouseEvent mouseEvent) {
-        if (!getSkinnable().isDragging()) {
-            getSkinnable().setDragging(true);
-            mouseInitX = mouseEvent.getScreenX();
-            mouseInitY = mouseEvent.getScreenY();
-            stageInitX = primaryStage.getX();
-            stageInitY = primaryStage.getY();
-            stageInitWidth = primaryStage.getWidth();
-            stageInitHeight = primaryStage.getHeight();
-        }
-
-        if (primaryStage.isFullScreen() || !mouseEvent.isPrimaryButtonDown() || mouseEvent.isStillSincePress())
-            return;
-
-        double dx = mouseEvent.getScreenX() - mouseInitX;
-        double dy = mouseEvent.getScreenY() - mouseInitY;
-
-        Cursor cursor = root.getCursor();
-        if (getSkinnable().isAllowMove()) {
-            if (cursor == Cursor.DEFAULT) {
-                primaryStage.setX(stageInitX + dx);
-                primaryStage.setY(stageInitY + dy);
-                mouseEvent.consume();
-            }
-        }
-
-        if (getSkinnable().isResizable()) {
-            if (cursor == Cursor.E_RESIZE) {
-                resizeStage(stageInitWidth + dx, -1);
-                mouseEvent.consume();
-
-            } else if (cursor == Cursor.S_RESIZE) {
-                resizeStage(-1, stageInitHeight + dy);
-                mouseEvent.consume();
-
-            } else if (cursor == Cursor.W_RESIZE) {
-                resizeStage(stageInitWidth - dx, -1);
-                primaryStage.setX(stageInitX + stageInitWidth - primaryStage.getWidth());
-                mouseEvent.consume();
-
-            } else if (cursor == Cursor.N_RESIZE) {
-                resizeStage(-1, stageInitHeight - dy);
-                primaryStage.setY(stageInitY + stageInitHeight - primaryStage.getHeight());
-                mouseEvent.consume();
-
-            } else if (cursor == Cursor.SE_RESIZE) {
-                resizeStage(stageInitWidth + dx, stageInitHeight + dy);
-                mouseEvent.consume();
-
-            } else if (cursor == Cursor.SW_RESIZE) {
-                resizeStage(stageInitWidth - dx, stageInitHeight + dy);
-                primaryStage.setX(stageInitX + stageInitWidth - primaryStage.getWidth());
-                mouseEvent.consume();
-
-            } else if (cursor == Cursor.NW_RESIZE) {
-                resizeStage(stageInitWidth - dx, stageInitHeight - dy);
-                primaryStage.setX(stageInitX + stageInitWidth - primaryStage.getWidth());
-                primaryStage.setY(stageInitY + stageInitHeight - primaryStage.getHeight());
-                mouseEvent.consume();
-
-            } else if (cursor == Cursor.NE_RESIZE) {
-                resizeStage(stageInitWidth + dx, stageInitHeight - dy);
-                primaryStage.setY(stageInitY + stageInitHeight - primaryStage.getHeight());
-                mouseEvent.consume();
-            }
-        }
-    }
-
-    enum NavBarAnimations implements TransitionPane.AnimationProducer {
-        NEXT {
-            @Override
-            public void init(TransitionPane container, Node previousNode, Node nextNode) {
-                super.init(container, previousNode, nextNode);
-                nextNode.setTranslateX(container.getWidth());
-            }
-
-            @Override
-            public Timeline animate(
-                    Pane container, Node previousNode, Node nextNode,
-                    Duration duration, Interpolator interpolator) {
-                return new Timeline(
-                        new KeyFrame(Duration.ZERO,
-                                new KeyValue(nextNode.translateXProperty(), 50, interpolator),
-                                new KeyValue(previousNode.translateXProperty(), 0, interpolator),
-                                new KeyValue(nextNode.opacityProperty(), 0, interpolator),
-                                new KeyValue(previousNode.opacityProperty(), 1, interpolator)),
-                        new KeyFrame(duration,
-                                new KeyValue(nextNode.translateXProperty(), 0, interpolator),
-                                new KeyValue(previousNode.translateXProperty(), -50, interpolator),
-                                new KeyValue(nextNode.opacityProperty(), 1, interpolator),
-                                new KeyValue(previousNode.opacityProperty(), 0, interpolator))
-                );
-            }
-
-            @Override
-            public TransitionPane.AnimationProducer opposite() {
-                return NEXT;
-            }
-        },
-
-        PREVIOUS {
-            @Override
-            public void init(TransitionPane container, Node previousNode, Node nextNode) {
-                super.init(container, previousNode, nextNode);
-                nextNode.setTranslateX(container.getWidth());
-            }
-
-            @Override
-            public Timeline animate(Pane container, Node previousNode, Node nextNode, Duration duration, Interpolator interpolator) {
-                return new Timeline(
-                        new KeyFrame(Duration.ZERO,
-                                new KeyValue(nextNode.translateXProperty(), -50, interpolator),
-                                new KeyValue(previousNode.translateXProperty(), 0, interpolator),
-                                new KeyValue(nextNode.opacityProperty(), 0, interpolator),
-                                new KeyValue(previousNode.opacityProperty(), 1, interpolator)),
-                        new KeyFrame(duration,
-                                new KeyValue(nextNode.translateXProperty(), 0, interpolator),
-                                new KeyValue(previousNode.translateXProperty(), 50, interpolator),
-                                new KeyValue(nextNode.opacityProperty(), 1, interpolator),
-                                new KeyValue(previousNode.opacityProperty(), 0, interpolator))
-                );
-            }
-
-            @Override
-            public TransitionPane.AnimationProducer opposite() {
-                return PREVIOUS;
-            }
-        };
-    }
-}

HMCL/src/main/java/org/jackhuang/hmcl/ui/decorator/MainWindowPane.java

@@ -0,0 +1,424 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.ui.decorator;
+
+import com.jfoenix.controls.JFXButton;
+import javafx.animation.Interpolator;
+import javafx.animation.KeyFrame;
+import javafx.animation.KeyValue;
+import javafx.animation.Timeline;
+import javafx.beans.InvalidationListener;
+import javafx.beans.binding.Bindings;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import javafx.scene.Node;
+import javafx.scene.control.Label;
+import javafx.scene.layout.Background;
+import javafx.scene.layout.BackgroundFill;
+import javafx.scene.layout.BorderPane;
+import javafx.scene.layout.CornerRadii;
+import javafx.scene.layout.HBox;
+import javafx.scene.layout.Pane;
+import javafx.scene.layout.Priority;
+import javafx.scene.layout.Region;
+import javafx.scene.layout.StackPane;
+import javafx.scene.paint.Color;
+import javafx.scene.shape.Rectangle;
+import javafx.util.Duration;
+import org.glavo.monetfx.ColorRole;
+import org.glavo.monetfx.ColorScheme;
+import org.jackhuang.hmcl.Metadata;
+import org.jackhuang.hmcl.theme.Themes;
+import org.jackhuang.hmcl.ui.FXUtils;
+import org.jackhuang.hmcl.ui.SVG;
+import org.jackhuang.hmcl.ui.WeakListenerHolder;
+import org.jackhuang.hmcl.ui.animation.ContainerAnimations;
+import org.jackhuang.hmcl.ui.animation.Motion;
+import org.jackhuang.hmcl.ui.animation.TransitionPane;
+import org.jackhuang.hmcl.ui.wizard.Navigation;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
+
+/// Renders the clipped background, title bar, and navigation content owned by a [Decorator].
+@NotNullByDefault
+final class MainWindowPane extends StackPane {
+    /// The diameter, in pixels, of the rounded window corners.
+    private static final double ARC = 8.0;
+
+    /// The decorator whose state and actions are represented by this pane.
+    private final Decorator decorator;
+
+    /// The content clip, rounded only for normal windows with custom decoration.
+    private final Rectangle clip = new Rectangle();
+
+    /// The frame containing the title bar and current navigation page.
+    private final BorderPane frame;
+
+    /// The title bar containing page navigation state.
+    private final BorderPane titleBar;
+
+    /// The custom help, minimize, and close buttons shared by both decoration styles.
+    private final HBox windowButtons;
+
+    /// The transition container used when the title-bar state changes.
+    private final TransitionPane navBarPane;
+
+    /// Retains listener delegates that are registered through weak listener wrappers.
+    @SuppressWarnings("FieldCanBeLocal")
+    private final WeakListenerHolder holder = new WeakListenerHolder();
+
+    /// Creates and wires the main-window content for `decorator`.
+    ///
+    /// @param decorator the owning window decorator
+    MainWindowPane(Decorator decorator) {
+        this.decorator = decorator;
+
+        clip.widthProperty().bind(widthProperty());
+        clip.heightProperty().bind(heightProperty());
+        clip.setArcWidth(ARC);
+        clip.setArcHeight(ARC);
+        setClip(clip);
+
+        backgroundProperty().bind(Bindings.createObjectBinding(
+                () -> Themes.windowTransparentProperty().get()
+                        ? null
+                        : new Background(new BackgroundFill(
+                        Themes.getColorScheme().getColor(ColorRole.SURFACE_CONTAINER),
+                        CornerRadii.EMPTY,
+                        Insets.EMPTY)),
+                Themes.windowTransparentProperty(),
+                Themes.colorSchemeProperty()));
+
+        Region backgroundNode = createBackgroundNode();
+
+        frame = new BorderPane();
+        frame.getStyleClass().add("jfx-decorator");
+
+        StackPane center = new StackPane();
+        center.getStyleClass().add("jfx-decorator-content-container");
+        FXUtils.setOverflowHidden(center);
+        center.getChildren().setAll(decorator.getNavigator());
+        frame.setCenter(center);
+
+        windowButtons = createWindowButtons();
+        titleBar = new BorderPane();
+        titleBar.setPickOnBounds(false);
+        titleBar.getStyleClass().add("jfx-tool-bar");
+        titleBar.setRight(windowButtons);
+
+        navBarPane = new TransitionPane();
+        titleBar.setCenter(navBarPane);
+        decorator.capableDraggingWindow(navBarPane);
+        frame.setTop(titleBar);
+
+        updateTitleBarBackground();
+        InvalidationListener titleBarBackgroundListener = observable -> updateTitleBarBackground();
+        Themes.colorSchemeProperty().addListener(holder.weak(titleBarBackgroundListener));
+        Themes.titleBarTransparentProperty().addListener(holder.weak(titleBarBackgroundListener));
+
+        InvalidationListener navBarListener = observable -> updateNavBar();
+        decorator.stateProperty().addListener(holder.weak(navBarListener));
+        updateNavBar();
+
+        decorator.capableDraggingWindow(titleBar);
+
+        getChildren().setAll(backgroundNode, frame);
+    }
+
+    /// Moves the custom title bar into or out of the native dragging header.
+    ///
+    /// @param decoration the native header support, or `null` for custom decoration
+    void setNativeDecoration(@Nullable NativeWindowDecoration decoration) {
+        frame.setTop(null);
+        if (decoration == null) {
+            frame.setTop(titleBar);
+        } else {
+            decoration.setContent(titleBar);
+            decoration.headerBar.backgroundProperty().bind(titleBar.backgroundProperty());
+            frame.setTop(decoration.headerBar);
+        }
+    }
+
+    /// Enables or disables custom rounding of the content corners.
+    ///
+    /// Native decoration uses square content bounds so the platform can shape the window outline.
+    ///
+    /// @param rounded whether to round the content corners
+    void setWindowCornersRounded(boolean rounded) {
+        double arc = rounded ? ARC : 0.0;
+        clip.setArcWidth(arc);
+        clip.setArcHeight(arc);
+    }
+
+    /// Creates the launcher-background layer and keeps it synchronized with the active theme.
+    ///
+    /// @return the mouse-transparent background node
+    private Region createBackgroundNode() {
+        Region backgroundNode = new Region();
+        backgroundNode.setMouseTransparent(true);
+        StackPane.setAlignment(backgroundNode, Pos.BOTTOM_CENTER);
+        holder.onWeakChangeAndOperate(Themes.backgroundProperty(), background -> {
+            double opacity = background.opacity();
+            if (opacity >= 0.001) {
+                backgroundNode.setBackground(background.background());
+                backgroundNode.setOpacity(opacity);
+            } else {
+                backgroundNode.setBackground(null);
+                backgroundNode.setOpacity(0);
+            }
+        });
+        return backgroundNode;
+    }
+
+    /// Creates the help, minimize, and application-close buttons.
+    ///
+    /// @return a size-limited top-right button row
+    private HBox createWindowButtons() {
+        HBox buttons = new HBox();
+        buttons.setAlignment(Pos.TOP_RIGHT);
+        decorator.capableDraggingWindow(buttons);
+        buttons.setMaxSize(Region.USE_PREF_SIZE, 40);
+
+        JFXButton helpButton = new JFXButton();
+        helpButton.setFocusTraversable(false);
+        helpButton.setGraphic(SVG.HELP.createIcon(Themes.titleFillProperty()));
+        helpButton.getStyleClass().add("jfx-decorator-button");
+        helpButton.setOnAction(event -> FXUtils.openLink(Metadata.CONTACT_URL));
+        decorator.forbidDraggingWindow(helpButton);
+
+        JFXButton minimizeButton = new JFXButton();
+        minimizeButton.setFocusTraversable(false);
+        minimizeButton.setGraphic(SVG.MINIMIZE_CENTER.createIcon(Themes.titleFillProperty()));
+        minimizeButton.getStyleClass().add("jfx-decorator-button");
+        minimizeButton.setOnAction(event -> decorator.minimizeWindow());
+        decorator.forbidDraggingWindow(minimizeButton);
+
+        JFXButton closeButton = new JFXButton();
+        closeButton.setFocusTraversable(false);
+        closeButton.setGraphic(SVG.CLOSE.createIcon(Themes.titleFillProperty()));
+        closeButton.getStyleClass().add("jfx-decorator-button");
+        closeButton.setOnAction(event -> decorator.closeWindow());
+        decorator.forbidDraggingWindow(closeButton);
+
+        buttons.getChildren().setAll(helpButton, minimizeButton, closeButton);
+        return buttons;
+    }
+
+    /// Recomputes the title-bar background for the current theme and transparency preference.
+    private void updateTitleBarBackground() {
+        @Nullable ColorScheme colorScheme = Themes.getColorScheme();
+        if (colorScheme == null) {
+            titleBar.setBackground(null);
+        } else if (Themes.titleBarTransparentProperty().get()) {
+            Color surface = colorScheme.getSurface();
+            titleBar.setBackground(new Background(new BackgroundFill(
+                    new Color(surface.getRed(), surface.getGreen(), surface.getBlue(), 0.5),
+                    CornerRadii.EMPTY,
+                    Insets.EMPTY)));
+        } else {
+            titleBar.setBackground(new Background(new BackgroundFill(
+                    colorScheme.getPrimaryContainer(),
+                    CornerRadii.EMPTY,
+                    Insets.EMPTY)));
+        }
+    }
+
+    /// Rebuilds the navigation bar from the current page state.
+    private void updateNavBar() {
+        DecoratorPage.@Nullable State state = decorator.getState();
+        if (state == null) {
+            navBarPane.getChildren().clear();
+            return;
+        }
+
+        Node navBar = createNavBar(state);
+
+        if (state.animate()) {
+            TransitionPane.AnimationProducer animation = switch (decorator.getNavigationDirection()) {
+                case NEXT -> NavBarAnimations.NEXT;
+                case PREVIOUS -> NavBarAnimations.PREVIOUS;
+                default -> ContainerAnimations.FADE;
+            };
+            decorator.setNavigationDirection(Navigation.NavigationDirection.START);
+            navBarPane.setContent(navBar, animation, Motion.SHORT4);
+        } else {
+            navBarPane.getChildren().setAll(navBar);
+        }
+    }
+
+    /// Creates the page-specific navigation controls and title.
+    ///
+    /// @param state the current page state
+    /// @return a newly constructed navigation bar
+    private Node createNavBar(DecoratorPage.State state) {
+        HBox navBar = new HBox();
+        navBar.setAlignment(Pos.CENTER_LEFT);
+        decorator.capableDraggingWindow(navBar);
+
+        // Left navigation buttons
+        if (state.backable()) {
+            JFXButton backButton = new JFXButton();
+            backButton.setFocusTraversable(false);
+            backButton.setGraphic(SVG.ARROW_BACK.createIcon(Themes.titleFillProperty()));
+            backButton.getStyleClass().add("jfx-decorator-button");
+            backButton.setOnAction(event -> decorator.back());
+            decorator.forbidDraggingWindow(backButton);
+            navBar.getChildren().add(backButton);
+        }
+
+        if (decorator.canCloseProperty().get()) {
+            boolean showCloseAsHome = decorator.showCloseAsHomeProperty().get();
+
+            JFXButton closeButton = new JFXButton();
+            closeButton.setFocusTraversable(false);
+            closeButton.setGraphic((showCloseAsHome ? SVG.HOME : SVG.CLOSE).createIcon(Themes.titleFillProperty()));
+            closeButton.getStyleClass().add("jfx-decorator-button");
+            closeButton.setOnAction(event -> decorator.closeCurrentPage());
+            decorator.forbidDraggingWindow(closeButton);
+            navBar.getChildren().add(closeButton);
+        }
+
+        // Center title area
+        StackPane titleArea = new StackPane();
+        titleArea.setAlignment(Pos.CENTER_LEFT);
+        titleArea.setMinWidth(0);
+        decorator.capableDraggingWindow(titleArea);
+        HBox.setHgrow(titleArea, Priority.ALWAYS);
+        if (state.titleNode() != null) {
+            titleArea.getChildren().setAll(state.titleNode());
+            StackPane.setMargin(state.titleNode(), new Insets(0, 0, 0, 8));
+        } else if (state.title() != null) {
+            Label titleLabel = new Label(state.title());
+            titleLabel.textFillProperty().bind(Themes.titleFillProperty());
+            titleLabel.getStyleClass().add("jfx-decorator-title");
+            titleLabel.setMinWidth(0);
+            titleLabel.setMouseTransparent(true);
+            titleArea.getChildren().setAll(titleLabel);
+        }
+
+        decorator.registerTitleBar(titleArea);
+
+        if (!navBar.getChildren().isEmpty()) {
+            Insets padding = new Insets(0, 0, 0, 5);
+            navBar.setPadding(padding);
+            titleArea.setPadding(padding);
+        }
+
+        navBar.getChildren().add(titleArea);
+
+        // Right refresh button
+        if (state.refreshable()) {
+            JFXButton refreshButton = new JFXButton();
+            refreshButton.setFocusTraversable(false);
+            refreshButton.setGraphic(SVG.REFRESH.createIcon(Themes.titleFillProperty()));
+            refreshButton.getStyleClass().add("jfx-decorator-button");
+            refreshButton.setOnAction(event -> decorator.refresh());
+            decorator.forbidDraggingWindow(refreshButton);
+
+            navBar.getChildren().add(refreshButton);
+        }
+
+        return navBar;
+    }
+
+    /// Produces directional transitions for page-title changes.
+    private enum NavBarAnimations implements TransitionPane.AnimationProducer {
+        /// Moves the next title in from the right.
+        NEXT {
+            /// {@inheritDoc}
+            @Override
+            public void init(TransitionPane container, Node previousNode, Node nextNode) {
+                super.init(container, previousNode, nextNode);
+                nextNode.setTranslateX(container.getWidth());
+            }
+
+            /// {@inheritDoc}
+            @Override
+            public Timeline animate(
+                    Pane container,
+                    Node previousNode,
+                    Node nextNode,
+                    Duration duration,
+                    Interpolator interpolator) {
+                return createTimeline(previousNode, nextNode, 50, -50, duration, interpolator);
+            }
+
+            /// {@inheritDoc}
+            @Override
+            public TransitionPane.AnimationProducer opposite() {
+                return PREVIOUS;
+            }
+        },
+
+        /// Moves the previous title in from the left.
+        PREVIOUS {
+            /// {@inheritDoc}
+            @Override
+            public void init(TransitionPane container, Node previousNode, Node nextNode) {
+                super.init(container, previousNode, nextNode);
+                nextNode.setTranslateX(-container.getWidth());
+            }
+
+            /// {@inheritDoc}
+            @Override
+            public Timeline animate(
+                    Pane container,
+                    Node previousNode,
+                    Node nextNode,
+                    Duration duration,
+                    Interpolator interpolator) {
+                return createTimeline(previousNode, nextNode, -50, 50, duration, interpolator);
+            }
+
+            /// {@inheritDoc}
+            @Override
+            public TransitionPane.AnimationProducer opposite() {
+                return NEXT;
+            }
+        };
+
+        /// Creates a title transition with the supplied horizontal offsets.
+        ///
+        /// @param previousNode   the title being removed
+        /// @param nextNode       the title being shown
+        /// @param nextOffset     the initial offset of the next title
+        /// @param previousOffset the final offset of the previous title
+        /// @param duration       the transition duration
+        /// @param interpolator   the transition interpolator
+        /// @return the unstarted transition timeline
+        private static Timeline createTimeline(
+                Node previousNode,
+                Node nextNode,
+                double nextOffset,
+                double previousOffset,
+                Duration duration,
+                Interpolator interpolator) {
+            return new Timeline(
+                    new KeyFrame(Duration.ZERO,
+                            new KeyValue(nextNode.translateXProperty(), nextOffset, interpolator),
+                            new KeyValue(previousNode.translateXProperty(), 0, interpolator),
+                            new KeyValue(nextNode.opacityProperty(), 0, interpolator),
+                            new KeyValue(previousNode.opacityProperty(), 1, interpolator)),
+                    new KeyFrame(duration,
+                            new KeyValue(nextNode.translateXProperty(), 0, interpolator),
+                            new KeyValue(previousNode.translateXProperty(), previousOffset, interpolator),
+                            new KeyValue(nextNode.opacityProperty(), 1, interpolator),
+                            new KeyValue(previousNode.opacityProperty(), 0, interpolator)));
+        }
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/ui/decorator/NativeWindowDecoration.java

@@ -0,0 +1,245 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.ui.decorator;
+
+import javafx.application.ConditionalFeature;
+import javafx.application.Platform;
+import javafx.collections.ListChangeListener;
+import javafx.scene.Node;
+import javafx.scene.Parent;
+import javafx.scene.control.Control;
+import javafx.scene.control.Label;
+import javafx.scene.layout.Region;
+import javafx.stage.Stage;
+import javafx.stage.StageStyle;
+import org.jackhuang.hmcl.util.platform.OSVersion;
+import org.jackhuang.hmcl.util.platform.OperatingSystem;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
+
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodHandles;
+import java.lang.invoke.MethodType;
+import java.util.Objects;
+
+import static org.jackhuang.hmcl.util.logging.Logger.LOG;
+
+/// Accesses the JavaFX 27 extended-window APIs without linking them on older runtimes.
+@NotNullByDefault
+final class NativeWindowDecoration {
+    /// Marks nodes whose title-content descendants are already observed for native hit testing.
+    private static final Object DRAG_CONFIGURED = new Object();
+
+    /// Whether the user explicitly enabled native decoration regardless of automatic platform or brightness exclusions.
+    private final boolean forced;
+
+    /// The platform-supported extended stage style.
+    final StageStyle style;
+
+    /// The header bar that supplies native dragging around the custom title content.
+    final Region headerBar;
+
+    /// Assigns the header bar's center content.
+    private final MethodHandle setCenter;
+
+    /// Assigns a node's native header hit-test behavior.
+    private final MethodHandle setDragType;
+
+    /// Reads explicit native drag exclusions on title nodes.
+    private final MethodHandle getDragType;
+
+    /// Sets the system button height to zero to hide the platform-provided buttons.
+    private final MethodHandle setSystemButtonHeight;
+
+    /// Marks only the specified node as draggable, preserving child control interaction.
+    private final Object draggable;
+
+    /// Excludes a node and its descendants from native dragging.
+    private final Object notDraggable;
+
+    /// Ignores an overlay and its descendants when testing underlying native header areas.
+    private final Object transparentSubtree;
+
+    /// Resolves all required public APIs and creates a detached header bar.
+    ///
+    /// @param forced whether to bypass the automatic theme brightness exclusion
+    /// @throws Throwable if a required API cannot be resolved or invoked
+    private NativeWindowDecoration(boolean forced) throws Throwable {
+        this.forced = forced;
+        MethodHandles.Lookup lookup = MethodHandles.publicLookup();
+        style = (StageStyle) lookup.findStaticGetter(StageStyle.class, "EXTENDED", StageStyle.class).invokeExact();
+        Class<?> headerClass = Class.forName("javafx.scene.layout.HeaderBar");
+        Class<?> dragClass = Class.forName("javafx.scene.layout.HeaderDragType");
+        // Adapt runtime-only types once so cached handles can be invoked with exact, statically known signatures.
+        setCenter = lookup.findVirtual(headerClass, "setCenter", MethodType.methodType(void.class, Node.class))
+                .asType(MethodType.methodType(void.class, Region.class, Node.class));
+        setDragType = lookup.findStatic(headerClass, "setDragType", MethodType.methodType(void.class, Node.class, dragClass))
+                .asType(MethodType.methodType(void.class, Node.class, Object.class));
+        getDragType = lookup.findStatic(headerClass, "getDragType", MethodType.methodType(dragClass, Node.class))
+                .asType(MethodType.methodType(Object.class, Node.class));
+        setSystemButtonHeight = lookup.findStatic(headerClass, "setSystemButtonHeight",
+                MethodType.methodType(void.class, Stage.class, double.class));
+        draggable = Objects.requireNonNull(lookup.findStaticGetter(dragClass, "DRAGGABLE", dragClass).invoke());
+        notDraggable = Objects.requireNonNull(lookup.findStaticGetter(dragClass, "NONE", dragClass).invoke());
+        transparentSubtree = Objects.requireNonNull(lookup.findStaticGetter(dragClass, "TRANSPARENT_SUBTREE", dragClass).invoke());
+        headerBar = (Region) lookup.findConstructor(headerClass, MethodType.methodType(void.class)).invoke();
+    }
+
+    /// Creates native decoration support according to the configured preference and runtime capabilities.
+    ///
+    /// The `hmcl.nativeDecoration` system property takes precedence over `HMCL_NATIVE_DECORATION`.
+    /// Values are case-insensitive and trimmed: `false` disables native decoration, `true` enables it on
+    /// any supported platform, and `auto` enables it only on macOS or Windows 11 and later. Missing or
+    /// unrecognized values use `auto`. All modes require JavaFX 27 or later and extended-window support.
+    /// The preference is read when this method is called and retained by the returned instance.
+    ///
+    /// @return the resolved support, or `null` when disabled by policy or unavailable on the runtime
+    static @Nullable NativeWindowDecoration create() {
+        @Nullable String preference = System.getProperty("hmcl.nativeDecoration", System.getenv("HMCL_NATIVE_DECORATION"));
+        if (preference != null) {
+            preference = preference.trim();
+        }
+        if ("false".equalsIgnoreCase(preference)) {
+            return null;
+        }
+        boolean forced = "true".equalsIgnoreCase(preference);
+        if (!forced && preference != null && !"auto".equalsIgnoreCase(preference)) {
+            LOG.warning("Invalid native decoration preference: " + preference + "; using auto");
+        }
+        if (!forced && OperatingSystem.CURRENT_OS != OperatingSystem.MACOS
+                && !OperatingSystem.SYSTEM_VERSION.isAtLeast(OSVersion.WINDOWS_11)) {
+            return null;
+        }
+        try {
+            int version = Integer.parseInt(System.getProperty("javafx.version", "0").split("[.\\-+]")[0]);
+            if (version < 27 || !Platform.isSupported(ConditionalFeature.valueOf("EXTENDED_WINDOW"))) {
+                return null;
+            }
+            return new NativeWindowDecoration(forced);
+        } catch (Throwable e) {
+            LOG.warning("Native window decoration is unavailable; using custom decoration", e);
+            return null;
+        }
+    }
+
+    /// Returns whether to use native decoration with the current transparency and theme brightness.
+    ///
+    /// Transparent windows always use custom decoration. Automatic mode also excludes dark windows on Windows;
+    /// explicitly enabling native decoration bypasses only that brightness exclusion.
+    ///
+    /// @param transparent whether the theme requests window transparency
+    /// @param dark whether the current theme is dark
+    /// @return whether this instance permits native decoration for the supplied theme settings
+    boolean isPreferred(boolean transparent, boolean dark) {
+        return !transparent && (forced || !(OperatingSystem.CURRENT_OS == OperatingSystem.WINDOWS && dark));
+    }
+
+    /// Sets or removes the header content; the caller must first detach it from any other parent.
+    ///
+    /// Configures native dragging on non-interactive descendants and observes later child additions.
+    /// Controls other than labels and nodes explicitly excluded from dragging retain ordinary input handling.
+    ///
+    /// @param content the title-bar content, or `null` to detach it
+    void setContent(@Nullable Node content) {
+        try {
+            if (content != null) {
+                configureTitleDragging(content);
+            }
+            setCenter.invokeExact(headerBar, content);
+        } catch (Throwable e) {
+            throw new IllegalStateException("Cannot update native header content", e);
+        }
+    }
+
+    /// Marks a node as draggable or explicitly non-draggable during native header hit testing.
+    ///
+    /// Draggability does not extend to descendants, so interactive title content retains its behavior.
+    ///
+    /// @param node the node to configure
+    /// @param enabled whether the node itself may move the window
+    void setDraggable(Node node, boolean enabled) {
+        try {
+            setDragType.invokeExact(node, enabled ? draggable : notDraggable);
+        } catch (Throwable e) {
+            throw new IllegalStateException("Cannot configure native header dragging", e);
+        }
+    }
+
+    /// Lets native header hit testing pass through an overlay and its descendants.
+    ///
+    /// Ordinary mouse picking is unchanged. This does not create draggable areas outside the underlying
+    /// header. Descendants excluded with [#setDraggable(Node, boolean)] block native dragging instead.
+    ///
+    /// @param overlay the overlay above the header
+    void setDragTransparent(Node overlay) {
+        try {
+            setDragType.invokeExact(overlay, transparentSubtree);
+        } catch (Throwable e) {
+            throw new IllegalStateException("Cannot configure native header overlay", e);
+        }
+    }
+
+    /// Configures native hit testing for title content, including subsequently added descendants.
+    ///
+    /// Containers and label graphics may move the window. Other controls and nodes explicitly excluded with
+    /// [#setDraggable(Node, boolean)] retain ordinary input handling, including all of their descendants.
+    ///
+    /// @param node the title content to configure
+    private void configureTitleDragging(Node node) {
+        if (node.getProperties().putIfAbsent(DRAG_CONFIGURED, Boolean.TRUE) != null) {
+            return;
+        }
+        try {
+            if ((Object) getDragType.invokeExact(node) == notDraggable) {
+                return;
+            }
+        } catch (Throwable e) {
+            throw new IllegalStateException("Cannot read native header dragging", e);
+        }
+        if (node instanceof Control && !(node instanceof Label)) {
+            setDraggable(node, false);
+            return;
+        }
+
+        // Native hit testing starts at the deepest picked node; marking only its parent is insufficient.
+        setDraggable(node, true);
+        if (node instanceof Parent parent) {
+            parent.getChildrenUnmodifiable().addListener((ListChangeListener<Node>) change -> {
+                while (change.next()) {
+                    for (Node child : change.getAddedSubList()) {
+                        configureTitleDragging(child);
+                    }
+                }
+            });
+            for (Node child : parent.getChildrenUnmodifiable()) {
+                configureTitleDragging(child);
+            }
+        }
+    }
+
+    /// Hides platform-provided window buttons.
+    ///
+    /// @param stage the extended stage to configure
+    void configureStage(Stage stage) {
+        try {
+            setSystemButtonHeight.invokeExact(stage, 0.0);
+        } catch (Throwable e) {
+            throw new IllegalStateException("Cannot hide native window buttons", e);
+        }
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/ui/decorator/WindowBounds.java

@@ -0,0 +1,307 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.ui.decorator;
+
+import javafx.application.Platform;
+import javafx.beans.InvalidationListener;
+import javafx.beans.property.ReadOnlyDoubleProperty;
+import javafx.beans.property.ReadOnlyDoubleWrapper;
+import javafx.beans.value.ChangeListener;
+import javafx.beans.value.ObservableValue;
+import javafx.event.EventHandler;
+import javafx.geometry.Insets;
+import javafx.geometry.Rectangle2D;
+import javafx.scene.Scene;
+import javafx.scene.layout.Region;
+import javafx.stage.Stage;
+import javafx.stage.StageStyle;
+import javafx.stage.WindowEvent;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.util.Objects;
+import java.util.function.Consumer;
+
+/// Tracks content bounds independently of the stage's native frame and the root's shadow padding.
+///
+/// All access must occur on the JavaFX application thread. The scene and root must remain attached to the stage
+/// until [#close()] is called. Normal bounds are sampled after layout, and once more before hiding or detaching.
+/// Maximized bounds under [WindowState]'s policy, full-screen bounds, and iconified bounds are not reported
+/// as normal bounds. Transparent macOS windows retain normal bounds despite native zoom notifications.
+/// Minimum sizes are configured separately after showing or a display-scale or resizability change;
+/// ordinary geometry tracking does not write window constraints.
+@NotNullByDefault
+final class WindowBounds implements AutoCloseable {
+    /// The stage whose outer geometry is managed.
+    private final Stage stage;
+
+    /// The scene providing client dimensions and offsets within the native window.
+    private final Scene scene;
+
+    /// The root whose padding reserves space for custom shadows.
+    private final Region root;
+
+    /// The padding used in the normal window state, even when maximized padding is empty.
+    private final Insets normalInsets;
+
+    /// The minimum content width in JavaFX screen coordinates.
+    private final double minWidth;
+
+    /// The minimum content height in JavaFX screen coordinates.
+    private final double minHeight;
+
+    /// Receives normal content bounds in JavaFX screen coordinates.
+    private final Consumer<Rectangle2D> saveBounds;
+
+    /// The latest normal content rectangle, retained through hiding and non-normal window states.
+    private Rectangle2D normalBounds;
+
+    /// The content width excluding both native borders and custom shadow padding.
+    private final ReadOnlyDoubleWrapper contentWidth = new ReadOnlyDoubleWrapper();
+
+    /// The content height excluding both native borders and custom shadow padding.
+    private final ReadOnlyDoubleWrapper contentHeight = new ReadOnlyDoubleWrapper();
+
+    /// Whether the current show operation is still resolving native client offsets.
+    private boolean restoringPosition;
+
+    /// Whether native geometry can be sampled, including during WINDOW_HIDING.
+    private boolean shown;
+
+    /// Whether geometry must be sampled after the next layout pulse.
+    private boolean dirty;
+
+    /// Whether the native minimum needs configuration once normal geometry has stopped changing between pulses.
+    private boolean minimumSizePending;
+
+    /// Whether this tracker has released its listeners.
+    private boolean closed;
+
+    /// Marks geometry for sampling after layout without assuming an order for stage and scene notifications.
+    private final ChangeListener<Object> boundsListener = (observable, oldValue, newValue) -> invalidate();
+
+    /// Compensates for native offsets discovered while creating the window peer.
+    private final InvalidationListener offsetListener = observable -> restorePosition();
+
+    /// Requests new native minimum dimensions when the display scale or resizability changes.
+    private final ChangeListener<Object> minimumSizeListener = (observable, oldValue, newValue) -> invalidateMinimumSize();
+
+    /// Establishes the normal restore rectangle before the native peer becomes visible.
+    private final EventHandler<WindowEvent> showingHandler = event -> restoreBounds();
+
+    /// Completes initial positioning and enables geometry sampling.
+    private final EventHandler<WindowEvent> shownHandler = event -> {
+        restorePosition();
+        restoringPosition = false;
+        shown = true;
+        invalidateMinimumSize();
+    };
+
+    /// Samples geometry before JavaFX clears the hidden scene's native offsets.
+    private final EventHandler<WindowEvent> hidingHandler = event -> {
+        updateBounds();
+        shown = false;
+        restoringPosition = false;
+    };
+
+    /// Samples geometry and separately processes pending minimum-size configuration after layout.
+    private final Runnable pulseListener = this::onPulse;
+
+    /// The properties observed for geometry, state, and padding changes.
+    private final ObservableValue<?> @Unmodifiable [] observed;
+
+    /// The properties that can change the normal native frame dimensions.
+    private final ObservableValue<?> @Unmodifiable [] minimumSizeObserved;
+
+    /// Initializes client sizing and installs listeners on an attached stage and scene.
+    ///
+    /// The root's current padding must be its normal-state shadow padding. Initial bounds exclude that padding
+    /// and native decoration. [Stage#sizeToScene()] lets JavaFX determine the required native outer size.
+    ///
+    /// @param stage the stage with `root` installed as its scene root
+    /// @param root the scene root, whose minimum and preferred sizes are managed by this tracker
+    /// @param initialBounds the normal content rectangle to restore
+    /// @param minWidth the minimum content width
+    /// @param minHeight the minimum content height
+    /// @param saveBounds the callback receiving sampled normal content bounds
+    WindowBounds(Stage stage, Region root, Rectangle2D initialBounds,
+                 double minWidth, double minHeight, Consumer<Rectangle2D> saveBounds) {
+        this.stage = stage;
+        this.scene = Objects.requireNonNull(stage.getScene());
+        this.root = root;
+        this.normalInsets = root.getPadding();
+        this.normalBounds = initialBounds;
+        this.minWidth = minWidth;
+        this.minHeight = minHeight;
+        this.saveBounds = saveBounds;
+        // Enforce minimum content size on the stage, independently of the current page's layout minimum.
+        root.setMinSize(0, 0);
+        contentWidth.set(initialBounds.getWidth());
+        contentHeight.set(initialBounds.getHeight());
+        observed = new ObservableValue<?>[] {
+                stage.xProperty(), stage.yProperty(), stage.widthProperty(), stage.heightProperty(),
+                stage.maximizedProperty(), stage.fullScreenProperty(), stage.iconifiedProperty(),
+                scene.xProperty(), scene.yProperty(), scene.widthProperty(), scene.heightProperty(),
+                root.paddingProperty()
+        };
+        for (ObservableValue<?> observable : observed) {
+            observable.addListener(boundsListener);
+        }
+        scene.xProperty().addListener(offsetListener);
+        scene.yProperty().addListener(offsetListener);
+        minimumSizeObserved = new ObservableValue<?>[] {
+                stage.outputScaleXProperty(), stage.outputScaleYProperty(), stage.resizableProperty()
+        };
+        for (ObservableValue<?> observable : minimumSizeObserved) {
+            observable.addListener(minimumSizeListener);
+        }
+        scene.addPostLayoutPulseListener(pulseListener);
+        stage.addEventHandler(WindowEvent.WINDOW_SHOWING, showingHandler);
+        stage.addEventHandler(WindowEvent.WINDOW_SHOWN, shownHandler);
+        stage.addEventHandler(WindowEvent.WINDOW_HIDING, hidingHandler);
+        stage.setMinWidth(minWidth + normalInsets.getLeft() + normalInsets.getRight());
+        stage.setMinHeight(minHeight + normalInsets.getTop() + normalInsets.getBottom());
+        restoreBounds();
+        if (stage.isShowing()) {
+            restoringPosition = false;
+            shown = true;
+            invalidateMinimumSize();
+        }
+    }
+
+    /// Returns the content width, excluding native borders and the root's current padding.
+    ReadOnlyDoubleProperty contentWidthProperty() {
+        return contentWidth.getReadOnlyProperty();
+    }
+
+    /// Returns the content height, excluding native borders and the root's current padding.
+    ReadOnlyDoubleProperty contentHeightProperty() {
+        return contentHeight.getReadOnlyProperty();
+    }
+
+    /// Requests one layout pulse to coalesce geometry notifications.
+    private void invalidate() {
+        dirty = true;
+        Platform.requestNextPulse();
+    }
+
+    /// Schedules native minimum-size configuration independently of ordinary geometry sampling.
+    private void invalidateMinimumSize() {
+        minimumSizePending = true;
+        invalidate();
+    }
+
+    /// Samples dirty geometry, then configures pending minimums on a subsequent quiet layout pulse.
+    private void onPulse() {
+        if (closed) {
+            return;
+        }
+        if (dirty) {
+            updateBounds();
+            if (minimumSizePending && isNormal()) {
+                Platform.requestNextPulse();
+            }
+        } else if (minimumSizePending && isNormal()) {
+            updateMinimumSize();
+        }
+    }
+
+    /// Returns whether the visible stage can supply normal window geometry.
+    private boolean isNormal() {
+        return shown && !restoringPosition && !stage.isIconified()
+                && !WindowState.isMaximized(stage) && !stage.isFullScreen();
+    }
+
+    /// Requests the normal client size and starts compensating for native client offsets.
+    private void restoreBounds() {
+        restoringPosition = true;
+        root.setPrefSize(normalBounds.getWidth() + normalInsets.getLeft() + normalInsets.getRight(),
+                normalBounds.getHeight() + normalInsets.getTop() + normalInsets.getBottom());
+        restorePosition();
+        stage.sizeToScene();
+    }
+
+    /// Aligns the content origin while the native peer is being initialized.
+    private void restorePosition() {
+        if (restoringPosition) {
+            stage.setX(normalBounds.getMinX() - scene.getX() - normalInsets.getLeft());
+            stage.setY(normalBounds.getMinY() - scene.getY() - normalInsets.getTop());
+        }
+    }
+
+    /// Updates content dimensions and saves normal bounds when native geometry is available.
+    private void updateBounds() {
+        dirty = false;
+        if (!shown || restoringPosition || stage.isIconified()) {
+            return;
+        }
+
+        Insets insets = root.getPadding();
+        double width = scene.getWidth() - insets.getLeft() - insets.getRight();
+        double height = scene.getHeight() - insets.getTop() - insets.getBottom();
+        if (width <= 0 || height <= 0) {
+            return;
+        }
+        contentWidth.set(width);
+        contentHeight.set(height);
+        if (WindowState.isMaximized(stage) || stage.isFullScreen()) {
+            return;
+        }
+
+        normalBounds = new Rectangle2D(
+                stage.getX() + scene.getX() + insets.getLeft(),
+                stage.getY() + scene.getY() + insets.getTop(),
+                Math.max(minWidth, width), Math.max(minHeight, height));
+        saveBounds.accept(normalBounds);
+    }
+
+    /// Measures the normal native frame and applies content minimums including frame and shadow padding.
+    private void updateMinimumSize() {
+        // Stage and Scene sizes arrive separately. Only measure after pending geometry notifications
+        // have been processed, never from an individual size listener or an ordinary resize pulse.
+        boolean hasFrame = stage.getStyle() != StageStyle.TRANSPARENT && stage.getStyle() != StageStyle.UNDECORATED;
+        double frameWidth = hasFrame ? Math.max(0, stage.getWidth() - scene.getWidth()) : 0;
+        double frameHeight = hasFrame ? Math.max(0, stage.getHeight() - scene.getHeight()) : 0;
+        minimumSizePending = false;
+        stage.setMinWidth(minWidth + normalInsets.getLeft() + normalInsets.getRight() + frameWidth);
+        stage.setMinHeight(minHeight + normalInsets.getTop() + normalInsets.getBottom() + frameHeight);
+    }
+
+    /// Saves the last available bounds and removes all listeners without hiding or detaching the stage.
+    /// Repeated calls have no effect.
+    @Override
+    public void close() {
+        if (closed) {
+            return;
+        }
+        updateBounds();
+        closed = true;
+        for (ObservableValue<?> observable : observed) {
+            observable.removeListener(boundsListener);
+        }
+        scene.xProperty().removeListener(offsetListener);
+        scene.yProperty().removeListener(offsetListener);
+        for (ObservableValue<?> observable : minimumSizeObserved) {
+            observable.removeListener(minimumSizeListener);
+        }
+        scene.removePostLayoutPulseListener(pulseListener);
+        stage.removeEventHandler(WindowEvent.WINDOW_SHOWING, showingHandler);
+        stage.removeEventHandler(WindowEvent.WINDOW_SHOWN, shownHandler);
+        stage.removeEventHandler(WindowEvent.WINDOW_HIDING, hidingHandler);
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/ui/decorator/WindowState.java

@@ -0,0 +1,53 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.ui.decorator;
+
+import javafx.stage.Stage;
+import javafx.stage.StageStyle;
+import org.jackhuang.hmcl.util.platform.OperatingSystem;
+import org.jetbrains.annotations.NotNullByDefault;
+
+/// Applies the main window's platform-specific maximization policy.
+/// All methods must be called on the JavaFX application thread.
+@NotNullByDefault
+public final class WindowState {
+    /// Prevents instantiation of this utility class.
+    private WindowState() {
+    }
+
+    /// Returns whether the launcher honors maximization for the stage's platform and style.
+    ///
+    /// Transparent windows on macOS do not support maximization in the launcher: native zoom notifications
+    /// can mark an ordinary borderless window as maximized, including during initialization.
+    /// This policy does not suppress full-screen or iconified states.
+    ///
+    /// @param stage the main stage to inspect
+    /// @return `false` for transparent stages on macOS; `true` otherwise
+    public static boolean supportsMaximization(Stage stage) {
+        // https://github.com/HMCL-dev/HMCL/issues/4290
+        return OperatingSystem.CURRENT_OS != OperatingSystem.MACOS || stage.getStyle() != StageStyle.TRANSPARENT;
+    }
+
+    /// Returns whether the stage is maximized under the launcher's platform policy.
+    ///
+    /// @param stage the main stage to inspect
+    /// @return `true` if maximization is supported and the stage reports that it is maximized
+    public static boolean isMaximized(Stage stage) {
+        return supportsMaximization(stage) && stage.isMaximized();
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/ui/directory/GameDirectoryListItemSkin.java

@@ -57,7 +57,7 @@ public class GameDirectoryListItemSkin extends SkinBase<GameDirectoryListItem> {
 
         FXUtils.onChangeAndOperate(skinnable.selectedProperty(), active -> {
             skinnable.pseudoClassStateChanged(SELECTED, active);
-            
+
             SVG targetIcon = active ? SVG.FOLDER_FILL : SVG.FOLDER;
             if (left.getIcon() != targetIcon) {
                 left.setIcon(targetIcon, Motion.SHORT4);

HMCL/src/main/java/org/jackhuang/hmcl/ui/directory/GameDirectoryPage.java

@@ -22,7 +22,10 @@ import com.jfoenix.controls.JFXTextField;
 import com.jfoenix.validation.RequiredFieldValidator;
 import com.jfoenix.validation.base.ValidatorBase;
 import javafx.beans.binding.Bindings;
-import javafx.beans.property.*;
+import javafx.beans.property.ReadOnlyObjectProperty;
+import javafx.beans.property.ReadOnlyObjectWrapper;
+import javafx.beans.property.SimpleStringProperty;
+import javafx.beans.property.StringProperty;
 import javafx.beans.value.ChangeListener;
 import javafx.beans.value.ObservableValue;
 import javafx.geometry.Insets;
@@ -40,6 +43,7 @@ import org.jackhuang.hmcl.ui.Controllers;
 import org.jackhuang.hmcl.ui.FXUtils;
 import org.jackhuang.hmcl.ui.construct.*;
 import org.jackhuang.hmcl.ui.decorator.DecoratorPage;
+import org.jackhuang.hmcl.util.FXThread;
 import org.jackhuang.hmcl.util.PortablePath;
 import org.jackhuang.hmcl.util.StringUtils;
 import org.jackhuang.hmcl.util.i18n.LocalizedText;
@@ -117,10 +121,12 @@ public final class GameDirectoryPage extends BorderPane implements DecoratorPage
                                 setMessage(i18n("game_directory.already_exists"));
                             }
 
+                            /// Rejects names used by other game directories, excluding the entry being edited.
                             @Override
                             protected void eval() {
                                 JFXTextField control = (JFXTextField) this.getSrcControl();
                                 hasErrors.set(GameDirectoryManager.getGameDirectories().stream()
+                                        .filter(existingGameDirectory -> existingGameDirectory != gameDirectory)
                                         .anyMatch(existingGameDirectory -> Objects.equals(
                                                 GameDirectoryManager.getGameDirectoryCustomName(existingGameDirectory), control.getText())));
                             }
@@ -162,46 +168,56 @@ public final class GameDirectoryPage extends BorderPane implements DecoratorPage
             StackPane.setAlignment(saveButton, Pos.BOTTOM_RIGHT);
             saveButton.setPrefSize(100, 40);
             saveButton.setOnAction(e -> onSave());
+            String initialLocation = getLocation();
+            boolean initialUseRelativePath = toggleUseRelativePath.isSelected();
             saveButton.disableProperty().bind(Bindings.createBooleanBinding(
-                    () -> !txtGameDirectoryName.validate() || StringUtils.isBlank(getLocation()),
-                    txtGameDirectoryName.textProperty(), location));
+                    () -> !txtGameDirectoryName.validate() || StringUtils.isBlank(getLocation())
+                            || (gameDirectory != null
+                            && Objects.equals(txtGameDirectoryName.getText(), gameDirectoryDisplayName)
+                            && Objects.equals(getLocation(), initialLocation)
+                            && toggleUseRelativePath.isSelected() == initialUseRelativePath),
+                    txtGameDirectoryName.textProperty(), location, toggleUseRelativePath.selectedProperty()));
         }
 
-        ChangeListener<String> locationChangeListener = (observable, oldValue, newValue) -> {
-            Path newPath;
-            try {
-                newPath = FileUtils.toAbsolute(Path.of(newValue));
-            } catch (InvalidPathException ignored) {
-                return;
-            }
-
-            if (!".minecraft".equals(FileUtils.getName(newPath)))
-                return;
-
-            Path parent = newPath.getParent();
-            if (parent == null)
-                return;
-
-            String suggestedName = FileUtils.getName(parent);
-            if (!suggestedName.isBlank()) {
-                txtGameDirectoryName.setText(suggestedName);
-            }
-        };
-        locationProperty().addListener(locationChangeListener);
-
-        txtGameDirectoryName.textProperty().addListener(new ChangeListener<>() {
-            @Override
-            public void changed(ObservableValue<? extends String> observable, String oldValue, String newValue) {
-                if (txtGameDirectoryName.isFocused()) {
-                    txtGameDirectoryName.textProperty().removeListener(this);
-                    locationProperty().removeListener(locationChangeListener);
+        if (gameDirectory == null) {
+            ChangeListener<String> locationChangeListener = (observable, oldValue, newValue) -> {
+                Path newPath;
+                try {
+                    newPath = FileUtils.toAbsolute(Path.of(newValue));
+                } catch (InvalidPathException ignored) {
+                    return;
                 }
-            }
-        });
+
+                if (!".minecraft".equals(FileUtils.getName(newPath)))
+                    return;
+
+                @Nullable Path parent = newPath.getParent();
+                if (parent == null)
+                    return;
+
+                String suggestedName = FileUtils.getName(parent);
+                if (!suggestedName.isBlank()) {
+                    txtGameDirectoryName.setText(suggestedName);
+                }
+            };
+            locationChangeListener.changed(locationProperty(), this.location.get(), this.location.get());
+            locationProperty().addListener(locationChangeListener);
+
+            txtGameDirectoryName.textProperty().addListener(new ChangeListener<>() {
+                /// Stops automatic name suggestions after the user edits the name.
+                @Override
+                public void changed(ObservableValue<? extends String> observable, String oldValue, String newValue) {
+                    if (txtGameDirectoryName.isFocused()) {
+                        txtGameDirectoryName.textProperty().removeListener(this);
+                        locationProperty().removeListener(locationChangeListener);
+                    }
+                }
+            });
+        }
     }
 
-    /// Saves the edited game directory or adds a new entry to the appropriate game directory store.
-    private void onSave() {
+    @FXThread
+    private void doSave() {
         if (gameDirectory != null) {
             LocalizedText name = LocalizedText.plain(txtGameDirectoryName.getText());
             PortablePath path = StringUtils.isNotBlank(getLocation()) ? createPortableLocation() : gameDirectory.getPath();
@@ -228,27 +244,39 @@ public final class GameDirectoryPage extends BorderPane implements DecoratorPage
                     Controllers.confirmBackupAndOverwrite(i18n("settings.game_directories.read_only"), () -> {
                         SettingsManager.forceOverwriteUserGameDirectories();
                         GameDirectoryManager.addUserGameDirectory(newGameDirectory);
+                        GameDirectoryManager.setSelectedGameDirectory(newGameDirectory);
                         fireEvent(new PageCloseEvent());
                     });
                     return;
                 }
                 GameDirectoryManager.addUserGameDirectory(newGameDirectory);
+                GameDirectoryManager.setSelectedGameDirectory(newGameDirectory);
             } else {
                 if (SettingsManager.isLocalGameDirectoriesReadOnly()) {
                     Controllers.confirmBackupAndOverwrite(i18n("settings.game_directories.read_only"), () -> {
                         SettingsManager.forceOverwriteLocalGameDirectories();
                         GameDirectoryManager.addLocalGameDirectory(newGameDirectory);
+                        GameDirectoryManager.setSelectedGameDirectory(newGameDirectory);
                         fireEvent(new PageCloseEvent());
                     });
                     return;
                 }
                 GameDirectoryManager.addLocalGameDirectory(newGameDirectory);
+                GameDirectoryManager.setSelectedGameDirectory(newGameDirectory);
             }
         }
 
         fireEvent(new PageCloseEvent());
     }
 
+    /// Saves the edited game directory or adds a new entry to the appropriate game directory store.
+    @FXThread
+    private void onSave() {
+        if (Objects.equals(Path.of(getLocation()).getRoot(), Path.of(getLocation()))) {
+            Controllers.confirm(i18n("game_directory.root"), i18n("message.warning"), MessageDialogPane.MessageType.WARNING, this::doSave, null);
+        } else doSave();
+    }
+
     /// Creates the portable path for the current location according to the relative-path toggle.
     private PortablePath createPortableLocation() {
         if (toggleUseRelativePath.isSelected()) {

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/AbstractInstallersPage.java

@@ -28,9 +28,9 @@ import javafx.scene.layout.BorderPane;
 import javafx.scene.layout.FlowPane;
 import javafx.scene.layout.HBox;
 import javafx.scene.layout.Priority;
-
 import org.jackhuang.hmcl.download.DownloadProvider;
-import org.jackhuang.hmcl.download.LibraryAnalyzer;
+import org.jackhuang.hmcl.game.GameComponentType;
+import org.jackhuang.hmcl.game.GameInstanceID;
 import org.jackhuang.hmcl.ui.Controllers;
 import org.jackhuang.hmcl.ui.FXUtils;
 import org.jackhuang.hmcl.ui.InstallerItem;
@@ -40,11 +40,14 @@ import org.jackhuang.hmcl.ui.wizard.Navigation;
 import org.jackhuang.hmcl.ui.wizard.WizardController;
 import org.jackhuang.hmcl.ui.wizard.WizardPage;
 import org.jackhuang.hmcl.util.SettingsMap;
+import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
 
 import static org.jackhuang.hmcl.setting.SettingsManager.state;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 
 public abstract class AbstractInstallersPage extends Control implements WizardPage {
+    public static final SettingsMap.Key<GameInstanceID> INSTANCE_ID = new SettingsMap.Key<>("instanceId");
+
     public static final String FABRIC_QUILT_API_TIP = "fabricQuiltApi";
     protected final WizardController controller;
 
@@ -53,39 +56,39 @@ public abstract class AbstractInstallersPage extends Control implements WizardPa
 
     protected BooleanProperty installable = new SimpleBooleanProperty();
 
-    public AbstractInstallersPage(WizardController controller, String gameVersion, DownloadProvider downloadProvider) {
+    public AbstractInstallersPage(WizardController controller, GameVersionNumber gameVersion, DownloadProvider downloadProvider) {
         this.controller = controller;
         this.group = new InstallerItem.InstallerItemGroup(gameVersion, getInstallerItemStyle());
 
-        for (InstallerItem library : group.getLibraries()) {
-            String libraryId = library.getLibraryId();
-            if (libraryId.equals(LibraryAnalyzer.LibraryType.MINECRAFT.getPatchId())) continue;
-            library.setOnInstall(() -> {
+        for (InstallerItem component : group.getComponents()) {
+            GameComponentType type = component.getComponentType();
+            if (type == GameComponentType.GAME) continue;
+            component.setOnInstall(() -> {
                 if (!Boolean.TRUE.equals(state().getShownTips().get(FABRIC_QUILT_API_TIP))
-                        && (LibraryAnalyzer.LibraryType.FABRIC_API.getPatchId().equals(libraryId)
-                        || LibraryAnalyzer.LibraryType.QUILT_API.getPatchId().equals(libraryId)
-                        || LibraryAnalyzer.LibraryType.LEGACY_FABRIC_API.getPatchId().equals(libraryId))) {
+                        && (type == GameComponentType.FABRIC_API
+                        || type == GameComponentType.QUILT_API
+                        || type == GameComponentType.LEGACY_FABRIC_API)) {
                     Controllers.dialog(new MessageDialogPane.Builder(
-                            i18n("install.installer.fabric-quilt-api.warning", i18n("install.installer." + libraryId)),
+                            i18n("install.installer.fabric-quilt-api.warning", i18n("install.installer." + type.getPatchId())),
                             i18n("message.warning"),
                             MessageDialogPane.MessageType.WARNING
                     ).ok(null).addCancel(i18n("button.do_not_show_again"), () -> state().getShownTips().put(FABRIC_QUILT_API_TIP, true)).build());
                 }
 
-                if (!(library.resolvedStateProperty().get() instanceof InstallerItem.IncompatibleState))
+                if (!(component.resolvedStateProperty().get() instanceof InstallerItem.IncompatibleState))
                     controller.onNext(
                             new VersionsPage(
                                     controller,
-                                    i18n("install.installer.choose", i18n("install.installer." + libraryId)),
+                                    i18n("install.installer.choose", i18n("install.installer." + type.getPatchId())),
                                     gameVersion,
                                     downloadProvider,
-                                    libraryId,
+                                    type,
                                     () -> controller.onPrev(false, Navigation.NavigationDirection.PREVIOUS)
                             ), Navigation.NavigationDirection.NEXT
                     );
             });
-            library.setOnRemove(() -> {
-                controller.getSettings().remove(libraryId);
+            component.setOnRemove(() -> {
+                controller.getSettings().remove(type.getPatchId());
                 reload();
             });
         }
@@ -115,28 +118,12 @@ public abstract class AbstractInstallersPage extends Control implements WizardPa
         return new InstallersPageSkin(this);
     }
 
-    /**
-     * Determines whether to display the extension pane.
-     * <p>
-     * This method controls the visibility of the extension pane in the UI.
-     * When this method returns {@code true} and the pane is visible, users can 
-     * interact with the features inside it, which includes triggering the 
-     * "Reset to Default Name" button handled by {@link #resetDefaultName()}.
-     * </p>
-     *
-     * @return {@code true} if the extension pane should be displayed; {@code false} otherwise.
-     */
+    /// Returns whether the name field includes clear and reset controls.
+    ///
+    /// @return `true` to display the controls; `false` otherwise
     protected abstract boolean showExtendPane();
 
-    /**
-     * Resets the name to its default value.
-     * <p>
-     * This method contains the business logic for the "Reset to Default Name" button 
-     * located within the extension pane. This logic can only be triggered by the user 
-     * clicking the corresponding button after {@link #showExtendPane()} returns 
-     * {@code true} and the extension pane is successfully displayed.
-     * </p>
-     */
+    /// Restores the default value of the name field.
     protected abstract void resetDefaultName();
 
     protected static class InstallersPageSkin extends SkinBase<AbstractInstallersPage> {
@@ -159,8 +146,8 @@ public abstract class AbstractInstallersPage extends Control implements WizardPa
 
                 HBox.setHgrow(control.txtName, Priority.ALWAYS);
 
-                versionNamePane.getChildren().addAll(new Label(i18n("version.name")), control.txtName);
-                
+                versionNamePane.getChildren().addAll(new Label(i18n("instance.name")), control.txtName);
+
                 if (control.showExtendPane()) {
                     JFXButton clearButton = FXUtils.newToggleButton4(SVG.CLOSE);
                     FXUtils.installFastTooltip(clearButton, i18n("button.clear"));
@@ -171,7 +158,7 @@ public abstract class AbstractInstallersPage extends Control implements WizardPa
                     FXUtils.installFastTooltip(resetButton, i18n("button.reset"));
                     resetButton.disableProperty().bind(control.txtName.disableProperty());
                     resetButton.setOnAction(e -> control.resetDefaultName());
-                    
+
                     versionNamePane.getChildren().addAll(clearButton, resetButton);
                 }
 
@@ -179,16 +166,16 @@ public abstract class AbstractInstallersPage extends Control implements WizardPa
             }
 
             {
-                InstallerItem[] libraries = control.group.getLibraries();
+                InstallerItem[] components = control.group.getComponents();
 
-                FlowPane libraryPane = new FlowPane(16, 16, libraries);
+                FlowPane libraryPane = new FlowPane(16, 16, components);
                 ScrollPane scrollPane = new ScrollPane(libraryPane);
                 scrollPane.setFitToWidth(true);
                 scrollPane.setFitToHeight(true);
                 BorderPane.setMargin(scrollPane, new Insets(16, 0, 16, 0));
                 root.setCenter(scrollPane);
 
-                if (libraries.length <= 8)
+                if (components.length <= 8)
                     scrollPane.setVbarPolicy(ScrollPane.ScrollBarPolicy.NEVER);
             }
 

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/AdditionalInstallersPage.java

@@ -20,47 +20,47 @@ package org.jackhuang.hmcl.ui.download;
 import javafx.beans.binding.Bindings;
 import javafx.beans.property.BooleanProperty;
 import javafx.beans.property.SimpleBooleanProperty;
+import org.jackhuang.hmcl.download.ComponentRemoteVersion;
 import org.jackhuang.hmcl.download.DownloadProvider;
-import org.jackhuang.hmcl.download.LibraryAnalyzer;
-import org.jackhuang.hmcl.download.RemoteVersion;
-import org.jackhuang.hmcl.game.GameRepository;
-import org.jackhuang.hmcl.game.HMCLGameRepository;
-import org.jackhuang.hmcl.game.Version;
+import org.jackhuang.hmcl.game.GameComponentType;
+import org.jackhuang.hmcl.game.GameInstanceManifest;
+import org.jackhuang.hmcl.game.HMCLGameInstance;
 import org.jackhuang.hmcl.ui.InstallerItem;
 import org.jackhuang.hmcl.ui.wizard.WizardController;
 import org.jackhuang.hmcl.util.Lang;
 import org.jackhuang.hmcl.util.SettingsMap;
+import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
 
 import java.util.Optional;
 
-import static org.jackhuang.hmcl.download.LibraryAnalyzer.LibraryType.MINECRAFT;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 
 class AdditionalInstallersPage extends AbstractInstallersPage {
     protected final BooleanProperty compatible = new SimpleBooleanProperty();
-    protected final GameRepository repository;
-    protected final String gameVersion;
-    protected final Version version;
+    protected final GameVersionNumber gameVersion;
+    protected final GameInstanceManifest manifest;
+    protected final HMCLGameInstance instance;
 
-    public AdditionalInstallersPage(String gameVersion, Version version, WizardController controller, HMCLGameRepository repository, DownloadProvider downloadProvider) {
+    public AdditionalInstallersPage(HMCLGameInstance instance, GameVersionNumber gameVersion, WizardController controller, DownloadProvider downloadProvider) {
         super(controller, gameVersion, downloadProvider);
+        this.instance = instance;
         this.gameVersion = gameVersion;
-        this.version = version;
-        this.repository = repository;
+        this.manifest = instance.getManifest();
 
-        txtName.setText(version.getId());
+        txtName.setText(instance.getId().id());
         txtName.setEditable(false);
 
-        for (InstallerItem library : group.getLibraries()) {
-            String libraryId = library.getLibraryId();
-            if (libraryId.equals("game")) continue;
-            library.setOnRemove(() -> {
-                controller.getSettings().put(libraryId, new UpdateInstallerWizardProvider.RemoveVersionAction(libraryId));
+        for (InstallerItem component : group.getComponents()) {
+            if (component.getComponentType() == GameComponentType.GAME) continue;
+            component.setOnRemove(() -> {
+                controller.getSettings().put(
+                        component.getComponentType().getPatchId(),
+                        new UpdateInstallerWizardProvider.RemoveComponentAction(component.getComponentType()));
                 reload();
             });
         }
 
-        installable.bind(Bindings.createBooleanBinding(() -> compatible.get() && txtName.validate(), txtName.textProperty(), compatible));
+        installable.bind(Bindings.createBooleanBinding(() -> txtName.validate(), txtName.textProperty()));
     }
 
     @Override
@@ -70,42 +70,25 @@ class AdditionalInstallersPage extends AbstractInstallersPage {
 
     @Override
     public String getTitle() {
-        return i18n("settings.tabs.installers");
+        return i18n("install.change_version.title", instance.getId().id());
     }
 
-    private String getVersion(String id) {
-        return Optional.ofNullable(controller.getSettings().get(id))
-                .flatMap(it -> Lang.tryCast(it, RemoteVersion.class))
-                .map(RemoteVersion::getSelfVersion).orElse(null);
+    private String getVersion(GameComponentType type) {
+        return Optional.ofNullable(controller.getSettings().get(type.getPatchId()))
+                .flatMap(it -> Lang.tryCast(it, ComponentRemoteVersion.class))
+                .map(ComponentRemoteVersion::getSelfVersion).orElse(null);
     }
 
     @Override
     protected void reload() {
-        Version resolved = version.resolvePreservingPatches(repository);
-        LibraryAnalyzer analyzer = LibraryAnalyzer.analyze(resolved, repository.getGameVersion(resolved).orElse(null));
-        String game = analyzer.getVersion(MINECRAFT).orElse(null);
-        String currentGameVersion = Lang.nonNull(getVersion("game"), game);
-
-        boolean compatible = true;
-
-        for (InstallerItem library : group.getLibraries()) {
-            String libraryId = library.getLibraryId();
-            String version = analyzer.getVersion(libraryId).orElse(null);
-            String libraryVersion = Lang.requireNonNullElse(getVersion(libraryId), version);
-            boolean alreadyInstalled = version != null && !(controller.getSettings().get(libraryId) instanceof UpdateInstallerWizardProvider.RemoveVersionAction);
-            if (!"game".equals(libraryId) && currentGameVersion != null && !currentGameVersion.equals(game) && getVersion(libraryId) == null && alreadyInstalled) {
-                // For third-party libraries, if game version is being changed, and the library is not being reinstalled,
-                // warns the user that we should update the library.
-                library.versionProperty().set(new InstallerItem.InstalledState(libraryVersion, false, true));
-                compatible = false;
-            } else if (alreadyInstalled || getVersion(libraryId) != null) {
-                library.versionProperty().set(new InstallerItem.InstalledState(libraryVersion, false, false));
+        for (InstallerItem component : group.getComponents()) {
+            GameComponentType componentType = component.getComponentType();
+            if (controller.getSettings().containsKey(componentType.getPatchId())) {
+                component.versionProperty().set(new InstallerItem.InstalledState(getVersion(componentType), false, false));
             } else {
-                library.versionProperty().set(null);
+                component.versionProperty().set(null);
             }
         }
-
-        this.compatible.set(compatible);
     }
 
     @Override

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/DownloadPage.java

@@ -25,6 +25,11 @@ import org.jackhuang.hmcl.addon.RemoteAddon;
 import org.jackhuang.hmcl.addon.repository.CurseForgeRemoteAddonRepository;
 import org.jackhuang.hmcl.download.*;
 import org.jackhuang.hmcl.download.game.GameRemoteVersion;
+import org.jackhuang.hmcl.game.GameComponentType;
+import org.jackhuang.hmcl.game.GameInstanceID;
+import org.jackhuang.hmcl.game.HMCLDependencyManager;
+import org.jackhuang.hmcl.game.HMCLGameBuilder;
+import org.jackhuang.hmcl.game.HMCLGameInstance;
 import org.jackhuang.hmcl.game.HMCLGameRepository;
 import org.jackhuang.hmcl.setting.DownloadProviders;
 import org.jackhuang.hmcl.setting.GameDirectoryManager;
@@ -42,37 +47,35 @@ import org.jackhuang.hmcl.ui.construct.TabHeader;
 import org.jackhuang.hmcl.ui.construct.Validator;
 import org.jackhuang.hmcl.ui.decorator.DecoratorAnimatedPage;
 import org.jackhuang.hmcl.ui.decorator.DecoratorPage;
-import org.jackhuang.hmcl.ui.versions.DownloadListPage;
-import org.jackhuang.hmcl.ui.versions.HMCLLocalizedDownloadListPage;
-import org.jackhuang.hmcl.ui.versions.VersionPage;
-import org.jackhuang.hmcl.ui.versions.Versions;
+import org.jackhuang.hmcl.ui.instances.DownloadListPage;
+import org.jackhuang.hmcl.ui.instances.HMCLLocalizedDownloadListPage;
+import org.jackhuang.hmcl.ui.instances.Instances;
 import org.jackhuang.hmcl.ui.wizard.Navigation;
 import org.jackhuang.hmcl.ui.wizard.WizardController;
 import org.jackhuang.hmcl.ui.wizard.WizardProvider;
+import org.jackhuang.hmcl.util.FileNameSet;
 import org.jackhuang.hmcl.util.SettingsMap;
 import org.jackhuang.hmcl.util.TaskCancellationAction;
+import org.jackhuang.hmcl.util.i18n.I18n;
 import org.jackhuang.hmcl.util.io.FileUtils;
+import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
 import org.jetbrains.annotations.Nullable;
 
-import java.io.IOException;
-import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Locale;
-import java.util.Set;
 import java.util.concurrent.CancellationException;
 import java.util.function.Supplier;
-import java.util.stream.Collectors;
 
 import static org.jackhuang.hmcl.ui.FXUtils.runInFX;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 
 public class DownloadPage extends DecoratorAnimatedPage implements DecoratorPage {
-    public static final org.jackhuang.hmcl.ui.versions.DownloadPage.DownloadCallback FOR_MOD =
+    public static final org.jackhuang.hmcl.ui.instances.DownloadPage.DownloadCallback FOR_MOD =
             (downloadProvider, repository, version, mod, file) -> download(downloadProvider, repository, version, file, "mods");
-    public static final org.jackhuang.hmcl.ui.versions.DownloadPage.DownloadCallback FOR_RESOURCE_PACK =
+    public static final org.jackhuang.hmcl.ui.instances.DownloadPage.DownloadCallback FOR_RESOURCE_PACK =
             (downloadProvider, repository, version, pack, file) -> download(downloadProvider, repository, version, file, "resourcepacks");
-    public static final org.jackhuang.hmcl.ui.versions.DownloadPage.DownloadCallback FOR_SHADER =
+    public static final org.jackhuang.hmcl.ui.instances.DownloadPage.DownloadCallback FOR_SHADER =
             (downloadProvider, repository, version, shader, file) -> download(downloadProvider, repository, version, file, "shaderpacks");
 
     private final ReadOnlyObjectWrapper<DecoratorPage.State> state = new ReadOnlyObjectWrapper<>(DecoratorPage.State.fromTitle(i18n("download"), -1));
@@ -92,16 +95,16 @@ public class DownloadPage extends DecoratorAnimatedPage implements DecoratorPage
         this(null);
     }
 
-    public DownloadPage(String uploadVersion) {
-        newGameTab.setNodeSupplier(loadVersionFor(() -> new VersionsPage(versionPageNavigator, i18n("install.installer.choose", i18n("install.installer.game")), "", DownloadProviders.getDownloadProvider(),
-                "game", versionPageNavigator::onGameSelected)));
+    public DownloadPage(GameInstanceID uploadInstance) {
+        newGameTab.setNodeSupplier(loadVersionFor(() -> new VersionsPage(versionPageNavigator, i18n("install.installer.choose", i18n("install.installer.game")), GameVersionNumber.unknown(), DownloadProviders.getDownloadProvider(),
+                GameComponentType.GAME, versionPageNavigator::onGameSelected)));
         modpackTab.setNodeSupplier(loadVersionFor(() -> {
             DownloadListPage page = HMCLLocalizedDownloadListPage.ofModPack((downloadProvider, repository, __, modpack, file) -> {
-                Versions.downloadModpackImpl(downloadProvider, repository, uploadVersion, modpack, file);
+                Instances.downloadModpackImpl(downloadProvider, repository, uploadInstance, modpack, file);
             }, false);
 
             JFXButton installLocalModpackButton = FXUtils.newRaisedButton(i18n("install.modpack"));
-            installLocalModpackButton.setOnAction(e -> Versions.importModpack());
+            installLocalModpackButton.setOnAction(e -> Instances.importModpack());
 
             page.getActions().add(installLocalModpackButton);
             return page;
@@ -109,7 +112,7 @@ public class DownloadPage extends DecoratorAnimatedPage implements DecoratorPage
         modTab.setNodeSupplier(loadVersionFor(() -> HMCLLocalizedDownloadListPage.ofMod(FOR_MOD, true)));
         resourcePackTab.setNodeSupplier(loadVersionFor(() -> HMCLLocalizedDownloadListPage.ofResourcePack(FOR_RESOURCE_PACK, true)));
         shaderTab.setNodeSupplier(loadVersionFor(() -> HMCLLocalizedDownloadListPage.ofShaderPack(FOR_SHADER, true)));
-        worldTab.setNodeSupplier(loadVersionFor(() -> new DownloadListPage(CurseForgeRemoteAddonRepository.WORLDS)));
+        worldTab.setNodeSupplier(loadVersionFor(() -> new DownloadListPage(RemoteAddon.Type.WORLD, CurseForgeRemoteAddonRepository.getInstance())));
         tab = new TabHeader(transitionPane, newGameTab, modpackTab, modTab, resourcePackTab, shaderTab, worldTab);
 
         GameDirectoryManager.registerVersionsListener(this::loadVersions);
@@ -134,51 +137,47 @@ public class DownloadPage extends DecoratorAnimatedPage implements DecoratorPage
     private static <T extends Node> Supplier<T> loadVersionFor(Supplier<T> nodeSupplier) {
         return () -> {
             T node = nodeSupplier.get();
-            if (node instanceof VersionPage.GameInstanceLoadable loadable) {
-                loadable.loadInstance(GameDirectoryManager.getSelectedRepository(), null);
+            if (node instanceof DownloadListPage page) {
+                page.loadInstance(HMCLGameInstance.Optional.empty(GameDirectoryManager.getSelectedRepository()));
             }
             return node;
         };
     }
 
-    public static void download(DownloadProvider downloadProvider, HMCLGameRepository repository, @Nullable String version, RemoteAddon.Version file, String subdirectoryName) {
-        if (version == null) version = repository.getSelectedInstance();
+    public static void download(DownloadProvider downloadProvider, HMCLGameRepository repository, @Nullable GameInstanceID instanceId, RemoteAddon.Version file, String subdirectoryName) {
+        @Nullable HMCLGameInstance instance = instanceId != null
+                ? repository.findInstance(instanceId)
+                : repository.getSelectedInstance();
+        Path runDirectory = instance != null ? instance.getRunDirectory() : repository.getBaseDirectory();
 
-        Path runDirectory = repository.hasVersion(version) ? repository.getRunDirectory(version) : repository.getBaseDirectory();
+        var targetPath = runDirectory.resolve(subdirectoryName);
 
-        Set<String> existingFiles;
-
-        try (var list = Files.list(runDirectory.resolve(subdirectoryName))) {
-            existingFiles = list.map(Path::getFileName)
-                    .map(Path::toString)
-                    .collect(Collectors.toSet());
-        } catch (IOException e) {
-            LOG.warning("Failed to list files in " + runDirectory.resolve(subdirectoryName), e);
-            existingFiles = Set.of();
+        FileNameSet existingPaths;
+        try {
+            existingPaths = FileNameSet.list(targetPath, null);
+        } catch (Exception e) {
+            LOG.warning("Failed to list folders in " + targetPath, e);
+            existingPaths = new FileNameSet(false);
         }
 
-        Set<String> finalExistingFiles = existingFiles;
-
         Controllers.prompt(i18n("archive.file.name"), (result, handler) -> {
-            Path dest = runDirectory.resolve(subdirectoryName).resolve(result);
+            Path dest = targetPath.resolve(result);
 
             Controllers.taskDialog(Task.composeAsync(() -> {
-                var task = new FileDownloadTask(downloadProvider.injectURLWithCandidates(file.file().url()), dest);
+                var task = new FileDownloadTask(downloadProvider.getDownloadCandidates(file.file().url()), dest);
                 task.setName(file.name());
                 return task;
             }).whenComplete(Schedulers.javafx(), exception -> {
                 if (exception != null) {
-                    if (exception instanceof CancellationException) {
-                        Controllers.showToast(i18n("message.cancelled"));
-                    } else {
-                        Controllers.dialog(DownloadProviders.localizeErrorMessage(exception), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR);
+                    if (!(exception instanceof CancellationException)) {
+                        Controllers.dialog(I18n.localizeErrorMessage(exception), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR);
                     }
                 } else {
                     Controllers.showToast(i18n("install.success"));
                 }
             }), i18n("message.downloading"), TaskCancellationAction.NORMAL);
             handler.resolve();
-        }, file.file().filename(), new Validator(i18n("install.new_game.malformed"), FileUtils::isNameValid), new Validator(i18n("game_directory.already_exists"), (it) -> !finalExistingFiles.contains(it)));
+        }, file.file().filename(), new Validator(i18n("install.new_game.malformed"), FileUtils::isNameValid), new Validator(i18n("game_directory.already_exists"), existingPaths::notContains));
 
     }
 
@@ -188,19 +187,19 @@ public class DownloadPage extends DecoratorAnimatedPage implements DecoratorPage
             if (repository.getGameDirectory() == GameDirectoryManager.getSelectedGameDirectory()) {
                 listenerHolder.add(FXUtils.onWeakChangeAndOperate(GameDirectoryManager.selectedInstanceProperty(), version -> {
                     if (modTab.isInitialized()) {
-                        modTab.getNode().loadInstance(repository, null);
+                        modTab.getNode().loadInstance(HMCLGameInstance.Optional.empty(repository));
                     }
                     if (modpackTab.isInitialized()) {
-                        modpackTab.getNode().loadInstance(repository, null);
+                        modpackTab.getNode().loadInstance(HMCLGameInstance.Optional.empty(repository));
                     }
                     if (resourcePackTab.isInitialized()) {
-                        resourcePackTab.getNode().loadInstance(repository, null);
+                        resourcePackTab.getNode().loadInstance(HMCLGameInstance.Optional.empty(repository));
                     }
                     if (shaderTab.isInitialized()) {
-                        shaderTab.getNode().loadInstance(repository, null);
+                        shaderTab.getNode().loadInstance(HMCLGameInstance.Optional.empty(repository));
                     }
                     if (worldTab.isInitialized()) {
-                        worldTab.getNode().loadInstance(repository, null);
+                        worldTab.getNode().loadInstance(HMCLGameInstance.Optional.empty(repository));
                     }
                 }));
             }
@@ -287,7 +286,7 @@ public class DownloadPage extends DecoratorAnimatedPage implements DecoratorPage
 
     private static class VanillaInstallWizardProvider implements WizardProvider {
         private final HMCLGameRepository repository;
-        private final DefaultDependencyManager dependencyManager;
+        private final HMCLDependencyManager dependencyManager;
         private final DownloadProvider downloadProvider;
         private final GameRemoteVersion gameVersion;
 
@@ -302,26 +301,44 @@ public class DownloadPage extends DecoratorAnimatedPage implements DecoratorPage
         public void start(SettingsMap settings) {
             settings.put(ModpackPage.GAME_DIRECTORY, repository.getGameDirectory());
             settings.put(ModpackPage.REPOSITORY, repository);
-            settings.put(LibraryAnalyzer.LibraryType.MINECRAFT.getPatchId(), gameVersion);
+            settings.put(GameComponentType.GAME.getPatchId(), gameVersion);
         }
 
-        private Task<Void> finishVersionDownloadingAsync(SettingsMap settings) {
-            GameBuilder builder = dependencyManager.gameBuilder();
+        /// Builds the selected instance and selects it after successful completion.
+        ///
+        /// @param settings the installer selections and target instance id
+        /// @return the builder task with its stage hints preserved as the outermost task wrapper
+        private Task<?> finishVersionDownloadingAsync(SettingsMap settings) {
+            @Nullable GameInstanceID instanceId = settings.get(AbstractInstallersPage.INSTANCE_ID);
+            if (instanceId == null) {
+                throw new IllegalStateException("Instance ID is not set");
+            }
 
-            String name = (String) settings.get("name");
-            builder.name(name);
-            builder.gameVersion(((RemoteVersion) settings.get(LibraryAnalyzer.LibraryType.MINECRAFT.getPatchId())).getGameVersion());
+            try (HMCLGameBuilder builder = dependencyManager.newGameBuilder(instanceId)) {
+                builder.component(GameComponentType.GAME, ((ComponentRemoteVersion) settings.get(GameComponentType.GAME.getPatchId())).getGameVersion().toString());
 
-            settings.asStringMap().forEach((key, value) -> {
-                if (!LibraryAnalyzer.LibraryType.MINECRAFT.getPatchId().equals(key)
-                        && value instanceof RemoteVersion remoteVersion)
-                    builder.version(remoteVersion);
-            });
+                settings.asStringMap().forEach((key, value) -> {
+                    if (!GameComponentType.GAME.getPatchId().equals(key)
+                            && value instanceof ComponentRemoteVersion remoteVersion)
+                        builder.component(remoteVersion);
+                });
 
-            repository.applyDefaultIsolationSettingForNewInstance(name, settings.isInstallingModdedVersion());
-            return builder.buildAsync().whenComplete(any -> {
-                repository.refreshVersions();
-            }).thenRunAsync(Schedulers.javafx(), () -> repository.setSelectedInstance(name));
+                boolean modded = GameComponentType.MOD_LOADERS.stream()
+                        .anyMatch(componentType ->
+                                settings.get(componentType.getPatchId()) instanceof ComponentRemoteVersion);
+                if (repository.shouldIsolateNewInstance(modded)) {
+                    builder.enableIsolation();
+                }
+
+                Task<?> buildTask = builder.buildAsync();
+                settings.put(TaskCleanup.KEY, builder::abort);
+                buildTask.onDone().register(event -> {
+                    if (!event.isFailed()) {
+                        runInFX(() -> repository.setSelectedInstance(repository.getInstance(instanceId)));
+                    }
+                });
+                return buildTask;
+            }
         }
 
         @Override
@@ -337,7 +354,7 @@ public class DownloadPage extends DecoratorAnimatedPage implements DecoratorPage
         public Node createPage(WizardController controller, int step, SettingsMap settings) {
             switch (step) {
                 case 0:
-                    return new InstallersPage(controller, repository, ((RemoteVersion) controller.getSettings().get("game")).getGameVersion(), downloadProvider);
+                    return new InstallersPage(controller, repository, ((ComponentRemoteVersion) controller.getSettings().get("game")).getGameVersion(), downloadProvider);
                 default:
                     throw new IllegalStateException("error step " + step + ", settings: " + settings + ", pages: " + controller.getPages());
             }

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/InstallersPage.java

@@ -18,8 +18,9 @@
 package org.jackhuang.hmcl.ui.download;
 
 import org.jackhuang.hmcl.download.DownloadProvider;
-import org.jackhuang.hmcl.download.LibraryAnalyzer;
-import org.jackhuang.hmcl.download.RemoteVersion;
+import org.jackhuang.hmcl.download.ComponentRemoteVersion;
+import org.jackhuang.hmcl.game.GameComponentType;
+import org.jackhuang.hmcl.game.GameInstanceID;
 import org.jackhuang.hmcl.game.HMCLGameRepository;
 import org.jackhuang.hmcl.ui.Controllers;
 import org.jackhuang.hmcl.ui.InstallerItem;
@@ -29,6 +30,7 @@ import org.jackhuang.hmcl.ui.construct.Validator;
 import org.jackhuang.hmcl.ui.wizard.WizardController;
 import org.jackhuang.hmcl.util.SettingsMap;
 import org.jackhuang.hmcl.util.i18n.I18n;
+import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
 
 import static javafx.beans.binding.Bindings.createBooleanBinding;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
@@ -37,13 +39,13 @@ public class InstallersPage extends AbstractInstallersPage {
 
     private boolean isNameModifiedByUser = false;
 
-    public InstallersPage(WizardController controller, HMCLGameRepository repository, String gameVersion, DownloadProvider downloadProvider) {
+    public InstallersPage(WizardController controller, HMCLGameRepository repository, GameVersionNumber gameVersion, DownloadProvider downloadProvider) {
         super(controller, gameVersion, downloadProvider);
 
         txtName.getValidators().addAll(
                 new RequiredValidator(),
-                new Validator(i18n("install.new_game.already_exists"), str -> !repository.versionIdConflicts(str)),
-                new Validator(i18n("install.new_game.malformed"), HMCLGameRepository::isValidVersionId));
+                new Validator(i18n("install.new_game.already_exists"), str -> !repository.instanceIdConflicts(str)),
+                new Validator(i18n("install.new_game.malformed"), HMCLGameRepository::isValidInstanceId));
         installable.bind(createBooleanBinding(txtName::validate, txtName.textProperty()));
 
         txtName.textProperty().addListener((obs, oldText, newText) -> isNameModifiedByUser = true);
@@ -51,20 +53,20 @@ public class InstallersPage extends AbstractInstallersPage {
 
     @Override
     public String getTitle() {
-        return ((RemoteVersion) controller.getSettings().get("game")).getGameVersion();
+        return ((ComponentRemoteVersion) controller.getSettings().get("game")).getGameVersion().toString();
     }
 
     private String getVersion(String id) {
-        return I18n.getDisplayVersion((RemoteVersion) controller.getSettings().get(id));
+        return I18n.getDisplayVersion((ComponentRemoteVersion) controller.getSettings().get(id));
     }
 
     protected void reload() {
-        for (InstallerItem library : group.getLibraries()) {
-            String libraryId = library.getLibraryId();
+        for (InstallerItem component : group.getComponents()) {
+            String libraryId = component.getComponentType().getPatchId();
             if (controller.getSettings().containsKey(libraryId)) {
-                library.versionProperty().set(new InstallerItem.InstalledState(getVersion(libraryId), false, false));
+                component.versionProperty().set(new InstallerItem.InstalledState(getVersion(libraryId), false, false));
             } else {
-                library.versionProperty().set(null);
+                component.versionProperty().set(null);
             }
         }
         if (!isNameModifiedByUser) {
@@ -91,22 +93,22 @@ public class InstallersPage extends AbstractInstallersPage {
     }
 
     protected void onInstall() {
-        String name = txtName.getText();
+        GameInstanceID instanceId = new GameInstanceID(txtName.getText());
 
-        if (!checkName(name)) {
+        if (!checkName(instanceId.id())) {
             Controllers.dialog(new MessageDialogPane.Builder(
                     i18n("install.name.invalid"),
                     i18n("message.warning"),
                     MessageDialogPane.MessageType.QUESTION)
                     .yesOrNo(() -> {
-                        controller.getSettings().put("name", name);
+                        controller.getSettings().put(INSTANCE_ID, instanceId);
                         controller.onFinish();
                     }, () -> {
                         // The user selects Cancel and does nothing.
                     })
                     .build());
         } else {
-            controller.getSettings().put("name", name);
+            controller.getSettings().put(INSTANCE_ID, instanceId);
             controller.onFinish();
         }
     }
@@ -114,30 +116,25 @@ public class InstallersPage extends AbstractInstallersPage {
     private void setTxtNameWithLoaders() {
         StringBuilder nameBuilder = new StringBuilder(getTitle());
 
-        for (InstallerItem library : group.getLibraries()) {
-            String libraryId = library.getLibraryId().replace(LibraryAnalyzer.LibraryType.MINECRAFT.getPatchId(), "");
-            if (!controller.getSettings().containsKey(libraryId)) {
+        for (InstallerItem component : group.getComponents()) {
+            if (component.getComponentType() == GameComponentType.GAME
+                    || !controller.getSettings().containsKey(component.getComponentType().getPatchId()))
                 continue;
-            }
 
-            LibraryAnalyzer.LibraryType libraryType = LibraryAnalyzer.LibraryType.fromPatchId(libraryId);
+            String loaderName = switch (component.getComponentType()) {
+                case FORGE -> "Forge";
+                case NEO_FORGE -> "NeoForge";
+                case CLEANROOM -> "Cleanroom";
+                case LEGACY_FABRIC -> "LegacyFabric";
+                case FABRIC -> "Fabric";
+                case LITELOADER -> "LiteLoader";
+                case QUILT -> "Quilt";
+                case OPTIFINE -> "OptiFine";
+                default -> null;
+            };
 
-            if (libraryType != null) {
-                String loaderName = switch (libraryType) {
-                    case FORGE -> "Forge";
-                    case NEO_FORGE -> "NeoForge";
-                    case CLEANROOM -> "Cleanroom";
-                    case LEGACY_FABRIC -> "LegacyFabric";
-                    case FABRIC -> "Fabric";
-                    case LITELOADER -> "LiteLoader";
-                    case QUILT -> "Quilt";
-                    case OPTIFINE -> "OptiFine";
-                    default -> null;
-                };
-
-                if (loaderName != null)
-                    nameBuilder.append('-').append(loaderName);
-            }
+            if (loaderName != null)
+                nameBuilder.append('-').append(loaderName);
         }
 
         txtName.setText(nameBuilder.toString());

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/LocalModpackPage.java

@@ -20,11 +20,18 @@ package org.jackhuang.hmcl.ui.download;
 import javafx.application.Platform;
 import javafx.beans.property.BooleanProperty;
 import javafx.beans.property.SimpleBooleanProperty;
+import javafx.collections.FXCollections;
+import javafx.collections.ObservableList;
+import javafx.collections.ObservableSet;
+import javafx.collections.transformation.FilteredList;
 import javafx.stage.FileChooser;
 import org.jackhuang.hmcl.game.HMCLGameRepository;
 import org.jackhuang.hmcl.game.ManuallyCreatedModpackException;
 import org.jackhuang.hmcl.game.ModpackHelper;
 import org.jackhuang.hmcl.modpack.Modpack;
+import org.jackhuang.hmcl.modpack.ModpackFile;
+import org.jackhuang.hmcl.modpack.ModpackManifest;
+import org.jackhuang.hmcl.setting.DownloadProviders;
 import org.jackhuang.hmcl.setting.GameDirectoryManager;
 import org.jackhuang.hmcl.task.Schedulers;
 import org.jackhuang.hmcl.task.Task;
@@ -39,9 +46,15 @@ import org.jackhuang.hmcl.util.SettingsMap;
 import org.jackhuang.hmcl.util.StringUtils;
 import org.jackhuang.hmcl.util.io.CompressingUtils;
 import org.jackhuang.hmcl.util.io.FileUtils;
+import org.jetbrains.annotations.Nullable;
 
 import java.nio.charset.Charset;
 import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
 
 import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
@@ -51,10 +64,22 @@ public final class LocalModpackPage extends ModpackPage {
     private final BooleanProperty installAsVersion = new SimpleBooleanProperty(true);
     private Modpack manifest = null;
     private Charset charset;
+    private final ObservableList<ModpackFile> allFiles = FXCollections.observableList(new ArrayList<>());
+    private final ObservableSet<String> excludedFiles = FXCollections.observableSet(new HashSet<>());
+    private final BooleanProperty loadingOptionalFiles = new SimpleBooleanProperty(false);
+    private final BooleanProperty loadedOptionalFiles = new SimpleBooleanProperty(true);
 
     public LocalModpackPage(WizardController controller) {
         super(controller);
 
+        btnOptionalFiles.setOnAction(ev -> controller.onNext(new OptionalFilesPage(
+                this::onInstall,
+                this::loadOptionalFiles,
+                loadingOptionalFiles,
+                loadedOptionalFiles,
+                new FilteredList<>(allFiles, ModpackFile::optional),
+                excludedFiles)));
+
         HMCLGameRepository repository = controller.getSettings().get(ModpackPage.REPOSITORY);
 
         String name = controller.getSettings().get(MODPACK_NAME);
@@ -66,8 +91,8 @@ public final class LocalModpackPage extends ModpackPage {
                 if (installAsVersion) {
                     txtModpackName.getValidators().setAll(
                             new RequiredValidator(),
-                            new Validator(i18n("install.new_game.already_exists"), str -> !repository.versionIdConflicts(str)),
-                            new Validator(i18n("install.new_game.malformed"), HMCLGameRepository::isValidVersionId));
+                            new Validator(i18n("install.new_game.already_exists"), str -> !repository.instanceIdConflicts(str)),
+                            new Validator(i18n("install.new_game.malformed"), HMCLGameRepository::isValidInstanceId));
                 } else {
                     txtModpackName.getValidators().setAll(
                             new RequiredValidator(),
@@ -75,7 +100,7 @@ public final class LocalModpackPage extends ModpackPage {
                                     && GameDirectoryManager.getGameDirectories().stream()
                                             .noneMatch(existingProfile ->
                                                     str.equals(GameDirectoryManager.getGameDirectoryCustomName(existingProfile)))),
-                            new Validator(i18n("install.new_game.malformed"), HMCLGameRepository::isValidVersionId));
+                            new Validator(i18n("install.new_game.malformed"), HMCLGameRepository::isValidInstanceId));
                 }
             });
         }
@@ -103,8 +128,7 @@ public final class LocalModpackPage extends ModpackPage {
         Task.supplyAsync(() -> CompressingUtils.findSuitableEncoding(selectedFile))
                 .thenApplyAsync(encoding -> {
                     charset = encoding;
-                    manifest = ModpackHelper.readModpackManifest(selectedFile, encoding);
-                    return manifest;
+                    return ModpackHelper.readModpackManifest(selectedFile, encoding);
                 })
                 .whenComplete(Schedulers.javafx(), (manifest, exception) -> {
                     if (exception instanceof ManuallyCreatedModpackException) {
@@ -126,7 +150,11 @@ public final class LocalModpackPage extends ModpackPage {
                         LOG.warning("Failed to read modpack manifest", exception);
                         Controllers.dialog(i18n("modpack.task.install.error"), i18n("message.error"), MessageDialogPane.MessageType.ERROR);
                         Platform.runLater(controller::onEnd);
+                    } else if (manifest == null) {
+                        Controllers.dialog(i18n("modpack.task.install.error"), i18n("message.error"), MessageDialogPane.MessageType.ERROR);
+                        Platform.runLater(controller::onEnd);
                     } else {
+                        this.manifest = manifest;
                         hideSpinner();
                         controller.getSettings().put(MODPACK_MANIFEST, manifest);
                         nameProperty.set(manifest.getName());
@@ -139,6 +167,33 @@ public final class LocalModpackPage extends ModpackPage {
                         }
 
                         btnDescription.setVisible(StringUtils.isNotBlank(manifest.getDescription()));
+
+                        if (manifest.getManifest() instanceof ModpackManifest.SupportOptional supportOptional) {
+                            allFiles.setAll(supportOptional.getFiles());
+                            if (allFiles.stream().anyMatch(ModpackFile::optional)) {
+                                loadOptionalFiles();
+                                btnOptionalFiles.setVisible(true);
+                                btnOptionalFiles.setManaged(true);
+                            }
+                        }
+                    }
+                }).start();
+    }
+
+    private void loadOptionalFiles() {
+        Objects.requireNonNull(manifest);
+        loadingOptionalFiles.set(true);
+        loadedOptionalFiles.set(false);
+        Task.supplyAsync(() -> manifest.getManifest().getProvider().loadFiles(DownloadProviders.getDownloadProvider(), manifest.getManifest()))
+                .whenComplete(Schedulers.javafx(), (manifest1, exception) -> {
+                    loadingOptionalFiles.set(false);
+                    List<? extends ModpackFile> files = ((ModpackManifest.SupportOptional) manifest1).getFiles();
+                    manifest.setManifest(manifest1);
+                    allFiles.setAll(files);
+                    if (files.stream().anyMatch(s -> s.optional() && (!s.addonQueried() || s.fileName() == null))) {
+                        LOG.warning("Failed to load optional files");
+                    } else {
+                        loadedOptionalFiles.set(true);
                     }
                 }).start();
     }
@@ -157,21 +212,28 @@ public final class LocalModpackPage extends ModpackPage {
                     i18n("install.name.invalid"),
                     i18n("message.warning"),
                     MessageDialogPane.MessageType.QUESTION)
-                    .yesOrNo(() -> {
-                        controller.getSettings().put(MODPACK_NAME, name);
-                        controller.getSettings().put(MODPACK_CHARSET, charset);
-                        controller.onFinish();
-                    }, () -> {
+                    .yesOrNo(() -> finishInstall(name), () -> {
                         // The user selects Cancel and does nothing.
                     })
                     .build());
         } else {
-            controller.getSettings().put(MODPACK_NAME, name);
-            controller.getSettings().put(MODPACK_CHARSET, charset);
-            controller.onFinish();
+            finishInstall(name);
         }
     }
 
+    private void finishInstall(String name) {
+        controller.getSettings().put(MODPACK_NAME, name);
+        controller.getSettings().put(MODPACK_CHARSET, charset);
+        controller.getSettings().put(MODPACK_EXCLUDED_FILES, getExcludedFiles());
+        controller.onFinish();
+    }
+
+    private @Nullable Set<String> getExcludedFiles() {
+        if (allFiles.isEmpty())
+            return null;
+        return Set.copyOf(excludedFiles);
+    }
+
     protected void onDescribe() {
         if (manifest != null)
             Controllers.navigate(new WebPage(i18n("modpack.description"), manifest.getDescription()));
@@ -183,4 +245,5 @@ public final class LocalModpackPage extends ModpackPage {
     public static final SettingsMap.Key<Charset> MODPACK_CHARSET = new SettingsMap.Key<>("MODPACK_CHARSET");
     public static final SettingsMap.Key<Boolean> MODPACK_MANUALLY_CREATED = new SettingsMap.Key<>("MODPACK_MANUALLY_CREATED");
     public static final SettingsMap.Key<String> MODPACK_ICON_URL = new SettingsMap.Key<>("MODPACK_ICON_URL");
+    public static final SettingsMap.Key<Set<String>> MODPACK_EXCLUDED_FILES = new SettingsMap.Key<>("MODPACK_EXCLUDED_FILES");
 }

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/ModpackInstallWizardProvider.java

@@ -18,9 +18,7 @@
 package org.jackhuang.hmcl.ui.download;
 
 import javafx.scene.Node;
-import org.jackhuang.hmcl.game.HMCLGameRepository;
-import org.jackhuang.hmcl.game.ManuallyCreatedModpackException;
-import org.jackhuang.hmcl.game.ModpackHelper;
+import org.jackhuang.hmcl.game.*;
 import org.jackhuang.hmcl.modpack.MismatchedModpackTypeException;
 import org.jackhuang.hmcl.modpack.Modpack;
 import org.jackhuang.hmcl.modpack.ModpackCompletionException;
@@ -57,14 +55,14 @@ public final class ModpackInstallWizardProvider implements WizardProvider {
         this(repository, modpackFile, null);
     }
 
-    public ModpackInstallWizardProvider(HMCLGameRepository repository, String updateVersion) {
-        this(repository, null, updateVersion);
+    public ModpackInstallWizardProvider(HMCLGameRepository repository, GameInstanceID updateInstanceId) {
+        this(repository, null, updateInstanceId);
     }
 
-    public ModpackInstallWizardProvider(HMCLGameRepository repository, Path modpackFile, String updateVersion) {
+    public ModpackInstallWizardProvider(HMCLGameRepository repository, Path modpackFile, GameInstanceID updateInstanceId) {
         this.repository = repository;
         this.file = modpackFile;
-        this.updateVersion = updateVersion;
+        this.updateVersion = updateInstanceId != null ? updateInstanceId.toString() : null;
     }
 
     public void setIconUrl(String iconUrl) {
@@ -92,6 +90,7 @@ public final class ModpackInstallWizardProvider implements WizardProvider {
         String iconUrl = settings.get(LocalModpackPage.MODPACK_ICON_URL);
         Charset charset = settings.get(LocalModpackPage.MODPACK_CHARSET);
         boolean isManuallyCreated = settings.getOrDefault(LocalModpackPage.MODPACK_MANUALLY_CREATED, false);
+        var excludedFiles = settings.get(LocalModpackPage.MODPACK_EXCLUDED_FILES);
 
         if (isManuallyCreated) {
             return ModpackHelper.getInstallManuallyCreatedModpackTask(selected, name, charset);
@@ -99,6 +98,8 @@ public final class ModpackInstallWizardProvider implements WizardProvider {
 
         if ((selected == null && serverModpackManifest == null) || modpack == null || name == null) return null;
 
+        GameInstanceID instanceId = new GameInstanceID(name);
+
         if (updateVersion != null) {
             if (selected == null) {
                 Controllers.dialog(i18n("modpack.unsupported"), i18n("message.error"), MessageType.ERROR);
@@ -106,9 +107,9 @@ public final class ModpackInstallWizardProvider implements WizardProvider {
             }
             try {
                 if (serverModpackManifest != null) {
-                    return ModpackHelper.getUpdateTask(repository, serverModpackManifest, modpack.getEncoding(), name, ModpackHelper.readModpackConfiguration(repository.getModpackConfiguration(name)));
+                    return ModpackHelper.getUpdateTask(repository, serverModpackManifest, modpack.getEncoding(), instanceId, ModpackHelper.readModpackConfiguration(repository.getLayout().getModpackConfigurationFile(instanceId)));
                 } else {
-                    return ModpackHelper.getUpdateTask(repository, selected, modpack.getEncoding(), name, ModpackHelper.readModpackConfiguration(repository.getModpackConfiguration(name)));
+                    return ModpackHelper.getUpdateTask(repository, selected, modpack.getEncoding(), instanceId, ModpackHelper.readModpackConfiguration(repository.getLayout().getModpackConfigurationFile(instanceId)), excludedFiles);
                 }
             } catch (UnsupportedModpackException | ManuallyCreatedModpackException e) {
                 Controllers.dialog(i18n("modpack.unsupported"), i18n("message.error"), MessageType.ERROR);
@@ -120,11 +121,11 @@ public final class ModpackInstallWizardProvider implements WizardProvider {
             return null;
         } else {
             if (serverModpackManifest != null) {
-                return ModpackHelper.getInstallTask(repository, serverModpackManifest, name, modpack)
-                        .thenRunAsync(Schedulers.javafx(), () -> repository.setSelectedInstance(name));
+                return ModpackHelper.getInstallTask(repository, serverModpackManifest, instanceId, modpack)
+                        .thenRunAsync(Schedulers.javafx(), () -> repository.setSelectedInstance(repository.getInstance(instanceId)));
             } else {
-                return ModpackHelper.getInstallTask(repository, selected, name, modpack, iconUrl)
-                        .thenRunAsync(Schedulers.javafx(), () -> repository.setSelectedInstance(name));
+                return ModpackHelper.getInstallTask(repository, selected, instanceId, modpack, iconUrl, excludedFiles)
+                        .thenRunAsync(Schedulers.javafx(), () -> repository.setSelectedInstance(repository.getInstance(instanceId)));
             }
         }
     }

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/ModpackPage.java

@@ -22,6 +22,7 @@ import com.jfoenix.controls.JFXTextField;
 import javafx.beans.property.StringProperty;
 import javafx.geometry.Pos;
 import javafx.scene.layout.BorderPane;
+import javafx.scene.layout.HBox;
 import javafx.scene.layout.VBox;
 import org.jackhuang.hmcl.game.HMCLGameRepository;
 import org.jackhuang.hmcl.setting.GameDirectory;
@@ -49,6 +50,7 @@ public abstract class ModpackPage extends SpinnerPane implements WizardPage {
     protected final JFXTextField txtModpackName;
     protected final JFXButton btnInstall;
     protected final JFXButton btnDescription;
+    protected final JFXButton btnOptionalFiles;
 
     protected ModpackPage(WizardController controller) {
         this.controller = controller;
@@ -62,12 +64,10 @@ public abstract class ModpackPage extends SpinnerPane implements WizardPage {
             var archiveNamePane = new LinePane();
             {
                 FXUtils.setLimitHeight(archiveNamePane, 75);
-
-                archiveNamePane.setTitle(i18n("version.name"));
+                archiveNamePane.setTitle(i18n("instance.name"));
 
                 txtModpackName = new JFXTextField();
                 txtModpackName.setPrefWidth(300);
-                // BorderPane.setMargin(txtModpackName, new Insets(0, 0, 8, 32));
                 BorderPane.setAlignment(txtModpackName, Pos.CENTER_RIGHT);
                 archiveNamePane.setRight(txtModpackName);
             }
@@ -96,10 +96,19 @@ public abstract class ModpackPage extends SpinnerPane implements WizardPage {
                 btnDescription.setOnAction(e -> onDescribe());
                 descriptionPane.setLeft(btnDescription);
 
+                var installHBox = new HBox(8);
+                btnOptionalFiles = FXUtils.newRaisedButton(i18n("modpack.optional_files"));
+                btnOptionalFiles.setVisible(false);
+                btnOptionalFiles.setManaged(false);
+                installHBox.getChildren().add(btnOptionalFiles);
+
                 btnInstall = FXUtils.newRaisedButton(i18n("button.install"));
                 btnInstall.setOnAction(e -> onInstall());
-                btnInstall.disableProperty().bind(createBooleanBinding(() -> !txtModpackName.validate(), txtModpackName.textProperty()));
-                descriptionPane.setRight(btnInstall);
+                var nameInvalid = createBooleanBinding(() -> !txtModpackName.validate(), txtModpackName.textProperty());
+                btnInstall.disableProperty().bind(nameInvalid);
+                btnOptionalFiles.disableProperty().bind(nameInvalid);
+                installHBox.getChildren().add(btnInstall);
+                descriptionPane.setRight(installHBox);
             }
 
             componentList.getContent().setAll(

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/ModpackSelectionPage.java

@@ -27,6 +27,8 @@ import javafx.scene.layout.BorderPane;
 import javafx.scene.layout.VBox;
 import javafx.scene.shape.SVGPath;
 import javafx.stage.FileChooser;
+import org.glavo.url.WebURL;
+import org.jackhuang.hmcl.game.GameInstanceID;
 import org.jackhuang.hmcl.game.ModpackHelper;
 import org.jackhuang.hmcl.modpack.server.ServerModpackManifest;
 import org.jackhuang.hmcl.task.FileDownloadTask;
@@ -43,7 +45,6 @@ import org.jackhuang.hmcl.util.SettingsMap;
 import org.jackhuang.hmcl.util.TaskCancellationAction;
 import org.jackhuang.hmcl.util.gson.JsonUtils;
 
-import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
@@ -113,7 +114,6 @@ public final class ModpackSelectionPage extends VBox implements WizardPage {
         chooser.getExtensionFilters().add(new FileChooser.ExtensionFilter(i18n("modpack"), "*.zip", "*.mrpack"));
         Path selectedFile = Controllers.showOpenDialog(chooser);
         if (selectedFile == null) {
-            Platform.runLater(controller::onEnd);
             return;
         }
 
@@ -126,7 +126,7 @@ public final class ModpackSelectionPage extends VBox implements WizardPage {
             try {
                 if (url.endsWith("server-manifest.json")) {
                     // if urlString ends with .json, we assume that the url is server-manifest.json
-                    Controllers.taskDialog(new GetTask(url).whenComplete(Schedulers.javafx(), (result, e) -> {
+                    Controllers.taskDialog(new GetTask(WebURL.parse(url)).whenComplete(Schedulers.javafx(), (result, e) -> {
                         ServerModpackManifest manifest = JsonUtils.fromMaybeMalformedJson(result, ServerModpackManifest.class);
                         if (manifest == null) {
                             handler.reject(i18n("modpack.type.server.malformed"));
@@ -157,15 +157,15 @@ public final class ModpackSelectionPage extends VBox implements WizardPage {
                             TaskCancellationAction.NORMAL
                     );
                 }
-            } catch (IOException e) {
-                handler.reject(e.getMessage());
+            } catch (Exception e) {
+                handler.reject(i18n("message.failed"));
             }
         }, "", new URLValidator());
     }
 
     public void onChooseRepository() {
         String modPackName = controller.getSettings().get(MODPACK_NAME);
-        DownloadPage downloadPage = new DownloadPage(modPackName);
+        DownloadPage downloadPage = new DownloadPage(modPackName != null ? new GameInstanceID(modPackName) : null);
         downloadPage.showModpackDownloads();
         Controllers.navigate(downloadPage);
     }

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/OptionalFilesPage.java

@@ -0,0 +1,322 @@
+/*
+ * Hello Minecraft! Launcher
+ * Copyright (C) 2026 huangyuhui <huanghongxun2008@126.com> and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.jackhuang.hmcl.ui.download;
+
+import com.jfoenix.controls.JFXButton;
+import com.jfoenix.controls.JFXCheckBox;
+import com.jfoenix.controls.JFXDialogLayout;
+import com.jfoenix.controls.JFXListView;
+import javafx.beans.binding.Bindings;
+import javafx.beans.property.BooleanProperty;
+import javafx.beans.property.SimpleBooleanProperty;
+import javafx.beans.value.ObservableBooleanValue;
+import javafx.collections.ObservableList;
+import javafx.collections.ObservableSet;
+import javafx.collections.SetChangeListener;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import javafx.scene.control.Label;
+import javafx.scene.image.ImageView;
+import javafx.scene.layout.BorderPane;
+import javafx.scene.layout.HBox;
+import javafx.scene.layout.Priority;
+import javafx.scene.layout.Region;
+import javafx.scene.layout.VBox;
+import org.jackhuang.hmcl.addon.RemoteAddon;
+import org.jackhuang.hmcl.modpack.ModpackFile;
+import org.jackhuang.hmcl.task.Schedulers;
+import org.jackhuang.hmcl.ui.Controllers;
+import org.jackhuang.hmcl.ui.FXUtils;
+import org.jackhuang.hmcl.ui.SVG;
+import org.jackhuang.hmcl.ui.construct.ComponentList;
+import org.jackhuang.hmcl.ui.construct.DialogCloseEvent;
+import org.jackhuang.hmcl.ui.construct.JFXHyperlink;
+import org.jackhuang.hmcl.ui.construct.MDListCell;
+import org.jackhuang.hmcl.ui.construct.SpinnerPane;
+import org.jackhuang.hmcl.ui.construct.TwoLineListItem;
+import org.jackhuang.hmcl.ui.wizard.WizardPage;
+import org.jackhuang.hmcl.util.SettingsMap;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+
+import static org.jackhuang.hmcl.ui.FXUtils.onEscPressed;
+import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
+
+/// Wizard page that lets the user choose which optional modpack files to install.
+@NotNullByDefault
+public class OptionalFilesPage extends SpinnerPane implements WizardPage {
+
+    /// Fixed row height used to size [#body] to its items.
+    private static final double CELL_HEIGHT = 48;
+
+    /// Maximum list viewport height before scrolling.
+    private static final double MAX_LIST_HEIGHT = 320;
+
+    /// Keys of files the user unchecked; empty means all optional files will be installed.
+    private final ObservableSet<String> excludedFiles;
+
+    /// Per-file selected state mirrored from [#excludedFiles] (`true` means install / not excluded).
+    private final Map<String, BooleanProperty> selectedByKey = new HashMap<>();
+
+    /// Whether [#selectedByKey] is being updated from an [#excludedFiles] set change.
+    private boolean updatingFromSet;
+
+    /// List view showing optional files.
+    private final JFXListView<ModpackFile> body = new JFXListView<>();
+
+    /// Creates the optional-files selection page.
+    ///
+    /// @param install         callback that finishes the install wizard
+    /// @param retry           callback that reloads optional-file metadata
+    /// @param loading         whether remote metadata is still loading
+    /// @param successful      whether remote metadata loaded successfully
+    /// @param optionalFiles   optional files to display
+    /// @param excludedFiles   mutable set of unchecked optional file keys
+    public OptionalFilesPage(
+            Runnable install,
+            Runnable retry,
+            ObservableBooleanValue loading,
+            ObservableBooleanValue successful,
+            ObservableList<ModpackFile> optionalFiles,
+            ObservableSet<String> excludedFiles) {
+        this.excludedFiles = excludedFiles;
+        excludedFiles.addListener((SetChangeListener<String>) change -> {
+            updatingFromSet = true;
+            try {
+                if (change.wasRemoved()) {
+                    BooleanProperty selected = selectedByKey.get(change.getElementRemoved());
+                    if (selected != null)
+                        selected.set(true);
+                }
+                if (change.wasAdded()) {
+                    BooleanProperty selected = selectedByKey.get(change.getElementAdded());
+                    if (selected != null)
+                        selected.set(false);
+                }
+            } finally {
+                updatingFromSet = false;
+            }
+        });
+
+        VBox borderPane = new VBox();
+        borderPane.setAlignment(Pos.CENTER);
+        borderPane.setMaxHeight(Region.USE_PREF_SIZE);
+        FXUtils.setLimitWidth(borderPane, 500);
+
+        ComponentList componentList = new ComponentList();
+
+        Label lblRetry = new Label(i18n("modpack.retry_optional_files"));
+        lblRetry.setOnMouseClicked(e -> retry.run());
+
+        VBox tail = new VBox();
+        {
+            var descPane = new BorderPane();
+            HBox selectionButtons = new HBox(8);
+            JFXButton btnSelectAll = FXUtils.newBorderButton(i18n("button.select_all"));
+            btnSelectAll.setOnAction(e -> excludedFiles.clear());
+            JFXButton btnClear = FXUtils.newBorderButton(i18n("button.clear"));
+            btnClear.setOnAction(e -> {
+                excludedFiles.clear();
+                for (ModpackFile file : optionalFiles) {
+                    excludedFiles.add(file.key());
+                }
+            });
+            selectionButtons.getChildren().setAll(btnSelectAll, btnClear);
+            descPane.setLeft(selectionButtons);
+
+            var btnInstall = FXUtils.newRaisedButton(i18n("button.install"));
+            descPane.setRight(btnInstall);
+            btnInstall.setOnAction(e -> install.run());
+            tail.getChildren().add(descPane);
+        }
+
+        // ListView defaults to a large preferred height (~400) regardless of item count, which
+        // leaves empty viewport space when few optional files exist. Size exactly to content —
+        // do not add extra pixels, or a blank strip appears under the last row.
+        body.setFixedCellSize(CELL_HEIGHT);
+        body.prefHeightProperty().bind(Bindings.createDoubleBinding(
+                () -> Math.min(MAX_LIST_HEIGHT, optionalFiles.size() * CELL_HEIGHT + 2),
+                optionalFiles));
+        body.setMaxHeight(Region.USE_PREF_SIZE);
+        body.setCellFactory(it -> new OptionalFileEntry(body));
+        body.setItems(optionalFiles);
+
+        Runnable refreshContent = () -> {
+            if (successful.get()) {
+                componentList.getContent().setAll(body, tail);
+            } else {
+                componentList.getContent().setAll(lblRetry, body, tail);
+            }
+        };
+        refreshContent.run();
+        successful.addListener((obs, oldVal, newVal) -> refreshContent.run());
+
+        borderPane.getChildren().setAll(componentList);
+        setContent(borderPane);
+        loadingProperty().bind(loading);
+    }
+
+    /// Returns the selected property for `key`, creating and wiring it on first use.
+    ///
+    /// @param key the file exclusion key
+    /// @return a property that is `true` when the file is selected for install
+    private BooleanProperty selectedProperty(String key) {
+        return selectedByKey.computeIfAbsent(key, k -> {
+            BooleanProperty selected = new SimpleBooleanProperty(!excludedFiles.contains(k));
+            selected.addListener((obs, wasSelected, isSelected) -> {
+                if (updatingFromSet)
+                    return;
+                if (isSelected) {
+                    excludedFiles.remove(k);
+                } else {
+                    excludedFiles.add(k);
+                }
+            });
+            return selected;
+        });
+    }
+
+    /// List cell for one optional file with checkbox and detail button.
+    private final class OptionalFileEntry extends MDListCell<ModpackFile> {
+        private final JFXCheckBox checkBox = new JFXCheckBox();
+        private final TwoLineListItem content = new TwoLineListItem();
+        private final JFXButton infoButton = new JFXButton();
+        private final HBox container = new HBox(8);
+
+        /// Currently bidirectionally bound selected property, or `null` when unbound.
+        private @Nullable BooleanProperty boundSelected = null;
+
+        /// Creates a cell bound to `listView`.
+        ///
+        /// @param listView the owning list view
+        public OptionalFileEntry(JFXListView<ModpackFile> listView) {
+            super(listView);
+            container.setPickOnBounds(false);
+            container.setAlignment(Pos.CENTER_LEFT);
+            HBox.setHgrow(content, Priority.ALWAYS);
+            content.setMouseTransparent(true);
+            setSelectable();
+            container.getChildren().setAll(checkBox, content);
+
+            infoButton.getStyleClass().add("toggle-icon4");
+            infoButton.setGraphic(SVG.INFO.createIcon());
+            container.getChildren().add(infoButton);
+            getContainer().getChildren().setAll(container);
+        }
+
+        @Override
+        protected void updateControl(ModpackFile item, boolean empty) {
+            if (empty) {
+                if (boundSelected != null) {
+                    checkBox.selectedProperty().unbindBidirectional(boundSelected);
+                    boundSelected = null;
+                }
+                return;
+            }
+            String name = item.fileName();
+            if (name != null) {
+                content.setTitle(name);
+            } else {
+                content.setTitle(i18n("modpack.unknown_optional_file"));
+            }
+            RemoteAddon addon = item.remoteAddon();
+            if (addon != null) {
+                content.setSubtitle(addon.title());
+                infoButton.setOnMouseClicked(e -> Controllers.dialog(new ModInfo(addon)));
+                infoButton.setManaged(true);
+                infoButton.setVisible(true);
+            } else {
+                content.setSubtitle("");
+                infoButton.setOnMouseClicked(null);
+                infoButton.setManaged(false);
+                infoButton.setVisible(false);
+            }
+            BooleanProperty selected = OptionalFilesPage.this.selectedProperty(item.key());
+            if (boundSelected != selected) {
+                if (boundSelected != null)
+                    checkBox.selectedProperty().unbindBidirectional(boundSelected);
+                checkBox.selectedProperty().bindBidirectional(selected);
+                boundSelected = selected;
+            }
+        }
+    }
+
+    /// Dialog showing remote addon details for an optional file.
+    private static final class ModInfo extends JFXDialogLayout {
+        /// Creates a detail dialog for `addon`.
+        ///
+        /// @param addon the remote addon
+        public ModInfo(RemoteAddon addon) {
+            HBox container = new HBox(8);
+            SpinnerPane spinnerPane = new SpinnerPane();
+            ImageView imageView = new ImageView();
+            imageView.setFitHeight(32);
+            imageView.setFitWidth(32);
+            spinnerPane.setContent(imageView);
+            spinnerPane.setPrefSize(32, 32);
+            spinnerPane.setLoading(true);
+            CompletableFuture.supplyAsync(() -> {
+                try {
+                    return FXUtils.getRemoteImageTask(addon.iconUrl(), 32, 32, true, true).run();
+                } catch (Exception e) {
+                    throw new RuntimeException(e);
+                }
+            }, Schedulers.io()).thenAcceptAsync((image) -> {
+                imageView.setImage(image);
+                spinnerPane.setLoading(false);
+            }, Schedulers.javafx());
+            container.getChildren().add(spinnerPane);
+
+            TwoLineListItem title = new TwoLineListItem();
+            title.setTitle(addon.title());
+            title.setSubtitle(addon.author());
+            container.getChildren().add(title);
+            setHeading(container);
+
+            Label description = new Label(addon.description());
+            description.setWrapText(true);
+            description.setPadding(new Insets(8, 0, 0, 0));
+            setBody(description);
+
+            JFXHyperlink pageButton = new JFXHyperlink(i18n("mods.url"));
+            pageButton.setOnAction(e -> FXUtils.openLink(addon.pageUrl()));
+            getActions().add(pageButton);
+
+            JFXButton okButton = new JFXButton();
+            okButton.getStyleClass().add("dialog-accept");
+            okButton.setText(i18n("button.ok"));
+            okButton.setOnAction(e -> fireEvent(new DialogCloseEvent()));
+            getActions().add(okButton);
+
+            onEscPressed(this, okButton::fire);
+        }
+    }
+
+    @Override
+    public String getTitle() {
+        return i18n("modpack.optional_files");
+    }
+
+    @Override
+    public void cleanup(SettingsMap settings) {
+    }
+}

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/RemoteModpackPage.java

@@ -66,8 +66,8 @@ public final class RemoteModpackPage extends ModpackPage {
             txtModpackName.setText(manifest.getName().trim());
             txtModpackName.getValidators().addAll(
                     new RequiredValidator(),
-                    new Validator(i18n("install.new_game.already_exists"), str -> !repository.versionIdConflicts(str)),
-                    new Validator(i18n("install.new_game.malformed"), HMCLGameRepository::isValidVersionId));
+                    new Validator(i18n("install.new_game.already_exists"), str -> !repository.instanceIdConflicts(str)),
+                    new Validator(i18n("install.new_game.malformed"), HMCLGameRepository::isValidInstanceId));
         }
 
         btnDescription.setVisible(StringUtils.isNotBlank(manifest.getDescription()));

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/UpdateInstallerWizardProvider.java

@@ -20,9 +20,11 @@ package org.jackhuang.hmcl.ui.download;
 import javafx.scene.Node;
 import org.jackhuang.hmcl.download.*;
 import org.jackhuang.hmcl.download.game.GameAssetIndexDownloadTask;
+import org.jackhuang.hmcl.download.game.GameRemoteVersion;
 import org.jackhuang.hmcl.download.game.LibraryDownloadException;
-import org.jackhuang.hmcl.game.HMCLGameRepository;
-import org.jackhuang.hmcl.game.Version;
+import org.jackhuang.hmcl.game.GameComponentType;
+import org.jackhuang.hmcl.game.GameInstanceManifest;
+import org.jackhuang.hmcl.game.HMCLGameInstance;
 import org.jackhuang.hmcl.setting.DownloadProviders;
 import org.jackhuang.hmcl.task.DownloadException;
 import org.jackhuang.hmcl.task.Task;
@@ -34,11 +36,11 @@ import org.jackhuang.hmcl.util.SettingsMap;
 import org.jackhuang.hmcl.util.StringUtils;
 import org.jackhuang.hmcl.util.i18n.I18n;
 import org.jackhuang.hmcl.util.io.ResponseCodeException;
+import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.net.SocketTimeoutException;
-import java.net.URI;
 import java.util.ArrayList;
 import java.util.concurrent.CancellationException;
 import java.util.zip.ZipException;
@@ -46,66 +48,71 @@ import java.util.zip.ZipException;
 import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 
 public final class UpdateInstallerWizardProvider implements WizardProvider {
-    private final HMCLGameRepository repository;
+    private final HMCLGameInstance gameInstance;
     private final DefaultDependencyManager dependencyManager;
-    private final String gameVersion;
-    private final Version version;
-    private final String libraryId;
+    private final GameComponentType componentType;
     private final String oldLibraryVersion;
     private final DownloadProvider downloadProvider;
 
-    public UpdateInstallerWizardProvider(@NotNull HMCLGameRepository repository, @NotNull String gameVersion, @NotNull Version version, @NotNull String libraryId, @Nullable String oldLibraryVersion) {
-        this.repository = repository;
-        this.gameVersion = gameVersion;
-        this.version = version;
-        this.libraryId = libraryId;
+    public UpdateInstallerWizardProvider(@NotNull HMCLGameInstance gameInstance, @NotNull GameComponentType componentType, @Nullable String oldLibraryVersion) {
+        this.gameInstance = gameInstance;
+        this.componentType = componentType;
         this.oldLibraryVersion = oldLibraryVersion;
         this.downloadProvider = DownloadProviders.getDownloadProvider();
-        this.dependencyManager = repository.getDependency(downloadProvider);
+        this.dependencyManager = gameInstance.getRepository().getDependency(downloadProvider);
     }
 
     @Override
     public void start(SettingsMap settings) {
     }
 
+    /// Creates a task that updates components and synchronizes the client JAR with the resulting manifest.
     @Override
     public Object finish(SettingsMap settings) {
         settings.put("title", i18n("install.change_version.process"));
         settings.put("success_message", i18n("install.success"));
         settings.put(FailureCallback.KEY, (settings1, exception, next) -> alertFailureMessage(exception, next));
 
-        // We remove library but not save it,
-        // so if installation failed will not break down current version.
-        Task<Version> ret = Task.supplyAsync(() -> version);
         var hints = new ArrayList<Task.StagesHint>();
         for (Object value : settings.asStringMap().values()) {
-            if (value instanceof RemoteVersion remoteVersion) {
-                ret = ret.thenComposeAsync(version -> dependencyManager.installLibraryAsync(version, remoteVersion));
-                hints.add(new Task.StagesHint(String.format("hmcl.install.%s:%s", remoteVersion.getLibraryId(), remoteVersion.getSelfVersion())));
-                if ("game".equals(remoteVersion.getLibraryId())) {
-                    hints.add(new Task.StagesHint("hmcl.install.libraries"));
+            if (value instanceof ComponentRemoteVersion remoteVersion) {
+                hints.add(new Task.StagesHint("hmcl.install.libraries"));
+
+                hints.add(new Task.StagesHint(String.format("hmcl.install.%s:%s", remoteVersion.getComponentType().getPatchId(), remoteVersion.getSelfVersion())));
+                if (remoteVersion.getComponentType() == GameComponentType.GAME) {
                     hints.add(new Task.StagesHint("hmcl.install.assets"));
                 }
-            } else if (value instanceof RemoveVersionAction removeVersionAction) {
-                ret = ret.thenComposeAsync(version -> dependencyManager.removeLibraryAsync(version, removeVersionAction.libraryId));
             }
         }
 
-        return ret.thenComposeAsync(repository::saveAsync).thenComposeAsync(repository.refreshVersionsAsync()).withStagesHints(hints);
+        return dependencyManager.updateInstanceAsync(gameInstance.getId(), publishedInstance -> {
+            Task<GameInstanceManifest> update = Task.supplyAsync(publishedInstance::getManifest);
+            for (Object value : settings.asStringMap().values()) {
+                if (value instanceof ComponentRemoteVersion remoteVersion) {
+                    update = update.thenComposeAsync(manifest ->
+                            dependencyManager.installComponentRemoteAsync(publishedInstance, manifest, remoteVersion));
+                } else if (value instanceof RemoveComponentAction removeComponentAction) {
+                    update = update.thenApplyAsync(manifest ->
+                            manifest.removeComponent(removeComponentAction.componentType));
+
+                }
+            }
+            return update;
+        }).withStagesHints(hints);
     }
 
     @Override
     public Node createPage(WizardController controller, int step, SettingsMap settings) {
         switch (step) {
             case 0:
-                return new VersionsPage(controller, i18n("install.installer.choose", i18n("install.installer." + libraryId)), gameVersion, downloadProvider, libraryId, () -> {
+                return new VersionsPage(controller, i18n("install.installer.choose", i18n("install.installer." + componentType.getPatchId())), gameInstance.getVersion(), downloadProvider, componentType, () -> {
                     if (oldLibraryVersion == null) {
                         controller.onFinish();
-                    } else if ("game".equals(libraryId)) {
-                        String newGameVersion = ((RemoteVersion) settings.get(libraryId)).getSelfVersion();
-                        controller.onNext(new AdditionalInstallersPage(newGameVersion, version, controller, repository, downloadProvider));
+                    } else if (componentType == GameComponentType.GAME) {
+                        GameVersionNumber newGameVersion = ((GameRemoteVersion) settings.get(componentType.getPatchId())).getGameVersion();
+                        controller.onNext(new AdditionalInstallersPage(gameInstance, newGameVersion, controller, downloadProvider));
                     } else {
-                        Controllers.confirm(i18n("install.change_version.confirm", i18n("install.installer." + libraryId), oldLibraryVersion, ((RemoteVersion) settings.get(libraryId)).getSelfVersion()),
+                        Controllers.confirm(i18n("install.change_version.confirm", i18n("install.installer." + componentType.getPatchId()), oldLibraryVersion, ((ComponentRemoteVersion) settings.get(componentType.getPatchId())).getSelfVersion()),
                                 i18n("install.change_version"), controller::onFinish, controller::onCancel);
                     }
                 });
@@ -128,41 +135,39 @@ public final class UpdateInstallerWizardProvider implements WizardProvider {
 
     public static void alertFailureMessage(Exception exception, Runnable next) {
         if (exception instanceof LibraryDownloadException) {
-            String message = i18n("launch.failed.download_library", ((LibraryDownloadException) exception).getLibrary().getName()) + "\n";
-            if (exception.getCause() instanceof ResponseCodeException) {
-                ResponseCodeException rce = (ResponseCodeException) exception.getCause();
+            String message = i18n("launch.failed.download_library", ((LibraryDownloadException) exception).getLibrary().name()) + "\n";
+            if (exception.getCause() instanceof ResponseCodeException rce) {
                 int responseCode = rce.getResponseCode();
-                String uri = rce.getUri();
+                String url = rce.getUrl();
                 if (responseCode == 404)
-                    message += i18n("download.code.404", uri);
+                    message += i18n("download.code.404", url);
                 else
-                    message += i18n("download.failed", uri, responseCode);
+                    message += i18n("download.failed", url, responseCode);
             } else {
                 message += StringUtils.getStackTrace(exception.getCause());
             }
             Controllers.dialog(message, i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR, next);
-        } else if (exception instanceof DownloadException) {
-            URI uri = ((DownloadException) exception).getUri();
+        } else if (exception instanceof DownloadException de) {
+            String url = de.getUrl();
             if (exception.getCause() instanceof SocketTimeoutException) {
-                Controllers.dialog(i18n("install.failed.downloading.timeout", uri), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR, next);
-            } else if (exception.getCause() instanceof ResponseCodeException) {
-                ResponseCodeException responseCodeException = (ResponseCodeException) exception.getCause();
+                Controllers.dialog(i18n("install.failed.downloading.timeout", url), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR, next);
+            } else if (exception.getCause() instanceof ResponseCodeException responseCodeException) {
                 if (I18n.hasKey("download.code." + responseCodeException.getResponseCode())) {
-                    Controllers.dialog(i18n("download.code." + responseCodeException.getResponseCode(), uri), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR, next);
+                    Controllers.dialog(i18n("download.code." + responseCodeException.getResponseCode(), url), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR, next);
                 } else {
-                    Controllers.dialog(i18n("install.failed.downloading.detail", uri) + "\n" + StringUtils.getStackTrace(exception.getCause()), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR, next);
+                    Controllers.dialog(i18n("install.failed.downloading.detail", url) + "\n" + StringUtils.getStackTrace(exception.getCause()), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR, next);
                 }
             } else {
-                Controllers.dialog(i18n("install.failed.downloading.detail", uri) + "\n" + StringUtils.getStackTrace(exception.getCause()), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR, next);
+                Controllers.dialog(i18n("install.failed.downloading.detail", url) + "\n" + StringUtils.getStackTrace(exception.getCause()), i18n("install.failed.downloading"), MessageDialogPane.MessageType.ERROR, next);
             }
-        } else if (exception instanceof UnsupportedInstallationException) {
-            switch (((UnsupportedInstallationException) exception).getReason()) {
-                case UnsupportedInstallationException.FORGE_1_17_OPTIFINE_H1_PRE2:
+        } else if (exception instanceof UnsupportedInstallationException unsupportedInstallationException) {
+            switch (unsupportedInstallationException.getReason()) {
+                case UnsupportedInstallationException.CLEANROOM_NOT_COMPATIBLE_WITH_FORGE ->
+                    Controllers.dialog(i18n("install.failed.cleanroom_not_compatible_with_forge"), i18n("install.failed"), MessageDialogPane.MessageType.ERROR, next);
+                case UnsupportedInstallationException.FORGE_1_17_OPTIFINE_H1_PRE2 ->
                     Controllers.dialog(i18n("install.failed.optifine_forge_1.17"), i18n("install.failed"), MessageDialogPane.MessageType.ERROR, next);
-                    break;
-                default:
+                default ->
                     Controllers.dialog(i18n("install.failed.optifine_conflict"), i18n("install.failed"), MessageDialogPane.MessageType.ERROR, next);
-                    break;
             }
         } else if (exception instanceof DefaultDependencyManager.UnsupportedLibraryInstallerException) {
             Controllers.dialog(i18n("install.failed.install_online"), i18n("install.failed"), MessageDialogPane.MessageType.ERROR, next);
@@ -170,8 +175,7 @@ public final class UpdateInstallerWizardProvider implements WizardProvider {
             Controllers.dialog(i18n("install.failed.malformed"), i18n("install.failed"), MessageDialogPane.MessageType.ERROR, next);
         } else if (exception instanceof GameAssetIndexDownloadTask.GameAssetIndexMalformedException) {
             Controllers.dialog(i18n("assets.index.malformed"), i18n("install.failed"), MessageDialogPane.MessageType.ERROR, next);
-        } else if (exception instanceof VersionMismatchException) {
-            VersionMismatchException e = ((VersionMismatchException) exception);
+        } else if (exception instanceof VersionMismatchException e) {
             Controllers.dialog(i18n("install.failed.version_mismatch", e.getExpect(), e.getActual()), i18n("install.failed"), MessageDialogPane.MessageType.ERROR, next);
         } else if (exception instanceof CancellationException) {
             // Ignore cancel
@@ -180,11 +184,6 @@ public final class UpdateInstallerWizardProvider implements WizardProvider {
         }
     }
 
-    public static class RemoveVersionAction {
-        private final String libraryId;
-
-        public RemoveVersionAction(String libraryId) {
-            this.libraryId = libraryId;
-        }
+    public record RemoveComponentAction(GameComponentType componentType) {
     }
 }

HMCL/src/main/java/org/jackhuang/hmcl/ui/download/VersionsPage.java

@@ -31,8 +31,7 @@ import javafx.scene.input.KeyCode;
 import javafx.scene.input.KeyEvent;
 import javafx.scene.layout.*;
 import org.jackhuang.hmcl.download.DownloadProvider;
-import org.jackhuang.hmcl.download.RemoteVersion;
-import org.jackhuang.hmcl.download.VersionList;
+import org.jackhuang.hmcl.download.ComponentRemoteVersion;
 import org.jackhuang.hmcl.download.cleanroom.CleanroomRemoteVersion;
 import org.jackhuang.hmcl.download.fabric.FabricAPIRemoteVersion;
 import org.jackhuang.hmcl.download.fabric.FabricRemoteVersion;
@@ -45,7 +44,8 @@ import org.jackhuang.hmcl.download.neoforge.NeoForgeRemoteVersion;
 import org.jackhuang.hmcl.download.optifine.OptiFineRemoteVersion;
 import org.jackhuang.hmcl.download.quilt.QuiltAPIRemoteVersion;
 import org.jackhuang.hmcl.download.quilt.QuiltRemoteVersion;
-import org.jackhuang.hmcl.setting.VersionIconType;
+import org.jackhuang.hmcl.game.GameComponentType;
+import org.jackhuang.hmcl.setting.GameInstanceIconType;
 import org.jackhuang.hmcl.task.Schedulers;
 import org.jackhuang.hmcl.task.Task;
 import org.jackhuang.hmcl.ui.FXUtils;
@@ -65,6 +65,7 @@ import org.jackhuang.hmcl.util.i18n.I18n;
 import org.jackhuang.hmcl.util.platform.OperatingSystem;
 import org.jackhuang.hmcl.util.platform.Platform;
 import org.jackhuang.hmcl.util.versioning.GameVersionNumber;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.Locale;
 import java.util.regex.Pattern;
@@ -76,31 +77,29 @@ import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 
 public final class VersionsPage extends Control implements WizardPage, Refreshable {
-    private final String gameVersion;
-    private final String libraryId;
+    private final @Nullable GameVersionNumber gameVersion;
+    private final GameComponentType componentType;
     private final String title;
     private final Navigation navigation;
     private final DownloadProvider downloadProvider;
-    private final VersionList<?> versionList;
     private final Runnable callback;
 
-    private final ObservableList<RemoteVersion> versions = FXCollections.observableArrayList();
+    private final ObservableList<ComponentRemoteVersion> versions = FXCollections.observableArrayList();
     private final ObjectProperty<Status> status = new SimpleObjectProperty<>(Status.LOADING);
 
     public VersionsPage(Navigation navigation,
-                        String title, String gameVersion,
+                        String title, GameVersionNumber gameVersion,
                         DownloadProvider downloadProvider,
-                        String libraryId,
+                        GameComponentType componentType,
                         Runnable callback) {
         this.title = title;
-        this.gameVersion = gameVersion;
-        this.libraryId = libraryId;
+        this.gameVersion = componentType == GameComponentType.GAME ? null : gameVersion;
+        this.componentType = componentType;
         this.navigation = navigation;
         this.downloadProvider = downloadProvider;
-        this.versionList = downloadProvider.getVersionListById(libraryId);
         this.callback = callback;
 
-        refresh();
+        load(false);
     }
 
     @Override
@@ -110,9 +109,12 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
 
     @Override
     public void refresh() {
+        load(true);
+    }
+
+    private void load(boolean refresh) {
         status.set(Status.LOADING);
-        Task<?> task = versionList.refreshAsync(gameVersion)
-                .thenSupplyAsync(() -> versionList.getVersions(gameVersion).stream().sorted().collect(Collectors.toList()))
+        Task<?> task = downloadProvider.getVersionsAsync(componentType, gameVersion, refresh)
                 .whenComplete(Schedulers.javafx(), (items, exception) -> {
                     if (exception == null) {
                         versions.setAll(items);
@@ -152,12 +154,13 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
         OLD
     }
 
-    private static class RemoteVersionListCell extends ListCell<RemoteVersion> {
+    private static class RemoteVersionListCell extends ListCell<ComponentRemoteVersion> {
         private final VersionsPage control;
 
         private final TwoLineListItem twoLineListItem = new TwoLineListItem();
         private final ImageView imageView = new ImageView();
         private final StackPane pane = new StackPane();
+        private final RipplerContainer ripplerContainer;
 
         RemoteVersionListCell(VersionsPage control) {
             this.control = control;
@@ -172,7 +175,7 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
             HBox actions = new HBox(8);
             actions.setAlignment(Pos.CENTER);
             {
-                if ("game".equals(control.libraryId)) {
+                if (control.componentType == GameComponentType.GAME) {
                     JFXButton wikiButton = newToggleButton4(SVG.GLOBE_BOOK);
                     wikiButton.setOnAction(event -> onOpenWiki());
                     FXUtils.installFastTooltip(wikiButton, i18n("wiki.tooltip"));
@@ -188,22 +191,22 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
 
             pane.getStyleClass().add("md-list-cell");
             StackPane.setMargin(hbox, new Insets(10, 16, 10, 16));
-            pane.getChildren().setAll(new RipplerContainer(hbox));
+            pane.getChildren().setAll(ripplerContainer = new RipplerContainer(hbox));
 
             FXUtils.onClicked(this, this::onAction);
         }
 
         private void onAction() {
-            RemoteVersion item = getItem();
+            ComponentRemoteVersion item = getItem();
             if (item == null)
                 return;
 
-            control.navigation.getSettings().put(control.libraryId, item);
+            control.navigation.getSettings().put(control.componentType.getPatchId(), item);
             control.callback.run();
         }
 
         private void onOpenWiki() {
-            RemoteVersion item = getItem();
+            ComponentRemoteVersion item = getItem();
             if (!(item instanceof GameRemoteVersion))
                 return;
 
@@ -211,19 +214,22 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
         }
 
         @Override
-        public void updateItem(RemoteVersion remoteVersion, boolean empty) {
-            RemoteVersion oldRemoteVersion = getItem();
-            
+        public void updateItem(ComponentRemoteVersion remoteVersion, boolean empty) {
+            ComponentRemoteVersion oldRemoteVersion = getItem();
+            boolean oldEmpty = isEmpty();
+
             super.updateItem(remoteVersion, empty);
 
+            if (oldRemoteVersion == remoteVersion && oldEmpty == empty) return;
+
+            ripplerContainer.releaseRippleImmediately();
+
             if (empty) {
                 setGraphic(null);
                 return;
             }
             setGraphic(pane);
 
-            if (oldRemoteVersion == remoteVersion) return;
-
             twoLineListItem.setTitle(I18n.getDisplayVersion(remoteVersion));
             if (remoteVersion.getReleaseDate() != null) {
                 twoLineListItem.setSubtitle(I18n.formatDateTime(remoteVersion.getReleaseDate()));
@@ -234,57 +240,56 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
             twoLineListItem.getTags().clear();
 
             if (remoteVersion instanceof GameRemoteVersion) {
-                RemoteVersion.Type versionType = remoteVersion.getVersionType();
-                GameVersionNumber gameVersion = GameVersionNumber.asGameVersion(remoteVersion.getGameVersion());
+                ComponentRemoteVersion.Type versionType = remoteVersion.getVersionType();
+                GameVersionNumber gameVersion = remoteVersion.getGameVersion();
 
                 switch (versionType) {
                     case RELEASE -> {
-                        twoLineListItem.addTag(i18n("version.game.release"));
-                        imageView.setImage(VersionIconType.GRASS.getIcon());
+                        twoLineListItem.addTag(i18n("instance.game.release"));
+                        imageView.setImage(GameInstanceIconType.GRASS.getIcon());
                     }
                     case SNAPSHOT, PENDING, UNOBFUSCATED -> {
-                        if (versionType == RemoteVersion.Type.SNAPSHOT
-                                && GameVersionNumber.asGameVersion(remoteVersion.getGameVersion()).isAprilFools()) {
-                            twoLineListItem.addTag(i18n("version.game.april_fools"));
-                            imageView.setImage(VersionIconType.APRIL_FOOLS.getIcon());
+                        if (versionType == ComponentRemoteVersion.Type.SNAPSHOT && gameVersion.isAprilFools()) {
+                            twoLineListItem.addTag(i18n("instance.game.april_fools"));
+                            imageView.setImage(GameInstanceIconType.APRIL_FOOLS.getIcon());
                         } else {
-                            twoLineListItem.addTag(i18n("version.game.snapshot"));
-                            imageView.setImage(VersionIconType.COMMAND.getIcon());
+                            twoLineListItem.addTag(i18n("instance.game.snapshot"));
+                            imageView.setImage(GameInstanceIconType.COMMAND.getIcon());
                         }
                     }
                     default -> {
-                        twoLineListItem.addTag(i18n("version.game.old"));
-                        imageView.setImage(VersionIconType.CRAFT_TABLE.getIcon());
+                        twoLineListItem.addTag(i18n("instance.game.old"));
+                        imageView.setImage(GameInstanceIconType.CRAFT_TABLE.getIcon());
                     }
                 }
 
                 switch (NativePatcher.checkSupportedStatus(gameVersion, Platform.SYSTEM_PLATFORM, OperatingSystem.SYSTEM_VERSION)) {
-                    case UNTESTED -> twoLineListItem.addTagWarning(i18n("version.game.support_status.untested"));
-                    case UNSUPPORTED -> twoLineListItem.addTagWarning(i18n("version.game.support_status.unsupported"));
+                    case UNTESTED -> twoLineListItem.addTagWarning(i18n("instance.game.support_status.untested"));
+                    case UNSUPPORTED -> twoLineListItem.addTagWarning(i18n("instance.game.support_status.unsupported"));
                 }
             } else {
-                VersionIconType iconType;
+                GameInstanceIconType iconType;
                 if (remoteVersion instanceof LiteLoaderRemoteVersion)
-                    iconType = VersionIconType.CHICKEN;
+                    iconType = GameInstanceIconType.CHICKEN;
                 else if (remoteVersion instanceof OptiFineRemoteVersion)
-                    iconType = VersionIconType.OPTIFINE;
+                    iconType = GameInstanceIconType.OPTIFINE;
                 else if (remoteVersion instanceof ForgeRemoteVersion)
-                    iconType = VersionIconType.FORGE;
+                    iconType = GameInstanceIconType.FORGE;
                 else if (remoteVersion instanceof CleanroomRemoteVersion)
-                    iconType = VersionIconType.CLEANROOM;
+                    iconType = GameInstanceIconType.CLEANROOM;
                 else if (remoteVersion instanceof NeoForgeRemoteVersion)
-                    iconType = VersionIconType.NEO_FORGE;
+                    iconType = GameInstanceIconType.NEO_FORGE;
                 else if (remoteVersion instanceof LegacyFabricRemoteVersion || remoteVersion instanceof LegacyFabricAPIRemoteVersion)
-                    iconType = VersionIconType.LEGACY_FABRIC;
+                    iconType = GameInstanceIconType.LEGACY_FABRIC;
                 else if (remoteVersion instanceof FabricRemoteVersion || remoteVersion instanceof FabricAPIRemoteVersion)
-                    iconType = VersionIconType.FABRIC;
+                    iconType = GameInstanceIconType.FABRIC;
                 else if (remoteVersion instanceof QuiltRemoteVersion || remoteVersion instanceof QuiltAPIRemoteVersion)
-                    iconType = VersionIconType.QUILT;
+                    iconType = GameInstanceIconType.QUILT;
                 else
-                    iconType = VersionIconType.COMMAND;
+                    iconType = GameInstanceIconType.COMMAND;
 
                 imageView.setImage(iconType.getIcon());
-                String displayGameVersion = I18n.getDisplayVersion(GameVersionNumber.asGameVersion(remoteVersion.getGameVersion()));
+                String displayGameVersion = I18n.getDisplayVersion(remoteVersion.getGameVersion());
 
                 if (twoLineListItem.getSubtitle() == null)
                     twoLineListItem.setSubtitle(displayGameVersion);
@@ -295,7 +300,7 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
     }
 
     private static final class VersionsPageSkin extends SkinBase<VersionsPage> {
-        private final JFXListView<RemoteVersion> list;
+        private final JFXListView<ComponentRemoteVersion> list;
 
         private final TransitionPane transitionPane;
         private final JFXSpinner spinner;
@@ -321,7 +326,7 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
             column2.setMaxWidth(150);
             ColumnConstraints column3 = new ColumnConstraints();
 
-            if (control.versionList.hasType())
+            if (control.downloadProvider.hasType(control.componentType))
                 searchPane.getColumnConstraints().setAll(nameColumn, column1, nameColumn, column2, column3);
             else
                 searchPane.getColumnConstraints().setAll(nameColumn, column1, column3);
@@ -334,10 +339,10 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
 
                 {
                     nameField = new JFXTextField();
-                    nameField.setPromptText(i18n("version.search.prompt"));
+                    nameField.setPromptText(i18n("instance.search.prompt"));
                     nameField.textProperty().addListener(o -> updateList());
 
-                    if ("game".equals(control.libraryId)) {
+                    if (control.componentType == GameComponentType.GAME) {
                         categoryField.getItems().setAll(
                                 VersionTypeFilter.ALL,
                                 VersionTypeFilter.RELEASE,
@@ -354,21 +359,21 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
                         );
                         categoryField.getSelectionModel().select(VersionTypeFilter.ALL);
                     }
-                    categoryField.setConverter(stringConverter(type -> i18n("version.game." + type.name().toLowerCase(Locale.ROOT))));
+                    categoryField.setConverter(stringConverter(type -> i18n("instance.game." + type.name().toLowerCase(Locale.ROOT))));
                     categoryField.getSelectionModel().selectedItemProperty().addListener(o -> updateList());
 
                     JFXButton refreshButton = FXUtils.newRaisedButton(i18n("button.refresh"));
                     refreshButton.setOnAction(event -> control.onRefresh());
 
-                    if (control.versionList.hasType()) {
+                    if (control.downloadProvider.hasType(control.componentType)) {
                         searchPane.addRow(rowIndex++,
-                                new Label(i18n("version.search")), nameField,
-                                new Label(i18n("version.game.type")), categoryField,
+                                new Label(i18n("instance.search")), nameField,
+                                new Label(i18n("instance.game.type")), categoryField,
                                 refreshButton
                         );
                     } else {
                         searchPane.addRow(rowIndex++,
-                                new Label(i18n("version.search")), nameField,
+                                new Label(i18n("instance.search")), nameField,
                                 refreshButton
                         );
                     }
@@ -394,7 +399,7 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
                         RemoteVersionListCell dummyCell = new RemoteVersionListCell(control);
                         dummyCell.twoLineListItem.setTitle("Dummy");
                         dummyCell.twoLineListItem.setSubtitle("Dummy");
-                        dummyCell.imageView.setImage(VersionIconType.GRASS.getIcon());
+                        dummyCell.imageView.setImage(GameInstanceIconType.GRASS.getIcon());
                         prepareNode(dummyCell.pane);
                         list.setFixedCellSize(dummyCell.pane.prefHeight(-1));
 
@@ -453,20 +458,20 @@ public final class VersionsPage extends Control implements WizardPage, Refreshab
         }
 
         private void updateList() {
-            Stream<RemoteVersion> versions = getSkinnable().versions.stream();
+            Stream<ComponentRemoteVersion> versions = getSkinnable().versions.stream();
 
             VersionTypeFilter filter = categoryField.getSelectionModel().getSelectedItem();
             if (filter != null)
                 versions = versions.filter(it -> {
-                    RemoteVersion.Type versionType = it.getVersionType();
+                    ComponentRemoteVersion.Type versionType = it.getVersionType();
                     return switch (filter) {
-                        case RELEASE -> versionType == RemoteVersion.Type.RELEASE;
-                        case SNAPSHOTS -> versionType == RemoteVersion.Type.SNAPSHOT
-                                || versionType == RemoteVersion.Type.PENDING
-                                || versionType == RemoteVersion.Type.UNOBFUSCATED;
-                        case APRIL_FOOLS -> versionType == RemoteVersion.Type.SNAPSHOT
-                                && GameVersionNumber.asGameVersion(it.getGameVersion()).isAprilFools();
-                        case OLD -> versionType == RemoteVersion.Type.OLD;
+                        case RELEASE -> versionType == ComponentRemoteVersion.Type.RELEASE;
+                        case SNAPSHOTS -> versionType == ComponentRemoteVersion.Type.SNAPSHOT
+                                || versionType == ComponentRemoteVersion.Type.PENDING
+                                || versionType == ComponentRemoteVersion.Type.UNOBFUSCATED;
+                        case APRIL_FOOLS -> versionType == ComponentRemoteVersion.Type.SNAPSHOT
+                                && it.getGameVersion().isAprilFools();
+                        case OLD -> versionType == ComponentRemoteVersion.Type.OLD;
                         // case ALL,
                         default -> true;
                     };

HMCL/src/main/java/org/jackhuang/hmcl/ui/export/ExportWizardProvider.java

@@ -19,23 +19,21 @@ package org.jackhuang.hmcl.ui.export;
 
 import javafx.scene.Node;
 import org.jackhuang.hmcl.Metadata;
-import org.jackhuang.hmcl.game.HMCLGameRepository;
+import org.jackhuang.hmcl.game.HMCLGameInstance;
 import org.jackhuang.hmcl.modpack.ModAdviser;
 import org.jackhuang.hmcl.modpack.ModpackExportInfo;
 import org.jackhuang.hmcl.modpack.mcbbs.McbbsModpackExportTask;
 import org.jackhuang.hmcl.modpack.modrinth.ModrinthModpackExportTask;
-import org.jackhuang.hmcl.modpack.multimc.MultiMCInstanceConfiguration;
-import org.jackhuang.hmcl.modpack.multimc.MultiMCModpackExportTask;
 import org.jackhuang.hmcl.modpack.server.ServerModpackExportTask;
 import org.jackhuang.hmcl.setting.*;
 import org.jackhuang.hmcl.task.Task;
 import org.jackhuang.hmcl.ui.wizard.WizardController;
 import org.jackhuang.hmcl.ui.wizard.WizardProvider;
-import org.jackhuang.hmcl.util.Lang;
 import org.jackhuang.hmcl.util.SettingsMap;
 import org.jackhuang.hmcl.util.gson.JsonUtils;
 import org.jackhuang.hmcl.util.io.JarUtils;
 import org.jackhuang.hmcl.util.io.Zipper;
+import org.jetbrains.annotations.Nullable;
 
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -46,12 +44,10 @@ import java.util.List;
 import static org.jackhuang.hmcl.setting.SettingsManager.settings;
 
 public final class ExportWizardProvider implements WizardProvider {
-    private final HMCLGameRepository repository;
-    private final String version;
+    private final HMCLGameInstance gameInstance;
 
-    public ExportWizardProvider(HMCLGameRepository repository, String version) {
-        this.repository = repository;
-        this.version = version;
+    public ExportWizardProvider(HMCLGameInstance gameInstance) {
+        this.gameInstance = gameInstance;
     }
 
     @Override
@@ -70,11 +66,11 @@ public final class ExportWizardProvider implements WizardProvider {
     }
 
     private Task<?> exportWithLauncher(String modpackType, ModpackExportInfo exportInfo, Path modpackFile) {
-        Path launcherJar = JarUtils.thisJarPath();
+        @Nullable Path launcherJar = JarUtils.thisJarPath();
         boolean packWithLauncher = exportInfo.isPackWithLauncher() && launcherJar != null;
         return new Task<>() {
-            Path tempModpack;
-            Task<?> exportTask;
+            @Nullable Path tempModpack;
+            @Nullable Task<?> exportTask;
 
             {
                 setSignificance(TaskSignificance.MODERATE);
@@ -98,9 +94,6 @@ public final class ExportWizardProvider implements WizardProvider {
                     case ModpackTypeSelectionPage.MODPACK_TYPE_MCBBS:
                         exportTask = exportAsMcbbs(exportInfo, dest);
                         break;
-                    case ModpackTypeSelectionPage.MODPACK_TYPE_MULTIMC:
-                        exportTask = exportAsMultiMC(exportInfo, dest);
-                        break;
                     case ModpackTypeSelectionPage.MODPACK_TYPE_SERVER:
                         exportTask = exportAsServer(exportInfo, dest);
                         break;
@@ -135,9 +128,12 @@ public final class ExportWizardProvider implements WizardProvider {
                     zip.putTextFile(
                             JsonUtils.GSON.toJson(exportedServers, AuthlibInjectorServerList.class),
                             ".hmcl/config/authlib-injector-servers.json");
-                    zip.putFile(tempModpack, ModpackTypeSelectionPage.MODPACK_TYPE_MODRINTH.equals(modpackType)
+
+                    // Bundled package under .hmcl/modpack/ (not the process workdir).
+                    String packageName = ModpackTypeSelectionPage.MODPACK_TYPE_MODRINTH.equals(modpackType)
                             ? "modpack.mrpack"
-                            : "modpack.zip");
+                            : "modpack.zip";
+                    zip.putFile(tempModpack, ".hmcl/" + Metadata.BUNDLED_MODPACK_DIRECTORY_NAME + "/" + packageName);
 
                     for (String extension : FontManager.FONT_EXTENSIONS) {
                         String fileName = "font." + extension;
@@ -149,6 +145,13 @@ public final class ExportWizardProvider implements WizardProvider {
                     }
 
                     zip.putFile(launcherJar, launcherJar.getFileName().toString());
+                } finally {
+                    if (tempModpack != null) {
+                        try {
+                            Files.deleteIfExists(tempModpack);
+                        } catch (Exception ignored) {
+                        }
+                    }
                 }
             }
         };
@@ -156,7 +159,7 @@ public final class ExportWizardProvider implements WizardProvider {
 
     private Task<?> exportAsMcbbs(ModpackExportInfo exportInfo, Path modpackFile) {
         return new Task<Void>() {
-            Task<?> dependency = null;
+            @Nullable Task<?> dependency;
 
             {
                 setSignificance(TaskSignificance.MODERATE);
@@ -164,55 +167,7 @@ public final class ExportWizardProvider implements WizardProvider {
 
             @Override
             public void execute() {
-                dependency = new McbbsModpackExportTask(repository, version, exportInfo, modpackFile);
-            }
-
-            @Override
-            public Collection<Task<?>> getDependencies() {
-                return Collections.singleton(dependency);
-            }
-        };
-    }
-
-    private Task<?> exportAsMultiMC(ModpackExportInfo exportInfo, Path modpackFile) {
-        return new Task<Void>() {
-            Task<?> dependency;
-
-            {
-                setSignificance(TaskSignificance.MODERATE);
-            }
-
-            @Override
-            public void execute() {
-                GameSettings.Effective setting = repository.getEffectiveGameSettings(version);
-                dependency = new MultiMCModpackExportTask(repository, version, exportInfo.getWhitelist(),
-                        new MultiMCInstanceConfiguration(
-                                "OneSix",
-                                exportInfo.getName() + "-" + exportInfo.getVersion(),
-                                null,
-                                Lang.toIntOrNull(setting.getInheritable(GameSettings::permSizeProperty)),
-                                setting.getInheritable(GameSettings::commandWrapperProperty),
-                                setting.getInheritable(GameSettings::preLaunchCommandProperty),
-                                null,
-                                exportInfo.getDescription(),
-                                null,
-                                exportInfo.getJavaArguments(),
-                                setting.getInheritable(GameSettings::windowTypeProperty) == GameWindowType.FULLSCREEN,
-                                setting.getWidth(),
-                                setting.getHeight(),
-                                null,
-                                exportInfo.getMinMemory(),
-                                setting.getInheritable(GameSettings::showLogsProperty),
-                                /* showConsoleOnError */ true,
-                                /* autoCloseConsole */ false,
-                                /* overrideMemory */ true,
-                                /* overrideJavaLocation */ false,
-                                /* overrideJavaArgs */ true,
-                                /* overrideConsole */ true,
-                                /* overrideCommands */ true,
-                                /* overrideWindow */ true,
-                                /* iconKey */ null // TODO
-                        ), modpackFile);
+                dependency = new McbbsModpackExportTask(resolveCurrentGameInstance(), exportInfo, modpackFile);
             }
 
             @Override
@@ -224,7 +179,7 @@ public final class ExportWizardProvider implements WizardProvider {
 
     private Task<?> exportAsServer(ModpackExportInfo exportInfo, Path modpackFile) {
         return new Task<Void>() {
-            Task<?> dependency;
+            @Nullable Task<?> dependency;
 
             {
                 setSignificance(TaskSignificance.MODERATE);
@@ -232,7 +187,7 @@ public final class ExportWizardProvider implements WizardProvider {
 
             @Override
             public void execute() {
-                dependency = new ServerModpackExportTask(repository, version, exportInfo, modpackFile);
+                dependency = new ServerModpackExportTask(resolveCurrentGameInstance(), exportInfo, modpackFile);
             }
 
             @Override
@@ -244,7 +199,7 @@ public final class ExportWizardProvider implements WizardProvider {
 
     private Task<?> exportAsModrinth(ModpackExportInfo exportInfo, Path modpackFile) {
         return new Task<Void>() {
-            Task<?> dependency;
+            @Nullable Task<?> dependency;
 
             {
                 setSignificance(TaskSignificance.MODERATE);
@@ -253,8 +208,7 @@ public final class ExportWizardProvider implements WizardProvider {
             @Override
             public void execute() {
                 dependency = new ModrinthModpackExportTask(
-                        repository,
-                        version,
+                        resolveCurrentGameInstance(),
                         exportInfo,
                         modpackFile
                 );
@@ -267,12 +221,19 @@ public final class ExportWizardProvider implements WizardProvider {
         };
     }
 
+    /// Returns the current registered snapshot for the instance selected by this wizard.
+    ///
+    /// @return the current registered instance
+    private HMCLGameInstance resolveCurrentGameInstance() {
+        return gameInstance.getRepository().getInstance(gameInstance.getId());
+    }
+
     @Override
     public Node createPage(WizardController controller, int step, SettingsMap settings) {
         return switch (step) {
             case 0 -> new ModpackTypeSelectionPage(controller);
-            case 1 -> new ModpackInfoPage(controller, repository, version);
-            case 2 -> new ModpackFileSelectionPage(controller, repository, version, ModAdviser::suggestMod);
+            case 1 -> new ModpackInfoPage(controller, gameInstance);
+            case 2 -> new ModpackFileSelectionPage(controller, gameInstance, ModAdviser::suggestMod);
             default -> throw new IllegalArgumentException("step");
         };
     }

HMCL/src/main/java/org/jackhuang/hmcl/ui/export/ModpackFileSelectionPage.java

@@ -18,25 +18,31 @@
 package org.jackhuang.hmcl.ui.export;
 
 import com.jfoenix.controls.JFXButton;
-import com.jfoenix.controls.JFXCheckBox;
+import com.jfoenix.controls.JFXCheckTreeCell;
 import com.jfoenix.controls.JFXTreeView;
 import javafx.geometry.Insets;
 import javafx.geometry.Pos;
+import javafx.scene.Node;
 import javafx.scene.control.CheckBoxTreeItem;
 import javafx.scene.control.Label;
 import javafx.scene.control.TreeItem;
 import javafx.scene.layout.BorderPane;
 import javafx.scene.layout.HBox;
-import org.jackhuang.hmcl.game.HMCLGameRepository;
+import javafx.scene.layout.StackPane;
+import org.jackhuang.hmcl.game.HMCLGameInstance;
 import org.jackhuang.hmcl.modpack.ModAdviser;
+import org.jackhuang.hmcl.task.Schedulers;
 import org.jackhuang.hmcl.ui.FXUtils;
 import org.jackhuang.hmcl.ui.construct.NoneMultipleSelectionModel;
+import org.jackhuang.hmcl.ui.construct.SpinnerPane;
 import org.jackhuang.hmcl.ui.wizard.WizardController;
 import org.jackhuang.hmcl.ui.wizard.WizardPage;
 import org.jackhuang.hmcl.util.Pair;
 import org.jackhuang.hmcl.util.SettingsMap;
 import org.jackhuang.hmcl.util.StringUtils;
 import org.jackhuang.hmcl.util.io.FileUtils;
+import org.jetbrains.annotations.NotNullByDefault;
+import org.jetbrains.annotations.Nullable;
 
 import java.io.IOException;
 import java.nio.file.Files;
@@ -44,6 +50,7 @@ import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.CompletableFuture;
 
 import static org.jackhuang.hmcl.ui.FXUtils.onEscPressed;
 import static org.jackhuang.hmcl.util.Lang.mapOf;
@@ -56,37 +63,71 @@ import static org.jackhuang.hmcl.util.logging.Logger.LOG;
  */
 public final class ModpackFileSelectionPage extends BorderPane implements WizardPage {
     private final WizardController controller;
-    private final String version;
+    private final HMCLGameInstance gameInstance;
     private final ModAdviser adviser;
-    private final ModpackFileTreeItem rootNode;
+    private @Nullable ModpackFileTreeItem rootNode;
 
-    public ModpackFileSelectionPage(WizardController controller, HMCLGameRepository repository, String version, ModAdviser adviser) {
+    /// Creates a file-selection page and starts loading the instance's exportable files.
+    public ModpackFileSelectionPage(WizardController controller, HMCLGameInstance gameInstance, ModAdviser adviser) {
         this.controller = controller;
-        this.version = version;
+        this.gameInstance = gameInstance;
         this.adviser = adviser;
 
         JFXTreeView<String> treeView = new JFXTreeView<>();
-        rootNode = getTreeItem(repository.getRunDirectory(version), "minecraft", 0);
-        treeView.setRoot(rootNode);
+        treeView.setCellFactory(__ -> new ModpackFileTreeCell());
         treeView.setSelectionModel(new NoneMultipleSelectionModel<>());
         onEscPressed(treeView, () -> controller.onPrev(true));
-        setMargin(treeView, new Insets(10, 10, 5, 10));
-        this.setCenter(treeView);
+
+        Label placeholder = new Label(i18n("modpack.files.empty"));
+        StackPane placeholderPane = new StackPane(placeholder);
+        placeholderPane.getStyleClass().add("notice-pane");
+        placeholderPane.setVisible(false);
+
+        SpinnerPane spinnerPane = new SpinnerPane();
+        StackPane center = new StackPane(treeView, placeholderPane);
+        spinnerPane.setContent(center);
+
+        setMargin(spinnerPane, new Insets(10, 10, 5, 10));
+        this.setCenter(spinnerPane);
+
 
         HBox nextPane = new HBox();
         nextPane.setPadding(new Insets(16, 16, 16, 0));
         nextPane.setAlignment(Pos.CENTER_RIGHT);
-        {
-            JFXButton btnNext = FXUtils.newRaisedButton(i18n("wizard.next"));
-            btnNext.setPrefSize(100, 40);
-            btnNext.setOnAction(e -> onNext());
 
-            nextPane.getChildren().setAll(btnNext);
-        }
+        JFXButton btnNext = FXUtils.newRaisedButton(i18n("wizard.next"));
+        btnNext.setPrefSize(100, 40);
+        btnNext.setOnAction(e -> onNext());
+        nextPane.getChildren().setAll(btnNext);
+
+        loadRoot(treeView, placeholderPane, spinnerPane, btnNext);
+        spinnerPane.setOnFailedAction((__) -> loadRoot(treeView, placeholderPane, spinnerPane, btnNext));
 
         this.setBottom(nextPane);
     }
 
+    private void loadRoot(JFXTreeView<String> treeView, StackPane placeholderPane, SpinnerPane spinnerPane, JFXButton btnNext) {
+        spinnerPane.setLoading(true);
+        btnNext.setDisable(true);
+        CompletableFuture
+                .supplyAsync(() -> getTreeItem(gameInstance.getRunDirectory(), "minecraft", 0), Schedulers.io())
+                .whenCompleteAsync((root, throwable) -> {
+                    if (throwable == null) {
+                        if (root != null) {
+                            treeView.setRoot(rootNode = root);
+                        } else {
+                            placeholderPane.setVisible(true);
+                        }
+                        spinnerPane.setFailedReason(null);
+                        btnNext.setDisable(false);
+                    } else {
+                        LOG.warning("Failed to load modpack file tree", throwable);
+                        spinnerPane.setFailedReason(i18n("modpack.files.load_failed"));
+                    }
+                    spinnerPane.setLoading(false);
+                }, Schedulers.javafx());
+    }
+
     private ModpackFileTreeItem getTreeItem(Path file, String basePath, int level) {
         if (Files.notExists(file))
             return null;
@@ -94,7 +135,7 @@ public final class ModpackFileSelectionPage extends BorderPane implements Wizard
         boolean isDirectory = Files.isDirectory(file);
 
         ModAdviser.ModSuggestion state = ModAdviser.ModSuggestion.SUGGESTED;
-        if (basePath.length() > "minecraft/".length()) {
+        if (level > 0) {
             state = adviser.advise(StringUtils.substringAfter(basePath, "minecraft/") + (isDirectory ? "/" : ""), isDirectory);
 
             String fileName = FileUtils.getName(file);
@@ -107,12 +148,12 @@ public final class ModpackFileSelectionPage extends BorderPane implements Wizard
                 }
                 if (fileName.startsWith("._")) // macOS system file
                     state = ModAdviser.ModSuggestion.HIDDEN;
-                if (FileUtils.getNameWithoutExtension(file).equals(version))
+                if (FileUtils.getNameWithoutExtension(file).equals(gameInstance.getId().toString()))
                     state = ModAdviser.ModSuggestion.HIDDEN;
             }
 
             if (isDirectory) {
-                if (fileName.equals(version + "-natives")) { // Ignore <version>-natives
+                if (fileName.equals(gameInstance.getId() + "-natives")) { // Ignore <version>-natives
                     state = ModAdviser.ModSuggestion.HIDDEN;
                 }
                 if (level == 1 && fileName.startsWith("natives-")) { // Ignore natives-os-arch
@@ -123,7 +164,7 @@ public final class ModpackFileSelectionPage extends BorderPane implements Wizard
                 return null;
         }
 
-        ModpackFileTreeItem node = new ModpackFileTreeItem(level == 0 ? version : StringUtils.substringAfterLast(basePath, '/'), basePath);
+        ModpackFileTreeItem node = new ModpackFileTreeItem(level == 0 ? gameInstance.getId().toString() : StringUtils.substringAfterLast(basePath, '/'), basePath);
         if (state == ModAdviser.ModSuggestion.SUGGESTED)
             node.setSelected(true);
 
@@ -157,14 +198,16 @@ public final class ModpackFileSelectionPage extends BorderPane implements Wizard
         return node;
     }
 
-    private void getFilesNeeded(ModpackFileTreeItem node, String basePath, List<String> list) {
+    /// Appends selected paths relative to `minecraft/`, traversing partially selected directories.
+    /// A `null` node contributes no paths.
+    private void getFilesNeeded(@Nullable ModpackFileTreeItem node, String basePath, List<String> list) {
         if (node == null) return;
         if (node.isSelected() || node.isIndeterminate()) {
             if (basePath.length() > "minecraft/".length())
                 list.add(StringUtils.substringAfter(basePath, "minecraft/"));
             for (TreeItem<String> child : node.getChildren()) {
                 if (child instanceof ModpackFileTreeItem mChild) {
-                    getFilesNeeded(mChild, basePath + "/" + mChild.getFileName(), list);
+                    getFilesNeeded(mChild, basePath + "/" + mChild.getValue(), list);
                 }
             }
         }
@@ -205,39 +248,69 @@ public final class ModpackFileSelectionPage extends BorderPane implements Wizard
             pair("minecraft/scripts", i18n("modpack.files.scripts"))
     );
 
+    /// Stores a file name, optional explanation, and hierarchical selection state.
+    @NotNullByDefault
     private static final class ModpackFileTreeItem extends CheckBoxTreeItem<String> {
 
-        private final String fileName;
+        /// The localized explanation for a recognized path, or `null` if none exists.
+        private final @Nullable String comment;
 
+        /// Creates an item whose value is the file name; only the `minecraft` root starts expanded.
         public ModpackFileTreeItem(String fileName, String basePath) {
-            this.fileName = fileName;
-
-            HBox graphic = new HBox();
-            JFXCheckBox checkBox = new JFXCheckBox();
-            checkBox.selectedProperty().bindBidirectional(this.selectedProperty());
-            checkBox.indeterminateProperty().bindBidirectional(this.indeterminateProperty());
-            graphic.getChildren().add(checkBox);
-
-            {
-                Label text = new Label(fileName);
-                text.setMouseTransparent(true);
-                graphic.getChildren().add(text);
-            }
-            if (TRANSLATION.containsKey(basePath)) {
-                Label comment = new Label(TRANSLATION.get(basePath));
-                comment.setStyle("-fx-text-fill: -monet-on-surface-variant;");
-                comment.setMouseTransparent(true);
-                graphic.getChildren().add(comment);
-            }
-            graphic.setPickOnBounds(false);
+            super(fileName);
+            this.comment = TRANSLATION.get(basePath);
             this.setExpanded("minecraft".equals(basePath));
-            this.setValue(""); // To disable the default display of text
-            this.setGraphic(graphic);
+        }
+    }
+
+    /// Renders file names and localized explanations alongside the bound checkbox.
+    @NotNullByDefault
+    private static final class ModpackFileTreeCell extends JFXCheckTreeCell<String> {
+
+        /// Contains the inherited checkbox graphic followed by the file labels.
+        private final HBox content = new HBox();
+
+        /// Displays the current file name.
+        private final Label fileName = new Label();
+
+        /// Displays the current path's optional explanation.
+        private final Label comment = new Label();
+
+        /// Creates reusable labels whose mouse events pass through to the cell.
+        private ModpackFileTreeCell() {
+            fileName.setMouseTransparent(true);
+            comment.setStyle("-fx-text-fill: -monet-on-surface-variant;");
+            comment.setMouseTransparent(true);
+            content.setAlignment(Pos.CENTER_LEFT);
+            content.setPickOnBounds(false);
         }
 
-        public String getFileName() {
-            return fileName;
-        }
+        /// Refreshes the file labels and removes content when the cell is cleared.
+        @Override
+        protected void updateDisplay(@Nullable String item, boolean empty) {
+            content.getChildren().clear();
+            super.updateDisplay(item, empty);
 
+            fileName.setText(null);
+            comment.setText(null);
+            if (empty || item == null) {
+                return;
+            }
+
+            // Updating the text makes the skin reattach the current graphic to the cell.
+            // Clear it before moving the checkbox graphic into the content container.
+            setText(null);
+            @Nullable Node graphic = getGraphic();
+            if (graphic != null) {
+                content.getChildren().add(graphic);
+            }
+            fileName.setText(item);
+            content.getChildren().add(fileName);
+            if (getTreeItem() instanceof ModpackFileTreeItem treeItem && treeItem.comment != null) {
+                comment.setText(treeItem.comment);
+                content.getChildren().add(comment);
+            }
+            setGraphic(content);
+        }
     }
 }

HMCL/src/main/java/org/jackhuang/hmcl/ui/export/ModpackInfoPage.java

@@ -35,7 +35,7 @@ import javafx.stage.FileChooser;
 import org.jackhuang.hmcl.Metadata;
 import org.jackhuang.hmcl.auth.Account;
 import org.jackhuang.hmcl.auth.authlibinjector.AuthlibInjectorServer;
-import org.jackhuang.hmcl.game.HMCLGameRepository;
+import org.jackhuang.hmcl.game.HMCLGameInstance;
 import org.jackhuang.hmcl.modpack.ModpackExportInfo;
 import org.jackhuang.hmcl.modpack.mcbbs.McbbsModpackManifest;
 import org.jackhuang.hmcl.setting.Accounts;
@@ -64,9 +64,8 @@ import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 
 public final class ModpackInfoPage extends Control implements WizardPage {
     private final WizardController controller;
-    private final HMCLGameRepository gameRepository;
+    private final HMCLGameInstance gameInstance;
     private final ModpackExportInfo.Options options;
-    private final String versionName;
     private final boolean canIncludeLauncher;
 
     private final ModpackExportInfo exportInfo = new ModpackExportInfo();
@@ -87,19 +86,18 @@ public final class ModpackInfoPage extends Control implements WizardPage {
     private final SimpleBooleanProperty noCreateRemoteFiles = new SimpleBooleanProperty();
     private final SimpleBooleanProperty skipCurseForgeRemoteFiles = new SimpleBooleanProperty();
 
-    public ModpackInfoPage(WizardController controller, HMCLGameRepository gameRepository, String version) {
+    public ModpackInfoPage(WizardController controller, HMCLGameInstance gameInstance) {
         this.controller = controller;
-        this.gameRepository = gameRepository;
+        this.gameInstance = gameInstance;
         this.options = controller.getSettings().get(MODPACK_INFO_OPTION);
-        this.versionName = version;
 
         if (this.options == null)
             throw new IllegalArgumentException("Settings.MODPACK_INFO_OPTION is required");
 
-        name.set(version);
+        name.set(gameInstance.getId().toString());
         author.set(Optional.ofNullable(Accounts.getSelectedAccount()).map(Account::getProfileName).orElse(""));
 
-        GameSettings.Effective versionSetting = gameRepository.getEffectiveGameSettings(versionName);
+        GameSettings.Effective versionSetting = gameInstance.getEffectiveSettings();
         minMemory.set(Optional.ofNullable(versionSetting.getInheritable(GameSettings::minMemoryProperty)).orElse(0));
         launchArguments.set(versionSetting.getInheritable(GameSettings::gameArgumentsProperty));
         javaArguments.set(versionSetting.getInheritable(GameSettings::jvmOptionsProperty));
@@ -212,7 +210,7 @@ public final class ModpackInfoPage extends Control implements WizardPage {
                     var instanceNamePane = new LineTextPane();
                     {
                         instanceNamePane.setTitle(i18n("modpack.wizard.step.initialization.exported_version"));
-                        instanceNamePane.setText(skinnable.versionName);
+                        instanceNamePane.setText(skinnable.gameInstance.getId().toString());
 
                         list.getContent().add(instanceNamePane);
                     }

HMCL/src/main/java/org/jackhuang/hmcl/ui/export/ModpackTypeSelectionPage.java

@@ -26,7 +26,6 @@ import javafx.scene.layout.BorderPane;
 import javafx.scene.layout.VBox;
 import org.jackhuang.hmcl.modpack.ModpackExportInfo;
 import org.jackhuang.hmcl.modpack.mcbbs.McbbsModpackExportTask;
-import org.jackhuang.hmcl.modpack.multimc.MultiMCModpackExportTask;
 import org.jackhuang.hmcl.modpack.server.ServerModpackExportTask;
 import org.jackhuang.hmcl.modpack.modrinth.ModrinthModpackExportTask;
 import org.jackhuang.hmcl.ui.SVG;
@@ -55,7 +54,6 @@ public final class ModpackTypeSelectionPage extends VBox implements WizardPage {
         this.getChildren().setAll(
                 title,
                 createButton(MODPACK_TYPE_MCBBS, McbbsModpackExportTask.OPTION),
-                createButton(MODPACK_TYPE_MULTIMC, MultiMCModpackExportTask.OPTION),
                 createButton(MODPACK_TYPE_SERVER, ServerModpackExportTask.OPTION),
                 createButton(MODPACK_TYPE_MODRINTH, ModrinthModpackExportTask.OPTION)
         );
@@ -98,7 +96,6 @@ public final class ModpackTypeSelectionPage extends VBox implements WizardPage {
     public static final SettingsMap.Key<String> MODPACK_TYPE = new SettingsMap.Key<>("modpack.type");
 
     public static final String MODPACK_TYPE_MCBBS = "mcbbs";
-    public static final String MODPACK_TYPE_MULTIMC = "multimc";
     public static final String MODPACK_TYPE_SERVER = "server";
     public static final String MODPACK_TYPE_MODRINTH = "modrinth";
 }

HMCL/src/main/java/org/jackhuang/hmcl/ui/game/GameSettingsPage.java

@@ -27,6 +27,7 @@ import javafx.beans.property.Property;
 import javafx.beans.property.ReadOnlyObjectProperty;
 import javafx.beans.property.SimpleObjectProperty;
 import javafx.beans.value.ChangeListener;
+import javafx.beans.value.ObservableValue;
 import javafx.collections.FXCollections;
 import javafx.collections.ObservableList;
 import javafx.css.PseudoClass;
@@ -49,8 +50,8 @@ import org.jackhuang.hmcl.setting.property.SettingProperty;
 import org.jackhuang.hmcl.ui.*;
 import org.jackhuang.hmcl.ui.construct.*;
 import org.jackhuang.hmcl.ui.decorator.DecoratorPage;
-import org.jackhuang.hmcl.ui.versions.VersionIconDialog;
-import org.jackhuang.hmcl.ui.versions.VersionPage;
+import org.jackhuang.hmcl.ui.instances.GameInstanceIconDialog;
+import org.jackhuang.hmcl.ui.instances.GameInstancePage;
 import org.jackhuang.hmcl.util.Holder;
 import org.jackhuang.hmcl.util.Pair;
 import org.jackhuang.hmcl.util.ServerAddress;
@@ -76,7 +77,7 @@ import static org.jackhuang.hmcl.util.i18n.I18n.i18n;
 /// @author Glavo
 @NotNullByDefault
 public final class GameSettingsPage<S extends GameSettings> extends StackPane
-        implements DecoratorPage, VersionPage.GameInstanceLoadable, PageAware {
+        implements DecoratorPage, PageAware {
 
     private static final Object INHERIT_BUTTON_TOOLTIP_KEY = new Object();
     private static final PseudoClass PSEUDO_OVERRIDDEN = PseudoClass.getPseudoClass("overridden");
@@ -88,20 +89,13 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
     private final ObjectProperty<State> state = new SimpleObjectProperty<>(this, "state", new State("", null, false, false, false));
     private final WeakListenerHolder holder = new WeakListenerHolder();
 
-    /// The selected game directory.
-    private @Nullable GameDirectory gameDirectory;
-
-    /// The selected repository.
-    private @Nullable HMCLGameRepository repository;
-
-    /// The current instance ID.
-    private @Nullable String instanceId;
+    /// The current game instance when editing instance settings, or `null` for preset settings.
+    private final ObjectProperty<@Nullable HMCLGameInstance> gameInstance =
+            new SimpleObjectProperty<>(this, "gameInstance");
 
     /// The current setting.
     private final ObjectProperty<@Nullable S> currentSetting = new SimpleObjectProperty<>(this, "setting");
 
-    private final ObjectProperty<GameVersionNumber> currentGameVersionNumber = new SimpleObjectProperty<>(this, "currentGameVersionNumber", GameVersionNumber.unknown());
-
     private boolean updatingJavaSetting = false;
     private boolean updatingSelectedJava = false;
     private boolean updatingParentSetting = false;
@@ -129,12 +123,24 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
     private final InvalidationListener javaListener = o -> refreshJavaSettings();
     private final InvalidationListener weakJavaListener = holder.weak(javaListener);
 
-    public GameSettingsPage(Class<S> settingType) {
+    /// Creates a settings page.
+    ///
+    /// @param settingType     [GameSettings.Instance] or [GameSettings.Preset]
+    /// @param instanceContext parent instance property for instance settings; ignored for presets and may be `null`
+    public GameSettingsPage(
+            Class<S> settingType,
+            @Nullable ObservableValue<? extends HMCLGameInstance.Optional> instanceContext) {
         assert settingType == GameSettings.Preset.class || settingType == GameSettings.Instance.class;
 
         this.isPresetSetting = settingType == GameSettings.Preset.class;
         if (!isPresetSetting) {
             bindActiveParentSetting();
+            Objects.requireNonNull(instanceContext, "instanceContext");
+            holder.add(FXUtils.onWeakChangeAndOperate(instanceContext, current -> {
+                if (current != null) {
+                    loadInstance(current);
+                }
+            }));
         }
 
         this.scrollPane = new ScrollPane();
@@ -787,19 +793,26 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
             graphicsSettings.getContent().add(vulkanRendererPane);
             vulkanRendererPane.setTitle(i18n("settings.advanced.renderer.vulkan"));
 
-            this.currentGameVersionNumber.addListener((o, oldValue, newValue) -> {
-                boolean showBackendChoose = isPresetSetting || newValue.compareTo("26.2-snapshot-2") >= 0;
+            var highPerformancePane = createInheritableBooleanButton(GameSettings::highPerformanceProperty);
+            graphicsSettings.getContent().add(highPerformancePane);
+            highPerformancePane.setTitle(i18n("settings.advanced.renderer.gpu_preferences"));
+
+            InvalidationListener updateGraphicsVisibility = o -> {
+                GameVersionNumber version = currentGameVersion();
+                boolean showBackendChoose = isPresetSetting || version.compareTo("26.2-snapshot-2") >= 0;
                 graphicsBackendPane.setVisible(showBackendChoose);
                 graphicsBackendPane.setManaged(showBackendChoose);
 
-                boolean showOpenGL = GraphicsAPI.OPENGL.isSupported(newValue);
+                boolean showOpenGL = GraphicsAPI.OPENGL.isSupported(version);
                 openGLRendererPane.setVisible(showOpenGL);
                 openGLRendererPane.setManaged(showOpenGL);
 
-                boolean showVulkan = GraphicsAPI.VULKAN.isSupported(newValue);
+                boolean showVulkan = isPresetSetting || GraphicsAPI.VULKAN.isSupported(version);
                 vulkanRendererPane.setVisible(showVulkan);
                 vulkanRendererPane.setManaged(showVulkan);
-            });
+            };
+            this.gameInstance.addListener(updateGraphicsVisibility);
+            updateGraphicsVisibility.invalidated(this.gameInstance);
         }
 
         var nativeLibrarySettings = new ComponentList();
@@ -816,20 +829,24 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
             nativeLibrarySettings.getContent().add(nativesDirPane);
             nativesDirPane.setTitle(i18n("settings.advanced.natives_directory"));
             {
-                var txtNativesDir = new JFXTextField();
-                txtNativesDir.setPrefWidth(400);
-                nativesDirPane.setRight(txtNativesDir);
-                bindIndependentTextField(nativesDirPane, txtNativesDir, GameSettings::nativesDirectoryProperty);
+                var nativesDirSelector = new FileSelector()
+                        .setSelectionMode(FileSelector.SelectionMode.DIRECTORY);
+                nativesDirSelector.setPrefWidth(400);
+                nativesDirPane.setRight(nativesDirSelector);
+                bindInheritableStringProperty(
+                        nativesDirPane,
+                        nativesDirSelector.valueProperty(),
+                        GameSettings::nativesDirectoryProperty);
             }
 
             var noNativesPatchPane = createIndependentBooleanButton(GameSettings::notPatchNativesProperty);
             nativeLibrarySettings.getContent().add(noNativesPatchPane);
             noNativesPatchPane.setTitle(i18n("settings.advanced.dont_patch_natives"));
 
-            var useNativeGLFWPane = createIndependentBooleanButton(GameSettings::useNativeGLFWProperty);
-            nativeLibrarySettings.getContent().add(useNativeGLFWPane);
-            useNativeGLFWPane.setTitle(i18n("settings.advanced.use_native_glfw"));
-            useNativeGLFWPane.setSubtitle(i18n("settings.advanced.linux_freebsd_only"));
+            var useNativeGLFWORsdlPane = createIndependentBooleanButton(GameSettings::useNativeGLFWorSDLProperty);
+            nativeLibrarySettings.getContent().add(useNativeGLFWORsdlPane);
+            useNativeGLFWORsdlPane.setTitle(i18n("settings.advanced.use_native_glfw_or_sdl"));
+            useNativeGLFWORsdlPane.setSubtitle(i18n("settings.advanced.linux_freebsd_only"));
 
             var useNativeOpenALPane = createIndependentBooleanButton(GameSettings::useNativeOpenALProperty);
             nativeLibrarySettings.getContent().add(useNativeOpenALPane);
@@ -1721,7 +1738,7 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
             }
             refresh.invalidated(instance);
 
-            fireEvent(new VersionPage.WorkingDirChangedEvent());
+            fireEvent(new GameInstancePage.WorkingDirChangedEvent());
         });
 
         currentSetting.addListener((observable, oldValue, newValue) -> {
@@ -1811,7 +1828,7 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
             }
             refresh.invalidated(instance);
 
-            fireEvent(new VersionPage.WorkingDirChangedEvent());
+            fireEvent(new GameInstancePage.WorkingDirChangedEvent());
 
             event.consume();
         });
@@ -1833,7 +1850,7 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
                 updating.value = false;
             }
 
-            fireEvent(new VersionPage.WorkingDirChangedEvent());
+            fireEvent(new GameInstancePage.WorkingDirChangedEvent());
         });
 
         currentSetting.addListener((observable, oldValue, newValue) -> {
@@ -1855,16 +1872,20 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
     }
 
     private boolean isCurrentInstanceModpack() {
-        return repository != null && instanceId != null && repository.isModpack(instanceId);
+        HMCLGameInstance gameInstance = this.gameInstance.get();
+        return gameInstance != null && gameInstance.isModpack();
     }
 
     /// Returns the current instance version root displayed for modpack running directories.
     private String getCurrentInstanceVersionRoot() {
-        if (repository == null || instanceId == null) {
-            return "";
-        }
+        HMCLGameInstance gameInstance = this.gameInstance.get();
+        return gameInstance != null ? gameInstance.getInstanceRoot().toString() : "";
+    }
 
-        return repository.getVersionRoot(instanceId).toString();
+    /// Returns the Minecraft version of the loaded instance, or [GameVersionNumber#unknown()] for presets.
+    private GameVersionNumber currentGameVersion() {
+        HMCLGameInstance gameInstance = this.gameInstance.get();
+        return gameInstance != null ? gameInstance.getVersion() : GameVersionNumber.unknown();
     }
 
     /// Keeps a listener attached to the current instance's parent preset property.
@@ -2584,8 +2605,9 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
 
     /// Returns the runtime parent preset for an instance, including the game directory's migrated preset fallback.
     private GameSettings.Preset getEffectiveParentGameSettings(GameSettings.Instance instance) {
-        if (repository != null) {
-            return repository.getParentGameSettings(instance);
+        HMCLGameInstance gameInstance = this.gameInstance.get();
+        if (gameInstance != null) {
+            return gameInstance.getRepository().getParentGameSettings(instance);
         }
 
         return getExplicitParentGameSettings(instance);
@@ -2624,26 +2646,21 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
     }
 
     @SuppressWarnings("unchecked")
-    @Override
-    public void loadInstance(HMCLGameRepository repository, @Nullable String instanceId) {
-        this.gameDirectory = repository.getGameDirectory();
-        this.repository = repository;
-        this.instanceId = instanceId;
+    public void loadInstance(HMCLGameInstance.Optional instance) {
+        HMCLGameInstance gameInstance = instance.instance();
+        this.gameInstance.set(gameInstance);
 
-        assert isPresetSetting == (instanceId == null);
+        assert isPresetSetting == (gameInstance == null);
 
-        if (instanceId != null) {
-            this.currentGameVersionNumber.set(GameVersionNumber.asGameVersion(repository.getGameVersion(instanceId)));
-
-            @Nullable GameSettings.Instance setting = repository.getInstanceGameSettingsOrCreate(instanceId);
+        if (gameInstance != null) {
+            @Nullable GameSettings.Instance setting = gameInstance.getSettingsOrCreate();
             this.currentSetting.set((S) setting);
             setSettingsReadOnly(
-                    setting == null || repository.isInstanceGameSettingsReadOnly(instanceId),
+                    setting == null || gameInstance.isSettingsReadOnly(),
                     i18n("settings.game.instance_settings.unsupported"),
                     setting != null ? this::forceOverwriteInstanceGameSettings : null);
             loadIcon();
         } else {
-            this.currentGameVersionNumber.set(GameVersionNumber.unknown());
             this.currentSetting.set((S) SettingsManager.getDefaultGameSettingsPresetOrCreate());
             setSettingsReadOnly(
                     SettingsManager.isGameSettingsReadOnly(),
@@ -2691,12 +2708,13 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
 
     /// Backs up and overwrites the current instance's `instance-game-settings.json`.
     private void forceOverwriteInstanceGameSettings() {
-        if (repository == null || instanceId == null) {
+        HMCLGameInstance gameInstance = this.gameInstance.get();
+        if (gameInstance == null) {
             return;
         }
 
         Controllers.confirmBackupAndOverwrite(i18n("settings.game.instance_settings.unsupported"), () -> {
-            repository.forceOverwriteInstanceGameSettings(instanceId);
+            gameInstance.forceOverwriteSettings();
             setSettingsReadOnly(false, "");
         });
     }
@@ -2710,10 +2728,12 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
     }
 
     private void loadIcon() {
-        if (repository == null || instanceId == null)
+        HMCLGameInstance gameInstance = this.gameInstance.get();
+        if (gameInstance == null) {
             return;
+        }
 
-        iconPickerItem.setImage(repository.getVersionIconImage(instanceId));
+        iconPickerItem.setImage(gameInstance.getIconImage());
     }
 
     /// Refreshes Java selection controls and keeps inherited parent Java properties observed.
@@ -2777,16 +2797,19 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
     private void initJavaSubtitle() {
         S setting = currentSetting.get();
 
-        if (setting == null || gameDirectory == null)
+        if (setting == null) {
             return;
+        }
         initializeSelectedJava();
 
         JavaVersionType javaVersionType = setting.javaTypeProperty().getValue();
-        GameSettings.Effective effectiveSetting = this.instanceId != null && repository != null ? repository.getEffectiveGameSettings(this.instanceId) : null;
+        HMCLGameInstance gameInstance = this.gameInstance.get();
+        @Nullable GameSettings.Effective effectiveSetting =
+                gameInstance != null ? gameInstance.getEffectiveSettings() : null;
         JavaVersionType effectiveJavaVersionType = effectiveSetting != null ? effectiveSetting.getInheritable(GameSettings::javaTypeProperty) : javaVersionType;
         boolean autoSelected = effectiveJavaVersionType == JavaVersionType.AUTO || effectiveJavaVersionType == JavaVersionType.VERSION;
 
-        if (instanceId == null && autoSelected) {
+        if (gameInstance == null && autoSelected) {
             javaSublist.setDescription(i18n("settings.game.java_directory.auto"));
             return;
         }
@@ -2798,18 +2821,13 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
         }
 
         if (JavaManager.isInitialized()) {
-            GameVersionNumber gameVersionNumber = this.currentGameVersionNumber.get();
-            Version version;
-            if (this.instanceId == null) {
-                version = null;
-            } else {
-                version = repository != null ? repository.getResolvedVersion(this.instanceId) : null;
-            }
+            GameVersionNumber gameVersionNumber = currentGameVersion();
+            GameInstanceManifest manifest = gameInstance != null ? gameInstance.getResolvedManifest() : null;
 
             try {
                 JavaRuntime java = effectiveSetting != null
-                        ? effectiveSetting.getJava(gameVersionNumber, version)
-                        : resolveEffectiveSetting(setting).getJava(gameVersionNumber, version);
+                        ? effectiveSetting.getJava(gameVersionNumber, manifest)
+                        : resolveEffectiveSetting(setting).getJava(gameVersionNumber, manifest);
                 if (java != null) {
                     javaSublist.setDescription(java.getBinary().toString());
                 } else {
@@ -2824,20 +2842,23 @@ public final class GameSettingsPage<S extends GameSettings> extends StackPane
     }
 
     private void onExploreIcon() {
-        if (repository == null || instanceId == null)
+        HMCLGameInstance gameInstance = this.gameInstance.get();
+        if (gameInstance == null) {
             return;
-
-        Controllers.dialog(new VersionIconDialog(repository, instanceId, this::loadIcon));
+        }
+        Controllers.dialog(new GameInstanceIconDialog(gameInstance, this::loadIcon));
     }
 
     private void onDeleteIcon() {
-        if (repository == null || instanceId == null)
+        HMCLGameInstance gameInstance = this.gameInstance.get();
+        if (gameInstance == null) {
             return;
+        }
 
-        repository.deleteIconFile(instanceId);
-        GameSettings.Instance localGameSettings = repository.getInstanceGameSettingsOrCreate(instanceId);
+        gameInstance.deleteIconFile();
+        GameSettings.Instance localGameSettings = gameInstance.getSettingsOrCreate();
         if (localGameSettings != null) {
-            localGameSettings.iconProperty().setValue(VersionIconType.DEFAULT);
+            localGameSettings.iconProperty().setValue(GameInstanceIconType.DEFAULT);
         }
         loadIcon();
     }

HMCL/src/main/java/org/jackhuang/hmcl/ui/game/IndependentSettingBinder.java

@@ -38,6 +38,7 @@ import org.jackhuang.hmcl.ui.construct.LineInheritableToggleButton;
 import org.jackhuang.hmcl.ui.construct.RadioChoiceList;
 import org.jackhuang.hmcl.util.Holder;
 import org.jackhuang.hmcl.util.StringUtils;
+import org.jackhuang.hmcl.util.platform.Platform;
 import org.jackhuang.hmcl.util.platform.SystemInfo;
 import org.jackhuang.hmcl.util.platform.hardware.PhysicalMemoryStatus;
 import org.jetbrains.annotations.NotNullByDefault;
@@ -621,7 +622,7 @@ final class IndependentSettingBinder {
 
         long memoryAllocated;
         if (Boolean.TRUE.equals(autoMemory)) {
-            memoryAllocated = HMCLGameRepository.getAutoAllocatedMemory(memoryStatus.available());
+            memoryAllocated = HMCLGameRepository.getAutoAllocatedMemory(memoryStatus.available(), Platform.SYSTEM_PLATFORM);
         } else if (maxMemory != null && maxMemory > 0) {
             memoryAllocated = maxMemory * 1024L * 1024L;
         } else {

HMCL/src/main/java/org/jackhuang/hmcl/ui/image/ImageUtils.java

@@ -40,6 +40,7 @@ import org.jackhuang.hmcl.ui.image.apng.chunks.PngFrameControl;
 import org.jackhuang.hmcl.ui.image.apng.error.PngException;
 import org.jackhuang.hmcl.ui.image.apng.error.PngIntegrityException;
 import org.jackhuang.hmcl.ui.image.internal.AnimationImageImpl;
+import org.jetbrains.annotations.NotNullByDefault;
 import org.jetbrains.annotations.Nullable;
 
 import java.io.IOException;
@@ -50,13 +51,16 @@ import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
+import java.util.function.Supplier;
 import java.util.regex.Pattern;
 
 import static org.jackhuang.hmcl.util.logging.Logger.LOG;
 
-/**
- * @author Glavo
- */
+/// Provides image-format detection and loaders for image formats not handled
+/// directly by JavaFX.
+///
+/// @author Glavo
+@NotNullByDefault
 public final class ImageUtils {
 
     // ImageLoaders
@@ -81,38 +85,37 @@ public final class ImageUtils {
         LoaderParameters parameters = new LoaderParameters();
         parameters.autoStartAnimations = false;
 
-        SVGImage image;
+        Supplier<Image> supplier = () -> {
+            SVGImage image = SVGLoader.load(content, parameters);
+            var snapshotParameters = new SnapshotParameters();
+            snapshotParameters.setFill(Color.TRANSPARENT);
+
+            if (requestedWidth <= 0. || requestedHeight <= 0.) {
+                return image.toImage(snapshotParameters);
+            }
+
+            double scaleX = requestedWidth / image.getScaledWidth();
+            double scaleY = requestedHeight / image.getScaledHeight();
+
+            if (preserveRatio || scaleX == scaleY) {
+                double scale = Math.min(scaleX, scaleY);
+                return image.scale(scale).toImage(snapshotParameters);
+            } else {
+                // FIXME: Use DEFAULT_SVG_SNAPSHOT_PARAMS
+                return image.toImageScaled(ScaleQuality.RENDER_QUALITY, scaleX, scaleY);
+            }
+        };
+
+        @Nullable Image image;
 
         if (Platform.isFxApplicationThread()) {
-            image = SVGLoader.load(content, parameters);
+            image = supplier.get();
         } else {
             // TODO: Currently, SVGLoader.load(...) requires the javafx.swing module if it operates on a non-JavaFX thread.
-            image = CompletableFuture.supplyAsync(
-                    () -> SVGLoader.load(content, parameters),
-                    Schedulers.javafx()
-            ).get();
+            image = CompletableFuture.supplyAsync(supplier, Schedulers.javafx()).get();
         }
 
-        if (image == null)
-            throw new IOException("Failed to load SVG image");
-
-        var snapshotParameters = new SnapshotParameters();
-        snapshotParameters.setFill(Color.TRANSPARENT);
-
-        if (requestedWidth <= 0. || requestedHeight <= 0.) {
-            return image.toImage(snapshotParameters);
-        }
-
-        double scaleX = requestedWidth / image.getScaledWidth();
-        double scaleY = requestedHeight / image.getScaledHeight();
-
-        if (preserveRatio || scaleX == scaleY) {
-            double scale = Math.min(scaleX, scaleY);
-            return image.scale(scale).toImage(snapshotParameters);
-        } else {
-            // FIXME: Use DEFAULT_SVG_SNAPSHOT_PARAMS
-            return image.toImageScaled(ScaleQuality.RENDER_QUALITY, scaleX, scaleY);
-        }
+        return image;
     };
 
     public static final ImageLoader APNG = (input, requestedWidth, requestedHeight, preserveRatio, smooth) -> {
@@ -198,6 +201,7 @@ public final class ImageUtils {
 
     // ------
 
+    /// Maximum number of leading bytes inspected when selecting an image loader.
     public static final int HEADER_BUFFER_SIZE = 1024;
 
     private static final byte[] RIFF_HEADER = {'R', 'I', 'F', 'F'};
@@ -209,12 +213,272 @@ public final class ImageUtils {
                 && Arrays.equals(headerBuffer, 8, 12, WEBP_HEADER, 0, 4);
     }
 
-    private static final byte[] SVG_HEADER = "<svg".getBytes(StandardCharsets.US_ASCII);
+    /// ASCII local name of an SVG document element.
+    private static final String SVG_ELEMENT_NAME = "svg";
 
-    // This is currently a simple check, more complex checks can be considered in the future
+    /// ASCII prefix of an XML comment.
+    private static final String XML_COMMENT_START = "<!--";
+
+    /// ASCII suffix of an XML comment.
+    private static final String XML_COMMENT_END = "-->";
+
+    /// ASCII prefix of an XML processing instruction.
+    private static final String XML_PROCESSING_INSTRUCTION_START = "<?";
+
+    /// ASCII suffix of an XML processing instruction.
+    private static final String XML_PROCESSING_INSTRUCTION_END = "?>";
+
+    /// Case-sensitive ASCII prefix of an XML document type declaration.
+    private static final String XML_DOCTYPE_START = "<!DOCTYPE";
+
+    /// Returns whether the supplied prefix identifies an SVG XML document.
+    ///
+    /// An optional UTF-8 byte-order mark, XML whitespace, comments, processing
+    /// instructions, and a document type declaration may precede the document
+    /// element. The method identifies the document element only; it does not
+    /// validate the remainder of the XML document. XML markup must use its
+    /// ASCII byte representation; UTF-16 and UTF-32 prefixes are not recognized.
+    ///
+    /// @param headerBuffer leading bytes of the candidate image
+    /// @return whether the first XML document element is `svg`
     public static boolean isSVG(byte[] headerBuffer) {
-        return headerBuffer.length > SVG_HEADER.length
-                && Arrays.equals(headerBuffer, 0, SVG_HEADER.length, SVG_HEADER, 0, SVG_HEADER.length);
+        int offset = hasUtf8ByteOrderMark(headerBuffer) ? 3 : 0;
+
+        while (true) {
+            offset = skipXmlWhitespace(headerBuffer, offset);
+
+            if (isSvgElementStart(headerBuffer, offset))
+                return true;
+
+            if (matchesAscii(headerBuffer, offset, XML_COMMENT_START)) {
+                offset = indexAfterAscii(
+                        headerBuffer,
+                        offset + XML_COMMENT_START.length(),
+                        XML_COMMENT_END
+                );
+            } else if (matchesAscii(headerBuffer, offset, XML_PROCESSING_INSTRUCTION_START)) {
+                offset = indexAfterAscii(
+                        headerBuffer,
+                        offset + XML_PROCESSING_INSTRUCTION_START.length(),
+                        XML_PROCESSING_INSTRUCTION_END
+                );
+            } else if (isDoctypeStart(headerBuffer, offset)) {
+                offset = skipDoctype(headerBuffer, offset);
+            } else {
+                return false;
+            }
+
+            if (offset < 0)
+                return false;
+        }
+    }
+
+    /// Returns whether the byte array starts with a UTF-8 byte-order mark.
+    ///
+    /// @param data bytes to inspect
+    /// @return whether `data` begins with `EF BB BF`
+    private static boolean hasUtf8ByteOrderMark(byte[] data) {
+        return svgScanLimit(data) >= 3
+                && data[0] == (byte) 0xef
+                && data[1] == (byte) 0xbb
+                && data[2] == (byte) 0xbf;
+    }
+
+    /// Returns the bounded length available to SVG detection.
+    ///
+    /// @param data source bytes
+    /// @return the lesser of the array length and [#HEADER_BUFFER_SIZE]
+    private static int svgScanLimit(byte[] data) {
+        return Math.min(data.length, HEADER_BUFFER_SIZE);
+    }
+
+    /// Skips XML whitespace from an array offset.
+    ///
+    /// @param data  source bytes
+    /// @param start inclusive offset at which to begin
+    /// @return the first offset that does not contain XML whitespace
+    private static int skipXmlWhitespace(byte[] data, int start) {
+        int limit = svgScanLimit(data);
+        while (start < limit && isXmlWhitespace(data[start]))
+            start++;
+        return start;
+    }
+
+    /// Returns whether an SVG document-element qualified name begins at an array offset.
+    ///
+    /// @param data  source bytes
+    /// @param start offset of a possible element opening delimiter
+    /// @return whether the unprefixed or prefixed element has the local name `svg`
+    private static boolean isSvgElementStart(byte[] data, int start) {
+        int limit = svgScanLimit(data);
+        if (start < 0 || start >= limit || data[start] != '<')
+            return false;
+
+        int nameStart = start + 1;
+        int localNameStart = nameStart;
+        boolean hasPrefix = false;
+
+        for (int index = nameStart; index < limit; index++) {
+            byte value = data[index];
+            if (value == '>' || isXmlWhitespace(value)
+                    || value == '/' && index + 1 < limit && data[index + 1] == '>') {
+                return index - localNameStart == SVG_ELEMENT_NAME.length()
+                        && matchesAscii(data, localNameStart, SVG_ELEMENT_NAME);
+            }
+
+            if (value == ':') {
+                if (hasPrefix || index == nameStart)
+                    return false;
+                hasPrefix = true;
+                localNameStart = index + 1;
+                continue;
+            }
+
+            boolean nameStartCharacter = index == nameStart || index == localNameStart;
+            if (nameStartCharacter
+                    ? !isAsciiXmlNameStart(value)
+                    : !isAsciiXmlNamePart(value)) {
+                return false;
+            }
+        }
+
+        return false;
+    }
+
+    /// Returns whether a byte can begin an ASCII XML name component.
+    ///
+    /// @param value byte to inspect
+    /// @return whether the byte is an ASCII letter or underscore
+    private static boolean isAsciiXmlNameStart(byte value) {
+        return value >= 'A' && value <= 'Z'
+                || value >= 'a' && value <= 'z'
+                || value == '_';
+    }
+
+    /// Returns whether a byte can continue an ASCII XML name component.
+    ///
+    /// @param value byte to inspect
+    /// @return whether the byte is accepted after the first name character
+    private static boolean isAsciiXmlNamePart(byte value) {
+        return isAsciiXmlNameStart(value)
+                || value >= '0' && value <= '9'
+                || value == '-'
+                || value == '.';
+    }
+
+    /// Returns whether an XML document type declaration begins at an offset.
+    ///
+    /// @param data  source bytes
+    /// @param start offset of a possible declaration
+    /// @return whether the case-sensitive keyword is followed by XML whitespace
+    private static boolean isDoctypeStart(byte[] data, int start) {
+        int keywordEnd = start + XML_DOCTYPE_START.length();
+        return matchesAscii(data, start, XML_DOCTYPE_START)
+                && keywordEnd < svgScanLimit(data)
+                && isXmlWhitespace(data[keywordEnd]);
+    }
+
+    /// Skips an XML document type declaration, including its internal subset.
+    ///
+    /// Quoted values, comments, and processing instructions are ignored while
+    /// locating the declaration-closing `>`.
+    ///
+    /// @param data  source bytes
+    /// @param start offset of the `<!DOCTYPE` prefix
+    /// @return the offset after the declaration, or `-1` if it is incomplete
+    private static int skipDoctype(byte[] data, int start) {
+        int internalSubsetDepth = 0;
+        byte quote = 0;
+        int limit = svgScanLimit(data);
+
+        for (int index = start + XML_DOCTYPE_START.length(); index < limit; index++) {
+            byte value = data[index];
+
+            if (quote != 0) {
+                if (value == quote)
+                    quote = 0;
+                continue;
+            }
+
+            if (value == '\'' || value == '"') {
+                quote = value;
+                continue;
+            }
+
+            if (matchesAscii(data, index, XML_COMMENT_START)) {
+                int commentEnd = indexAfterAscii(
+                        data,
+                        index + XML_COMMENT_START.length(),
+                        XML_COMMENT_END
+                );
+                if (commentEnd < 0)
+                    return -1;
+                index = commentEnd - 1;
+                continue;
+            }
+
+            if (matchesAscii(data, index, XML_PROCESSING_INSTRUCTION_START)) {
+                int instructionEnd = indexAfterAscii(
+                        data,
+                        index + XML_PROCESSING_INSTRUCTION_START.length(),
+                        XML_PROCESSING_INSTRUCTION_END
+                );
+                if (instructionEnd < 0)
+                    return -1;
+                index = instructionEnd - 1;
+                continue;
+            }
+
+            if (value == '[') {
+                internalSubsetDepth++;
+            } else if (value == ']' && internalSubsetDepth > 0) {
+                internalSubsetDepth--;
+            } else if (value == '>' && internalSubsetDepth == 0) {
+                return index + 1;
+            }
+        }
+
+        return -1;
+    }
+
+    /// Finds an ASCII sequence in a byte array.
+    ///
+    /// @param data       source bytes
+    /// @param start      inclusive offset at which to begin searching
+    /// @param asciiValue ASCII sequence to find
+    /// @return the offset after the first match, or `-1` if no match exists
+    private static int indexAfterAscii(byte[] data, int start, String asciiValue) {
+        int lastStart = svgScanLimit(data) - asciiValue.length();
+        for (int index = start; index <= lastStart; index++) {
+            if (matchesAscii(data, index, asciiValue))
+                return index + asciiValue.length();
+        }
+        return -1;
+    }
+
+    /// Compares an ASCII string with bytes at an array offset.
+    ///
+    /// @param data       source bytes
+    /// @param start      offset at which to compare
+    /// @param asciiValue ASCII sequence to compare
+    /// @return whether the complete sequence matches
+    private static boolean matchesAscii(byte[] data, int start, String asciiValue) {
+        if (start < 0 || start > svgScanLimit(data) - asciiValue.length())
+            return false;
+
+        for (int index = 0; index < asciiValue.length(); index++) {
+            if (Byte.toUnsignedInt(data[start + index]) != asciiValue.charAt(index))
+                return false;
+        }
+        return true;
+    }
+
+    /// Returns whether a byte is XML whitespace.
+    ///
+    /// @param value byte to inspect
+    /// @return whether the byte is space, tab, carriage return, or line feed
+    private static boolean isXmlWhitespace(byte value) {
+        return value == ' ' || value == '\t' || value == '\r' || value == '\n';
     }
 
     private static final byte[] PNG_HEADER = {
@@ -249,7 +513,7 @@ public final class ImageUtils {
 
         ByteBuffer buffer = ByteBuffer.wrap(headerBuffer, 8, headerBuffer.length - 8);
 
-        PngChunkHeader header;
+        @Nullable PngChunkHeader header;
         while ((header = PngChunkHeader.readHeader(buffer)) != null) {
             // https://wiki.mozilla.org/APNG_Specification#Structure
             // To be recognized as an APNG, an `acTL` chunk must appear in the stream before any `IDAT` chunks.
@@ -436,7 +700,7 @@ public final class ImageUtils {
             }
         }
 
-        PngAnimationControl animationControl = sequence.getAnimationControl();
+        @Nullable PngAnimationControl animationControl = sequence.getAnimationControl();
         int cycleCount;
         if (animationControl != null) {
             cycleCount = animationControl.numPlays();
@@ -465,6 +729,7 @@ public final class ImageUtils {
         return argb;
     }
 
+    /// Prevents instantiation.
     private ImageUtils() {
     }
 }