engine
Clocks, console, toasts, local player and weapon, cvars, commands, chat, clipboard, sounds and viewmodel overrides.
Functions
print(...)| Name | Type | Description |
|---|---|---|
| ...optional | any | Values, passed through tostring. |
Same as engine.print.
Replaces Lua's standard print in scripts.
engine.print
engine.print(...)| Name | Type | Description |
|---|---|---|
| ...optional | any | Values, passed through tostring. |
Prints tab-joined values to console with a "[lua] " prefix.
engine.log
engine.log(...)| Name | Type | Description |
|---|---|---|
| ...optional | any | Values to print. |
Same as engine.print.
engine.notify
engine.notify([title [, body]])| Name | Type | Description |
|---|---|---|
| titleoptional | string | Default "Lua". |
| bodyoptional | string | Toast text. Default "". |
Shows a toast notification.
Does nothing before notifications initialise.
engine.time
engine.time() -> numberClient clock in seconds, as game timestamps use; 0 if unavailable.
engine.real_time
engine.real_time() -> numberSeconds since Windows started (1 ms), runs while paused.
engine.perf_time
engine.perf_time() -> numberSub-millisecond monotonic seconds; only differences between calls mean anything.
engine.tickcount
engine.tickcount() -> integerMilliseconds since Windows started (engine.real_time() * 1000).
Not the game's tick or command number.
engine.frame_time
engine.frame_time() -> numberLast frame length in seconds; 0 before initialisation.
engine.frame_stats
engine.frame_stats() -> tableFPS now, plus average, min and max over about 90 samples.
Returns table {fps, avg_fps, min_fps, max_fps, frame_ms}
- Each call adds a sample; call once per frame, like on_paint.
- All scripts share the sample history.
engine.is_in_game
engine.is_in_game() -> booleanTrue while connected and in a map.
engine.max_players
engine.max_players() -> integerServer maxplayers; player indices run 1 to this.
engine.map_name
engine.map_name() -> stringCurrent level path, like "maps/de_dust2.bsp", or "".
engine.map
engine.map() -> stringShort map name, like "de_dust2". "" with no map.
engine.frame_count
engine.frame_count() -> integerFrames drawn since scripts started.
engine.net_info
engine.net_info() -> tablePing, loss and choke like net_graph.
Returns {ping, loss, choke, seq, ack}, nil when not connected
- ping is ms, loss and choke are %.
- seq is the command being sent, ack the last one the server confirmed.
engine.text_message
engine.text_message(name) -> text, x, y| Name | Type | Description |
|---|---|---|
| name | string | Like "__NETMESSAGE__3". |
Text of a HUD message by name.
Returns nil when there is no such message
- Server HUD messages arrive as HudText: hook it with net.hook_message and look the name up here.
- x, y are 0..1, -1 = centred.
engine.screen_size
engine.screen_size() -> number, numberGame window drawing area size.
Returns width, height in pixels
0, 0 before the overlay initialises.
engine.view_angles
engine.view_angles() -> AngleReal camera angles in degrees, not silent command angles.
engine.set_view_angles
engine.set_view_angles(angles)| Name | Type | Description |
|---|---|---|
| angles | Angle | Degrees. |
Turns the visible camera; for silent aim edit cmd.viewangles.
Raises an error if not an Angle.
engine.local_player
engine.local_player() -> Entity | nilYour player entity.
nil when not connected or not set up yet.
engine.local_weapon
engine.local_weapon() -> table | nilSnapshot of your active weapon from prediction; doesn't update.
Returns Weapon table (see fields).
nil when not in game.
engine.play_weapon_anim
engine.play_weapon_anim(sequence [, duration [, framerate]])| Name | Type | Description |
|---|---|---|
| sequence | integer | Index from engine.viewmodel_sequence. |
| durationoptional | number | Seconds to hold; <= 0 becomes 3. Default 3.0. |
| framerateoptional | number | Fps multiplier; <= 0 becomes 1. Default 1.0. |
Plays a viewmodel sequence from frame 0, like a knife inspect.
- Out-of-range index plays sequence 0.
- New calls replace it; script unload or losing the viewmodel clears it.
engine.stop_weapon_anim
engine.stop_weapon_anim()Cancels a play_weapon_anim override.
engine.viewmodel_sequence
engine.viewmodel_sequence() -> integerSequence the viewmodel is playing; print it to find indices.
Returns -1 without a viewmodel
engine.viewmodel_frame
engine.viewmodel_frame() -> numberViewmodel animation frame, 0 (first) to 255 (last).
Returns -1 without a viewmodel
engine.viewmodel_sequence_count
engine.viewmodel_sequence_count() -> integerSequence count of the held viewmodel; valid indices 0 to count-1.
0 without a viewmodel or valid studio model.
engine.set_viewmodel_offset
engine.set_viewmodel_offset(forward, right, up)| Name | Type | Description |
|---|---|---|
| forward | number | Along view direction, world units. |
| right | number | World units. |
| up | number | World units. |
Shifts the viewmodel along view axes until changed or reset.
Shares one override with set_viewmodel_angles; drops on script unload.
engine.set_viewmodel_angles
engine.set_viewmodel_angles(pitch, yaw, roll)| Name | Type | Description |
|---|---|---|
| pitch | number | Degrees. |
| yaw | number | Degrees. |
| roll | number | Degrees. |
Rotates the viewmodel by these degrees until changed or reset.
Absolute offsets, not accumulated across calls.
engine.reset_viewmodel
engine.reset_viewmodel()Clears viewmodel offset and angle overrides.
Doesn't stop play_weapon_anim.
engine.play_sound
engine.play_sound(file [, volume])| Name | Type | Description |
|---|---|---|
| file | string | Absolute with ':', else <settings_path>sounds\. |
| volumeoptional | number | 0 to 1, clamped. Default 1.0. |
Plays a sound only you hear.
Does nothing if sound isn't ready.
engine.register_cvar
engine.register_cvar(name [, default [, flags]]) -> boolean| Name | Type | Description |
|---|---|---|
| name | string | |
| defaultoptional | string | Default "0". |
| flagsoptional | integer | FCVAR_* bits; 1 = archive. Default 0. |
Creates a cvar usable from get_cvar, set_cvar and console.
Returns Always true.
- Existing cvar: nothing changes, default ignored.
- Can't be removed; persists until the game exits.
engine.add_command
engine.add_command(name, fn)| Name | Type | Description |
|---|---|---|
| name | string | |
| fn | function | fn(args): args[1] command, rest arguments. |
Adds a console command, usable from binds and engine.exec.
- Re-registering replaces the callback; after unload the command does nothing.
- Raises an error outside a running script.
engine.hit_stats
engine.hit_stats() -> tableHit and miss totals plus details of the last hit.
Returns table {hits, misses, last_damage, last_hitgroup, last_hitbox, last_headshot, last_victim, last_weapon_id, last_time}
All fields 0 or false before hit registration starts.
engine.say
engine.say(text [, team])| Name | Type | Description |
|---|---|---|
| text | string | |
| teamoptional | boolean | true sends to say_team. Default false. |
Sends a chat message as you.
Sanitised: " becomes ', ; becomes comma, newline becomes space.
engine.get_clipboard
engine.get_clipboard() -> stringReads Windows clipboard text, or "".
engine.set_clipboard
engine.set_clipboard(text)| Name | Type |
|---|---|
| text | string |
Copies text to the Windows clipboard.
engine.exec
engine.exec(command)| Name | Type | Description |
|---|---|---|
| command | string | Like "+jump"; newline added if missing. |
Runs a console line as if typed; ';' separates commands.
No filtering: server-forwarded commands run too.
engine.get_cvar
engine.get_cvar(name) -> number| Name | Type |
|---|---|
| name | string |
Reads a cvar as a number.
Unknown cvars read as 0.
engine.get_cvar_string
engine.get_cvar_string(name) -> string| Name | Type |
|---|---|
| name | string |
Reads a cvar as a string, "" if missing.
engine.set_cvar
engine.set_cvar(name, value)| Name | Type | Description |
|---|---|---|
| name | string | Truncated to 127 characters. |
| value | number | string | Numeric sets a number; text caps 255. |
Sets a cvar directly, bypassing the console.
Changes persist after the script unloads.
engine.settings_path
engine.settings_path() -> stringPer-game data folder (configs, sounds, scripts), ending in a backslash.
Empty string before initialisation.
engine.set_thirdperson
engine.set_thirdperson(enabled)| Name | Type |
|---|---|
| enabled | boolean |
Toggles thirdperson, same as the menu checkbox.
Changes the menu setting; unload doesn't restore it.
engine.is_thirdperson
engine.is_thirdperson() -> booleanLive view state; false while dead or spectating, even if enabled.
Fields
engine.local_weapon() table
| Name | Type | Description |
|---|---|---|
| id | integer | |
| name | string | Like "ak47"; "unknown" if unnamed. |
| clip | integer | Rounds in the magazine. |
| in_reload | boolean | |
| shots_fired | integer | Consecutive shots in current spray. |
| spread | number | Predicted spread cone. |
| accuracy | number | |
| next_attack | number | Primary attack countdown, seconds; <= 0 fires. |
| range | number | Max bullet distance, world units. |
| silenced | boolean | Silencer on (M4A1, USP). |
| reserve | integer | Rounds in reserve. nil until the game sends them (only when they change). |
| max_reserve | integer | Most it can carry in reserve. |
| can_attack | boolean | Can fire this command. |
| next_secondary_attack | number | Like next_attack, for alt fire. |
| is_grenade | boolean | |
| is_sniper | boolean | |
| is_pistol | boolean | |
| is_knife | boolean | |
| punch | Angle | Recoil kick right now; the bullet leaves at twice it. |