Functions

PoZoUSEMS mods are written in Luau and run in isolated, sandboxed VMs — one per mod. Scripts receive the global print function, the usems table, and the sandboxed Luau standard library. Registration calls follow Source’s own constructor argument orders.

Language reference

Luau is Lua 5.1 with types, faster VM, and sandboxing built in. The Luau syntax reference covers everything you can use inside a mod.

Function index

Function / Field	Namespace	Summary
print	global	Print values to the game console, live console, and log file.
usems.print	usems	Same as the global print.
usems.register_command	usems	Register a Source console command.
usems.register_cvar	usems	Register a Source console variable.
usems.get_cvar	usems	Read a USEMS-registered cvar’s value.
usems.hook	usems	Subscribe to an engine hook.

Properties (not calls): usems.version, usems.mod_name.

Globals

print

print(...)

Description

Prints any number of values to all three output sinks: the Source console, the PoZoUSEMS live console window, and %TEMP%\usems_core.log. Each line is prefixed with your mod’s id. Strings print unquoted; numbers, booleans, nil, tables, and functions render with sensible defaults.

Parameters

Name	Type	Description
...	any	Values to print, space-separated.

Return Value

None.

Example

print("hello")                --> [my-mod] hello
print("hp:", 100, true, nil)  --> [my-mod] hp: 100 true nil
print(1.5, 2/3)               --> [my-mod] 1.5 0.66666666666667

usems namespace

usems.print

usems.print(...)

Description

Identical to the global print — same sinks, same prefix. Exists so scripts that shadow or replace the global still have a guaranteed path to console output.

Parameters

Name	Type	Description
...	any	Values to print.

Return Value

None.

Example

local print = function() end  -- something clobbered the global
usems.print("still works")    --> [my-mod] still works

usems.version

usems.version

Description

The core’s build version string, format "1.BUILD" (e.g. "1.046"). Use it to feature-gate against older cores.

Type

string

Example

print(("running on PoZoUSEMS %s"):format(usems.version))
--> [my-mod] running on PoZoUSEMS 1.046

local build = tonumber(usems.version:match("%d+$"))
if build >= 46 then
    -- frame hooks are guaranteed on this core
    usems.hook("frame", function(dt) end)
end

usems.mod_name

usems.mod_name

Description

The human-readable name field from your mod.toml. Handy for banners since the manifest already carries it.

Type

string

Example

print(("loaded: %s"):format(usems.mod_name))
--> [my-mod] loaded: My Fancy Mod

usems.register_command

usems.register_command(name, callback, flags?, help?)

Description

Registers a real Source ConCommand — it appears in the game console, autocomplete included, and the engine dispatches it directly into your Luau callback. Argument order matches Source’s ConCommand(name, fn, flags, help) constructor.

Only callable while your entry script is loading (see Hooks — frozen registration).

Parameters

Name	Type	Default	Description
name	string	—	Console name. 1–64 chars of [a-z0-9_.-], starting with a letter or digit. usems* is reserved.
callback	function	—	Called with the command’s arguments (varargs; argv[0] not included).
flags	integer?	0	FCVAR_* bitmask (e.g. 128 = archive-related flags apply to cvars; commands commonly use 0).
help	string?	""	Help text shown by the console.

Return Value

Type	Description
boolean	true on success.

Errors

• Name violates the charset or starts with usems.
• Name already declared by this mod, or already exists in the engine.
• Called after load (frozen registration).
• flags doesn’t fit a 32-bit int.

Example

usems.register_command(
    "my_say",
    function(...)
        local words = { ... }
        print(("you said: %s"):format(table.concat(words, " ")))
    end,
    0,
    "Echo a message back to the console"
)

-- game console:  my_say hello world
-- --> [my-mod] you said: hello world

usems.register_cvar

usems.register_cvar(name, default, flags?, help?)

Description

Registers a real Source ConVar that persists in the engine console like any native cvar: users set it with name "value", and (with FCVAR_ARCHIVE) it survives restarts. Argument order matches Source’s ConVar(name, default, flags, help) constructor.

Only callable while your entry script is loading.

Parameters

Name	Type	Default	Description
name	string	—	Console name; same charset rules as commands. Must not collide with a command.
default	string	—	Default value. Numeric-looking strings gain int/float views engine-side.
flags	integer?	0	FCVAR_* bitmask. 128 = FCVAR_ARCHIVE (saved to config).
help	string?	""	Help text.

Return Value

Type	Description
boolean	true on success.

Errors

Same family as register_command (charset, collisions, frozen registration, flags range).

Example

usems.register_cvar(
    "my_greeting",
    "Hello, test subject!",
    128,                      -- FCVAR_ARCHIVE
    "What my_say greets you with"
)

-- game console:
--   my_greeting "Well done."     (persists across runs)

usems.get_cvar

usems.get_cvar(name)

Description

Reads the current string value of any PoZoUSEMS-registered cvar. Native engine cvars are not readable through this yet — that arrives with the ICvar FindVar binding.

Parameters

Name	Type	Description
name	string	The cvar’s console name.

Return Value

Type	Description
string?	Current value, or nil if no such USEMS cvar.

Example

usems.register_cvar("my_mode", "off", 0, "on/off")
usems.register_command("my_status", function()
    print(("mode is: %s"):format(usems.get_cvar("my_mode") or "<missing>"))
end, 0, "Show my_mode")

-- game console:
--   my_mode on
--   my_status
-- --> [my-mod] mode is: on

usems.hook

usems.hook(name, callback)

Description

Subscribes a callback to an engine hook — your code runs when the engine does something (every frame, later: tick, spawn, damage…). See Hooks for hook lifecycles and the full roadmap.

Only callable while your entry script is loading.

Parameters

Name	Type	Description
name	string	Hook name. Available: "frame".
callback	function	For "frame": function(dt) — dt is frametime in seconds.

Return Value

Type	Description
boolean	true on success.

Errors

• Unknown hook name (error lists what’s available).
• Frozen registration (called after load).

Example

local next_beat = os.clock() + 1.0
usems.hook("frame", function(dt)
    if os.clock() >= next_beat then
        next_beat = os.clock() + 1.0
        print(("dt=%.4f"):format(dt))
    end
end)