ss.console

The console namespace is a mod's way into the developer console, the ~ console of the Source engine recreated in the hook. A mod can run command lines, print to the console, read and set cvars, and add cvars and commands of its own that then behave like the built-in ones: help, find and cvarlist list them, Tab completes them, and archive cvars are saved to cfg\config.cfg with everything else.

Static members#

These elements are static to the class itself and can be accessed like so:

ss.console.exec("fps_max 144")

Static functions#

Commands#

A command is a name and a function. When the command is run, from the console, from a bind, from a cfg file or through ss.console.exec, the function receives one table with the arguments the console tokenised: quoted strings are one argument, and ; ends the command.

ss.console.register("magnet_strength", "Sets the magnet's pull, 0 to 10.", function(args)
	if args.n < 1 then
		ss.console.print("magnet_strength <0..10>")
		return
	end
	STRENGTH = math.min(10, math.max(0, tonumber(args[1]) or 0))
	ss.console.print("magnet strength is now", STRENGTH)
end)

The function runs on the game's main thread, so a slow one stalls the game for that long. An error inside it is printed in the console in the warning colour with a traceback, and the command stays registered. A command the mod does not want to be seen in find or Tab completion takes the hidden flag.

Cvar objects#

ss.console.cvar and ss.console.find return a live object: reading a field reads the cvar as it is now, and assigning value, number, int or bool sets it, clamped to the cvar's range, with its on_change run. Setting a value the cvar clamps prints the clamped value, as Source does. The sv_cheats gate is the command line's, not the cvar's, so it does not apply here.

local speed = ss.console.cvar("magnet_speed", "10", "How fast the magnet pulls.", { min = 0, max = 100 })
speed.number = 250            -- clamps to 100 and prints the clamp, as the console would
ss.console.print(speed.value) -- "100.000000"

local fps = ss.console.find("fps_max")
if fps and fps.int == 0 then ss.console.print("uncapped") end

Cvar options#

The keys of the opts table of ss.console.cvar. Every key is optional.

The same names, as a table or a number, are the fourth argument of ss.console.register.

From the console#

Two built-in commands run Lua the other way round. lua <code> runs the code in a script state of the console's own, with the whole ss API, and prints the results of an expression tab separated; print goes to the console there, not to the log. lua_mod <mod> <code> runs the code inside a mod's state, so a mod's globals can be read and changed while it runs; ss_mods lists the states by name. Both take the code as the rest of the line, quoted or not.

] lua return 1 + 1, ss.vehicle and ss.vehicle.speed_kmh
2	0
] lua_mod Magnet STRENGTH = 3
] magnet_strength
magnet_strength <0..10>

A mod's commands and cvars are gone with its state, so ss_mods is also where to look when a command of a mod is unknown: the mod has not loaded, or its script failed before the registration ran.

Example#

-- A cvar that turns the mod's overlay on and off, saved between runs, and a
-- command that reports where the player is.
local show = ss.console.cvar("hud_overlay", "1", "Show the mod's overlay.", {
	min = 0, max = 1, flags = { "archive" },
	on_change = function(new, old)
		ss.console.print("overlay", new == "1" and "on" or "off")
	end,
})

ss.console.register("whereami", "Prints the player's position.", function(args)
	local me = ss.vehicle
	if not me then
		ss.console.warning("not in a race")
		return
	end
	ss.console.print(string.format("%.1f %.1f %.1f", me.position.x, me.position.y, me.position.z))
end)

ss.on("draw", function(ev)
	if show.bool and ss.vehicle then
		ss.draw.text(string.format("%.0f km/h", ss.vehicle.speed_kmh), 20, 20, { size = 28 })
	end
end)