aowlspt_uistate.h

Source: abi/aowlspt_uistate.h — 235 lines, 12 file-scope functions.

What this header owns

Reproduced verbatim from the header's own banner comment — these notes are frequently the only written record of why the subsystem is shaped the way it is.

 aowlspt_uistate.h -- a MOD-FACING "which blocking UI surface is open" signal.

WHY THIS FILE EXISTS
--------------------
A mod that draws a HUD during a raid (the maps radar, an ESP overlay) has no
way to know that a BLOCKING UI surface is up in front of it -- the game's own
Settings screen, or one of our overlay panels (F6 admin, F3 debug) -- so it
keeps drawing on top of a screen the player is trying to read. The region ABI
(`aowlspt_region.h`) exposes no such mask. This file adds one PE export,
`aowl_ui_overlay_mask`, that any mod can `GetProcAddress` on
`aowlspt-host-il2cpp.dll` and poll each frame.

THE MASK
--------
  bit0  AOWL_UI_OVL_SETTINGS  the GAME's Settings screen is open
  bit1  AOWL_UI_OVL_ADMIN     our F6 admin overlay is open
  bit2  AOWL_UI_OVL_DEBUG     our F3 debug overlay is open
  bit3  AOWL_UI_OVL_OVERLAY   our F12 mod-manager / settings panel is open
Higher bits are reserved; a surface whose state cannot be determined reads 0
(an honestly-absent signal, never a guessed 1 -- CLAUDE.md 9b).

HOW EACH BIT IS SOURCED
-----------------------
bit1/bit2/bit3 are LEVELS already maintained by the cursor module
(`aowlspt_cursor.h`): the overlay DLL publishes F12 (OVERLAY, the mod-manager
/ settings panel) and F6 (ADMIN) and the host publishes F3 (DEBUGUI) every
frame, and a publication expires after `AOWL_CUR_STALE_MS`. We read that union
-- no game call, no new detour. bit3 was added because the F12 panel is the
one the launch hint tells the player to press ("F12 for Mod Settings"); it is
a full-screen blocking surface, yet its cursor bit (AOWL_CUR_P_OVERLAY) was
never folded into this mask, so a HUD polling the mask kept drawing over it.

bit0 is NOT a level the host already maintained. `gSettingsLiveSelf` is the
LAST-KNOWN SettingsScreen `this` (settingsui.nim); it is set on the ShowScreen
postfix and is never cleared, so it says "was opened once", NOT "is open now".
To answer "is it open NOW" truthfully we read the FINISHED STATE off that
pointer every tick: `Component::get_gameObject` then
`GameObject::get_activeInHierarchy`, two ordinary instance getters CALLED (not
detoured) at static RVAs byte-verified against the startup prologue snapshot.
A screen that has been closed deactivates its GameObject, so activeInHierarchy
is the negative-falsifiable test the task asks for. If either getter cannot be
verified, or `gSettingsLiveSelf` is null/unreadable, bit0 is 0 and the reason
is countable (see `aowl_ui_st_*`), never a guessed 1.

Both RVAs are re-used, byte-for-byte, from tables that already ship in this
repo (`aowlspt_invoke2.h` get_gameObject @0x11F57E0, `aowlspt_nativeui.h`
get_activeInHierarchy @0x52A8C90); they were resolved offline with
`il2cpp_resolve.py` on build 1.1.0.1.46777 and `--shared` annotated neither.
Calling a getter is safe even were it shared -- it is correct code for the
receiver passed -- and nothing here is detoured.

THE EIGHT RULES
---------------
 1. Prologue byte-verify (16 bytes, startup snapshot) before any call:
    `aowl_ui_fn`.
 2. `VirtualQuery` on the target page; `aowl_is_readable` on the SettingsScreen
    `this` and on the GameObject hop before each getter.
 3. ONE `aowl_p_p_seh`, installed by the caller (uistate.nim) around
    `aowl_ui_settings_probe_body`. Nothing here nests a guard.
 4. No loops but the capped one over `AOWL_UI_TARGET_COUNT` (2).
 5. The managed probe (bit0) is gated by `overlayStateSignal`, DEFAULT OFF.
    bit1/bit2 are pure reads of already-published state and always publish.
 6. Self-disables the bit0 probe after `AOWL_UI_MAX_FAULTS` faults.
 7. No managed allocation; the getters allocate nothing.
 8. Never writes anything into the game -- read-only throughout.

Constants

• AOWLSPT_UISTATE_H
• AOWL_UI_MAX_FAULTS
• AOWL_UI_OVL_ADMIN
• AOWL_UI_OVL_ALL
• AOWL_UI_OVL_DEBUG
• AOWL_UI_OVL_OVERLAY
• AOWL_UI_OVL_SETTINGS
• AOWL_UI_TARGET_COUNT
• AOWL_UI_T_GETACTIVE
• AOWL_UI_T_GETGO

Types

• struct AowlUiTarget

Functions

Signature	Line
void aowl_ui_publish_mask(uint32_t mask)	111
int32_t aowl_ui_profull_count(void)	150
void aowl_ui_fn(int32_t i)	155
void aowl_ui_settings_probe_body(void* a)	194
void aowl_ui_settings_probe_guarded(void* a)	218
int32_t aowl_ui_st_verified(void)	223
int32_t aowl_ui_st_rejected(void)	224
int32_t aowl_ui_st_faults(void)	225
int32_t aowl_ui_st_off(void)	226
int32_t aowl_ui_st_last_open(void)	227
void aowl_ui_st_set_self(void* p)	228
void aowl_ui_st_fault(void)	229