A modern Avalonia desktop launcher for Minecraft, built on top of CmlLib.Core. Microsoft device-code sign-in with multi-account switching, a Prism-style instance manager unified with the official launcher's installed versions, mod-loader install (Forge / Fabric / Quilt / NeoForge), Modrinth and CurseForge mod browsers, modpack import, crash-report parser, auto-backup of worlds, headless dedicated-server registry, CLI mode, 14-language UI, and a Minecraft-styled palette that matches the official Mojang launcher.
HyperionMinecraftLauncher is a drop-in alternative to the official Mojang launcher with the feature set of Prism / MultiMC for instance management and a single-window Avalonia 11 front-end. The Core library wraps CmlLib.Core behind a single IMinecraftLauncherService contract for version listing, install, authentication, launch, mod-loader install, server pinging, crash-report parsing, and backups. The App drives that contract through one view-model and renders a warm-dark, green-accented interface that matches the official Mojang launcher palette.
The launcher reads from and writes alongside the same .minecraft directory the official launcher uses, never overwriting Mojang's launcher_profiles.json or launcher_accounts.json. Its own state (instances, settings, MSAL refresh tokens, multi-account roster, cached news + skins, skin history, headless servers, backups) lives under %LOCALAPPDATA%\HyperionMinecraftLauncher\ on Windows and the appropriate XDG roots on Linux, so Hyperion and the official launcher coexist without stepping on each other.
- Microsoft sign-in with multi-account switcher. MSAL device-code flow with a readable user code in a modal; silent re-sign-in on subsequent launches; account chip in the header opens a flyout to switch, add, or sign out of accounts. Cached roster persists between sessions.
- Offline accounts in the account list. One is always there ("Steve" until you add your own nickname from the account flyout) and it is the active account until you sign in with Microsoft; picking it keeps you offline across restarts. Used for LAN games and offline-mode servers.
- Unified instance manager. User-created instances and versions already installed under
.minecraft/versions/show up in one list, with a small "auto" badge on the auto-imported ones. - Import from MultiMC / Prism. "Import from MultiMC..." on the Installations page takes either the
.zipproduced by Prism's "Export instance" or a copy of the on-disk instance folder. Hyperion parsesinstance.cfg+mmc-pack.json, maps the component UID (net.minecraft,net.minecraftforge,net.neoforged,net.fabricmc.fabric-loader,org.quiltmc.quilt-loader) to its ownModLoader, and copies the.minecraft/tree (mods, configs, saves, options, server list) into a fresh per-instance folder. JVM args, min/max RAM, and the iconKey carry over too. - Per-instance overrides. Edit dialog lets you override RAM, JVM args, game directory, and window resolution per instance. Empty values inherit from global Settings.
- Edit instance icon. Right-click any tile (or the green "..." button) and pick from a 15-tile Minecraft icon set. Auto-imported instances are protected from edits.
- Quick Play. Launch straight into a saved world or a multiplayer server via
--quickPlaySingleplayer/--quickPlayMultiplayer. Servers list grew a "Join" button; the Worlds tab grew a "Resume" button. - Auto-backup before launch. Worlds in the instance's
saves/directory are zipped togameDir/backups/{world}-{timestamp}.zipbefore every launch, with configurable retention. One-click restore per world. - Auto-detect or auto-download a matching JRE per Minecraft version. Java 8 / 17 / 21 / 25 picked automatically based on the version id (25 for the year-based 26.x versions). The launcher first reuses anything already on the host (the Settings override, then
JAVA_HOME, thenPATH, then well-known vendor directories likeC:\Program Files\Java,/usr/lib/jvm, or/Library/Java/JavaVirtualMachines), only falling back to a fresh Adoptium Temurin download when nothing matches. Downloads are cached once under%LOCALAPPDATA%/HyperionMinecraftLauncher/java/{requirement}/.
- Mod-loader installer. Forge, NeoForge (via
CmlLib.Core.Installer.*), Fabric and Quilt (via the loaders' official meta APIs) install transparently before launch. Loader-version dropdown on the New Instance dialog. - Modrinth + CurseForge mod browser. Search either source, install straight into a per-instance
mods/folder, enable / disable / remove. Disabled mods get the.jar.disabledsuffix (Prism convention) so toggling is one rename. - Modpack import. Drop a
.mrpack(Modrinth) or a CurseForge.zipand Hyperion writes the instance, downloads every file, and copies theoverrides/tree. - Crash report parser. A "Crashes" tab on each instance lists every report under
crash-reports/, parses the Forge pipe-table or Fabric hyphen-list mod block, ranks suspect mods by stacktrace frame, and offers one-click Modrinth + CurseForge search links.
- Multiplayer server lists (the Servers page and each instance's Servers tab) parsed from
servers.datwith live Server List Ping: server icon (the saved one, then the live favicon), status colour, latency, online / max players, and a Quick Play Join button. - Headless dedicated-server registry. Folder-per-server under
LOCALAPPDATA/headless_servers/{id}/with metadata, EULA, and a baselineserver.properties. Hyperion downloadsserver.jar(Mojang manifest, sha1 verified), auto-installs the matching Adoptium Temurin JRE, starts the JVM, streams stdout into a console pane on the Headless Servers page, and sends commands (say,op,stop, ...) over stdin.
- Skins. The full 3D player walking in place, with both skin layers, classic or slim arms and the cape, drawn by a built-in software renderer (no GPU or GL context); drag to orbit. Upload a new skin PNG, switch capes, browse a 10-entry skin history, re-apply a historic skin. The community catalog comes from crafty.gg: trending skins real players wear (banned ones filtered out) and a player-nickname search over each player's skin history.
- News feed from minecraft.net (falling back to
launchercontent.mojang.com/news.json, the source the official launcher uses), with a one-hour disk cache and a stale-on-failure fallback. The newest article also sits on the Home page. - Logs page. A dedicated sidebar entry shows today's
launcher-YYYY-MM-DD.logwith substring filter, copy-all, and "Open logs folder". - Per-instance browser. Screenshots, Worlds, Servers, Crashes, Resource packs, Shader packs, and Data packs tabs under each instance. PNG thumbnails open in the OS default viewer; world rows show humanised "last played"; right-click on a world opens its folder; pack tabs support enable / disable / remove and drag-drop install.
- Discord Rich Presence. "In Hyperion launcher" when idle, "Playing <version> - <instance>" when the game is running. Optional, falls back to a no-op when Discord isn't installed.
- Update banner + manual check. GitHub Releases polled hourly; a green banner appears when a newer version is published. Settings has a "Check for updates" button that reports either the update or "you're on the latest version".
- 14-language UI. Source is English; bundled translations: Russian, Ukrainian, Polish, Spanish, Brazilian Portuguese, German, French, Italian, Dutch, Turkish, Simplified Chinese, Japanese, Korean. Locale picker in Settings; falls back to OS culture by default.
- CLI mode.
--list-instances,--list-versions,--launch <id>,--help,--versionwork without opening the Avalonia window. UsesAttachConsoleon Windows so stdout reaches the parent shell. - Cross-platform. Windows installer, Linux
.AppImage, and macOS.appbundle (Intel + Apple Silicon, with optional.pkg/.dmg) all ship today. Linux paths follow the XDG Base Directory spec ($XDG_STATE_HOMEfor logs,$XDG_CONFIG_HOMEfor config, etc.); macOS uses~/Library/Application Supportand~/Library/Logs. - Minecraft palette. Warm dark background
#171615, surface tiles#262423, green CTAs with the#6CC349 -> #3C8527button shading from the official Mojang launcher. Pixel-style 1px black outlines, sharp 4dp corners, and a Minecraft-font sidebar.
- Serilog file log at
%LOCALAPPDATA%/HyperionMinecraftLauncher/logs/launcher-YYYY-MM-DD.log(Linux:$XDG_STATE_HOME/HyperionMinecraftLauncher/). Daily rotation, 14-day retention, 32 MB per-file cap, JSON compact format. - Startup timeline. One log line per launch reports the timings of every parallel refresh:
[startup] dispatcher=Xms versions=Yms ... TOTAL=Zms. - Parallel startup refreshes via
Task.WhenAll; MS-auth silent sign-in stays sequential at the end. - Single-source-of-truth versioning. Edit
/VERSIONat the repo root, build, and every consumer (the two.csprojfiles viaDirectory.Build.props, the sidebar label, the update-checker probe, the startup log line) picks up the new number automatically.
| Capability | Hyperion | Mojang official | Prism / MultiMC |
|---|---|---|---|
| Microsoft sign-in (multi-account switcher) | yes | yes (one account) | yes |
| Offline mode | yes | yes | yes |
| Instance manager + auto-import installed versions + MultiMC import | yes | no (profiles only) | yes |
| Per-instance icon / RAM / JVM / game-dir / resolution overrides | yes | no | yes |
| News feed (Mojang) | yes | yes | no |
| Multiplayer server list with live ping (servers.dat + SLP) | yes | yes (no ping) | yes |
| 3D skin + cape viewer, skin upload, cape switcher, skin history | yes | partial | varies |
| Forge / Fabric / Quilt / NeoForge installer | yes | yes | yes |
| OptiFine / Legacy-Forge installers | roadmap | no | yes |
| Modrinth + CurseForge mods browser, per-instance mod manager | yes | no | yes |
Modpack import (.mrpack Modrinth + CurseForge .zip) |
yes | no | yes |
Instance export / import as .zip for sharing |
yes | no | yes |
| Crash report parser with mod-link suggestions | yes | no | yes |
Auto-backup saves/ before launch + restore |
yes | no | partial |
| Headless dedicated-server registry (jar download + JVM + console) | yes | no | no |
| Resource pack / shader pack / datapack manager | yes | partial | yes |
| Process stdout / stderr piped into the launcher log | yes (Settings toggle) | no | yes |
CLI mode (--launch, --list-instances, ...) |
yes | no | no |
| Quick Play (jump into world or server) | yes | yes (1.20.5+) | varies |
| Auto-download Adoptium JRE per MC version | yes | yes | yes (manual) |
| Discord Rich Presence | yes | no | no |
| Update banner via GitHub Releases | yes | n/a | no |
| 14-language UI (en, ru, uk, pl, es, pt-BR, de, fr, it, nl, tr, zh-Hans, ja, ko) | yes | yes (more) | yes |
| Native AOT publish profile | opt-in (unvalidated) | n/a | no |
| Cross-platform | Windows + Linux AppImage + macOS .app today | Windows / macOS / Linux | all three |
| Open source | yes (MIT) | no | yes |
As of v0.32.0, Hyperion ships the full Prism feature set (mod loaders, per-instance settings, mod browser, crash parser, modpack import, zip share, auto-backup) on top of the official launcher's news feed and Microsoft auth path, plus Hyperion-only extras (multi-account switcher, Discord RPC, headless-server registry, CLI mode, 14-language UI) under a palette tuned to match the Mojang launcher.
dotnet build HyperionMinecraftLauncher.slnx
dotnet test HyperionMinecraftLauncher.slnx
dotnet run --project src/HyperionMinecraftLauncher.AppRequires .NET SDK 10. The Core library multi-targets net8.0;net9.0;net10.0; the App is net10.0 (Avalonia 11.2.x, WinExe).
build.cmdDouble-click build.cmd at the repo root (or invoke it from any shell). It calls scripts/build-release.ps1 -Rids win-x64 under the hood and produces:
HyperionMinecraftLauncher.exeat the repo root - a single self-extracting executable (~150 MB) with Avalonia's native libraries bundled inside viaIncludeNativeLibrariesForSelfExtract=true. Double-click to launch.outputs/HyperionMinecraftLauncher-<ver>-win-x64/- the full publish folder.outputs/HyperionMinecraftLauncher-<ver>-win-x64.zip- the archive that the GitHub Releases CI pipeline uploads on av*.*.*tag push, byte-for-byte equivalent to the CI artefact.
Pass-through arguments:
build.cmd -Rids All- full CI matrix (win-x64 + linux-x64 + osx-x64 + osx-arm64). Non-Windows RIDs are cross-compiled to raw publish folders; the Linux.AppImageand macOS.app+.dmgwrapping only runs on the matching host (where the underlyingappimagetool/sips/iconutil/hdiutiltools live).build.cmd -Clean- wipeoutputs/before publishing.
The root-level HyperionMinecraftLauncher.exe is .gitignored. On subsequent runs the build overwrites it; if the launcher is currently running the copy step fails with a clear "close it and re-run" message.
bash scripts/build-appimage.shPublishes a self-contained linux-x64 binary and packages it into HyperionMinecraftLauncher-x86_64.AppImage. appimagetool must be on $PATH.
bash scripts/build-macos-app.sh # .app bundle for Intel + Apple Silicon
bash scripts/build-macos-dmg.sh # optional: wrap each .app into a drag-to-install .dmgbuild-macos-app.sh publishes self-contained osx-x64 and osx-arm64 binaries, then assembles publish/HyperionMinecraftLauncher-x86_64.app and publish/HyperionMinecraftLauncher-arm64.app with a proper Info.plist, an AppIcon.icns generated from the repo-root icon.png via sips + iconutil, and the resx satellite assemblies mirrored into Contents/Resources/Localization/. If productbuild is on $PATH (it ships with Xcode Command Line Tools) the script also produces .pkg installers next to the bundles. The bundles are unsigned and not notarized - on first launch users must right-click the .app and pick "Open", or clear the Gatekeeper quarantine attribute manually:
xattr -d com.apple.quarantine HyperionMinecraftLauncher-x86_64.appbuild-macos-dmg.sh wraps each produced .app in a compressed .dmg with a /Applications symlink for the standard drag-to-install affordance. macOS-only (uses hdiutil).
HyperionMinecraftLauncher.exe --version
HyperionMinecraftLauncher.exe --list-instances
HyperionMinecraftLauncher.exe --list-versions --type release
HyperionMinecraftLauncher.exe --launch <instance-id> [--server host:port]dotnet run --project src/HyperionMinecraftLauncher.Appopens the launcher window.- The launcher auto-refreshes on startup in parallel: news, server list, installed versions, instances, manifest, accounts, skin history, plus a silent Microsoft sign-in if MSAL still holds a refresh token. A single
[startup] dispatcher=Xms ...log line reports per-step timings. - Click Sign in with Microsoft if you want online play. A modal shows the device code; sign in at the URL it prints; the chip flips to your username and your real skin face replaces Steve's.
- On the Home page pick an instance (the dropdown lists both your saved instances and any version already under
.minecraft/versions/). Per-instance overrides (RAM, JVM args, etc.) are reachable via right-click "Edit instance...". - Click Launch. Worlds in the instance are zipped to
gameDir/backups/first; then the loader (if any) installs; then the game starts within ~30 s on first launch and instantly thereafter.
| Path | Owner | Purpose |
|---|---|---|
%APPDATA%\.minecraft\versions\ |
Mojang launcher | Installed version manifests and JARs. Hyperion reads, never writes. |
%APPDATA%\.minecraft\launcher_profiles.json |
Mojang launcher | Profiles shown on the read-only cross-reference path. Hyperion reads, never writes. |
%APPDATA%\.minecraft\servers.dat |
Mojang launcher | Multiplayer server list (NBT). Hyperion reads, never writes. |
%LOCALAPPDATA%\HyperionMinecraftLauncher\instances\{Id}.json |
Hyperion | One JSON file per user-created instance. Atomic writes. |
%LOCALAPPDATA%\HyperionMinecraftLauncher\settings.json |
Hyperion | Persisted launcher settings (locale, RAM, JVM args, game-dir, Java exe override, Discord, auto-backup, CurseForge API key, ...). |
%LOCALAPPDATA%\HyperionMinecraftLauncher\accounts.v2.json |
Hyperion | Multi-account roster (v0.27+). Legacy accounts.json migrates on first read. |
%LOCALAPPDATA%\HyperionMinecraftLauncher\cache\ |
Hyperion | News + player-skin disk cache (1 h / 6 h TTL with stale-on-failure fallback). |
%LOCALAPPDATA%\HyperionMinecraftLauncher\skins_history\ |
Hyperion | Last 10 uploaded skin PNGs + index.json. |
%LOCALAPPDATA%\HyperionMinecraftLauncher\headless_servers\{id}\ |
Hyperion | One folder per registered headless server (metadata + eula + properties). |
%LOCALAPPDATA%\HyperionMinecraftLauncher\java\{Java8|Java17|Java21|Java25}\ |
Hyperion | Adoptium JRE installs, one per required Java major. |
%LOCALAPPDATA%\HyperionMinecraftLauncher\logs\launcher-YYYY-MM-DD.log |
Hyperion | Daily-rotated Serilog file log (JSON, 14-day retention, 32 MB cap). |
%LOCALAPPDATA%\.IdentityService\ |
Microsoft MSAL | MSAL refresh-token cache (managed by the library, used for silent sign-in). |
<instance.GameDirectory>\backups\{world}-{timestamp}.zip |
Hyperion | Auto-backup snapshots, pruned to LauncherSettings.AutoBackupKeepLatest per world. |
On Linux, paths follow XDG Base Directory: logs land under $XDG_STATE_HOME/HyperionMinecraftLauncher/ (~/.local/state/HyperionMinecraftLauncher/), config under $XDG_CONFIG_HOME/, data under $XDG_DATA_HOME/, cache under $XDG_CACHE_HOME/. On macOS, logs go to ~/Library/Logs/HyperionMinecraftLauncher/.
HyperionMinecraftLauncher/
+- VERSION <- single source of truth for the version
+- Directory.Build.props <- reads VERSION into <Version> for every project
+- src/HyperionMinecraftLauncher.Core/ <- library (multi-targets net8/9/10)
| +- Auth/, Auth/Accounts/ <- multi-account roster + MSAL contract
| +- Backups/ <- IBackupService + zip-per-world
| +- Cache/ <- FileCache (news + skin)
| +- CrashReports/ <- parser + listener with mod-link suggestions
| +- Diagnostics/ <- StartupTimeline
| +- InstanceBrowsing/ <- per-instance screenshots / worlds / servers / resource-packs / shader-packs / data-packs
| +- Installations/ <- InstalledVersion scan + LoaderDetector
| +- Installations/Loaders/ <- IModLoaderInstaller dispatch (Forge / Fabric / Quilt / NeoForge)
| +- Instances/, Instances/Export/ <- Instance record + FileInstanceStore + Hyperion-zip import / export
| +- Java/ <- Adoptium JRE auto-download
| +- Launcher/ <- IMinecraftLauncherService + CmlLib adapter
| +- Localization/ <- ILocalizationService + ResxLocalizationService
| +- Logging/ <- SerilogLauncherLogger + LogFiltering helper
| +- Mods/, Mods/Modrinth/, Mods/CurseForge/, <- mod abstractions + repositories
| | Mods/Modpacks/ <- modpack importers (.mrpack + CurseForge .zip)
| +- News/ <- Mojang news feed
| +- Platform/ <- IEnvironment + XdgPaths
| +- Presence/ <- IPresenceService (NullPresenceService default)
| +- Profiles/ <- launcher_profiles.json reader
| +- Servers/, Servers/Ping/, Servers/Headless/ <- servers.dat reader + SLP pinger + headless registry
| +- Settings/ <- LauncherSettings + store + SystemRam probe
| +- Skins/, Skins/History/ <- skin fetch + upload + cape + 10-entry history
| +- Updates/ <- GitHubReleasesUpdateChecker + SemverComparer
| +- Versions/ <- VersionMetadata
+- src/HyperionMinecraftLauncher.App/ <- Avalonia desktop front-end (WinExe, net10)
| +- Assets/Icons/MC/ <- bundled Minecraft icon set
| +- Auth/MicrosoftAuthService.cs <- MSAL device-code wrapper (multi-account)
| +- Cli/ <- CliArgumentParser + CliEntryPoint (Hyperion CLI)
| +- Controls/SkinPreview.cs <- 3D skin + cape viewer
| +- Localization/ <- Strings.resx (en source) + 13 translations
| +- Presence/DiscordPresenceService.cs <- Discord Rich Presence wrapper
| +- Themes/ <- MinecraftPalette.axaml + LiquidGlass.axaml redirector
| +- Views/ <- MainWindow + 11 dialogs
| +- ViewModels/MainViewModel.cs <- the one view-model behind everything
| +- App.axaml(.cs), Program.cs <- DI bootstrap + Avalonia entry + CLI dispatch
+- tests/HyperionMinecraftLauncher.Core.Tests/ <- 590 xUnit tests
+- scripts/ <- build-appimage.sh + build-macos-app.sh + build-macos-dmg.sh + Python helpers
+- .github/workflows/dotnet.yml <- build + test on ubuntu + windows + macos matrix
+- CHANGELOG.md
+- QUICKSTART.md
+- LICENSE.txt
+- README.md
The launcher version is stored in one file: /VERSION at the repo root. The build picks it up automatically:
+- VERSION (currently: 0.32.38)
+- Directory.Build.props (reads VERSION into <Version>)
+- src/*.csproj (inherit <Version>, no per-project override)
The sidebar label, the update-checker probe, and the startup log line all read the assembly version at runtime, so bumping is one edit:
echo "0.33.0" > VERSION
dotnet build HyperionMinecraftLauncher.slnxFormat is 3-part SemVer (X.Y.Z); commit format is vX.Y.Z <short description> capped at 72 characters.
Pushing to the product branch triggers .github/workflows/dotnet.yml (restore + build + test on Ubuntu, Windows, and macOS matrix, .NET 10). Packaging scripts (build-appimage.sh, build-macos-app.sh) do not run in dotnet.yml; the dedicated release.yml workflow described below picks them up on a version tag instead.
Cutting a new public release is a four-step ritual. The packaging job is intentionally decoupled from per-commit CI so day-to-day pushes do not burn artifact storage.
- Edit
/VERSIONto the new number (e.g.0.33.0). git commit -am "vX.Y.Z Release X.Y.Z".git tag vX.Y.Z && git push origin vX.Y.Zto trigger the release workflow.- The workflow (
.github/workflows/release.yml) builds Windows, Linux, and macOS artifacts in parallel and publishes a GitHub Release with the tag's body. The matrix runs:ubuntu-latest-> Linux AppImage viascripts/build-appimage.shwindows-latest-> self-containedwin-x64single-file publish, zippedmacos-latest-> Intel + Apple Silicon.appbundles viascripts/build-macos-app.sh, with optional.dmgwrappers fromscripts/build-macos-dmg.sh
The release body is only the tag's own ## [X.Y.Z] section of CHANGELOG.md (cut out by an awk step), followed by GitHub's generated "What's Changed". A version that is never tagged on its own therefore has to be folded into the section of the version that does get tagged, or its changes are missing from the release notes. Branch pushes never trigger this workflow; only tags matching v*.*.* do.
See CHANGELOG.md for the full release history.
Items still open after the v0.32.x parity push. Anything not listed here is shipped on product; see CHANGELOG.md for the full history.
- OptiFine and Legacy-Forge (1.7.10 era) installers.
CmlLibModLoaderInstallerthrowsNotSupportedExceptionfor these two cases today; the other four loaders (Forge / NeoForge / Fabric / Quilt) install transparently before launch.
- Free-text skin search. crafty.gg's public API offers trending skins and per-player skin history but no text or tag search, so the catalog searches by player nickname only.
- Validated Native AOT publish. The
ReleaseAotconfiguration is wired but Avalonia 11.2 + MSAL + CmlLib have not been validated for full AOT yet. Run the trim-warnings audit, suppress / re-architect where needed, ship a workingdotnet publish -c ReleaseAotstory. - Reduce startup dispatcher delta. The
[startup] dispatcher=Xmschunk is the biggest single contributor (~3 s in cold runs). Profile, hoist eager work out of the constructor path, defer where possible.
- Plural-form helpers. Some plural-fragile strings ("{0} resultado(s)") would benefit from ICU-style plural blocks. Not blocking, but improves polish on count-heavy lines.
- More languages. Open to PRs beyond the current 14. Each new locale is one
Strings.{culture}.resxand one entry inApp.axaml.cs'sAvailableCultureslist.
- Code-signing + notarization for macOS bundles.
build-macos-app.shproduces unsigned.app/.pkg; users must right-click -> Open or clearcom.apple.quarantineon first launch. Apple Developer credentials would let CI runcodesign+xcrun notarytool submitand emit a Gatekeeper-friendly artifact. - Material.Avalonia replacement audit. A handful of controls still pull Material.Avalonia for the
Depth0shadow override; verify these still look right against the Minecraft palette or replace with native Avalonia styles.
- QUICKSTART.md: five-minute new-developer walkthrough.
- CHANGELOG.md: release notes for every version.
- ARCHITECT_REVIEW.md: the internal architectural review.
- src/HyperionMinecraftLauncher.App/Localization/README.md: contributor doc for adding new locales.
Licensed under the MIT License. Copyright © Tech Tea Studio.
Built as part of the Hyperion Ecosystem by TechTeaStudio.