Overview

PoZoUSEMS is a universal modding system for Source 1 engine games. It consists of a thin native core that is injected into the game process, a set of runtime bridges that mod scripts run inside, and (eventually) a desktop launcher that manages everything.

Design principles

1. From the interfaces up. Source exposes its functionality through a discoverable CreateInterface factory system. PoZoUSEMS resolves those interfaces at runtime and drives them directly — no SourceMod, no Metamod, no SDK headers.
2. DIY reverse engineering. Every offset, vtable slot, and structure layout used by the system was recovered by disassembling the shipped game binaries. The tools/ directory contains the scripts that produced each fact, so every claim is reproducible.
3. A crash is a game crash. The core runs inside the game process, so safety is a first-class concern: sandboxed script runtimes, memory and time budgets, frozen registration windows, and per-game fingerprint checks before any game-specific offset is touched.
4. One API, many languages. Every runtime bridge talks to the same core API surface. Adding a language is adding one bridge, not rewiring the system.

Supported games

Game	Status
Portal 1	primary target, caps verified
Half-Life 2	planned (Phase 6)
HL2 Episodes	planned (Phase 6)
Portal 2	planned (Phase 6, needs its own RE pass)

All current targets are 32-bit (x86). The core hard-refuses to build for any other architecture.

Non-goals

• Multiplayer (mp-branch) support. Single-player only. The mp code compiled into the binaries can be hooked/read like any other code, but it is not a modding target.
• Steam Workshop integration, DRM, or encryption.
• Engine recompilation. Detours and vtable interposition only — we never rewrite engine code bytes.

Repository layout

PoZoUSEMS/
├── crates/
│   ├── usems-build-util/  # shared build versioning (1.BUILD stamping)
│   ├── usems-cap/         # per-game capability data: offsets, detection
│   ├── usems-core/        # the injected DLL: interfaces, hooks, Luau host
│   ├── usems-injector/    # CreateRemoteThread injector (x86)
│   ├── usems-launcher/    # egui desktop app (Phase 5)
│   └── usems-sdk/         # mod-author-facing API contract
├── mods/                  # development mod packages
├── tools/                 # offline RE + Python tooling (source of truth)
└── docs-site/             # these docs (Astro + Starlight)

Versioning

Version format is MAJOR.BUILD (e.g. 1.046). The major is bumped manually; the build counter auto-increments on every compile of any crate.