## File: README.md # Heroic Games Launcher [](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/latest) [](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/) [](https://flathub.org/apps/details/com.heroicgameslauncher.hgl) [](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/blob/main/COPYING) [](https://discord.gg/rHJ2uqdquK) [](https://patreon.com/heroicgameslauncher) [](https://www.paypal.me/heroiclauncher) [](https://ko-fi.com/heroicgames) Heroic is an Open Source Game Launcher for Linux, Windows and macOS. Right now it supports launching games from the Epic Games Store using [Legendary](https://github.com/derrod/legendary), GOG Games using our custom implementation with [gogdl](https://github.com/Heroic-Games-Launcher/heroic-gogdl) and Amazon Games using [Nile](https://github.com/imLinguin/nile). Heroic is built with Web Technologies: [](https://www.typescriptlang.org/) [](https://reactjs.org/) [](https://mui.com/) [](https://nodejs.org/) [](https://www.electronjs.org/) [](https://www.electron.build/) [](https://jestjs.io/) [](https://vitejs.dev/) ## Index - [Heroic Games Launcher](#heroic-games-launcher) - [Index](#index) - [Features available right now](#features-available-right-now) - [Planned features](#planned-features) - [Supported Operating Systems](#supported-operating-systems) - [Language Support](#language-support) - [Help with Translations Here](#help-with-translations-here) - [Installation](#installation) - [Linux](#linux) - [Flatpak](#flatpak) - [Debian, Ubuntu and Derivatives](#debian-ubuntu-and-derivatives) - [Arch (AUR)](#arch-aur) - [Fedora](#fedora) - [Nix(OS)](#nixos) - [Other Distributions (AppImage and TAR.XZ)](#other-distributions-appimage-and-tarxz) - [Windows](#windows) - [macOS](#macos) - [Development environment](#development-environment) - [Building Heroic Binaries](#building-heroic-binaries) - [Building with VS Code](#building-with-vs-code) - [Quickly testing/debugging Heroic on your own system](#quickly-testingdebugging-heroic-on-your-own-system) - [Testing with Docker](#testing-with-docker) - [Development on nix](#development-on-nix) - [Sponsors](#sponsors) - [Screenshots](#screenshots) - [Credits](#credits) ## Features available right now - Login with an existing Epic Games, GOG or Amazon account - Install, uninstall, update, repair and move Games - Import an already installed game - Play Epic games online [AntiCheat on macOS and on Linux depends on the game] - Play games using Wine or Proton [Linux] - Play games using Crossover [macOS] - Download custom Wine and Proton versions [Linux] - Access to Epic, GOG and Amazon Games stores directly from Heroic - Search for the game on ProtonDB for compatibility information [Linux] - Show ProtonDB and Steam Deck compatibility information [Linux] - Sync installed games with an existing Epic Games Store installation - Sync saves with the cloud - Custom Theming Support - Download queue - Add Games and Applications outside GOG, Epic Games and Amazon Games - Define your categories to organize your collection ## Planned features - Support Other Store (IndieGala, etc) ## Supported Operating Systems - Linux: - Ubuntu (latest 2 LTS versions) - Fedora (latest 2 versions) - Arch Linux & derivatives (Manjaro, Garuda, EndeavourOS) - Heroic will still _work_ on most distros, but it is up to you to _get_ it to work Chances are though that someone on our [Discord](https://discord.gg/rHJ2uqdquK) can help you - SteamOS (downloading using Discover only) - Windows 10 & 11 - macOS 14 or newer ## Language Support Expand Thanks to the community, Heroic was translated to almost 40 different languages so far: - English - Azerbaijani - Basque - Belarussian - Bosnian - Bulgarian - Catalan - Czech - Croatian - Simplified Chinese - Traditional Chinese - Dutch - Estonian - Finnish - French - German - Greek - Hebraic - Japanese - Korean - Hungarian - Italian - Indonesian - Malayalam - Norwegian Bokmål - Persian - Polish - Portuguese - Portuguese (Brazil) - Romanian - Russian - Serbian - Spanish - Slovak - Swedish - Tamil - Turkish - Ukrainian - Vietnamese ### Help with Translations [Here](https://hosted.weblate.org/projects/heroic-games-launcher) ## Installation ### Linux #### Flatpak [](https://flathub.org/apps/details/com.heroicgameslauncher.hgl) Heroic is available on Flathub, so you should be able to easily install it on most distros with Software Centers (Pop!\_Shop, Discover, etc.) #### Distribution-specific instructions If you're not using the Flatpak version, keep GE-Proton as your Wine runner. With umu enabled by default, no additional Wine dependencies are required. #### Debian, Ubuntu and Derivatives Download the file ending in .deb from the [latest release](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/latest). Double-click it to open it up in your Software Manager, or run `sudo dpkg -i Heroic*amd64.deb` to install it directly. #### Arch (AUR) We currently only support one AUR package: `heroic-games-launcher-bin`. Although you might find other packages there, do not ask support for them on this GitHub or on our Discord, ask their maintainers directly. - [](https://aur.archlinux.org/packages/heroic-games-launcher-bin) (stable release, recommended) Please see [the Arch Wiki](https://wiki.archlinux.org/title/Arch_User_Repository#Installing_and_upgrading_packages) on how to install them #### Fedora You can download the file ending in .rpm from the [latest release](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/latest) and install it with `sudo dnf install ./heroic-*.x86_64.rpm`. Alternatively, you can use the Flatpak package. #### Nix(OS) Two community-maintained versions are available in [nixpkgs](https://search.nixos.org/packages?type=packages&query=heroic), named [heroic](https://github.com/NixOS/nixpkgs/blob/nixos-25.05/pkgs/by-name/he/heroic-unwrapped/package.nix#L110) (with an [FHS environment](https://nixos.org/manual/nixpkgs/stable/#sec-fhs-environments)) and [heroic-unwrapped](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/he/heroic-unwrapped/package.nix) (without FHS). - Nix shell: `nix-shell -p heroic` - NixOS: ```nixos # /etc/nixos/configuration.nix { config, pkgs, ... }: { users.users.example = { isNormalUser = true; description = "Example user"; packages = with pkgs; [ heroic ]; }; } ``` #### Other Distributions (AppImage and TAR.XZ) Since these two distribution formats don't have a form of dependency management, make sure the `curl` command is available. You might run into weird issues if it's not. ##### AppImage - Download the file ending in .AppImage from the [latest release](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/latest) - Make it executable (`chmod +x Heroic*.AppImage`) - Run it (double-click in most file managers, or run `./Heroic*.AppImage`) ##### .tar.xz - Download the file ending in .tar.xz from the [latest release](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/latest) - Extract it anywhere - Run the `heroic` file in the folder you extracted it to (double-click in most file managers, or run `./heroic`) ### Windows #### WinGet If you use WinGet (installed by default on Windows 11 and modern versions of 10), you can run `winget install Heroic` in a terminal to install Heroic. #### Manual installl Download the Heroic Installer (`Heroic-x.x.x-Setup.exe`) or the portable version (`Heroic-x.x.x-Portable.exe`) from the [latest release](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/latest). Run the executable you downloaded to install/run Heroic. The Setup will create shortcuts to Heroic on your Desktop and in your Start Menu. ### macOS If you use Homebrew, you can run `brew install --cask --no-quarantine heroic` to install Heroic. Otherwise, download the file ending in .dmg from the [latest release](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/latest), double-click it to mount it, and drag the "Heroic" application into the "Applications" folder. ## Development environment This part will walk you through setting up a development environment so you can build Heroic binaries yourself or make changes to the code. 1. Make sure Git, NodeJS, and pnpm 10 are installed **NOTE**: On Windows, due to an issue with electron-builder, you'll need the standalone version of pnpm (`@pnpm/exe`) to build packages 2. Clone the repo and enter the cloned folder, for example with these commands: ```bash git clone https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher.git --recurse-submodules cd HeroicGamesLauncher ``` 3. Make sure all dependencies are installed by running `pnpm install` 4. Download all helper binaries using `pnpm download-helper-binaries` ### Building Heroic Binaries Run the appropriate command for your OS: - Build for Linux: ```bash pnpm dist:linux # Optionally specify a package to create (eg: deb, pacman, tar.xz, rpm, AppImage); default: AppImage ``` - Build for Windows: ```bash pnpm dist:win ``` - Build for Mac: ```bash pnpm dist:mac ``` ### Building with VS Code Instead of using the above commands to build Heroic, you can also use the Tasks in VSCode to build. To do that, open up the command palette (Ctrl + P), type in "task" and press Space. You will then see 3 build tasks, "Build for Linux", "Build for Windows", and "Build for MacOS". Click the one you want to run. ### Quickly testing/debugging Heroic on your own system If you want to quickly test a change, or you're implementing features that require a lot of restarts, you can use Vite's development server to speed up the process: Go to the "Run and Debug" tab of VSCode and start the "Launch Heroic (HMR & HR)" task (alternatively, if you're not using VSCode or just prefer the terminal, run `pnpm start`). Heroic will start up after a short while, and once you make any change to the code, it'll reload/restart. ### Development on Nix After cloning the repository, Nix users can use `nix-shell` to make Node.JS/pnpm available and automatically run [installation step](#development-environment) 3 and 4. See [shell.nix](shell.nix) for more information. ## Sponsors Thanks [Weblate](https://weblate.org/en/) for hosting our translations Thanks [Signpath](https://signpath.io/?utm_source=foundation&utm_medium=github&utm_campaign=heroicgameslauncher) for providing free signing of Windows binaries [](https://signpath.io/?utm_source=foundation&utm_medium=github&utm_campaign=heroicgameslauncher) ## Screenshots Expand ## Credits ### Weblate: Localization platform - URL: https://weblate.org/en/ ### Those Awesome Guys: Gamepad prompts images - URL: https://thoseawesomeguys.com/prompts/ [](#heroic-games-launcher) ### Tools We Use to Run Games Heroic would not be possible without the work done in many other projects: - Legendary: https://github.com/derrod/legendary (we use [a fork of it](https://github.com/Heroic-Games-Launcher/legendary)) - GOGdl: https://github.com/Heroic-Games-Launcher/heroic-gogdl - Nile: https://github.com/imLinguin/nile - Comet: https://github.com/imLinguin/comet - GE-Proton: https://github.com/GloriousEggroll/proton-ge-custom - Proton-cachyos: https://github.com/CachyOS/proton-cachyos - umu-launcher: https://github.com/Open-Wine-Components/umu-launcher - DXVK: https://github.com/doitsujin/dxvk - VKD3D: https://github.com/HansKristian-Work/vkd3d-proton - Game-Porting-Toolkit: https://github.com/Gcenx/game-porting-toolkit - Wine-Staging: https://github.com/Gcenx/macOS_Wine_builds - Wine-Crossover: https://github.com/Gcenx/winecx - DXVK-MacOS: https://github.com/Gcenx/DXVK-macOS - DXMT: https://github.com/3Shain/dxmt - Heroic-Epic integration exe: https://github.com/Etaash-mathamsetty/heroic-epic-integration - vulkan helper: https://github.com/imLinguin/vulkan-helper-rs So be sure to follow and support those projects too! --- ## File: doc/cla.md ## HEROIC GAMES LAUNCHER ### CONTRIBUTION LICENSE AGREEMENT This Contribution License Agreement (the “CLA”) is between the individual set forth in the signature block (“You”) and Heroic Labs, Inc. (“Heroic”), effective as of the date of Your signature and sets forth the terms pursuant to which You may provide Contributions to Heroic. You accept and agree to the following terms and conditions for Your past, present and future Contributions submitted to Heroic’s Heroic Games Launcher project (the “Project”). In return, Heroic will not use Your Contributions in a way that is contrary to Heroic’s business objectives. Except for the license granted herein to Heroic and recipients of software distributed by Heroic, You reserve all right, title, and interest in and to Your Contributions. 1. Definitions. “Contribution” means any original work of authorship, including any modifications or additions to an existing work, that You intentionally submit, or have submitted previously, to Heroic for inclusion in, or documentation of, the Project. “Submit” means any form of electronic, verbal, or written communication sent to Heroic or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Heroic for the purpose of discussing and improving the Project, but excluding communication that is conspicuously marked or otherwise designated in writing by You as “Not a Contribution.” 2. Copyright License. Subject to the terms and conditions of this CLA, You hereby grant to Heroic and to recipients of software distributed by Heroic a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works. 3. Patent License. Subject to the terms and conditions of this CLA, You hereby grant to Heroic and to recipients of software distributed by Heroic a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Project, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Project to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that Your Contribution, or the Project to which You have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this CLA for that Contribution or Project will terminate as of the date such litigation is filed. 4. Representations and Warranties. You represent and warrant to Heroic that: a. You are legally entitled to grant the above license, and if Your employer(s) has rights to intellectual property that You create that includes Your Contributions, then You represent and warrant that You have received permission to make Contributions on behalf of that employer, that Your employer has waived such rights for Your Contributions to Heroic, or that Your employer has executed a separate CLA with Heroic; b. Each of Your Contributions is Your original creation (see section 6 for submissions on behalf of others); and c. Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which You are personally aware and which are associated with any part of Your Contributions. 5. Support; Disclaimer. You are not expected to provide support for Your Contributions, except to the extent You desire to do so. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. 6. Third Party Works. If You wish to submit work that is not Your original creation, then You may submit it to Heroic separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which You are personally aware, and conspicuously marking the work as “Submitted on behalf of a third-party: [named here]”. 7. Notice. You agree to notify Heroic of any facts or circumstances of which You become aware that would make Your representations in this CLA inaccurate in any respect. 8. General. This CLA is the entire understanding and agreement with respect to the subject matter hereof, and supersedes any and all prior or contemporaneous representations, understandings, and agreements, between the parties regarding same. If any part of this CLA is found to be unenforceable, the remaining portions of this CLA will remain in full force and effect. No modification of or amendment to this CLA, nor any waiver of any rights under this CLA, will be effective unless in writing signed by the party to be charged, and the waiver of any breach or default will not constitute a waiver of any other right under this CLA or any subsequent breach or default. Nothing in this CLA creates and the parties do not intend to create, any partnership or joint venture between themselves. Either party may freely assign this CLA. This CLA is binding upon and will inure to the benefit of a party’s successors and permitted assigns. This CLA will be governed by the laws of the State of Delaware. Exclusive jurisdiction of any and all disputes hereunder will be in the state and federal courts in Wilmington, Delaware. This CLA may be executed in counterparts with the same effect as if all signatories had signed the same document. --- --- ## File: doc/electron_store.md Similar to our IPC system, we also type-check our Electron Stores. If you want to use its functionality in your code, remember: - Use `TypeCheckedStoreBackend` and `TypeCheckedStoreFrontend` - Modifying our list of stores (adding new ones, changing the structure) can be done in `src/common/types/electron_store.ts` Note that you'll have to be _very_ careful when changing an existing store's structure, as the old structure does not get converted to your new format automatically (to facilitate this, you can use [migrations](https://github.com/sindresorhus/electron-store#migrations)) - When accessing elements, use `.get` with a default value, or `.get_nodefault` if you can't/don't want to provide a default Specific store structure notes: - If you have a store with pre-set keys, you can just add those keys into the interface: ```ts interface StoreStructure { // ... myStoreName: { myKey: boolean /* or any other type here */ } } ``` - If your store's keys are set dynamically (for example, a store that uses AppNames as keys), you can use [Index Signatures](https://www.typescriptlang.org/docs/handbook/2/objects.html#index-signatures) instead: ```ts interface StoreStructure { // ... myStoreName: { [key: string]: boolean /* or any other type here */ } } ``` --- ## File: doc/frontend_design_system.md # Frotend Design System ## Type System the type system is adjustable with two variables. Like you've seen, font-size sets the medium font size (1rem) and --text-scale-ratio adjusts the difference between text size steps. By keeping these as variables instead of hardcoding all the --text- values in rem units, we ensure that each step is exactly 20% (if --text-scale-ratio equals 1.2) different from the next step. This ensures visual consistency and gives options uniformly along the range of text sizes we want to support. This makes it easy to iterate, add breakpoints, and prevents the situation where one font size is updated but the others are not whether that be in a breakpoint or in the \_typography.scss file. It also isn't much of a limitation at all on the design side of things. ## Spacing System ### Relative Spacing the spacing system is first specified in em units. This means that it is a multiple of that element's font size. So let's say you have h6 at 1 rem (16px) and want margin-bottom to be 50% of this font size. By setting margin-bottom = 0.5 em (--space-xs) on the element, you accomplish this. When someone introduces a breakpoint later and changes the font, the margin-bottom won't have to be updated because it's specified in em. (So you probably won't have to update these css vars in media query breakpoints.) By creating css variables for these sizes, we constrain the components to use one of these predefined sizes, which again enforces visual consistency and makes the code much more maintainable. Designers can now iterate on the entire app's margins and paddings by tweaking these values. ### Fixed Spacing The fixed spacing system is intended for margins and paddings that shouldn't change based on the font size of the element. So if you want something to truly be 4px instead of 25% of a 1rem, use this. ## FAQ #### How do I pick the spacing values? Ideally there is a figma file that has already designed the component. If not, it will be up to the frontend dev to select a font size or spacing value. #### How should I handle border-radius? If you want it to adjust dynamically to font size changes in the element (e.g. when hitting a breakpoint), use --space-X. If you want a constant value in px, use --space-X-fixed. #### Why should I use a spacing value instead of a text value? It's important that we keep our design system parameterized and defined in one place for maintainability and ease of iteration by our designers. #### I can't find the px value I want. Can I hardcode it? This isn't good practice. It's important to keep our text sizes, margins, and paddings constrained to a small number of choices so that we can provide a visual consistent user experience. If you truly need a different value, consider changing the --space or --space fixed category value defined in \_spacing.scss. Consult the designers first though. --- ## File: doc/frontend_testing.md # Overview of Frontend testing enviroment ## Configuration files The frontend test's are running via jest. The related config can be found under `src/jest.config.js` Jest using [ts-jest](https://kulshekhar.github.io/ts-jest/) to test `.tsx` and `.ts` files and is configured with the `tsconfig.js` from the root path. ## Mocks All the global mocks can be found under `src/test_helpers/mock` and are invoked if you import the following patterns in your frontend file: - `*.css` files - ignoring `*.css` imports in the test - `electron` - mocking all ipcRenderer calls with [jest-when](https://github.com/timkindberg/jest-when) plugin, which are invoked in the frontend source files. - provides a function to init all electron mocks. - this function is mostly called from other helper functions and shouldn't be needed that often. - `react-i18next` - mocks the `useTranslation` hook and the `t` function **Note1:** If you implement new ipcRenderer calls in the frontend, make sure they are resolved correctly in the `src/test_helpers/mock/electron.ts` file, else some test's can run in unresolved promises and fail. **Note2:** If new mocks are needed globally add them to the field `moduleNameMapper` in the `src/jest.config.js`. ## Pre defined type configurations In the file `src/test_helpers/testTypes.ts` are alot of predefined type configurations which can be used to provide configurations for the test's and also to manipulate them easy for your needs. All this type configurations are defined via a template class `TestType`. This provides the function `set()`, `get()` and `reset()`. Also there is a helper function `resetTestTypes()` which resets all type configurations to there default values. It is a good practice to call this in a `beforeEach()` of a describe entry. --- ## File: doc/ipc.md To add type safety to Electron's IPC system, we've made the following changes to what you'd usually see in an Electron app: - Since `contextIsolation` is turned on, you cannot simply use `ipcRenderer.send`/`ipcRenderer.invoke` in the frontend to make IPC calls to the backend. Instead, we define a helper function for each IPC channel in `src/backend/api/`, which will be injected into the frontend on load. It'll then be available as `window.api.yourFunction`. See [Context Isolation](https://www.electronjs.org/docs/latest/tutorial/context-isolation) for more details - To make sure that the parameters passed to & value returned from the callback of an `ipcMain.on`/`ipcMain.handle` call are correct, every IPC channel has to be defined in `src/common/typedefs/ipcBridge.d.ts` (adding new channels either to `SyncIPCFunctions` or `AsyncIPCFunctions`). This will also result in your callback's parameters automatically getting type annotations, and your helper function in `src/backend/api/` getting type-checked as well