Skip to content
PoZoUSEMS

Quick Start

Prerequisites

Section titled “Prerequisites”
  • Rust stable with the i686-pc-windows-msvc target
  • MSVC toolchain (VS 2022+ build tools — the core’s C++ bridge needs it)
  • Portal 1 installed (32-bit, Source 2007 branch)

1. Build

Section titled “1. Build”
Terminal window
git clone https://git.dexx.moe/pozo/PoZoUSEMS
cd PoZoUSEMS
cargo build --target i686-pc-windows-msvc -p usems-core   # the injected DLL
cargo build                                                # injector + host crates

The core hard-refuses non-x86 builds — Portal 1 is a 32-bit process.

2. Inject into Portal

Section titled “2. Inject into Portal”

Launch mode (starts the game suspended, injects, resumes):

Terminal window
target\i686-pc-windows-msvc\debug\usems-injector.exe `
  --exe "D:\...\Portal\hl2.exe" `
  --args "-game portal -steam -novid -console" `
  --dll target\i686-pc-windows-msvc\debug\usems_core.dll `
  --delay 8000 --timeout 5000

Attach mode (game already running — needs -console for full logs):

Terminal window
# start Portal however you like, then:
usems-injector.exe --pid <PID> --dll ...\usems_core.dll --timeout 5000

On success a PoZoUSEMS live console window opens, mirroring every log line. Everything also lands in %TEMP%\usems_core.log.

3. Your first mod

Section titled “3. Your first mod”

Create <Portal-install>\mods\my-first-mod\mod.toml:

id = "my-first-mod"
name = "My First Mod"
version = "0.1.0"
author = "you"
language = "luau"
entry = "init.luau"
enabled = true

And init.luau next to it:

print(("hello from %s!"):format(usems.mod_name))


usems.register_command(
    "hello",
    function(...)
        print(("args: %s"):format(table.concat({ ... }, ", ")))
    end,
    0,
    "Say hello"
)

Reinject (or restart Portal + inject). You’ll see:

[USEMS] mods: loaded 'my-first-mod' v0.1.0 by you (1 command(s), 0 cvar(s))
[my-first-mod] hello from My First Mod!

Open the game console (~) and type hello world — your Luau callback just ran through Source’s own command dispatch.

Troubleshooting

Section titled “Troubleshooting”
Symptom Cause / fix
usems_core.dll build fails with access denied Portal still has the old DLL loaded — close it first
Injection “completed” but no live console Check %TEMP%\usems_core.log; delay may be too short — try --delay 10000
VirtualAllocEx failed (err 5) Injection raced the game’s startup — retry with a longer delay
Mod listed as FAILED with a Luau error The error line names your script and the exact problem
no verified caps for this game Unsupported/modified binaries — game-specific features stay off by design