How It Works

usems-launcher (egui, Phase 5)
        │
        ▼
usems-injector ── CreateRemoteThread(LoadLibraryW) ──▶ hl2.exe (x86)
        │                                                       │
        │                                              usems_core.dll boots
        │                                                       │
        │                            ┌──────────────────────────┼───────────────┐
        │                            ▼                          ▼               ▼
        │                     game detection              interface layer   live console
        │                     (usems-cap)                (interfaces.rs)   (console_io)
        │                            │                          │
        │                            ▼                          ▼
        │                     regwalk (151 ifaces)      ICvar (VEngineCvar004)
        │                            │                          │
        │                            ▼                          ▼
        │                     hook engine ── frame ──▶ mod_runtime (Luau states)
        │                                                │
        └── profiles/mods on disk ──────▶ mods/<id>/mod.toml + init.luau

Stage by stage

1. Injection (usems-injector)

Classic x86 CreateRemoteThread + LoadLibraryW: resolve the game exe, allocate memory in the target, write the DLL path, and start a remote thread at LoadLibraryW. Two modes: launch-suspended (--exe) and attach (--pid). See Injection Pipeline.

2. Boot (lib.rs)

DllMain does nothing but flip a flag and spawn a worker thread (calling Win32 APIs that take the loader lock from DllMain is illegal). The worker waits for engine DLLs to map, then:

1. opens the live console (AllocConsole + WriteConsoleW),
2. resolves tier0 Msg/Warning for game-console output,
3. detects the game via usems-cap fingerprints,
4. dumps the interface registries,
5. loads mods,
6. installs the frame hook.

3. Interfaces (interfaces.rs, regwalk.rs)

Everything Source exposes is behind CreateInterface factories. We resolve the ones we use directly and can enumerate all of them by walking each module’s registry chain. See Interface Resolution.

4. Console objects (source_console_bridge.cpp)

Mod commands/cvars must be real Source ConCommand/ConVar objects with exact MSVC layouts. A small C++ bridge owns those layouts (with compile-time size assertions), registers/unregisters objects against the live ICvar, and routes engine dispatch into Rust by argv[0] name. Rust never hand-builds C++ objects.

5. Mod runtime (mod_runtime.rs)

Each mod package gets an isolated, sandboxed Luau state: safe stdlib only, 64 MB memory cap, 5-second execution budget per VM entry. During the entry script, usems.register_command/register_cvar/hook declare intent; when the script finishes, declarations freeze into real Source objects. See Sandbox & Limits.

6. Hook engine (hooks.rs)

Vtable interposition: copy the client interface’s vtable into RWX memory, replace the HudUpdate slot with a transparent stub (pushad → call Rust → popad → jmp original), repoint the object’s vptr. Engine code bytes are never modified. Every frame, subscribed Luau callbacks run with real frametime from gpGlobals. See Hook Engine.

Why every offset is in usems-cap

The mechanisms above are game-generic; the numbers (singleton RVAs, hook slots, registry heads) are per-game facts recovered by RE. Caps carry the facts, fingerprint-verified against the running binary. Wrong or unknown fingerprint → features degrade to no-ops with a log line, never a crash. See Per-Game Caps.