hearthstone-linux-gui
中文说明
·
Latest release
hearthstone-linux-gui is a native GTK4 desktop manager for installing,
updating, logging into, and launching Hearthstone on Linux. It is migrated from
the original hearthstone-linux
project, but the old script-driven workflow has been replaced by a packaged
Rust application with a graphical interface.
No terminal workflow is required for normal users. Download a release, install
or open it with your desktop environment, click Install / Update, click
Login, then click Play.
What Changed From The Original Project
The original hearthstone-linux proved that Hearthstone can run on Linux by
combining Blizzard's official game files with Unity's Linux runtime. This
project keeps that idea, but turns it into a desktop application that is easier
to distribute and maintain.
Original hearthstone-linux |
This project |
| Script-oriented setup |
GTK4/libadwaita desktop application |
| Manual command-line flow |
Button-driven install, login, update, and launch |
| Python/Bash toolchain expected by users |
Packaged runtime; no Python or Bash environment needed for normal use |
External keg downloader workflow |
Native Rust NGDP downloader with cache and verification |
| Distro-specific setup pain |
AppImage, DEB, RPM, and native Nix package outputs |
Highlights
- One-click desktop experience: install, update, login, and launch from a
GTK4 window.
- No command-line requirement: release builds are meant for graphical
installation and daily use.
- No Python/Bash runtime requirement: the launcher is a native Rust binary
packaged with the libraries it needs.
- Cross-distribution Linux packaging: use the same project on NixOS,
Debian, Ubuntu, Fedora, and other x86_64 Linux distributions.
- Portable AppImage: a self-contained build for broad Linux compatibility.
- Native Nix package: Nix users can consume a standard package output with
desktop integration.
- DEB/RPM installers: package-manager friendly builds for common desktop
distributions.
- Resumable downloads: Unity runtime downloads can continue from a partial
file after interruption.
- Cached game data: downloaded NGDP content is cached and verified to avoid
unnecessary network work.
- No Steam dependency: the AppImage carries the portable GTK/runtime layer;
the game itself is launched with the project's own runtime handling, not
steam-run.
Packages
| Package |
Best for |
User experience |
| AppImage |
Any x86_64 Linux desktop, including NixOS |
Download and open the application directly |
| DEB |
Debian, Ubuntu, Linux Mint, Pop!_OS, and related systems |
Open with the graphical software installer |
| RPM |
Fedora, RHEL-compatible, openSUSE-style workflows |
Open with the graphical software installer |
| Nix |
NixOS and Nix package users |
Native package output with desktop file and launcher |
Release builds are produced from the unified Nix build pipeline so every format
comes from the same source, version, and dependency graph.
Installation For Users
- Open the
latest release page.
- Download the package that matches your system.
- Open it with your desktop environment:
- AppImage: open the downloaded AppImage. If your file manager asks for it,
enable "Allow executing file as program" in file properties.
- DEB/RPM: double-click the package and install it with your graphical
software center.
- Nix/NixOS: install the native Nix package through your normal Nix workflow.
- Launch hearthstone-linux-gui from the application menu.
After the app opens, the normal flow is:
- Choose your Region and Locale.
- Click Install / Update.
- Click Login and complete Battle.net login in your browser.
- Return to the app and click Play.
The app stores user data under standard XDG locations in your home directory.
Interrupted Unity downloads are resumed automatically, and already downloaded
game data is reused when possible.
Nix, NixOS, And Home Manager
This repository is a flake for x86_64-linux. It currently exposes package,
app, and development shell outputs; it does not expose dedicated NixOS or Home
Manager modules. Use the package output in your system or home package list.
Run the application directly from GitHub:
nix run github:DawnMagnet/hearthstone-linux-gui
Build outputs from a local checkout:
nix build .#default
nix build .#AppImage
nix build .#runtime
The available flake outputs are:
| Output |
Purpose |
packages.x86_64-linux.default |
Native Nix package for the GTK launcher |
packages.x86_64-linux.runtime |
FHS runtime wrapper used to launch the downloaded Unity player |
packages.x86_64-linux.AppImage |
Portable AppImage build |
packages.x86_64-linux.AppDir |
Intermediate AppDir used to build the AppImage |
apps.x86_64-linux.default |
nix run entrypoint |
devShells.x86_64-linux.default |
Rust/GTK development shell |
For NixOS flakes, add the repository as an input and install the package with
environment.systemPackages:
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
hearthstone-linux-gui.url = "github:DawnMagnet/hearthstone-linux-gui";
};
outputs = { nixpkgs, hearthstone-linux-gui, ... }: {
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
({ pkgs, ... }: {
environment.systemPackages = [
hearthstone-linux-gui.packages.${pkgs.stdenv.hostPlatform.system}.default
];
})
];
};
};
}
For standalone Home Manager flakes, add it to home.packages:
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
home-manager.url = "github:nix-community/home-manager";
hearthstone-linux-gui.url = "github:DawnMagnet/hearthstone-linux-gui";
};
outputs = { nixpkgs, home-manager, hearthstone-linux-gui, ... }:
let
system = "x86_64-linux";
pkgs = nixpkgs.legacyPackages.${system};
in
{
homeConfigurations.my-user = home-manager.lib.homeManagerConfiguration {
inherit pkgs;
modules = [
{
home.username = "my-user";
home.homeDirectory = "/home/my-user";
home.stateVersion = "25.05";
home.packages = [
hearthstone-linux-gui.packages.${system}.default
];
}
];
};
};
}
If you use Home Manager as a NixOS module, put the same package expression in
home-manager.users.<name>.home.packages.
How It Works
Hearthstone ships official data through Blizzard's NGDP distribution system.
The game is built with Unity, and the Linux Unity player can run the game data
after the platform layout is adapted.
This launcher automates that process:
- Downloads the official Hearthstone game data for the selected region and
locale.
- Verifies and caches downloaded content.
- Transforms the macOS-style payload into a Linux-ready layout.
- Detects the required Unity version and installs the matching Linux Unity
player.
- Installs compatibility files and configuration needed by the game.
- Registers the login callback handler and stores the encrypted token locally.
- Launches the game through a controlled Linux runtime environment.
No proprietary Hearthstone files are stored in this repository or shipped in
the launcher packages. The application retrieves official files from their
upstream distribution endpoints during installation.
Status And Limitations
- Target architecture: x86_64 Linux.
- The game client runs, but this project is unofficial.
- The in-game shop may remain unavailable depending on upstream behavior.
- Use at your own risk. This project is not affiliated with Blizzard
Entertainment.
Troubleshooting
| Symptom |
What to try |
| The app says Login Required |
Click Login again and finish the browser flow (see Browser login). |
--write-token says the token format is invalid |
Keep the region prefix and both dashes (XX-<32 characters>-<account id>); the account id length varies between accounts. |
| The game closes the Battle.net connection with TLS errors |
See Certificate failures on rolling distros. |
| The game window is solid white / flickers at launch |
See White screen on some AMD GPUs. |
| Install was interrupted |
Click Install / Update again; resumable and cached downloads will be reused. |
| The game does not launch after an update |
Click Install / Update once to repair Unity/runtime files. |
The game exits immediately with Unable to load mono library (NixOS flake) |
Update the flake; the FHS environment now ships zlib, which the bundled Mono runtime requires. |
| A package opens but does not start on an unusual distro |
Try the AppImage release, which carries the widest runtime set. |
Browser login
Clicking Login registers the launcher as the system handler for the
blizzard-hearthstone:// URL scheme and opens the Battle.net sign-in page.
After you sign in, the browser redirects to that scheme and the launcher
writes the login token automatically — no copy-paste needed. The token is
stored encrypted at <game dir>/token.
If the browser instead shows http://localhost:0/... failing with
ERR_UNSAFE_PORT (Chrome) or NS_ERROR_PORT_ACCESS_NOT_ALLOWED
(Firefox), the handler was not registered or your release predates the
callback fix. You can finish the login manually:
- Copy the value of the
ST= parameter from the blocked URL (everything
after ST= up to the next &).
- Run:
hearthstone-linux-gui --write-token 'US-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-1234567'
With the AppImage: ./hearthstone-linux-gui_*.AppImage --write-token '...'.
Passing the whole failed URL to --auth-callback also works.
A valid token is a two-character region prefix, a dash, 32 alphanumeric
characters, a dash, and your numeric account id. If the command still rejects
the value, check that the region prefix was not stripped while copying.
Certificate failures on rolling distros
If the game starts but cannot sign in to Battle.net, and
~/.config/unity3d/Blizzard Entertainment/Hearthstone/Player.log or
<game dir>/Logs/**/BattleNet.log contains
Curl error 35 ... UnityTls error code: 7 or
Ssl error ... CERTIFICATE_VERIFY_FAILED / ERROR_SDK_SOCKET_CLOSED (1901),
the game cannot find the system certificate store. The Unity player hard-codes
Debian/RHEL CA bundle paths that do not exist on openSUSE and some other
rolling distros. Related upstream discussion:
0xf4b1/hearthstone-linux#108.
On openSUSE Tumbleweed:
# 1) Provide the CA bundle paths the Unity player expects (once, needs root)
sudo ln -sf /var/lib/ca-certificates/ca-bundle.pem /etc/ssl/certs/ca-bundle.crt
sudo ln -sf /var/lib/ca-certificates/ca-bundle.pem /etc/ssl/certs/ca-certificates.crt
# 2) Import the system roots into Mono's user trust store
# (cert-sync comes with the distro mono-core package)
cert-sync --user /etc/ssl/certs/ca-bundle.crt
If BattleNet.log still reports a missing libmono-btls-shared.so, copy that
library from your distro's mono-core package into
<game dir>/Bin/Hearthstone_Data/MonoBleedingEdge/x86_64/ and launch with
MONO_TLS_PROVIDER=btls.
White screen on some AMD GPUs
On some AMD integrated GPUs (for example Rembrandt / Radeon 680M), the game
window renders solid white and flickers, while Player.log shows
ERROR: Shader Hidden/Universal Render Pipeline/DBufferClear shader is not supported on this GPU. The Linux-repackaged game data is missing the shader
variants these feature levels need; this cannot be fixed from the launcher at
runtime and is tracked in #13.
Forcing a different renderer (-force-glcore, -force-vulkan) does not help,
but enabling Use discrete GPU in the launcher may.
Release builds default to INFO-level logging. Detailed diagnostic logs can be
enabled by developers with the standard RUST_LOG environment variable when
debugging locally.
Legal Notice
Hearthstone, Battle.net, Blizzard Entertainment, and related names, trademarks,
game assets, services, and other materials are owned by Blizzard Entertainment,
Inc. or its affiliates and licensors.
This project is an unofficial compatibility launcher. It is not produced,
published, sponsored, approved, endorsed, maintained, or supported by Blizzard
Entertainment, Battle.net, Microsoft, Activision Blizzard, or any of their
affiliates. No proprietary Hearthstone game assets are stored in this
repository or shipped in the launcher packages.
See LEGAL.md for the full legal information, project boundaries,
user responsibilities, and rights-holder request process.
它是一个原生 GTK4 桌面管理器，用 Rust 编写，用于在 Linux 上安装、更新、登录并启动《炉石传说》。