Hey and welcome, thanks for stopping by!
Heracles is an active continuation fork of saturn-xvi's Prometheus, a preservation and reverse-engineering project for the Overwatch 0.8.0 beta (Build 24919, October 2015). Since the original Prometheus project has been stalled for a while, Heracles picks up the torch to make the 2015 client genuinely playable offline.
(Note: Core project files and internal classes still use the prometheus name for now).
- 1. Usage
- 2. Game internals
- 3. What Heracles fixed & what's still broken
- 4. Tips & Tricks
- 5. Contributions Welcome!
- 6. NOTE
- 7. Open Source libraries used
- 8. License and Credits
If you haven't already, download the Overwatch Beta build we target from Hidden Palace and extract the files somewhere.
- ⚠� Make sure that you don't download any malicious executable and verify that
GameClientApp.exeis signed by Blizzard. The signature will get broken after applying that patch - but musn't be before. - You can optionally remove the
BlizzardErrordirectory.
- Download a
release.zipand extract all files to the game directory. - Execute
patcher.exe. It will ask for an inputGameClientApp.exe- select the one you downloaded and verified.- The patcher will write a
GameClientApp.patched.exefile into the same directory. The only thing this patched executable does is loadinject.dllbefore running the game code itself. - You only need to do this once; this patch is version-independent.
- The patcher will write a
- Rename
prometheus.dlltoinject.dll. - Launch
GameClientApp.patched.exe.
- Set the Windows version of the Wine prefix to Windows 10.
WINEPREFIX=~/.wine64/ WINEARCH=win64 winecfg
- Install the .NET 8 runtime. (For patcher only)
WINEPREFIX=~/.wine64/ WINEARCH=win64 winetricks dotnet8
- Install the .NET 8 desktop framework. (For patcher only)
WINEPREFIX=~/.wine64/ WINEARCH=win64 winetricks dotnetdesktop8
- Select the unpatched executable.
WINEPREFIX=~/.wine64/ WINEARCH=win64 wine patcher.exe
- Download Proton from GloriousEggroll and install umu-launcher. Launch the patched executable using umu.
WINEPREFIX=~/.wine64/ WINEARCH=win64 PROTONPATH="/home/tracer/GE-Proton10-25/" umu-run GameClientApp.patched.exe
Please note that the Linux build instructions have remained as-is from the original fork - I do not test building on Linux
- Download the MonaspaceXenon font and put the
-Regular.otfand-ExtraBold.otffiles in the game directory. - Download the Font Awesome v6 free desktop font files and put the
.otffiles into the game directory. - Once first started, the library will create
hashlibrary.json. You can add crc32 strings / elements to hash which will be displayed in various places where applicable. You can just add all the strings from the overtools github repository. To do so, add another root JSON element (an array) called"add"and put all your strings there.
The patcher itself just goes to TlsCallback_0 and patches some bytes so the executable loads inject.dll before anything else. inject.dll then restores the game to its original state, decrypts everything, emplaces the missing CASC encryption keys, and hooks stuff. Afterwards, it runs the game normally. This was achieved by copying the bytes that lazy_importer created for LoadLibrary and calling it with "inject.dll" as an argument.
- You need Visual Studio 2022 or newer.
- Make sure to initialize the submodules / clone recursively.
- Initialize the vcpkg repository with the
.ps1file located atexternal/vcpkg/scripts/bootstrap.ps1. - Compile as
Release/x64. No other configuration is tested (some flags and settings are missing).
At its core, almost every (in-game) problem with restoring Overwatch 0.8.0 to full playability comes down to one thing: the client was built to be a puppet controlled by a server - having to ask for permission to do just about anything. The client has all the models, animations, sounds, physics, and UI it needs, but it is constantly waiting for a server to tell it "you are allowed to shoot," "that bullet hit someone," or "where is the payload right now?". This project is fundamentally all about filling in the seams between what's controlled by the server (or pretends to be as a patch) and what the client tells the server - the game is fundamentally broken simply because of StateScripts and other functionality that was intentionally stripped during the build process.
The first thing Overwatch does is initialize all its "Managers". They handle things such as Dataflow, CASC, Window management, etc. This is the lowest level and not really interesting.
Afterwards, all the Entity Admins get initialized. First the Lobby, then Game, and finally Replay.
There is one Entity Admin base class on which all others depend. The LobbyEntityAdmin includes login, main menu UI, user settings, and an embedded Entity Admin (Component 0x54) used to render the background map on the main menu.
The GameEntityAdmin is the biggest one and contains, amongst others:
- A
uintthat says "this is the local entity". This must reference the Controller entity. Systems use Components0x2F(local player component) and0x20(model reference component) out of that entity to display the local player on screen. - A JAM virtual function table used to send JAM network messages.
- A table of map callbacks. Systems can subscribe to map change events (for example, if the map state changes from "Global Loading" to "World Loading").
- A virtual function table reference from the
MirrorSystem, which systems use to subscribe to pre- and post-component deserialization when a server sends updates. - An Accessor which searches for an Entity with the
PvPGameComponent(0x24) and takes match information from that.
A single player in the GameEntityAdmin is actually split across four layers of entities:
- The Controller ("Brain"): Reads your mouse/keyboard, tracks what hero you picked (
0x3F), and holds your camera (0x2F,0x20). - The 3P Hero Model ("Body"): The physical hero model that spawns in the world. Holds health (
0x28), movement/physics (0x12,0x15), and ability scripts (0x23). - The 1P Viewmodel ("Hands"): The floating first-person arms and guns only you see on your screen (referenced by Component
0x22). - Weapons & Gun Barrels: The weapon models attached to your hands (
0x1D), plus invisible "muzzle" entities attached to the barrel tips where firing particles play (0x0D).
STU is the proprietary structured data / reflection format for Overwatch. It gets used to read data out of CASC archives, and some in-game data gets serialized using this. Everything needed to read STU is located in STU.h. If you want to edit STU, include STU_Editable.h, but make sure to read the comments so you don't crash ;).
For usage examples, you can have a look in windows/stu_explorer.h.
A pull/publish system used to pipe game data into shaders, effects, and UI. DataFlow members can live both inside and outside of the Entity Component System.
8-byte GUIDs able to be sent from the client and server and observed by Statescript, with optional additional data. Other systems besides Statescript can also broadcast GameMessages.
Holds the current gamemode state, round counters, and overtime timers.
Statescript is Blizzard's visual scripting engine (very similar to Unreal's Blueprints - and, simmilarly, with obtuse internals) and controls:
- In-game weapons, abilities, and Ultimates (pretty much everything except basic WASD movement)
- User interface interactions and HUD viewmodels
- Login logic
- Music & sound triggers
- Sliding spawn doors, capture points, and health packs
A Statescript component (via its StatescriptSyncMgr inside) holds several StatescriptInstances, which run node graphs defined in STUStatescriptGraph resources. Scripts read and write variables stored in VarBags (dictionaries attached to either the script instance or the entity itself).
In Heracles, we found three major reasons why Statescript was failing - in general:
- Missing Client Authority Flags: Weapon and ability states check an execution bitflag asking "is this entity the local player's active aim target?" Without it, firing states started and aborted on the exact same frame (causing i.e. Tracer's guns to just click 5 times a second without shooting).
- Negative Client Script IDs: Online, the server assigns positive IDs (
1, 2, 3...) to scripts. Offline, client-loaded scripts get negative IDs (-1, -3, -24...). When the engine packs a negative 16-bit ID into a 13-bit handle and unpacks it without restoring the minus sign,-24turns into+8168causing muzzle flashes, bullet raycasts, and projectiles to fail their script lookups as well as a host of other downstream issues. - Stripped Server Nodes: Blizzard stripped the code for several server-only damage, healing, impulse, and entity-spawning nodes from the client executable. We (try our best to) emulate these missing nodes so abilities and Ultimates work offline across all 21 heroes.
Needed if an entity wants to be shown on the map. It holds position, scaling, rotation, visibility flags, and a bitflag (Bit 16) that tells the bullet raycaster whether this entity has skeletal bone hitboxes that can be shot (Havok-based).
Interestingly, Component 1 has two functions to move an object: one that moves both the solid physics collider and the 3D visual mesh, and an internal one used right before rendering a frame that moves only the 3D visual mesh.
(Encompasses movement_vt, Movement system(s), Component 0x12 STUMovementState, 0x15 STUCharacterMoverComponent, and 0x16 STUSimpleMovementComponent).
Component 0x12 holds a ring buffer of network movement snapshots from the server to interpolate moving objects smoothly. Offline, that buffer is completely empty. We discovered that when Component 0x12's buffer is empty, its fallback code literally writes (0, 0, 0) as the object's position every frame - and calls Component 1's visual-only move function.
For further reference for heroes specifically, please check out the TEST_MATRIX.md file in the repo root.
- Weapons shoot, reload, and show muzzle flashes: Primary and secondary fire, ammo consumption, reloading, and 1P barrel muzzle flashes (mostly) work across the cast. There are still issues - like dual-weapon heroes - but the core logic works. Damage nor damage type may yet be reflective of the actual projectile or hitscan used, nor is it very likely to reflect actual damage values - this is an area of active development and improvements and is likely to stabilize to original Beta values and functionality very soon.
- Spawning is reliable: Spawning uses a deferred state machine that waits for Component
0x23to finish loading before attaching weapons, so you no longer spawn with missing guns. Spawning natively, without the Player Spawner DeLuxe, has also been thoroughly debugged and should function correctly now. - D.Va spawns in her Mech: Spawning D.Va now puts her directly in her Mech (with 100 HP + 400 Armor) instead of floating around as Pilot D.Va. However, her ult and general de-meching is still broken, resulting in odd behavior and ocassional crashes.
- Pressing
Hto swap heroes works anywhere: You can pressHanywhere on any map to open the Hero Select screen and swap heroes in-place at your current position. This is a placeholder for native spawnroom detection. - Doors, Capture Points, and Payloads stay in place: Blocking Component
0x12's empty-buffer(0,0,0)overwrites keeps all map props, payloads, and doors at their proper map coordinates. - Spawn doors slide open and closed: You can open and close map spawn doors natively (with animations, sound, and collision) from the Player Spawner DeLuxe or the first Diagnostics window.
- Target Dummies & Full Combat Loop: You can spawn Enemy or Friendly bots in Player Spawner DeLuxe. Shooting them now hits their actual skeletal bone hitboxes (with headshots, armor reduction, blood/spark VFX, flinch animations, and hurt grunts), shows their overhead enemy healthbar, awards
0% -> 100%Ultimate charge, and triggers ragdoll knockouts, 3D death screams, red kill skulls, the "ELIMINATED [HERO]" banner, and a top-right HUD Killfeed on kill. - Hero & World Skin Switcher (
F1): Press F1 (or open Cosmetics -> Hero & World Skin Switcher (F1) in the top menu bar) to visually switch between all 84 skin themes (1 Classic + 3 Recolor themes per hero, with color swatches and weapon skin overrides) on yourself or any Friendly, Neutral, or Enemy hero in the world. - Hero Abilities & Ultimates: Many of the abilities across the roster already function correctly and reliably. The remaining issues cluster around a couple of very specific problems that generalize fixes across the cluster (targeted abilities, dual-weapon heroes, certain shield interactions and visuals etc.). This is being actively worked on. Please refer to the TEST_MATRIX.md - this is being updated as testing progresses in step with development.
- Main Menu matchmaking buttons: Main menu play buttons (as well as several other pre-menu items) only send JAM messages to a Battle.net server. Use the top bar workflow (
DP Load->Map) to load into a map. This will be hooked and hopefully usable at some point - low priority. - Gamemode objectives: Capture point progress rings and payload movement along tracks still need offline gamemode script orchestration, but function visually and, partially internally as well.
- "Press H to select Hero" banner: Controlled by a server flag and will probably stay visible on the HUD after spawning for the time being. Sorry.
- Communication wheel & dynamic voice lines: Tracer's spawn voiceline and 3D victim death screams work, but the full server-side communication wheel and contextual voice rules are still a TODO. I think I have most of the architecture nailed down, it just needs some love and several afternoons of work.
- Map unloading crashes the game: Just use the Restart button in the top bar when switching maps for now - or restart the game entirely. Note that map switching does ocassionally work - it's just not supported at the moment. This will hopefully change in the future.
- Window resizing: Resizing the game window messes with viewmodels (a bug in the 0.8 beta itself that may or may not be patch-able when everything else is functional). Borderless Windowed mode works best.
- Quick-start in 4 clicks: Click
DP Loadin the top bar -> pick a map underMap-> open Game -> Player Spawner DeLuxe -> pick a hero and clickSpawn(and clickOpen Spawn Doorsso you aren't locked in spawn yelling door stuck). - Hide the debug UI: Press
~to toggle all ImGui windows on/off so you can play with a clean screen. - Swap heroes with
H& switch skins withF1: Once you've spawned a hero, pressHat any time to open the native Hero Select screen and switch heroes on the fly, or pressF1to open the visual Hero & World Skin Switcher to change skins on yourself or any friendly/neutral/enemy hero in the world. Optionally, you can just select a hero normally from the in-game menu after you've loaded a map externally. It should work. If you encounter issues, simply spawn with the Player Spawner DeLuxe as described above. - Spawn Target Dummies: In Player Spawner DeLuxe, click
Spawn Jeff Kaplanto drop a target enemy dummy in front of you to test weapons, headshots, knockbacks, and Ultimates, orSpawn Friendly Dummy (Team 0)to test ally-based abilities. They don't do anything except just stand there waiting to get shot or blown up, but are very useful for development and general testing. - Teleport & Timescale: Use the Up / Down arrow keys to teleport yourself up or down. Use the Left / Right arrow keys to slow down or speed up the physics timescale. This is necessary on... most maps. On Hanamura, specifically just Genji falls through the floor when you try to spawn him. I still don't know why lol.
- World Map: Press
Min-game to toggle the overhead map overlay. - FreeLookView: Check out the
FreeLookViewcheckbox in Player Spawner DeLuxe to fly around the map with WASD + Shift without needing a hero. - Multiplayer ("Awful Demo Server"): Enable
Demo,DP Load, load a Map, select a hero and go in-game. Then go to Tools -> Awful Demo Server and start the server. Open a second instance and connect to the server before selecting a hero. (Currently only syncs player positions and hero models; seeserialization.handstate_replicator.h). Making this work properly is the core aim of this project after things function as-intended offline.
We envision a future in which we are able to play any Overwatch version that was released. With help from the community, this isn't just a dream, but a real possibility. Most of the code that's being worked on here is directly transferrable between different Overwatch 1 versions. Please help by forking, contributing, opening bug reports, and sharing <3. Remember, great science is always the result of collaboration!
Since this project is actively evolving and reverse-engineered structures are continuously being refined, many bugs, inaccouracies, and edge cases may still exist.
Also don't look into the window manager. It's an abomination. You have been warned.
- MinHook
- keystone
- capstone
- imgui
- imnodes
pe(Could not find the original repository, please open an issue if you know it!)- lazy_importer
- nlohmann_json
- ixwebsocket
- freetype
- fast-cpp-csv-parser
- Monaspace Xenon (optional)
- Font Awesome (optional)
- Original Prometheus Project: saturn-xvi / BreakingBread0
- Contributors: tslocum, Hazno-dev, Groot36-yep, EvESpirit, BreakingBread0
AGPL-3.0 License. Kept under AGPL to ensure this remains a project made by the community, for the community.
