Helldivers 2 模組是怎麼運作的

function H.install()
    if H.armed then return true end
    local original = rawget(_G, 'update')
    if type(original) ~= 'function' then
        writer('install refused: no global update()')
        return false
    end
    if not (Gui and Vector2 and Vector3 and Color and World and Unit and App) then
        writer('install refused: missing engine API')
        return false
    end
    H.text_ok = attempt(App.can_get, 'font', H.FONT) == true and attempt(App.can_get, 'material', H.FONT) == true
    H.armed = true
    -- Self-timing: how much frame time the HUD costs (QueryPerformanceCounter around H.update).
    pcall(ffi.cdef, 'int QueryPerformanceCounter(int64_t* c); int QueryPerformanceFrequency(int64_t* f);')
    local qpc, qbuf = nil, ffi.new('int64_t[1]')
    pcall(function()
        local k = ffi.load('kernel32')
        k.QueryPerformanceFrequency(qbuf)
        local freq = tonumber(qbuf[0])
        if freq and freq > 0 then
            qpc = function() k.QueryPerformanceCounter(qbuf); return tonumber(qbuf[0]) * 1000 / freq end
        end
    end)
    H.cost = {sum = 0, max = 0, n = 0, scan_sum = 0, scan_n = 0}
    rawset(_G, 'update', function(...)
        if H.armed then
            local on = H.option_enabled()
            if on ~= H.enabled then
                H.enabled = on
-- …（共 56 行，完整內容見原始碼頁）

function M.install()
    if M.armed then return true end
    local original = rawget(_G, 'update')
    if type(original) ~= 'function' then writer('install refused: no global update()'); return false end
    M.armed = true
    rawset(_G, 'update', function(...)
        if M.armed then
            if M.hello then writer(M.hello); M.hello = nil end
            local ok, why = pcall(function() M.poll_option(); M.update() end)
            if not ok then
                M.armed = false
                writer('disarmed after fault: ' .. tostring(why))
            end
        end
        return original(...)
    end)
    return true
end

-- HD2-Addon: mods/hivelordhud/hive_lord_hud

local function open_own_log()
    if own_log ~= nil then return own_log end
    own_log = false
    local name = 'HiveLordHud_' .. ((os and os.date and os.date('%Y%m%d_%H%M%S')) or 'session') .. '.log'
    local loader = rawget(_G, 'CowboyBingusModLoader')
    local ok, f = pcall(function() return loader and loader.open_log and loader.open_log(name) end)
    if not (ok and f) then
        local temp = os and os.getenv and os.getenv('TEMP')
        f = temp and io.open(temp .. '\\' .. name, 'w')
    end
    if f then own_log, H.log = f, name end
    return own_log
end

-- HD2-Addon: mods/hivelordhud/plate_fix

-- Lifecycle (same as HUD+, which is known to be stable):
--   * runs inside a wrapper around the engine's global `update` (main thread, once per frame) and disarms itself
--     permanently on the first Lua fault
--   * every engine call is gated on the world being live
--   * Gui is retained-mode: Gui.rect once -> id, then Gui.update_rect(id); World.destroy_gui on teardown
--   * vectors / colours are real engine objects: Vector3(x, y, layer), Vector2(w, h), Color(a, r, g, b)

local function world_is_live(world)
    if world == nil or not App then return false end
    local worlds = attempt(App.worlds)
    if type(worlds) ~= 'table' then return false end
    for i = 1, #worlds do
        if worlds[i] == world then return true end
    end
    return false
end

function H.find_hive_lord(worlds, t)
    if not World or type(World.units) ~= 'function' then return nil end
    if H.dead_addr and t - (H.dead_addr_t or t) > 300 then H.dead_addr = nil end
    local total = 0
    for _, rec in ipairs(settled_worlds(worlds, t)) do
        local units = attempt(World.units, rec.w)
        if type(units) == 'table' then
            rec.n = #units
            total = total + #units
            if not rec.logged then describe_world(rec, units) end
            local hl, hl_name, divers, cams = nil, nil, {}, {}
            for i = 1, #units do
                local u = units[i]
                -- The game crashed twice ~60 s after a Hive Lord died, while we kept polling its corpse as it was
                -- despawned (logs 222058 / 233615). Once dead it is never touched again, not even Unit.alive.
                if H.dead_addr and handle_addr(u) == H.dead_addr then
                    -- skip
                elseif attempt(Unit.alive, u) then
                    local name = attempt(Unit.resource_name, u)
                    if name ~= nil then
                        local s = tostring(name):lower()
                        if not hl and is_hive_lord(s) then hl, hl_name = u, tostring(name)
                        elseif s:find(AVATAR_HEX, 1, true) then divers[#divers + 1] = u
                        elseif s:find(CAMERA_HEX, 1, true) then cams[#cams + 1] = u end
                    end
                end
            end
            if hl then
                H.live.units_seen, H.live.divers, H.live.cams = total, divers, cams
                return hl, rec.w, hl_name
-- …（共 36 行，完整內容見原始碼頁）

-- Root node world position. Index 0 is the root (scene node indices are 0-based); guarded by node count.
-- Vector3 fields are unreliable here, so parse tostring 'Vector3(x, y, z)'.
-- Node 0 is a static root that reads (0,0,0) for the Hive Lord and every avatar, so named bones are used instead,
-- resolved once per unit (Unit.has_node first: Unit.node asserts on unknown names).
local BODY_NODES = {'root', 'j_root', 'hips', 'j_hips', 'pelvis', 'j_pelvis', 'spine', 'j_spine', 'head', 'j_head'}
local node_cache = setmetatable({}, {__mode = 'k'})

local function new_group(name)
    local g = {name = name, a = 0, prims = {}, born = H.frame}
    H.grp[name] = g
    return g
end

-- Rect prim: c = {a, r, g, b}; w may change later (bars).
local function add_rect(g, x, y, w, h, c, layer)
    local p = {kind = 'rect', x = x, y = y, w = w, h = h, c = c, layer = layer or LAYER}
    p.id = Gui.rect(H.ui.gui, Vector3(x, y, p.layer), Vector2(w, h), Color(0, c[2], c[3], c[4]))
    g.prims[#g.prims + 1] = p
    return p
end

-- Text prim, created with its real initial string (updates in the creation frame are dropped by the engine).
-- align: 'l' (x = left), 'r' (x = right edge), 'c' (x = centre).
local function text_pos(p)
    if p.align == 'l' then return p.x end
    local w = text_width(p.str, p.size)
    if p.align == 'r' then return p.x - w end
    return p.x - w / 2
end

-- Bold: the debug font has no bold face, so a text is drawn bold_px(size) + 1 times, each copy 1 px further right (a
-- solid thicker stroke; a single copy shifted by several px reads as a double image). Every copy sits on whole pixels
-- at a whole-pixel size: at fractional positions each copy is resampled on its own and the stack smears.
local function bold_px(size) return math.max(1, math.floor(size / 16 + 0.5)) end
local function px(v) return math.floor(v + 0.5) end
H.bold_px = bold_px

-- …（共 42 行，完整內容見原始碼頁）

local function destroy_group(name)
    local g = H.grp[name]
    if not g then return end
    if H.ui.gui then
        for _, p in ipairs(g.prims) do
            if p.kind == 'rect' then pcall(Gui.destroy_rect, H.ui.gui, p.id)
            elseif p.kind == 'tri' then tri_free(p)
            else
                pcall(Gui.destroy_text, H.ui.gui, p.id)
                for _, id in ipairs(p.copies or {}) do pcall(Gui.destroy_text, H.ui.gui, id) end
            end
        end
    end
    H.grp[name] = nil
end

-- Colour correction. The screen gui is drawn before the game's exposure / tone mapping, so a colour comes out roughly
-- 3x brighter with the darks crushed (a {96,2,18} strip showed as 243,0,0; greys of 150-240 as pure white). Colours
-- are authored as they should look and mapped back here: sent = shown / gain + black. 'Colour correction' slider:
-- 100 = gain 3, black 18; 0 = off; 150 = stronger.
function H.color_out(v)
    local f = (tonumber(H.cfg and H.cfg.color_fix) or 100) / 100
    if f <= 0 then return math.floor(v + 0.5) end
    local gain, black = 1 + 2 * f, 18 * f
    return math.floor(math.min(255, v / gain + black) + 0.5)
end
local color_out = H.color_out

local function draw(p, ga)
    local a = math.floor(p.c[1] * ga + 0.5)
    local k = ga < 1 and (0.15 + 0.85 * ga) or 1
    local r, gg, b = color_out(p.c[2] * k), color_out(p.c[3] * k), color_out(p.c[4] * k)
    if p.kind == 'rect' then
        local w = ga < 0.04 and 0 or p.w
        local key = a * 16777216 + r * 65536 + gg * 256 + b + math.floor(w * 4) * 4294967296
        local pk = math.floor(p.x) * 65536 + math.floor(p.y)
        if key == p.key and pk == p.pk and p.h == p.lh then return end
        p.key, p.pk, p.lh = key, pk, p.h
        Gui.update_rect(H.ui.gui, p.id, Vector3(p.x, p.y, p.layer or LAYER), Vector2(w, p.h), Color(a, r, gg, b))
    elseif p.kind == 'tri' then
        local key = a * 16777216 + r * 65536 + gg * 256 + b
        if key == p.key then return end
        p.key = key
        tri_free(p)
        tri_make(p, a, r, gg, b)
        if H.tri_error and (p.fi or p.tick) then     -- a facet / bar stripe failed to re-create: rects from now on
            H.poly_tri_off, H.tri_error, H.poly_rebuild = H.tri_error, nil, true
        end
    else
        local str = ga < 0.04 and ' ' or p.str
        local key = string.format('%d,%d,%d,%d|%d,%d|%s', a, r, gg, b, math.floor(p.x), math.floor(p.y), str)
        if key == p.key then return end
        p.key = key
        local tx, ty, col = px(text_pos(p)), px(p.y), Color(a, r, gg, b)
        Gui.update_text(H.ui.gui, p.id, str, H.font, p.size, H.font_mat, Vector3(tx, ty, p.layer), col)
        for k, id in ipairs(p.copies or {}) do
            Gui.update_text(H.ui.gui, id, str, H.font, p.size, H.font_mat, Vector3(tx + k, ty, p.layer), col)
        end
-- …（共 32 行，完整內容見原始碼頁）

function H.project(wx, wy, wz)
    local Camera, Quat = api('Camera'), api('Quaternion')
    if not Camera or type(Camera.world_to_screen) ~= 'function' then return nil end
    local pc = frame_camera(Camera, Quat)
    local c = pc.c
    if c == nil then return nil end
    if not H.tag_called then
        H.tag_called = true
        writer('tag: calling Camera.world_to_screen for the first time (if the game crashes now, this API is bad)')
    end
    local ok, v = pcall(Camera.world_to_screen, c, Vector3(wx, wy, wz))
    if not ok or v == nil then
        if not H.tag_err then H.tag_err = true; writer('tag: Camera.world_to_screen failed: ' .. tostring(v)) end
        return nil
    end
    local sx, sy, sz = parse3(v)
    if not (sx and sy) then return nil end
    local behind = false
    if pc.fx and pc.px then
        behind = (wx - pc.px) * pc.fx + (wy - pc.py) * pc.fy + (wz - pc.pz) * pc.fz < 0
    end
    if H.tag_scale == nil then
        local rw = type(Gui.render_resolution) == 'function' and attempt(Gui.render_resolution) or nil
        H.tag_scale = (type(rw) == 'number' and rw > 0) and (H.ui.width / rw) or 1
        writer(string.format('tag: first projection raw=(%s) gui=%dx%d render_w=%s scale=%.3f', tostring(v), H.ui.width,
            H.ui.height, tostring(rw), H.tag_scale))
    end
    sx, sy = sx * H.tag_scale, sy * H.tag_scale
    if H.tag_flip then sy = H.ui.height - sy end
    return sx, sy, behind, sz
-- …（共 31 行，完整內容見原始碼頁）

local function build_gui(world)
    local gui = World.create_screen_gui(world, 'scale', 1, 1)
    if gui == nil then return false end
    H.ui.gui, H.ui.world = gui, world
    H.grp = {}
    local w, h = Gui.resolution()
    if type(w) == 'number' and w > 0 and type(h) == 'number' and h > 0 then
        H.ui.width, H.ui.height = w, h
        H.ui.scale = math.min(w / 1920, h / 1080)
    end
    writer(string.format('overlay up (%dx%d, scale %.2f, text=%s)', H.ui.width, H.ui.height,
        H.ui.scale, tostring(H.text_ok)))
    return true
end

-- Destroy only if the world is still alive; a dead world already took the gui with it.
local function teardown()
    if H.ui.gui ~= nil and world_is_live(H.ui.world) then
        pcall(World.destroy_gui, H.ui.world, H.ui.gui)
    end
    H.ui.gui, H.ui.world, H.grp = nil, nil, {}
end

-- Overlay world: the settled world with the fewest units (the UI world; the game world has thousands).
-- main_world flips ~every 3s, so it can't be used to tell them apart. Once chosen, kept while it lives.
local t_now = 0
local function pick_overlay_world()
    local best
    for _, rec in ipairs(H.worlds_seen) do
        if t_now - rec.since >= 10 and rec.n ~= nil and (best == nil or rec.n < best.n) then best = rec end
    end
    if best then writer(string.format('overlay on world #%d (%d units)', best.idx, best.n)) end
    return best and best.w
end

pcall(ffi.cdef, [[
unsigned long long VirtualQuery(const void* addr, void* buf, unsigned long long len);
void* GetCurrentProcess(void);
int ReadProcessMemory(void* process, const void* addr, void* buf, size_t size, size_t* read);
typedef struct {
    void* BaseAddress; void* AllocationBase; unsigned long AllocationProtect; unsigned short PartitionId;
    unsigned long long RegionSize; unsigned long State; unsigned long Protect; unsigned long Type;
} HLH_MBI;
]])
local k32 = ffi.load('kernel32')

function H.game_base()
    if H.GAME_BASE then return H.GAME_BASE end                -- test harness
    local ok, m = pcall(function() return tonumber(ffi.cast('uintptr_t', ffi.C.GetModuleHandleA('game.dll'))) end)
    if ok and m and m ~= 0 then return m end
    return nil
end

local function health_sys()
    local base = H.game_base()
    if not base then return nil, 'game.dll not found' end
    local S = ptr(base + HEALTH_SYS_RVA)
    if not S then return nil, 'health system not created' end
    local keys, cap, recs = ptr(S + HS_KEYS), u32(S + HS_CAP), ptr(S + HS_RECS)
    if not (keys and cap and recs) or cap == 0 or cap > 0x40000 then
        return nil, string.format('health system layout unexpected (cap=%s)', tostring(cap))
    end
    return {S = S, keys = keys, cap = cap, recs = recs, empty = u32(S + HS_EMPTY)}
end

local function table_header(base_rva, keys_off, cap_off)
    local base = M.game_base()
    if not base then return nil end
    local S = ptr(base + base_rva)
    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

local OFF_MAIN, OFF_ARMOR0, OFF_MARKER = -0xE4, -0x98, 0x98
local WIN_LO, WIN_HI = 0xF0, 0xA0  -- read [Z - 0xF0, Z + 0xA0)
local WIN_LEN = WIN_LO + WIN_HI

-- Per-slot max HP / constitution, built from H.GROUPS.
local MAXHP, MAXCON = {}, {}
for _, g in ipairs(H.GROUPS) do
    for _, z in ipairs(g.zones) do MAXHP[z.slot], MAXCON[z.slot] = z.hp, z.con or g.con or 0 end
end

-- Read the record around zone base z into WIN and validate it. Returns true if it still looks like a Hive Lord.
-- Armor never changes in a fight, so it is the fingerprint: default zone, then slots 0..37.
local ARMOR = {5, 6, 10}
for _ = 1, 13 do ARMOR[#ARMOR + 1] = 5 end
for _ = 1, 7 do ARMOR[#ARMOR + 1] = 2 end
ARMOR[#ARMOR + 1] = 6; ARMOR[#ARMOR + 1] = 6
for _ = 1, 14 do ARMOR[#ARMOR + 1] = 5 end

-- HP is only sanity-bounded: destroyed zones (even ones without constitution) go below zero.
local function read_record(z)
    if safe_read(z - WIN_LO, WIN_LEN, WIN) < WIN_LEN then return false end
    local zb = WIN_LO
    if i32(WIN, zb + OFF_MARKER) ~= 0xFFFF then return false end
    for i = 1, #ARMOR do
        if i32(WIN, zb + OFF_ARMOR0 - 4 + (i - 1) * 4) ~= ARMOR[i] then return false end
    end
    for slot = 0, 37 do
        local v = i32(WIN, zb + slot * 4)
        if v > MAXHP[slot] or v < -(MAXCON[slot] + MAXHP[slot]) then return false end
    end
    return true
end

local function each_key(hs, fn)
    local per = 0x10000 / 8
    for first = 0, hs.cap - 1, per do
        local n = math.min(per, hs.cap - first)
        if safe_read(hs.keys + first * 8, n * 8, B8) < n * 8 then return false end
        local p, list = ffi.cast('uint32_t*', B8), {}
        for i = 0, n - 1 do
            local k, v = tonumber(p[i * 2]), tonumber(p[i * 2 + 1])
            if k ~= hs.empty and k ~= 0 and v < 0x100000 then list[#list + 1] = {k, v} end
        end
        for _, kv in ipairs(list) do if fn(kv[1], kv[2]) then return true end end
    end
    return true
end

-- The Hive Lord's armour values (default zone, then zones 0..37) never change in a fight: our fingerprint.
local ARMOR = {5, 6, 10}
for _ = 1, 13 do ARMOR[#ARMOR + 1] = 5 end
for _ = 1, 7 do ARMOR[#ARMOR + 1] = 2 end
ARMOR[#ARMOR + 1] = 6; ARMOR[#ARMOR + 1] = 6
for _ = 1, 14 do ARMOR[#ARMOR + 1] = 5 end

-- Plate zone -> its model mask (GoreComponent) ; constitution 35000 for every plate.
local PLATE_MASK = {}
for k = 0, 5 do PLATE_MASK[7 - k], PLATE_MASK[14 - k] = 1 + 4 * k, 2 + 4 * k end
local PLATE_CON = 35000
local FIX_DELAY, FIX_TRIES, RETRY_S = 1.5, 3, 2

local function each_key(keys, cap, fn)
    local per = 0x10000 / 8
    for first = 0, cap - 1, per do
        local n = math.min(per, cap - first)
        if safe_read(keys + first * 8, n * 8, BUF) < n * 8 then return false end
        local p, list = ffi.cast('uint32_t*', BUF), {}
        for i = 0, n - 1 do
            local k, v = tonumber(p[i * 2]), tonumber(p[i * 2 + 1])
            if k ~= 0xFFFFFFFF and k ~= 0 and v < 0x100000 then list[#list + 1] = {k, v} end
        end
        for _, kv in ipairs(list) do if fn(kv[1], kv[2]) then return true end end
    end
    return true
end

-- =========================================================================
-- Hive Lord data (tools/research/hive_lord_health.json)
-- =========================================================================
H.MAIN_HEALTH_MAX = 150000
H.GROUPS = {
    {label = 'HEAD',  color = {255, 230, 140, 40},  zones = {
        {slot = 0, hp = 150000}, {slot = 1, hp = 150000}, {slot = 22, hp = 10000}, {slot = 23, hp = 10000}}},
    {label = 'SPINE', con = 35000, color = {255, 230, 200, 60},  zones = {
        {slot = 2, hp = 15000}, {slot = 3, hp = 15000}, {slot = 4, hp = 15000}, {slot = 5, hp = 15000},
        {slot = 6, hp = 15000}, {slot = 7, hp = 15000}, {slot = 8, hp = 20000}, {slot = 9, hp = 15000},
        {slot = 10, hp = 15000}, {slot = 11, hp = 15000}, {slot = 12, hp = 15000}, {slot = 13, hp = 15000},
        {slot = 14, hp = 15000}}},
    {label = 'BODY',  color = {255, 220, 70, 60},   zones = {
        {slot = 15, hp = 150000}, {slot = 16, hp = 150000}, {slot = 17, hp = 150000}, {slot = 18, hp = 150000},
        {slot = 19, hp = 150000}, {slot = 20, hp = 150000}, {slot = 21, hp = 150000}}},
    {label = 'FINS',  color = {255, 120, 170, 210}, zones = {
        {slot = 24, hp = 5000}, {slot = 25, hp = 5000}, {slot = 26, hp = 5000}, {slot = 27, hp = 5000},
        {slot = 28, hp = 5000}, {slot = 29, hp = 5000}, {slot = 30, hp = 5000}, {slot = 31, hp = 5000},
        {slot = 32, hp = 5000}, {slot = 33, hp = 5000}, {slot = 34, hp = 5000}, {slot = 35, hp = 5000},
        {slot = 36, hp = 5000}, {slot = 37, hp = 5000}}},
}

local function writer(line)
    local R = recon()
    H.recent[#H.recent + 1] = line
    if #H.recent > 3 then table.remove(H.recent, 1) end
    line = '[HiveLordHud] ' .. line
    if R and R.write then R.write(line) return end
    print(line)
    local f = open_own_log()
    if f then pcall(function() f:write(line, '\n'); f:flush() end) end
end

-- =========================================================================
-- The live HP record straight from the game's health system (a game.dll global; RVA of build 25480438).
-- The damage code (game.dll 0x9235F0) indexes it the same way: hash of (entity u32, index u32) at +0x1030,
-- capacity at +0x1038, empty key at +0x103C, runtime records at +0x1058, 0x1B8 bytes each; zone HP at +0xF8
-- (our Z), main HP at +0x14. The game reallocates that array and the old copies stay readable and still pass
-- our fingerprint, so a heap scan can end up following a frozen copy. Going through the global always lands on the
-- live one; the heap scan is only the fallback when the global cannot be read (e.g. after a game update).
-- =========================================================================
do
local HEALTH_SYS_RVA, HS_KEYS, HS_CAP, HS_EMPTY, HS_RECS = 0x3326688, 0x1030, 0x1038, 0x103C, 0x1058
local REC_STRIDE, REC_Z = 0x1B8, 0xF8
local B8 = ffi.new('uint8_t[?]', 0x10000)
local function u32(addr)
    if safe_read(addr, 4, B8) < 4 then return nil end
    return tonumber(ffi.cast('uint32_t*', B8)[0])
end
local function ptr(addr)
    if not addr or safe_read(addr, 8, B8) < 8 then return nil end
    local p = tonumber(ffi.cast('uint64_t*', B8)[0])
    if p < 0x10000 or p > USER_END then return nil end
    return p
end

-- A Hive Lord plate that is destroyed (zone HP -35000) always loses its collider and its crack overlay: that is zone
-- state, synced to everyone (game.dll 0x925F10). The plate model itself is only hidden by gore (0x9057D0 -> 0x903C70),
-- which runs only on the machine that resolves the killing hit, and only if that hit passes gore's checks. When
-- gore never comes (seen on a client when a teammate's Eagle killed the plate), the plate stays drawn - looking
-- intact again - while shots pass through it to the flesh behind.
--
-- This module watches every Hive Lord through the game's own tables and, when a plate has been dead for
-- FIX_DELAY seconds and is still drawn, writes the same "hidden" override bit that gore would have written. The
-- game then updates the drawn mask itself. It only changes what this player sees: no damage, collision, network
-- or code is touched. Every read/write goes through Read/WriteProcessMemory, so a stale address fails instead of
-- crashing. RE notes: tools/research/hive_lord_armor_break.md. Globals are RVAs of build 25480438.

-- ---------- game tables ----------
-- Health system (game.dll+0x3326688): keys (entity u32, index u32) @+0x1030, capacity @+0x1038, empty key @+0x103C,
--   records @+0x1058, 0x1B8 bytes each: zone HP i32[38] @+0xF8, armor i32[39] @+0x5C, 0xFFFF marker @+0x190.
-- Visibility-mask system (game.dll+0x3326708): keys @+0x18, capacity @+0x20, entries @+0x38 (24 bytes: applied
--   mask @+0, override bits @+8, touched bits @+16), base masks @+0x40 (8 bytes each).
-- The setters (0x721D20 & co.) push to the material at once only while the unit's render record is live
-- ([rec+0x14] bit 0); then they write the base mask. Otherwise they only write override/touched, and the updater
-- 0x721680 later pushes (base & ~touched) | (override & touched) and keeps that in the entry's applied mask.
-- So "drawn" must not be judged by the base mask alone (the non-live path never changes it): a plate counts as
-- hidden when either the base or the applied mask has its bit. Every try logs all four masks.
local HEALTH_RVA, VIS_RVA = 0x3326688, 0x3326708
local REC_STRIDE = 0x1B8
local Z_OFF, ARMOR_OFF, MARKER_OFF = 0xF8, 0x5C, 0x190

local SLICE_S, CHUNK = 0.004, 1024 * 1024   -- 4 ms per frame (was 8: halved the FPS while it ran at ~130 FPS)

-- All reads go through ReadProcessMemory on our own process: heap memory can be freed by another
-- thread between a VirtualQuery check and a raw pointer read (that segfaulted in testing); RPM just fails.
local SELF = k32.GetCurrentProcess()
local NREAD = ffi.new('size_t[1]')
local SCRATCH = ffi.new('uint8_t[?]', CHUNK)
local WIN = ffi.new('uint8_t[?]', WIN_LEN)

local function safe_read(addr, n, dst)
    if k32.ReadProcessMemory(SELF, ffi.cast('const void*', addr), dst, n, NREAD) == 0 then return 0 end
    return tonumber(NREAD[0])
end

function H.locator_start()
    local list, why = H.direct_find()
    if list then
        H.loc = {phase = 'done', direct = true, cands = {}, adopted = nil, t0 = now_s(), scanned = 0, anchors = 0, last_poll = -1e9}
        local ids = {}
        for _, c in ipairs(list) do
            H.loc.cands[#H.loc.cands + 1] = {z = c.z, ent = c.ent, idx = c.idx, changed = -1e9}
            ids[#ids + 1] = string.format('entity 0x%X index %d', c.ent, c.idx)
        end
        if list[1] then
            writer('HP record found via the health system: ' .. table.concat(ids, ', '))
            H.direct_waiting = nil
        else
            H.loc.retry_at = now_s() + 3
            if not H.direct_waiting then writer('health system readable, no Hive Lord record yet - retrying every 3s') end
            H.direct_waiting = true
        end
        return
    end
    if not H.direct_fail_logged then
        writer('direct HP lookup unavailable (' .. tostring(why) .. ') - using the heap scan')
        H.direct_fail_logged = true
    end
    H.loc = {phase = 'scan', addr = 0x10000, rbase = nil, rend = nil, off = 0,
             scanned = 0, anchors = 0, cands = {}, adopted = nil, t0 = now_s()}
    writer('heap scan started (time-sliced, ~4ms/frame)')
end

local OWN = {
    {tonumber(ffi.cast('uintptr_t', SCRATCH)), CHUNK},
    {tonumber(ffi.cast('uintptr_t', WIN)), WIN_LEN},
}

local function test_anchor(L, hit)
    for _, r in ipairs(OWN) do
        if hit >= r[1] - WIN_LEN and hit < r[1] + r[2] then return end
    end
    L.anchors = L.anchors + 1
    if #L.cands < 8 and read_record(hit) then
        for _, c in ipairs(L.cands) do if c.z == hit then return end end
        L.cands[#L.cands + 1] = {z = hit, sig = signature(), changed = -1e9}
    end
end

local function scan_step(L)
    local t_end = clock() + SLICE_S
    while clock() < t_end do
        if L.rbase == nil then
            if L.addr >= USER_END or k32.VirtualQuery(ffi.cast('const void*', L.addr), mbi, MBI_SIZE) == 0 then
                return true
            end
            local m = mbi[0]
            local rb, rs = tonumber(ffi.cast('uintptr_t', m.BaseAddress)), tonumber(m.RegionSize)
            if rb + rs <= L.addr then return true end
            L.addr = rb + rs
            if m.State == MEM_COMMIT and m.Type == MEM_PRIVATE and m.Protect == PAGE_READWRITE then
                L.rbase, L.rend, L.off = rb, rb + rs, 0
            end
        else
            local take = math.min(CHUNK, L.rend - L.rbase - L.off)
            local cbase = L.rbase + L.off
            local got = safe_read(cbase, take, SCRATCH)
            -- Compare aligned int32s in place: building a Lua string would leave stale copies of the
            -- record in the heap for later scans to find.
            local ok = got == take
            if ok then
                local words = ffi.cast('const int32_t*', SCRATCH)
                for i = 0, got / 4 - 1 do
                    if words[i] == 6 and words[i + 1] == 10 and i + 1 < got / 4 then
                        test_anchor(L, cbase + i * 4 - OFF_ARMOR0)
                    end
                end
            end
            L.off = L.off + take
-- …（共 36 行，完整內容見原始碼頁）

function H.read_hp()
    local hp = {main = nil, zones = {}}
    local L = H.loc
    if not L then return hp end
    if L.phase == 'done' and not L.adopted and L.retry_at and now_s() >= L.retry_at then
        H.locator_start()
        return hp
    end
    if L.phase ~= 'done' or not L.cands[1] then return hp end
    local t = now_s()
    if t - L.last_poll >= 1 then
        L.last_poll = t
        local keep = {}
        for _, c in ipairs(L.cands) do
            if L.direct then c.z = H.direct_z(c, true) end
            if c.z and read_record(c.z) then
                local sig = signature()
                if sig ~= c.sig then c.sig, c.changed = sig, t end
                keep[#keep + 1] = c
            end
        end
        L.cands = keep
        if not keep[1] then
            writer('HP records moved or freed - rescanning')
            H.locator_start()
            return hp
        end
        -- The Hive Lord being fought is the record whose HP changed most recently.
        local still_valid = false
        for _, c in ipairs(keep) do if c == L.adopted then still_valid = true end end
-- …（共 104 行，完整內容見原始碼頁）

-- ---------- memory access (never dereference raw pointers: the game frees and moves these tables) ----------
pcall(ffi.cdef, 'void* GetModuleHandleA(const char* name);')
pcall(ffi.cdef, 'void* GetCurrentProcess(void);')
pcall(ffi.cdef, 'int ReadProcessMemory(void* process, const void* addr, void* buf, size_t size, size_t* read);')
pcall(ffi.cdef, 'int WriteProcessMemory(void* process, void* addr, const void* buf, size_t size, size_t* written);')
pcall(ffi.cdef, 'int QueryPerformanceCounter(int64_t* c); int QueryPerformanceFrequency(int64_t* f);')
local k32 = ffi.load('kernel32')
local SELF = k32.GetCurrentProcess()
local NIO = ffi.new('size_t[1]')
local BUF = ffi.new('uint8_t[?]', 0x10000)
local REC = ffi.new('uint8_t[?]', 0x1B8)
local WB = ffi.new('uint8_t[1]')
local USER_END = 0x7FFFFFFFFFFF

local function safe_read(addr, n, dst)
    if k32.ReadProcessMemory(SELF, ffi.cast('const void*', addr), dst, n, NIO) == 0 then return 0 end
    return tonumber(NIO[0])
end
local function u32(addr)
    if safe_read(addr, 4, BUF) < 4 then return nil end
    return tonumber(ffi.cast('uint32_t*', BUF)[0])
end
local function ptr(addr)
    if not addr or safe_read(addr, 8, BUF) < 8 then return nil end
    local p = tonumber(ffi.cast('uint64_t*', BUF)[0])
    if p < 0x10000 or p > USER_END then return nil end
    return p
end
local function mask(addr)
    if safe_read(addr, 8, BUF) < 8 then return nil end
-- …（共 37 行，完整內容見原始碼頁）

-- Sections (in file order):
--   Hive Lord data      zone layout, max HP / constitution per zone (from the unpacked HealthComponent)
--   Detection           finding the Hive Lord unit, its distance, surfacing and the emerge / pre-emerge states
--   Live HP locator     the HP record via the game's health system (heap scan only as a fallback)
--   Zone tracking       per-frame zone bookkeeping; host state events and the '<' upper-bound marker
--   GUI                 prims and groups: status text, armour panel (poly / pixel), tag, warning, preview, boss bar
--   Per-frame worker    world selection, gui lifetime, render()
--   Settings            cfg file and the Bingus Mod Options Menu rows
--   Install             the wrapper around the engine's global update()

if rawget(_G, 'HD2HiveLordHud') then return end
local H = {version = 121, release = 'v3', armed = false, faults = 0, frame = 0}
rawset(_G, 'HD2HiveLordHud', H)

function H.update()
    H.frame = (H.frame or 0) + 1
    -- Lua update rate (the overlay can only move this often), logged every 30 s while a Hive Lord is tracked.
    local tr = now_s()
    H.rate_t0 = H.rate_t0 or tr
    H.rate_n = (H.rate_n or 0) + 1
    if tr - H.rate_t0 >= 30 then
        local c = H.cost
        if H.live.unit and c then
            local normal_n = c.n - c.scan_n
            writer(string.format('update rate: %.0f Hz | HUD cost: avg %.3f ms, max %.2f ms per frame%s', H.rate_n / (tr - H.rate_t0),
                normal_n > 0 and (c.sum - c.scan_sum) / normal_n or 0, c.max,
                c.scan_n > 0 and string.format(' | during HP search: %d frames, avg %.2f ms', c.scan_n, c.scan_sum / c.scan_n) or ''))
        end
        if c then c.sum, c.max, c.n, c.scan_sum, c.scan_n = 0, 0, 0, 0, 0 end
        H.rate_t0, H.rate_n = tr, 0
    end
    local L, t = H.live, now_s()
    t_now = t
    -- A dead world already took its gui with it: forget, never destroy.
    if H.ui.gui ~= nil and not world_is_live(H.ui.world) then
        H.ui.gui, H.ui.world, H.grp = nil, nil, {}
    end

    if t - L.last_scan >= 2 then
        L.last_scan = t
        local worlds = attempt(App.worlds)
        if type(worlds) ~= 'table' then return end
        local u, _, uname = H.find_hive_lord(worlds, t)
        local a = u and (unit_addr(u) or u)
-- …（共 81 行，完整內容見原始碼頁）

function H.options_register(M)
    local function reg(id, spec)
        local ok, done, why = pcall(M.register_option, id, spec)
        if not (ok and done) then writer('mod options: register ' .. id .. ' failed: ' .. tostring(ok and why or done)) end
        return ok and done
    end
    H.option_ok = reg(OPTION_ID, {
        type = 'toggle', mod = 'Hive Lord HUD', label = 'Enable Hive Lord HUD', default = true,
        description = 'Turns the whole Hive Lord HUD on or off: HP bar, armor panel, tag, distance and '
            .. 'emerge warning. Off stops all of its work.'})
    if not H.option_ok then return end
    local n = 0
    for _, o in ipairs(H.OPTIONS) do
        local spec = {type = o.type, mod = 'Hive Lord HUD', label = o.label, description = o.description, gap = o.gap,
                      default = o.default, choices = o.choices, step = o.step}
        if o.type == 'choice' then spec.default = to_menu(o, o.default) end
        if o.type == 'slider' then spec.min, spec.max = SIZE_RANGE[o.key][1], SIZE_RANGE[o.key][2] end
        o.ok = reg(H.opt_id(o), spec)
        if o.ok then n = n + 1 end
    end
    writer(string.format('mod options: registered %s + %d of %d settings', OPTION_ID, n, #H.OPTIONS))
    pcall(M.set, 'hivelordhud.preview', false)     -- preview is per session: never comes back on by itself
    -- cfg.menu: 0 = menu never seen (copy every saved setting into it); 1, 2 = older menu layouts (copy the rows
    -- added since, see `since`); 3 = the menu is the source.
    if (H.cfg.menu or 0) < 3 then
        for _, o in ipairs(H.OPTIONS) do
            if o.ok and (o.since or 1) > (H.cfg.menu or 0) then pcall(M.set, H.opt_id(o), to_menu(o, H.cfg[o.key])) end
        end
        writer('mod options: copied saved settings into the menu (from cfg level ' .. tostring(H.cfg.menu) .. ')')
        H.cfg.menu = 3
-- …（共 50 行，完整內容見原始碼頁）

function M.poll_option()
    local MOM = rawget(_G, 'ModOptionsMenu')
    if type(MOM) ~= 'table' then return end
    if not M.option_tried then
        M.option_tried = true
        local ok, done = pcall(MOM.register_option, OPTION_ID, {
            type = 'toggle', mod = 'Hive Lord Plate Fix', label = 'Fix dead plates that stay on', default = true,
            description = "A plate destroyed by damage your game did not resolve itself (e.g. a teammate's Eagle) loses its collision but can stay drawn, looking intact. When a plate has been at 0% for 1.5 s and is still drawn, hide it the way the game would have. Only changes what you see."})
        M.option_ok = ok and done
        if not M.option_ok then writer('mod options: register failed') end
    end
    if not M.option_ok or M.frame % 10 ~= 0 then return end
    local ok, v = pcall(MOM.get, OPTION_ID)
    if ok and type(v) == 'boolean' and v ~= M.enabled then
        M.enabled = v
        writer('fix ' .. (v and 'enabled' or 'disabled') .. ' from Mod Options Menu')
    end
end

function M.now()                                   -- seconds; tests replace this
    k32.QueryPerformanceCounter(QB)
    return tonumber(QB[0]) / QFREQ
end

function M.game_base()
    if M.GAME_BASE then return M.GAME_BASE end      -- tests
    local ok, m = pcall(function() return tonumber(ffi.cast('uintptr_t', ffi.C.GetModuleHandleA('game.dll'))) end)
    if ok and m and m ~= 0 then return m end
    return nil
end

-- =========================================================================
-- Zone tracking
-- =========================================================================
-- Per-frame zone bookkeeping for H.state_diag (last zone HP, last main HP), plus one log line for a big one-frame main
-- HP drop or the drop to 0 at death (the host's death event snaps a client's main HP to 0). Research logging (per-
-- second zone changes, raw record dumps, late-join hit logs) lives in the optional diag module (hive_lord_diag.lua).
function H.track_zones(L, hp)
    local t = now_s()
    local d = L.diag
    local id = L.adopted.ent or L.adopted.z     -- the direct lookup's address moves with the array; the entity doesn't
    if not d or d.id ~= id then
        d = {id = id, last = {}}
        L.diag = d
        for slot = 0, 37 do d.last[slot] = hp.zones[slot] end
        return
    end
    H.state_diag(d, hp, t)
    if hp.main and d.last_main and (d.last_main - hp.main >= 8000 or (hp.main == 0 and d.last_main > 0)) then
        writer(string.format('MAIN JUMP t=%.1f: %d -> %d in one frame (drop %d)', t, d.last_main, hp.main, d.last_main - hp.main))
    end
    d.last_main = hp.main
    for slot = 0, 37 do
        local v = hp.zones[slot]
        if v ~= nil then d.last[slot] = v end
    end
end

-- Who changed a zone's state? Our machine only resolves the hits it simulates; the host sends zone-state
-- events, which the state machine applies with HP = min(HP, -1) (cracked) or min(HP, -constitution) (dead).
-- So: a state change that lands HP on exactly -1 / -constitution in a frame where our main HP did not drop came from
-- …（共 65 行，完整內容見原始碼頁）

-- OR one bit into the byte that holds it: a single-byte write keeps the window against the game's own writes tiny.
local function set_bit(addr, bit)
    local a = addr + math.floor(bit / 8)
    if safe_read(a, 1, WB) < 1 then return false end
    local v = bitlib.bor(WB[0], bitlib.lshift(1, bit % 8))
    if v == WB[0] then return true end
    WB[0] = v
    return k32.WriteProcessMemory(SELF, ffi.cast('void*', a), WB, 1, NIO) ~= 0
end

function M.check(L, t)
    local rec = health_index(L.ent)
    if not rec or not read_hive_record(rec) then return false end         -- gone (despawned)
    if t >= (L.next_vis or 0) or not L.vis then L.vis, L.next_vis = vis_entry(L.ent), t + 1 end
    local v = L.vis
    local lo, hi, alo, ahi = nil, nil, nil, nil
    if v then lo, hi = mask(v.rendered); alo, ahi = mask(v.applied) end
    -- Same sanity check as the HUD: the two unwired masks (32, 33) are always hidden on a Hive Lord. Anything else
    -- means the entry now belongs to another unit (the table was compacted): look it up again, write nothing.
    local sane = hi and bitlib.band(hi, 3) == 3
    if v and not sane then L.vis = nil end
    for slot, pm in pairs(PLATE_MASK) do
        local hp = i32(Z_OFF + slot * 4)
        if hp <= -PLATE_CON and not L.dead[slot] then L.dead[slot] = t end
        local died, f = L.dead[slot], L.fix[slot]
        if M.enabled and sane and died and not (f and f.gave_up) then
            local applied_hidden = alo and mbit(alo, ahi, pm)
            local shown = not mbit(lo, hi, pm) and not applied_hidden
            if shown and t - died >= FIX_DELAY then
                f = f or {n = 0}
                L.fix[slot] = f
                if t >= (f.next or 0) then
                    if f.n >= FIX_TRIES then
                        f.gave_up = true
                        writer(string.format('entity 0x%X plate slot %d: still drawn after %d tries - giving up (%s)',
                            L.ent, slot, f.n, M.masks(v)))
                    else
                        f.n, f.next, f.at = f.n + 1, t + RETRY_S, t
                        local ok = set_bit(v.override, pm) and set_bit(v.touched, pm)
                        writer(string.format('entity 0x%X plate slot %d: dead %.1f s but still drawn -> hid model mask %d (%s), try %d (%s)',
-- …（共 42 行，完整內容見原始碼頁）