Hephaistos
Hades.patched.with.Hephaistos.for.3840x1600.mp4
CLI tool for patching any resolution in Supergiant Games' Hades, primarily targeting ultrawide monitors (21:9, 32:9), multi-monitor (48:9), and Steam Deck (16:10).
By default, on Hades:
- Resolutions wider than 16:9 (e.g. 21:9) are pillarboxed with artwork / black bars on left / right.
- Resolutions taller than 16:9 (e.g. 16:10) are letterboxed with black bars on top / bottom.
Hephaistos can bypass both, and also allows using custom resolutions (useful for custom window sizes and multi-monitor without Eyefinity / Surround).
- For trying out Hephaistos right away, see Install.
- For a preview of how Hades looks in 21:9, 32:9, 48:9, and 16:10, see Showcase.
- For more details about how Hephaistos works, see Under the hood.
Issues
Hephaistos is in a stable state: many users have been using it for a long time (some of them even from their very first time on Hades), and nothing major has had to be fixed for a while.
Still, there might be some quirks or rare interactions on specific setups that haven't been detected yet: you are most welcome to report anything you witness by opening a new issue (ideally with screenshots / videos / a save file) and I will definitely have a look and fix it
Showcase
Before / after comparisons (click on items for more details):
21:9
32:9
48:9 / triple screen (with HUD centered)
16:10 / Steam Deck
Additional screenshots
21:9
32:9
48:9 / triple screen (with HUD centered)
16:10 / Steam Deck
ℹ️ More images can be found over at Nexus Mods and WSGF.
Install
Download
Hephaistos can be downloaded as an executable for Windows, macOS, and Linux, or as a Python archive (click on items for more details):
Windows
- Download hephaistos-windows.zip.
- Extract the archive. You should get an
hephaistos.exeexecutable. - Move
hephaistos.exeto Hades main directory. Hephaistos must be sitting right next to the default directories:- Steam / Epic Games
Hades/ ├── Content/ ├── x64/ ├── x64Vk/ ├── x86/ └── hephaistos.exe⚠️ If you don't know where Hades is, Hephaistos can try to give you a tip by auto-detecting from Steam and Epic Games configuration files: just runhephaistos.exe. Note that you still have to move the files to the Hades directory manually before continuing. - Microsoft Store
Hades/ ├── Content/ │ ├── Content/ │ ├── ja/ │ ├── Hades.exe │ └── ... ├── [hidden file] E0A69B86-F3DD-416D-BCA8-3782255B0B74 ├── [hidden file] ... └── hephaistos.exe>⚠️ If you don't know where Hades is, just reinstall Hades from the Microsoft Store: you can then choose where Hades will be located. > Note that you still have to move the files to the Hades directory manually before continuing.
- Steam / Epic Games
macOS
- Download hephaistos-macos.zip.
- Extract the archive. You should get an
hephaistosexecutable. - Move
hephaistosto Hades main directory. Hephaistos must be sitting right next to the default directories (Steam / Epic Games):Hades/ ├── Game.macOS.app/ └── hephaistos⚠️ If you don't know where Hades is, Hephaistos can try to give you a tip by auto-detecting from Steam and Epic Games configuration files: just runhephaistos. Note that you still have to move the files to the Hades directory manually before continuing.
Linux
- Download hephaistos-linux.zip.
- Extract the archive. You should get an
hephaistosexecutable. - Move
hephaistosto Hades main directory. Hephaistos must be sitting right next to the default directories (Steam):Hades/ ├── Content/ ├── x64/ ├── x64Vk/ ├── x86/ └── hephaistos⚠️ If you don't know where Hades is, Hephaistos can try to give you a tip by auto-detecting from Steam configuration files: just runhephaistos. Note that you still have to move the files to the Hades directory manually before continuing.
[Advanced] Python
- Download hephaistos-python.zip.
- Extract the archive. You should get
hephaistos,hephaistos-dataandsjsondirectories. - Move all directories to Hades main directory. Hephaistos must be sitting right next to the default directories (see Windows / macOS / Linux entries above for more details).
Usage
Once Hephaistos is placed in the proper directory, you can use it in two ways:
- [Easy] Directly run Hephaistos and follow the interactive instructions: see Interactive mode for detailed help.
- [Advanced] Use Hephaistos subcommands from the command line: see CLI usage below.
Interactive mode
- Windows: run
hephaistos.exe - macOS / Linux: run
hephaistos - Python: run
python -m hephaistos
When running Hephaistos in interactive mode, Hephaistos will guide you through the steps:
Hi! This interactive wizard will help you to set up Hephaistos.
Note: while Hephaistos can be used in interactive mode for basic usage, you will need to switch to non-interactive mode for any advanced usage. See the README for more details.
Current version: v1.x.y
Latest version: v1.x.y
Pick an option:
1. Patch Hades using Hephaistos
2. Restore Hades to its pre-Hephaistos state
3. Check current Hades / Hephaistos status
4. Exit
Choice:
Type 1 to pick the patch option. Hephaistos will again prompt you for your resolution and HUD preferences, and then patch Hades:
INFO:hephaistos:Using resolution: (3840, 1600)
INFO:hephaistos:Using '--scaling=hor+': computed patch viewport (2592, 1080)
INFO:hephaistos:Using '--hud=expand': HUD will be expanded horizontally / vertically
INFO:hephaistos:Patched 'x64\EngineWin64s.dll'
INFO:hephaistos:Reading SJSON data (this operation can take time, please be patient)
...
INFO:hephaistos:Installed Lua mod to 'Content\Mods\Hephaistos'
INFO:hephaistos:Patched 'Content\Scripts\RoomManager.lua' with hook 'Import "../Mods/Hephaistos/Hephaistos.lua"'
Press any key to continue...
⚠️ Reading SJSON data can take time depending on your CPU and hard drive, please be patient⏳
Hades binaries are now patched to work with the chosen resolution. Start the game and try it out for a bit.
Once done, use Hephaistos again, but this time type 2 to pick the restore option:
INFO:hephaistos:Restored backups from 'hephaistos-data\backups' to '.'
INFO:hephaistos:Discarded hashes at 'hephaistos-data\hashes'
INFO:hephaistos:Discarded SJSON data at 'hephaistos-data\sjson-data'
INFO:hephaistos:Uninstalled Lua mod from 'Content\Mods\Hephaistos'
Hades binaries are now restored to their pre-Hephaistos state.
Do note that every time it receives an update, Hades will automatically revert to its default resolution, and Hephaistos must be reapplied.
If in doubt, type 3 to pick the status option and check the current Hades / Hephaistos status.
This concludes the tutorial.
I hope you'll enjoy Hephaistos
CLI usage
- Windows: run
hephaistos.exe -h - macOS / Linux: run
hephaistos -h - Python: run
python -m hephaistos -h
Hephaistos is mostly self-documented via the CLI help.
Run hephaistos -h to find the available subcommands (patch, restore, etc.) which themselves are documented (e.g. hephaistos patch -h).
Add the -v flag to print information about what Hephaistos is doing under the hood.
The flag may be repeated twice (-vv) to display debug output.
Patching Hades using Hephaistos
Adjusting 3440 and 1440 with your own resolution:
hephaistos patch 3440 1440
ℹ️ You can safely repatch multiple times in a row as Hephaistos always patches based on the original files. There is no need to restore files in-between.
HUD
Hephaistos supports the following HUD resizing modes (click on items for more details):
expand (default)
Expand the HUD horizontally and vertically, i.e. HUD will scale with screen size. Static HUD elements will be repositioned to their intended location for the new screen size, e.g. health indicator will be in the bottom left, resource indicator will be in the bottom right.
center
Keep HUD in the center of the screen with the same size as the original HUD, i.e. screen size will change but HUD will not move.
You might want to use --hud=center for 32:9 or wider resolutions.
Scaling
Hephaistos supports the following scaling algorithms (click on items for more details):
hor+ (Hor+ scaling, default)
Expand aspect ratio and field of view horizontally, keep vertical height / field of view. This is the default scaling used by Hephaistos for aspect ratios wider than 16:9 (e.g. 21:9), and recommended for general usage as it strives to keep the experience as close to the original as possible.
vert+ (Vert+ scaling, default)
Expand aspect ratio and field of view vertically, keep horizontal height / field of view. This is the default scaling used by Hephaistos for aspect ratios taller than 16:9 (e.g. 16:10), and recommended for general usage as it strives to keep the experience as close to the original as possible.
pixel (pixel-based scaling)
Expand field of view in all directions without applying any scaling, disregarding aspect ratios. This scaling is not recommended for general usage as it effectively "zooms out" the camera and thus does not keep the experience close to the original, but it's fun if you have a big screen and want to see more of the screen at once.
Use --scaling=pixel if you wish to use pixel-based scaling.
Custom resolution
By default, Hephaistos patches a custom resolution in the ProfileX.sjson configuration file by updating its WindowWidth/WindowHeight and X/Y values.
This has two advantages:
- Ensure the game runs at the preferred resolution.
- Useful when inadvertently switching to a wrong resolution from the game settings.
- Useful when playing Hades on a secondary monitor.
- Allow running the game in windowed mode at a specific size.
- Useful for choosing your own window size in windowed mode.
- Useful for spanning the game window over multi-monitor without Eyefinity / Surround.
Neither of these are possible in the vanilla game: only the resolutions from the main display are offered from the game settings and the game window cannot be freely resized.
Use --no-custom-resolution if you wish not to force custom resolution through ProfileX.sjson.
Restoring Hades to its pre-Hephaistos state
hephaistos restoreChecking Hades / Hephaistos status
hephaistos statusPatching Hades again after a game update
Every time it receives an update, Hades will automatically revert to its default resolution, and Hephaistos must be reapplied. Trying to repatch after a game update will be blocked:
> hephaistos patch 3440 1440
ERROR:hephaistos:Hash file mismatch: 'XXX' was modified.
ERROR:hephaistos:Was the game updated? Re-run with '--force' to discard previous backups and re-patch Hades from its current state.And status will confirm this:
> hephaistos status
Hades was patched with Hephaistos, but Hades files were modified. Was the game updated?Since the game was updated, the previous backups can be safely discarded.
Use --force to repatch and create new backups:
hephaistos patch 3440 1440 --forceMiscellaneous options
Hades directory
By default, Hephaistos assumes that it has been placed in the main Hades directory. If it fails to detect Hades files, it will try to auto-detect Hades location from Steam and Epic Games configuration files and ask to be relocated.
You may use --hades-dir to manually specify where Hades is located, e.g. if you want to store Hephaistos and its files in a different location than the Hades directory.
Mod Importer
Hephaistos is compatible with Mod Importer1 (>= 1.3.0).
If Hephaistos detects it is available, it will run modimporter to register / unregister itself during patch and restore operations, instead of manually editing Content\Scripts\RoomManager.lua.
This can be bypassed with --no-modimporter, in which case Hephaistos will not run modimporter even if detected.
Under the hood
Hades uses an internal 1920x1080 viewport with static scaling (i.e. it can only played at 16:9, no matter the display resolution).
To bypass this limitation, Hephaistos patches the game's files with an ad-hoc viewport computed depending on chosen resolution and scaling algorithm:
> hephaistos patch 3440 1440 -v
INFO:hephaistos:Using resolution: (3440, 1440)
INFO:hephaistos:Using '--scaling=hor+': computed patch viewport (2580, 1080)
INFO:hephaistos:Using '--hud=expand': HUD will be expanded horizontally / vertically
INFO:hephaistos:Patched 'x64\EngineWin64s.dll'
...
INFO:hephaistos:Installed Lua mod 'hephaistos/lua' to 'Content/Mods/Hephaistos'
INFO:hephaistos:Patched 'Content/Scripts/RoomManager.lua' with hook 'Import "../Mods/Hephaistos/Hephaistos.lua"'
> python -m hephaistos patch 1280 800 -v
INFO:hephaistos:Using resolution: (1280, 800)
INFO:hephaistos:Using '--scaling=vert+': computed patch viewport (1920, 1200)
...- Backends' engine DLLs are hex patched to expand the resolution and camera viewports.
- Resource SJSON files are patched to resize / move around GUI elements.
- Gameplay Lua scripts are extended with a Lua mod recalculating sizes / positions of GUI elements.
ℹ️ Hephaistos is compatible with Mod Utility2 (>= 2.2.0). If available, it will leverageModUtilhook functions rather than its own custom hooks. This makes Hephaistos more compatible with otherModUtil-based mods if they also are hooking onto the same functions as Hephaistos (though it still won't magically fix conflicts or new GUI elements from other mods that Hephaistos wasn't tailored to).
While patching, Hephaistos stores:
- A backup of the original files.
- Allows restoring Hades to its pre-patch state if need be.
- File hashes of the patched files.
- Allows detecting any outside modifications made to the files -- mostly for detecting game updates.
- Allows detecting if we are repatching a previously patched installation, in which case the original files are used as basis for in-place repatching without an intermediate restore operation.
- (If patching an SJSON) A JSON-serialized
dictof the deserialized original SJSON data.- Speeds up in-place repatching as we avoid the need to deserialize the original SJSON data again (which is very slow, while deserializing the JSON is instantaneous).
Everything is stored under the hephaistos-data directory.
Why did you make this, and how did you know what to patch?
I love Hades and am an ultrawide player myself.
I decided to try my hand at modding ultrawide support by decompiling Hades and reverse-engineering the viewport logic just to see if I could, and here we are
See this blog post for more details about Hephaistos' genesis.
Footnotes
-
Mod Importer (GitHub / Nexus Mods) is a tool helping to manage mods and register / unregister them with Hades.
↩ -
Mod Utility (GitHub / Nexus Mods) is a mod-library helping mods integrate not only with Hades but also with other mods.
↩