# hmcl-dev/hmcl architecture

> Architecture diagram of the GitHub repository hmcl-dev/hmcl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hmcl-dev/hmcl
- Repository: https://github.com/hmcl-dev/hmcl

## Overview

HMCL is a cross-platform Minecraft launcher. A player opens the launcher UI, selects or configures a game instance, installs required game components, and launches Minecraft. The repository separates launcher UI and settings from game-instance management, downloads, authentication, and addon features. The README also documents mod management, mod-loader installation, modpack creation, and UI customization. Some major features are represented by their implementing directories because their source was not sampled; uncertain wiring is left unasserted.

Main entry points: [`HMCL/src/main/java/org/jackhuang/hmcl/ui/Controllers.java`](https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/ui/Controllers.java) (UI Controllers), [`HMCL/src/main/java/org/jackhuang/hmcl/ui/download`](https://github.com/hmcl-dev/hmcl/tree/main/HMCL/src/main/java/org/jackhuang/hmcl/ui/download) (Download UI), [`HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameInstance.java`](https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameInstance.java) (Game Instances), [`HMCL/src/main/java/org/jackhuang/hmcl/ui/game`](https://github.com/hmcl-dev/hmcl/tree/main/HMCL/src/main/java/org/jackhuang/hmcl/ui/game) (Game UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Launcher UI"]
  node_controllers["UI Controllers<br/>[Controllers.java]"]
  node_settings[("Launcher Settings")]
  node_gameui["Game UI"]
end

subgraph group_instances["Game Instances"]
  node_gameinstances["Game Instances"]
  node_gamerepository[("Instance Repository")]
  node_manifest["Instance Manifest"]
  node_launch["Game Launch"]
end

subgraph group_setup["Install and Download"]
  node_downloadui["Download UI"]
  node_dependencies["Dependency Install"]
  node_java["Java Management<br/>[JavaManager.java]"]
  node_modpacks["Modpack Install"]
  node_task["Async Task Layer<br/>[Task.java]"]
end

subgraph group_features["Accounts and Customization"]
  node_addons["Mod Management"]
  node_accounts["Account Login"]
  node_themes["Theme Packs"]
end

node_player(("Player"))

node_player -->|"uses"| node_controllers
node_controllers -->|"initializes"| node_settings
node_controllers -->|"starts search"| node_java
node_player -->|"selects instance"| node_gameui
node_gameui -.->|"configures"| node_gameinstances
node_gamerepository -->|"provides snapshots"| node_gameinstances
node_gameinstances -->|"reads metadata"| node_manifest
node_player -->|"requests install"| node_downloadui
node_downloadui -.->|"installs components"| node_dependencies
node_downloadui -.->|"installs pack"| node_modpacks
node_dependencies -.->|"runs tasks"| node_task
node_java -->|"runs tasks"| node_task
node_player -->|"launches game"| node_launch
node_player -->|"manages mods"| node_addons
node_player -.->|"authenticates"| node_accounts
node_player -->|"customizes UI"| node_themes

click node_controllers "https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/ui/Controllers.java"
click node_settings "https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/setting/SettingsManager.java"
click node_gameui "https://github.com/hmcl-dev/hmcl/tree/main/HMCL/src/main/java/org/jackhuang/hmcl/ui/game"
click node_gameinstances "https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameInstance.java"
click node_gamerepository "https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameRepository.java"
click node_manifest "https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/game/GameInstanceManifest.java"
click node_launch "https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLGameLauncher.java"
click node_downloadui "https://github.com/hmcl-dev/hmcl/tree/main/HMCL/src/main/java/org/jackhuang/hmcl/ui/download"
click node_dependencies "https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/download/DefaultDependencyManager.java"
click node_java "https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/java/JavaManager.java"
click node_modpacks "https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLModpackInstallTask.java"
click node_addons "https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/addon/LocalAddonManager.java"
click node_accounts "https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/auth/microsoft/MicrosoftService.java"
click node_themes "https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java"
click node_task "https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/task/Task.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controllers,node_settings,node_gameui toneBlue
class node_gameinstances,node_gamerepository,node_manifest,node_launch toneAmber
class node_downloadui,node_dependencies,node_java,node_modpacks,node_task toneMint
class node_addons,node_accounts,node_themes toneRose
class node_player toneIndigo
```

## Components

### Launcher UI

- [UI Controllers](https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/ui/Controllers.java): `HMCL/src/main/java/org/jackhuang/hmcl/ui/Controllers.java`
- [Launcher Settings](https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/setting/SettingsManager.java): `HMCL/src/main/java/org/jackhuang/hmcl/setting/SettingsManager.java`
- [Game UI](https://github.com/hmcl-dev/hmcl/tree/main/HMCL/src/main/java/org/jackhuang/hmcl/ui/game): `HMCL/src/main/java/org/jackhuang/hmcl/ui/game`

### Game Instances

- [Game Instances](https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameInstance.java): `HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameInstance.java`
- [Instance Repository](https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameRepository.java): `HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameRepository.java`
- [Instance Manifest](https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/game/GameInstanceManifest.java): `HMCLCore/src/main/java/org/jackhuang/hmcl/game/GameInstanceManifest.java`
- [Game Launch](https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLGameLauncher.java): `HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLGameLauncher.java`

### Install and Download

- [Download UI](https://github.com/hmcl-dev/hmcl/tree/main/HMCL/src/main/java/org/jackhuang/hmcl/ui/download): `HMCL/src/main/java/org/jackhuang/hmcl/ui/download`
- [Dependency Install](https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/download/DefaultDependencyManager.java): `HMCLCore/src/main/java/org/jackhuang/hmcl/download/DefaultDependencyManager.java`
- [Java Management](https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/java/JavaManager.java): `HMCL/src/main/java/org/jackhuang/hmcl/java/JavaManager.java`
- [Modpack Install](https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLModpackInstallTask.java): `HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLModpackInstallTask.java`
- [Async Task Layer](https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/task/Task.java): `HMCLCore/src/main/java/org/jackhuang/hmcl/task/Task.java`

### Accounts and Customization

- [Mod Management](https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/addon/LocalAddonManager.java): `HMCLCore/src/main/java/org/jackhuang/hmcl/addon/LocalAddonManager.java`
- [Account Login](https://github.com/hmcl-dev/hmcl/blob/main/HMCLCore/src/main/java/org/jackhuang/hmcl/auth/microsoft/MicrosoftService.java): `HMCLCore/src/main/java/org/jackhuang/hmcl/auth/microsoft/MicrosoftService.java`
- [Theme Packs](https://github.com/hmcl-dev/hmcl/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java): `HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackManager.java`

### Other components

- **Player**

## Connections

- Player → UI Controllers: uses
- UI Controllers → Launcher Settings: initializes (evidence: `HMCL/src/main/java/org/jackhuang/hmcl/ui/Controllers.java`)
- UI Controllers → Java Management: starts search (evidence: `HMCL/src/main/java/org/jackhuang/hmcl/ui/Controllers.java`)
- Player → Game UI: selects instance
- Game UI → Game Instances: configures
- Instance Repository → Game Instances: provides snapshots (evidence: `HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameInstance.java`)
- Game Instances → Instance Manifest: reads metadata (evidence: `HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameInstance.java`)
- Player → Download UI: requests install
- Download UI → Dependency Install: installs components
- Download UI → Modpack Install: installs pack
- Dependency Install → Async Task Layer: runs tasks (evidence: `HMCLCore/src/main/java/org/jackhuang/hmcl/download/DefaultDependencyManager.java`)
- Java Management → Async Task Layer: runs tasks (evidence: `HMCL/src/main/java/org/jackhuang/hmcl/java/JavaManager.java`)
- Player → Game Launch: launches game
- Player → Mod Management: manages mods
- Player → Account Login: authenticates
- Player → Theme Packs: customizes UI
