How Helldivers 2 mods work

The map: a mod, from idea to your screen

Start with the big picture. A mod's life has two halves: it gets built on your PC (build time), and it gets run inside the game (runtime). Each box in the diagram is labelled with the chapter that covers it.

How each chapter is laid out

• This chapter answers: one question. The whole chapter answers it.
• New concepts: terms that appear for the first time in this chapter, five or six at most, explained before they're used.
• Main text: written as “Because …, …” wherever possible, so you can see how the ideas connect.
• Hive Lord HUD at this point: what this principle actually meant while building the HUD.
• In the source: the lines of the real mod that implement this chapter, with a link to the annotated source page.
• Key points and Check yourself: after reading, try to answer first, then expand to see the answer. Anything you can't answer is a connection you haven't built yet.

What the game itself is

The code: compiled machine code

Arrowhead's engineers write the game in C++ (that's the source code), then a compiler translates it into machine code the CPU can run directly. During that translation, variable names, function names and comments all disappear, leaving only a string of bytes. Because all we have is the machine code, if you want to know what the game is doing, you have to work backwards from the machine code (Chapter 10).

Machine code lives in two kinds of files: the .exe is the main program, and a .dll is a library the main program loads while it runs. In Helldivers 2 the work is split like this:

When you hit “Play”, Windows starts helldivers2.exe and it becomes a process, which then loads game.dll and lua51.dll into itself. From that moment on, the engine, the game logic and the scripts all run inside the same process.

Resources: finding files by hash

data/ is full of files with names like 9ba626afa44a3aa3. These are archives, each holding many resources. When the engine wants a resource, it doesn't look it up by a text name. It uses two numbers instead: the type hash and the name hash.

A hash is a formula: the same text always produces the same number, but you can't work back from the number to the text. HD2 uses a formula called murmur64, which produces a 64-bit number. For example, the Hive Lord's model resource is called content/fac_bugs/cha_hive_lord/cha_hive_lord, and its hash is 0xD465D9C7F77A07CB; the hash of the type “lua” is 0xA14E8DFA2CD117E2. Because the files only store the numbers, you can't see any names just by opening an archive; you need a name list someone else has compiled to translate them back (Chapter 8).

The key that makes mods possible: patch files override the originals

There's a special kind of archive: files whose names end in .patch_0, .patch_1, and so on, called patch files. When the engine reads a resource, if a patch file contains a resource with the same type and the same name, it uses the version in the patch file and overrides the original. This mechanism was originally meant for game updates.

Because the engine dutifully reads any patch file placed in data/, and never checks whether its contents have been changed, anyone can make a patch file that swaps a resource for their own version. Every HD2 mod (cosmetic swaps and feature mods alike) is built on this.

How the game runs scripts every frame

The game loop

The game keeps repeating: read your input → update the world (enemies move, bullets fly) → draw the screen. Each repetition is called a frame; 60 FPS means 60 frames per second. Everything that “happens over time” happens inside this loop.

The scripting layer inside the engine

The Stingray engine has a built-in Lua runtime, using the LuaJIT version (its syntax is the same as Lua 5.1). Lua is a scripting language: the code exists as plain text, and LuaJIT only reads and runs it at runtime, with no compiling needed beforehand. The engine was originally designed so that most game logic would be written in Lua; but HD2 put almost all of its logic into the C++ game.dll, leaving Lua as just a thin layer of “glue”:

• When the engine starts, it loads a few Lua scripts (these are also resources in data/, with type lua).
• Every frame, the engine calls a Lua function named update, plus a few other fixed entry points such as render and shutdown.
• The engine exposes a set of features Lua can call (for example, listing the objects in the scene or drawing things on screen), called the stingray.* API (Chapter 4).

We measured it: the game's own Lua update takes almost no time per frame (close to 0 ms). In other words, the game itself barely uses this Lua environment, but it is always on and gets called every frame.

Why this is the way in for mods

Lua functions are stored in global variables, and global variables can be changed. Because every frame the engine “goes to the global variable update, takes the function there and calls it”, as soon as someone replaces update with their own function, the engine calls the new one on the next frame:

local original = update          -- first, save the game's original update
update = function(...)            -- replace it with our function
    do_my_stuff()                 -- do our own stuff first
    return original(...)          -- then call the original, so the game works as usual
end

This trick of “redirecting a call to yourself, then passing it back to where it was going” is called a hook. These five lines are what let a mod do something every frame.

But there's a catch: this code itself has to be run once first before it can replace update. The game only runs the few Lua scripts it knows about; it won't run an unfamiliar Lua resource. So who runs it that first time? That's the Loader, in the next chapter.

Who runs Lua that “someone else wrote”: Bingus Shared Loader

The key step: borrow a vanilla script that always runs

Put Chapter 1 and Chapter 2 together and the trick appears: when the game starts it always loads certain vanilla Lua scripts, and a patch file can override a vanilla resource with one of the same name. So if you make a patch file containing a Lua resource with the same name as a vanilla script, the game runs our version at startup.

Bingus Shared Loader picks core/wwise/lua/wwise_flow_callbacks: a callback script that the sound system (Wwise) always loads at startup. But the vanilla script handles sound, so if you just replace it, the game goes silent. So the Loader keeps every feature of the vanilla script, and does one extra thing on top: load mods.

• The game's resources live in archives in data/, located by “type + name hash (murmur64)”. The mod manager (Arsenal / HD2MM) deploys mods as extra 9ba626afa44a3aa3.patch_N files, and a resource with the same name inside them overrides the vanilla one.
• The Loader's archive holds just one lua resource, with name hash 0x7251FDD9BB62480A. We ran the same murmur64 and it matches core/wwise/lua/wwise_flow_callbacks exactly: the vanilla script the game's sound system (Wwise) requires at startup.
• So as soon as the game boots and loads the sound system, what actually runs is the Loader. It keeps all of the vanilla script's Wwise callbacks (wwise_trigger_event, wwise_load_bank…), so sound works as normal; the README also points out that it “keeps Wwise callbacks, does not replace boot”.
• The Loader itself is compiled LuaJIT bytecode (header \x1bLJ, about 20 KB). The flow below was pieced together from string constants in the bytecode, the README, and real logs.

What the Loader does after it starts

1. Enlarge the LuaJIT JIT cache: every mod shares the game's single LuaJIT, and the default cache is too small, so with many mods installed it keeps getting flushed. v18 raises it right away to 16 MB / 8,000 compiled code pieces (traces), grows it to 64 MB / 16,000 after a flush, and writes a LuaJIT cache: line to the log.
2. Create the shared log folder %LOCALAPPDATA%\CowboyBingus\Helldivers2\Logs and open BingusSharedLoader.log.
3. Create the global table CowboyBingusModLoader: it holds the version, the API level, a list of mod states, open_log(filename) (only accepts file names like ^[%w_-]+%.log$, so a mod cannot write to some other path), and JIT cache stats (jit.flushes and so on).
4. Find the game's data folder: use GetModuleFileNameA to get the executable's path, check that it ends in /bin/helldivers2.exe (if not, stop), and work out /data/ from it.
5. Scan every patch file: FindFirstFileA lists 9ba626afa44a3aa3.patch_*; each one is opened, the archive magic number 0xF0000011 and the tables are checked, the start of each lua resource is read, and its first line is matched against this pattern:

   ^%-%- HD2%-Addon: (mods/[A-Za-z0-9_]+/[A-Za-z0-9_/]+)

   The bytecode also contains a murmur64 implementation (hasher), which looks like it checks that the declared name matches the resource's hash (a guess, not confirmed in source).
6. Load: for the auto-discovered addons, plus a built-in list of CowboyBingus mods, check each one with Application.can_get('lua', name): if it does not exist, log not installed; if it does, run pcall(require, name) and log loaded on success, or load failed: reason on failure.

An example of BingusSharedLoader.log (excerpt):

Bingus Shared Loader loader-v18; API 1
Discovery: 8 declared entries
LuaJIT cache: expanded 16384 KB / 8000 traces; flushes 0, growth 0; watcher on
mods/cowboybingus/vanilla_plus_megapack: loaded
mods/cowboybingus/mod_options_menu: loaded
mods/hivelordhud/hive_lord_hud: loaded       ← our HUD
mods/hivelordhud/plate_fix: loaded           ← Dead Plate Fix
mods/cowboybingus/consistent_vaulting: not installed
…

Why there is one “shared” Loader

For any one resource, only one patch can win. If every mod overrode wwise_flow_callbacks on its own, only the last one would take effect and all the others would vanish. So the community uses one shared Loader to hold that entry point, and it loads all the mods in turn. Your mod does not need to override any vanilla resource. It just ships a Lua resource with a new name, and puts -- HD2-Addon: … on the first line so the Loader can find it.

The mod manager (Arsenal, HD2MM) writes each mod as one patch file in data/. Every time it deploys, it reassigns the patch numbers, so you cannot assume your mod always sits at a fixed number (you will run into this again in Chapter 14).

How a mod works with the Loader

Can it work without the Loader?

No. Our mod is just a lua resource called mods/hivelordhud/hive_lord_hud, and nothing in the game itself ever requires that name. Without the Loader, the resource gets deployed into the game folder but never runs: no error, and no effect at all.

• The only fallback in the code for “no Loader” is writing the log to %TEMP% instead. But that still assumes the mod was loaded, so in practice it never gets used.
• The settings menu disappears too: Mod Options Menu is itself a mod loaded by the Loader.
• In theory you could copy the Loader and replace a vanilla script yourself as an entry point. But only one patch can win per resource, so you would clash with the Loader and other mods, and you would have to maintain the vanilla script's features yourself — so we don't. That is the whole point of the Loader: all mods share one entry point instead of fighting over the same vanilla script.

So the install instructions list Bingus Shared Loader as a required dependency; Mod Options Menu (Megapack) is optional, and without it the HUD runs with default settings.

What a mod can do inside the game: the engine API

What the engine gives you

The engine opens part of its features to Lua; this is called the API. Mods use these groups the most:

• Application: the whole game. For example, Application.worlds() lists every current world (scene: the ship, a mission, and a menu are each one).
• World / Unit: World.units(world) lists every unit in a scene (a monster, a player, and a camera are all units). Unit.resource_name(u) tells you which model resource it uses (it returns a hash). Unit.node(u, 'head') finds the bone named head, and then you read its position.
• Camera: Camera.world_to_screen turns a 3D position into screen coordinates.
• Gui: draws rectangles, text and triangles on screen.

Note: the unit a script gets is only a handle (a ticket number), not the location of its data. You can use it to ask the engine questions, but you cannot go from it straight to the monster's HP data. And the engine does not offer any API like “read this monster's HP”. That fact decides the HUD's path from here on (Chapter 5).

Example: how the HUD finds the Hive Lord

• Every 2 seconds it scans World.units() for each world in Application.worlds() and compares Unit.resource_name. The release build returns a hashed IdString64, so it matches either the path string hive_lord or the hash d465d9c7f77a07cb (= murmur64 of content/fac_bugs/cha_hive_lord/cha_hive_lord).
• A newly appeared world is left alone until it has been stable for 10 seconds. main_world() changes about every 3 seconds, so you cannot rely on it.
• The HUD draws on “the stable world with the fewest units” (the UI world; the game world has thousands of units). Once a world disappears, its Gui disappears with it: just forget it, and never call destroy again.
• A unit value is a handle, not a pointer, so you cannot go from a unit straight to its component memory. HP has to be found another way (next section).
• After the Hive Lord dies, the HUD fades out over 2.5 seconds, and 1.5 seconds later it never touches that corpse again; it remembers the address and skips it in later scans. This avoids a situation that crashes the game (see “Pitfalls we hit”).

Drawing: the retained-mode Gui

The engine's Gui uses retained mode: Gui.rect(...) creates a rectangle and gives you an id; after that you use Gui.update_rect(id, ...) to change its position, size and colour; when you no longer need it, you destroy it. It does not clear the screen and redraw everything each frame.

• Each group fades in and out over 0.35–0.6 seconds, and is only destroyed once the fade-out finishes.
• A primitive is only sent to the Gui when its colour, size, position or text changes; nothing is sent on the frame it is created (text created and updated in the same frame never shows up in the game).
• Arguments must be real engine objects: Vector3(x, y, layer), Vector2(w, h), Color(a, r, g, b).
• Each facet of the low-poly panel is a real Gui.triangle. Its points must be written as Vector3(x, 0, y) (confirmed by disassembling helldivers2.exe: y and z are swapped). If creating a triangle fails, it automatically falls back to building it from 2 px rectangle strips.
• The font is core/performance_hud/debug, which is already in the base archive; bold is a copy of the same text drawn 1 px to the right.

Interactive demo: colour correction

The screen Gui is drawn before the game's exposure / tone mapping, so colours actually show about 3 times brighter and dark tones get crushed (sending a dark red of {96,2,18} shows up as 243,0,0 on screen; greys from 150–240 all turn pure white). Before sending, the HUD does the reverse conversion: sent value = wanted value ÷ gain + black; at 100% on the slider, gain = 3 and black = 18. The demo below simulates the measured boost model (shown ≈ 3 × (sent − 18)):

What happens when you get it wrong: two kinds of errors

• Lua-level errors (for example, adding to nil): these can be caught with pcall. So all of the mod's per-frame work is wrapped in pcall; on an error it switches itself off for good, and the game carries on.
• Errors inside the engine: every engine API has self-checks inside (assert). If an argument is wrong or the object no longer exists, it ends the whole game outright. pcall cannot catch this, because the error never gets back to Lua.

Because the second kind of error cannot be recovered from, the mod must make sure, before each call, that nothing will go wrong: is the world still there, is the unit still alive, are the arguments in the right format? Almost every one of these rules was learned after a crash (see below).

What the engine doesn't expose: LuaJIT FFI

What FFI is

LuaJIT has a feature that standard Lua does not: FFI (Foreign Function Interface). It lets Lua call functions written in C directly, including the Windows API, and it can also allocate, read and write a block of memory directly. The game's lua51.dll does not switch this feature off.

local ffi = require('ffi')
pcall(ffi.cdef, 'int QueryPerformanceCounter(int64_t* counter);')  -- tell FFI what the function looks like
local kernel32 = ffi.load('kernel32')                               -- load the dll that holds the function
local buf = ffi.new('int64_t[1]')                                   -- allocate a block of C memory
kernel32.QueryPerformanceCounter(buf)                               -- call the Windows API
print(tonumber(buf[0]))                                             -- value of the high-resolution timer

With FFI, what a mod can do suddenly becomes “whatever a normal Windows program can do”:

• For example, it can call the Windows thread API to choose which CPU core each game thread runs on.
• The HUD uses it to call ReadProcessMemory and read the game process's own memory.

Why FFI is also dangerous

• No safety net: get a function declaration wrong, pass a wrong argument, or read an address you shouldn't, and the game crashes on the spot. pcall can't catch it (Chapter 6 explains why).
• All mods share one Lua environment: declaring the same thing twice with ffi.cdef throws an error, so every declaration is wrapped in pcall. Keep the object you get from ffi.load alive, or the dll may be unloaded and its functions stop working.
• Same power as a normal program: a malicious Lua mod can also read your files and go online. That is why Chapter 16 says “only install mods you trust”.

Memory: where data lives

What a number looks like in memory

Memory is one long row of cells. Each cell is 1 byte (0–255), and each cell has a number called its address. Addresses and contents are usually written in hexadecimal (starting with 0x, each digit 0–9, A–F). An integer like HP is usually stored in 4 bytes, called an int32, and the “low byte comes first”, so 150,000 = 0x000249F0 sits in memory as F0 49 02 00:

Every process has its own set of addresses

The addresses a program sees are not the real locations on your RAM sticks. Windows gives every process its own virtual memory, managed in 4 KB pages, which are mapped to physical RAM (or parked on the SSD for a while).

This has three results that matter a lot for mods:

1. Outside programs can't touch the game's memory: the same address means different RAM in two processes. To read the game, an outside program must first ask Windows for a handle to the game (OpenProcess), then ask Windows to read on its behalf. Anti-cheat blocks exactly this step (Chapter 16). But a mod runs inside the game process and uses the game's own addresses, so it never goes through this step.
2. Reading the wrong address crashes the game: if an address isn't mapped to any page, or the page doesn't allow reading, the CPU raises an access violation and the program ends immediately. This is why Chapter 5 says FFI has “no safety net”.
3. Code can't be changed directly: pages that hold code are marked “readable, executable, not writable”. To change them, you first have to call VirtualProtect to change the permissions.

Three kinds of region inside a process

• Code section: the dll's machine code. It doesn't change while running.
• Data section: variables at fixed locations inside the dll (global variables). They stay in the same place for the whole session.
• Heap: data the game allocates while running, such as each enemy's HP. Its location differs every match, and the game may even move it.

Two more things make “finding the HP” harder:

• ASLR: every launch, Windows puts the dll at a different address (to stop attacks). So you can't remember an absolute address like “HP is at 0x7FFF…”. You can only remember “byte number N counted from the start of the dll”, called the RVA. Real address = this launch's base address + RVA.
• Pointers: data on the heap has no fixed location, but a global variable in the data section holds its address. A “value that holds an address” is called a pointer. Start from a fixed global variable, follow the pointers step by step, and you reach data whose location changes every match.

The shape of game data: structs, systems, hash tables

Structs and offsets

C++ uses a struct to keep related data together. After compiling, the names are gone; all that's left is “this field starts at byte N from the beginning”, called the offset. Many structs of the same kind are laid out one after another as an array. The size of each one is the stride, and record n sits at “start + n × stride”.

struct HealthRecord {        // one enemy's HP record
    // ...
    int32_t main_hp;         // main HP
    // ...
    int32_t armor[39];       // armour per zone
    int32_t zone_hp[38];     // HP per zone
    int32_t end_marker;      // 0xFFFF
};

HealthRecord* records;       // many records back to back
records[6].main_hp -= 500;   // enemy #6 loses 500 HP

// each record is 0x1B8 = 440 bytes, one after another
// record n is at: records + n × 0x1B8

+0x014  main HP       (4 bytes)
+0x05C  armour × 39   (4 bytes each)
+0x0F8  zone HP × 38  (4 bytes each)
+0x190  0xFFFF marker

// so "main HP of enemy #6" =
//   records + 6 × 0x1B8 + 0x14
// this is exactly the formula our mod reads with

Click the blocks below to see what each part of the Hive Lord's HP record (440 bytes) is:

How the game manages enemies: ECS

HD2 uses an architecture called ECS: everything in the level is just an entity ID (e.g. one Hive Lord is 0x22A). Data is attached to that ID in bundles called components (HP component, model component…). Each kind of component is managed in one place by a system. The health system keeps every enemy's HP record in one big array.

To get from an “entity ID” to “record number N in the array”, the health system uses a hash table: a fixed-size table where each slot holds {entity ID, record number}. The ID gives a starting slot; if that slot matches, read it, and if not, check the next slot.

Design values and runtime values

“Hive Lord max HP 150,000, each plate 15,000, armour 5” are design values. They are written in the game data tables under data/, and you can read them without the game running (Chapter 8). “This Hive Lord has 118,350 left right now” is a runtime value, and it exists only in that record in memory.

This split is very useful: design values can become a fingerprint. For example, the Hive Lord's 39 armour values (default zone 5, then 6, 10, 5, 5…) never change during a fight, and the combination is very unusual. So if you see a record in memory whose armour fields are exactly these 39 numbers, you can be almost certain it's the Hive Lord's record.

Reading game files offline: FileDiver

FileDiver is an open-source unpacking tool written by the community. It builds on Chapter 1 and Chapter 7: archives are binary files with a fixed format, names are hashes, and design values are arrays of structs.

How FileDiver works

How the game stores its resources

• The data/ folder holds a pile of archives named with 16 hex digits. Each archive is split into three files: the main file, .stream (streamed data, e.g. audio) and .gpu_resources (textures, model vertices).
• Main file format: header (magic number 0xF0000011, type count, file count) → type table → file table (each file's name hash, type hash, and its offset and size in each of the three files) → data. The patch files we build for our own mods use exactly the same format.
• File names are stored only as a murmur64 hash, not as strings. FileDiver ships a list of about 250,000 known names (hashes/) to turn hashes back into readable paths; anything not in the list can only be shown as a hash. We recovered the Hive Lord's zone names ourselves by brute-forcing the 32-bit hashes (the upper 32 bits of murmur64).
• When FileDiver opens data/, it reads the tables of every archive and builds a “(name, type) → location” index. Later patches override earlier files with the same name, just like the game does.

What it can export

Models (glTF / glb, two common 3D file formats, with skeleton and animations), textures (png), Wwise audio (ogg / wav), text tables (JSON), animation state machines, prefabs (pre-assembled groups of objects) and more. The ones we used:

• Hive Lord model: filediver.exe -g <game folder> -i content/fac_bugs/cha_hive_lord/cha_hive_lord.unit --model-format glb. From the names and positions of the bones and collision nodes, we confirmed that spine0 is at the tail end, which bone each plate belongs to, and that the plate above the tail doesn't belong to any zone.
• Animation state machine (sm-state-dumper): the state names of the locomotion and action layers used by the emerge warning.

Game data tables (datalib)

• Gameplay values (each enemy's components: health, armour, weapons, explosions…) live in datalib binary blobs (generated_entities.dl_bin and others). A separate type library, dl_library.dl_typelib, describes each struct's field names, types, offsets and sizes. FileDiver's source code includes these blobs and matching Go structs.
• Pitfall: FileDiver's hand-written Go structs go stale as the game updates. HealthComponent is actually 22,096 bytes with 51 fields; reading it with the old struct gives garbage. So we switched to reading the current field offsets straight from the type library. Another pitfall: the header in front of each blob (the DLInstance header) is 28 bytes, not 24. Get those 4 bytes wrong and everything after is misaligned.

Tools we added

The source is in tools/filediver-src (local changes, not contributed back to the original project):

Observing in-game: Recon

The star of this chapter, Recon, is a research mod we wrote for building the HUD and never released. The point is not the tool itself but its principle: anyone can write their own recon mod the same way.

The idea behind Recon is simple: make the observation tool itself a mod. Like the HUD, it is loaded by the Loader and runs inside the game process (Chapter 3), and it uses FFI to read its own process's memory (Chapters 5 and 6) — so it never hits the anti-cheat check that blocks outside access.

How Recon works

GameGuard blocks external debuggers and memory readers, so you can't look at the game directly with tools like Cheat Engine or x64dbg. Recon's approach is to make the “recon” itself a mod: it runs inside the game, reads its own process's memory with LuaJIT FFI, and writes the results to a log.

The usage loop

1. Write the commands for this round into %TEMP%\HD2Recon_cmd.lua (plain Lua, e.g. R.scan('48 8B ?? 20')).
2. Start the game. Once the Loader loads Recon, it first writes the base address, size and sections of game.dll and helldivers2.exe to the log (R.about).
3. It then reads the command file, compiles it with loadstring, gives it an environment that can call R.* via setfenv, and runs it inside pcall. An error only writes one run error line and doesn't affect the game.
4. Close the game, read the log, and decide what to check next. Every time you restart the game, the command file runs again.

Main functions

For safety, before every read it uses VirtualQuery to confirm the memory is allocated, readable and not a guard page. It never calls VirtualProtect and never modifies code.

Its role in this project: the first 69 versions of the HUD shipped bundled with Recon (sharing its log and tick); only at v70 did it become the standalone Hive Lord HUD. Recon made the first dump of the HP record and the unpacked dump of game.dll; the locations of the health system and the visibility-mask system were then found by static analysis of that unpacked dump.

Reading machine code: reverse engineering and assembly language

Reverse engineering means working out what a program does from its behaviour and machine code, without the source code. This guide uses two approaches:

• Signature (AOB, array of bytes): a byte pattern that can contain wildcards, e.g. 48 8B ?? 20, used to find specific code in memory.
• Fingerprint: a set of values that never change and are unique enough to confirm “what I found really is what I want”. For example, the armour values of the Hive Lord's 39 zones, which never change during a fight.

Why dump: packing

game.dll is packed with Themida: the file on disk is encrypted and only decrypted in memory when loaded. So disassembling the game.dll on disk just gives you garbage. You have to use Recon's dump_module to save the whole game.dll as already decrypted in memory (about 71 MiB), then analyse that.

Assembly language basics

A disassembler (capstone, Ghidra) turns machine code into assembly language: one very small action per line. For example, this one line of C++:

hp = std::min(hp, -1);   // HP at most -1

mov   eax, [r9+rdx*4+0xf8]  ; read hp from memory
mov   ecx, 0xffffffff       ; ecx = -1
cmp   eax, ecx              ; compare
cmovl ecx, eax              ; keep the smaller one in ecx
mov   [r9+rdx*4+0xf8], ecx  ; write back to memory

• Registers: rax, rcx, r9… are little slots built into the CPU; data has to be moved into them before any calculation.
• Square brackets [ … ] = read or write memory at this address. [r9+rdx*4+0xf8] = “record start + zone number × 4 + 0xF8”, which is exactly the offset from Chapter 7.
• Global variables: mov rdi, [rip + 0x2aa2ec6] = read the value stored at “address of the next instruction + 0x2aa2ec6”. Work out that offset and you get the global variable's RVA.
• Function arguments: the first 4 go in rcx, rdx, r8, r9; call calls a function; cmp + je/jne compare and jump (that's an if).

How the fixed starting point was found

Four steps

1. First, learn from the game data which values to look for. FileDiver extracted the Hive Lord's HealthComponent: main HP 150,000, 15,000 per plate, and 39 fixed armour values (5, 6, 10, 5…). This set of numbers is the fingerprint that identifies it in memory.
2. Search in-game to find the record. Units are handles, so you can't follow pointers to the component. Early versions (v7–v10) therefore scanned the whole heap in time slices looking for this set of numbers. Once found, we dumped the bytes around it and compared which values changed during a fight to work out the record layout: main HP +0x14, armour +0x5C, 38 zone HPs +0xF8, end marker 0xFFFF, 0x1B8 bytes per record.
3. Work backwards from the code to the global variable that manages these records.
   • Use the Recon addon to dump the whole game.dll as already unpacked in memory (the file on disk is encrypted by Themida).
   • Scan all the code with Python + capstone for instructions that use these offsets (the 0x1B8 stride, +0xF8, +0x14), finding the damage function 0x9235F0 and other health-related functions.
   • All of these functions load the system pointer from the same place, [rip + X], which works out to game.dll + 0x3326688. Then reading how the functions look up the table gives the offsets of the key table, the capacity and the record array.
   • The visibility-mask system +0x3326708 was found the same way: from the gore function 0x903C70 we traced to the mask-setting function 0x721D20, which also loads its system pointer from a global variable. The entry layout (applied / override / touched / base) was worked out by reading the code of the setter and the update function 0x721680.
4. Use it and verify. The program stores relative offsets (RVAs) and computes the real address at run time with GetModuleHandleA('game.dll') + RVA. Every read re-checks the fingerprint and skips on a mismatch. In-game logs confirmed both are correct: v83 found the record on the first try, and after Plate Fix v3 wrote to it the plate was hidden within 0.1 seconds.

The matching code (hive_lord_plate_fix.lua, excerpt):

local HEALTH_RVA, VIS_RVA = 0x3326688, 0x3326708

local function table_header(base_rva, keys_off, cap_off)
    local base = M.game_base()                -- GetModuleHandleA('game.dll')
    if not base then return nil end
    local S = ptr(base + base_rva)            -- system pointer stored in the global variable
    if not S then return nil end
    local keys, cap = ptr(S + keys_off), u32(S + cap_off)
    if not keys or not cap or cap == 0 or cap > 0x40000 then return nil end
    return S, keys, cap
end

-- ptr / u32 both go through ReadProcessMemory: a bad address just returns nil, no crash

Real assembly: how the game looks up health

This is real code from game.dll that looks up the health system before calling the damage function, along with the C++ reconstructed from it (the names are ours). Read it alongside the hash-table explanation in Chapter 7:

Before calling the damage function 0x9235F0, this code uses the entity number to find the record's index in the health system's hash table. 587 places in the code use the same global variable; this is one of them.

008837BB  mov  rdi, [rip+0x2aa2ec6]   ; rdi = *(game.dll+0x3326688): health system
008837C2  mov  ecx, r14d              ; i = 0
008837C5  mov  r9d, [rdi+0x1038]      ; capacity (power of 2)
008837CC  mov  r10d, [rdi+0x1040]     ; hash multiplier
008837D3  imul r10d, edx              ; h = multiplier × entity (edx)
008837D7  lea  r15d, [r9-1]           ; mask = capacity - 1
008837E0  mov  r11, [rdi+0x1030]      ; key table: {entity, index} × capacity
008837E7  mov  ebp, [rdi+0x103c]      ; key value meaning “empty slot”
008837F0  mov  eax, r15d
008837F3  lea  r8d, [rcx+r10]
008837F7  and  r8, rax                ; slot = (i + h) & mask
008837FA  mov  eax, [r11+r8*8]        ; key = keys[slot].entity
008837FE  cmp  eax, ebp
00883800  je   0x883860               ; empty slot: no such entity
00883802  cmp  eax, edx
00883804  je   0x883864               ; found: index is at [r11+r8*8+4]
00883806  inc  ecx                    ; next slot (linear probing)
00883808  cmp  ecx, r9d
0088380B  jb   0x8837f0
   ...
0088387C  mov  rcx, rdi               ; 1st argument = health system
   ...
00883913  call 0x9235f0               ; damage function

// game.dll+0x3326688
extern HealthSystem* g_health_system;

struct KeyValue { uint32_t entity, index; };

struct HealthSystem {
    // ...
    /* +0x1030 */ KeyValue*     keys;
    /* +0x1038 */ uint32_t      capacity;
    /* +0x103C */ uint32_t      empty_key;
    /* +0x1040 */ uint32_t      multiplier;
    // ...
    /* +0x1058 */ HealthRecord* records;  // 0x1B8 bytes each
};

uint32_t find_index(HealthSystem* hs, uint32_t entity) {
    uint32_t mask = hs->capacity - 1;
    uint32_t h    = hs->multiplier * entity;
    for (uint32_t i = 0; i < hs->capacity; ++i) {
        KeyValue& kv = hs->keys[(i + h) & mask];
        if (kv.entity == hs->empty_key) break;   // not present
        if (kv.entity == entity) return kv.index;
    }
    return NOT_FOUND;
}

// the damage function receives records[index]
apply_damage(g_health_system, entity, /* ... */);

Our Lua uses the same table (HS_KEYS = 0x1030, HS_CAP = 0x1038, HS_RECS = 0x1058), but instead of computing the hash, it reads through the whole key table looking for the entity. It's a bit slower, but it doesn't need to know the details of the hash function, so it won't break if the game changes how it hashes.

Reading safely and correctly

Direct reads vs ReadProcessMemory

If you use FFI to turn an address into a pointer and read it directly, a bad address means an access violation and the game crashes (Chapter 6). Recon first asks VirtualQuery “is this range readable?” and then reads. But there is a tiny gap between the “ask” and the “read”, and another game thread might free that memory right in that gap.

ReadProcessMemory has no such gap: if it can't read, it returns a failure instead of crashing. So the HUD and Plate Fix, which players use, always use it to read their own process; Recon is a development tool, so it accepts the small risk of direct reads. The HUD's offline tests actually caught this once: while reading the heap directly, memory was freed between the check and the read, and the test program crashed.

“Freed” does not mean “gone”: stale copies

When a C++ program gives back a block of memory, or an array grows and moves to a new place, the old block is usually just handed back to the program's own allocator. The contents are still there, and still readable — the game just stops updating them. If a mod finds data by “searching memory”, it may find one of these stale copies: the fingerprint is completely correct, but the values are frozen.

Validate every read

• On every read of a record, re-check the fingerprint (39 armour values + the 0xFFFF marker) and the value ranges (each zone's HP can't exceed its maximum). If anything doesn't match, treat it as not found and don't use that data.
• The game moves things around: every frame, re-read the array location from the global variable, and once a second, look up the record index again by entity ID.
• Have a fallback when nothing is found: if the global variable can't be read (for example, its location changed after a game update), fall back to the slower heap search and write the reason to the log.

Time budget

Searching the heap means reading several GB of memory; doing it all at once would freeze that frame for several seconds. So you split it into small pieces and do a little each frame. The HUD first spent 8 ms per frame, which cut FPS in half at 130 FPS; later it was lowered to 4 ms. After switching to going straight through the global variable, the normal per-frame cost dropped to a fraction of a millisecond.

The skeleton of a mod

The header of the Hive Lord HUD source code lists its sections, and they line up exactly with the principles from the earlier chapters, in order:

Rules every mod should follow

1. Singleton guard: at the start, check a unique global variable; if it already exists, don't run again.
2. Environment check: if a required API or the Loader is missing, write to the log and stop, instead of forcing it to run.
3. Wrap update, and disarm on error: wrap the per-frame work in pcall; on the first error, permanently shut yourself off, clear the screen, and write down the reason.
4. Always call the original update.
5. Check before you call: the world still exists, the unit is still alive (engine errors can't be recovered from).
6. Time budget and self-timing: measure how much time each frame takes and write it to the log regularly.
7. Rate-limit the log: only write state changes, not one line per frame.

Working with other mods: the settings menu

Mod Options Menu is also a mod loaded through the Loader. It puts a global ModOptionsMenu table in place; other mods can call register_option to register settings and use get to read values. Because the load order between mods is not guaranteed — so the HUD doesn't look for it at load time; it looks for it inside update, and only registers once it finds it. If it isn't installed, the HUD uses the values from its config file.

Pretending to be the game on your PC: offline testing

The principle: a mod only interacts with the game through three channels — the engine API, FFI memory reads, and the Loader. If you replace all three with fakes, the mod can't tell whether it's inside the game or not.

• The same Lua: use lupa's LuaJIT build to run the real mod source. With a newer Lua, syntax the game doesn't support, such as //, passes the tests and only fails to load once you're in the game.
• A fake engine: write your own World, Unit, Gui, Camera that record what the mod called. You can make them deliberately copy the game's bad habits, such as “crash if called on a dead unit”, to confirm the mod never does that.
• Fake memory: put a fake health system, hash table and HP records into real memory, and let the mod find them along the real path. Then add a few decoys that “look right but aren't”, to confirm the validation rejects them.
• Mutation testing: deliberately break the code (for example, remove the fingerprint check); the tests must fail. If they can't catch a bug you planted on purpose, the tests aren't really checking anything.
• You can see the screen offline too: record the Gui.rect and Gui.text calls the mod makes, draw them as an image with Python, and you can check the layout before going in-game. The Hive Lord HUD's showcase images and mod icon were made this way.

Packing and deploying: turning code into a patch file

What a patch file looks like

The packing tool simply writes the archive format from Chapter 1 in reverse: a header, a type table (only one type: lua), a file table (name hash, position, size), and finally the data. The data itself is “length + 2 (meaning plain text) + source code”, aligned to 16 bytes. Type a resource name and some code below to see the actual bytes (same algorithm as our packing tool):

The zip and the manifest

What the mod manager imports is a zip: manifest.json (name, description, options), one folder per option (holding a patch file), and Source/ (plain source code, so people can review it). A few key points:

• The GUID never changes: the manager uses it to recognise “this is a new version of the same mod”. Hive Lord HUD's GUID has been 4ef072f2-… from v1 to v3.
• Name uses only English letters, digits and spaces: it becomes a folder name, and a single colon makes the import fail.
• Options = separate patch files: Hive Lord HUD has two options, “Hive Lord HUD” and “Dead Plate Fix”. Each is its own patch file, so players can install just one of them.

Deploying: the manager renumbers slots

Arsenal reassigns patch numbers on every deploy, and each option takes its own slot. During development we copy the new patch file straight into data/ to save time — so you must not hard-code the number. Use the file contents (look for your own -- HD2-Addon: line) to confirm which slot is yours, and also update the copy Arsenal keeps for itself, or the next Deploy will put the old version back. You also can't deploy while the game is running: Lua is only loaded at startup.

Multiplayer and game updates: the boundaries of a mod

A client doesn't always see the whole picture

In a multiplayer game, the host decides many things (enemy AI, whether a zone gets broken), and clients only receive the results. In HD2, each machine simulates the bullets and damage it can see, and the host only sends results like “state changed” or “died”. So the numbers in a client's memory can differ from the host's, and a mod can only read its own machine.

The author always joins other people's games as a client, so the HUD has to be honest about one thing: zone HP on a client isn't necessarily true. From 30+ game logs and analysis of the network code in game.dll:

Telling who caused a state change (H.state_diag): if HP lands exactly on -1 or -constitution in the same frame and main HP didn't drop → host event; if HP was pushed past the threshold by damage and main HP dropped at the same time → local hit. In the log of one client-side fight, all 14 state changes came from the host, and our HP was behind every time and never ahead — so “<” means an upper bound, not an estimate.

This also decides what a client mod can't do: for example “keep the Hive Lord from running too far”. The AI runs on the host, and a client's mod can't change it.

Game updates change every address

When the game updates, game.dll is recompiled: the locations of functions and global variables (RVAs), struct offsets, and table sizes can all change. Every address in this document is valid only for build 25480438. So a mod should be designed to “stop safely when things don't match”:

• Verify the fingerprint on every read; if it's wrong, don't use it (Chapter 11).
• Have a fallback when the main path fails (the HUD falls back to a heap search; Plate Fix simply stops acting).
• Write clearly in the log “why it stopped”, so when players report it you know the update caused it.
• The Loader itself is also tied to the game version; after a big update, wait for the Loader to update first.

Anti-cheat: the space a mod operates in

What GameGuard does

GameGuard (nProtect) is Helldivers 2's anti-cheat. It consists of a kernel driver and a monitoring process (GameMon) that starts with the game. Its internals aren't public; what follows is pieced together from its behaviour and what we actually ran into:

Separately, game.dll itself is packed with Themida. That's a different layer of protection, not part of GameGuard. The game.dll on disk is encrypted; it only becomes unpacked code once it's loaded into memory.

• Packing (Themida): encrypts the code and only decrypts it in memory at run time. So the game.dll on disk is unreadable; you have to dump it from the running process's memory to analyse it.
• Zombie process: after the game crashes, the process is still protected by the anti-cheat, Task Manager can't end it, and only a reboot helps. We ran into this several times during development.
• Code-hash check: regularly hashes the code sections (subsection 3); if even 1 byte is changed, the hash won't match. This is also why the mods never modify code.

Why Plate Fix reads and writes memory, yet GameGuard doesn't care

Because GameGuard mainly guards against “outside programs touching the game”, while Plate Fix is the game touching its own memory. From the operating system's point of view, these are two completely different things.

Why the data and Lua we add don't get caught

In one sentence: anti-cheat like GameGuard looks for foreign code and foreign access (injected DLLs, handles opened by outside programs, modified code, known cheat programs). What a mod adds is data, which is then read and run by code the game already has. From the anti-cheat's point of view, it can't be told apart from the game running normally. Layer by layer:

Compare that with how real cheats usually work: a separate exe opens the game's handle (intercepted by the driver), injects a DLL into the game (an unknown module shows up), or modifies code for infinite bullets (the code hash no longer matches). Mods do none of these three things.

This also explains why GameGuard can block an outside Cheat Engine but not Recon: Recon reads memory the same way Plate Fix does. So the line isn't technical — it's about what you do: our mods only read data and only change things on your own screen. They don't affect damage, collision or networking, and they don't touch other players.

Development history

It started with one sentence: “It should be possible to make a Hive Lord health bar that shows main HP and the HP of every armour plate.” Then came 5 days, 121 internal builds and 3 public releases. The author tested every build in the real game, and the logs were the telemetry.

Development method and toolchain

The principle is “offline first”: anything that can be computed and tested on the PC never needs the author to go into the game. Game time is only used to answer questions that can't be answered offline.

Tried and dropped

Pitfalls we hit

What's in the download

The build and deploy scripts, offline tests, research notes and the development-only diagnostics mod used during development are not published. This document mentions them to explain the principles behind them.

Installation

1. Enable Bingus Shared Loader in Arsenal (optional: the Mod Options Menu from Vanilla Plus Megapack).
2. Import HiveLordHUDv3.zip, tick Hive Lord HUD, Dead Plate Fix or both under Options, then Deploy.
3. The log is at %LOCALAPPDATA%\CowboyBingus\Helldivers2\Logs\HiveLordHud_*.log; lines starting with [PlateFix] are fix records.

Package format (brief)

HiveLordHUDv3.zip
├─ manifest.json        GUID 4ef072f2-… (fixed; Arsenal uses it to recognise updates of the same mod)
├─ icon.png
├─ options/core/9ba626afa44a3aa3.patch_0       ← the HUD's lua resource
├─ options/platefix/9ba626afa44a3aa3.patch_0   ← Plate Fix's lua resource
└─ Source/…                                    ← plain-text source code

Each patch = a Stingray archive: header + type table (lua) + file table, resource names are murmur64 hashes,
data section aligned to 16 bytes; lua resource = (length, 2 = plain-text source) + source, first line must be -- HD2-Addon: <resource name>

Mini glossary

Document date 2026-10-07. All addresses match game build 25480438; assembly is taken from the Oct 2 unpacked dump.