xhookLua
Game

engine

Clocks, console, toasts, local player and weapon, cvars, commands, chat, clipboard, sounds and viewmodel overrides.

Functions

print

print(...)
NameTypeDescription
...optionalanyValues, passed through tostring.

Same as engine.print.

Replaces Lua's standard print in scripts.

engine.print

engine.print(...)
NameTypeDescription
...optionalanyValues, passed through tostring.

Prints tab-joined values to console with a "[lua] " prefix.

engine.log

engine.log(...)
NameTypeDescription
...optionalanyValues to print.

Same as engine.print.

engine.notify

engine.notify([title [, body]])
NameTypeDescription
titleoptionalstringDefault "Lua".
bodyoptionalstringToast text. Default "".

Shows a toast notification.

Does nothing before notifications initialise.

engine.time

engine.time() -> number

Client clock in seconds, as game timestamps use; 0 if unavailable.

engine.real_time

engine.real_time() -> number

Seconds since Windows started (1 ms), runs while paused.

engine.perf_time

engine.perf_time() -> number

Sub-millisecond monotonic seconds; only differences between calls mean anything.

engine.tickcount

engine.tickcount() -> integer

Milliseconds since Windows started (engine.real_time() * 1000).

Not the game's tick or command number.

engine.frame_time

engine.frame_time() -> number

Last frame length in seconds; 0 before initialisation.

engine.frame_stats

engine.frame_stats() -> table

FPS 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() -> boolean

True while connected and in a map.

engine.max_players

engine.max_players() -> integer

Server maxplayers; player indices run 1 to this.

engine.map_name

engine.map_name() -> string

Current level path, like "maps/de_dust2.bsp", or "".

engine.map

engine.map() -> string

Short map name, like "de_dust2". "" with no map.

engine.frame_count

engine.frame_count() -> integer

Frames drawn since scripts started.

engine.net_info

engine.net_info() -> table

Ping, 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
NameTypeDescription
namestringLike "__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, number

Game window drawing area size.

Returns width, height in pixels

0, 0 before the overlay initialises.

engine.view_angles

engine.view_angles() -> Angle

Real camera angles in degrees, not silent command angles.

engine.set_view_angles

engine.set_view_angles(angles)
NameTypeDescription
anglesAngleDegrees.

Turns the visible camera; for silent aim edit cmd.viewangles.

Raises an error if not an Angle.

engine.local_player

engine.local_player() -> Entity | nil

Your player entity.

nil when not connected or not set up yet.

engine.local_weapon

engine.local_weapon() -> table | nil

Snapshot 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]])
NameTypeDescription
sequenceintegerIndex from engine.viewmodel_sequence.
durationoptionalnumberSeconds to hold; <= 0 becomes 3. Default 3.0.
framerateoptionalnumberFps 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() -> integer

Sequence the viewmodel is playing; print it to find indices.

Returns -1 without a viewmodel

engine.viewmodel_frame

engine.viewmodel_frame() -> number

Viewmodel animation frame, 0 (first) to 255 (last).

Returns -1 without a viewmodel

engine.viewmodel_sequence_count

engine.viewmodel_sequence_count() -> integer

Sequence 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)
NameTypeDescription
forwardnumberAlong view direction, world units.
rightnumberWorld units.
upnumberWorld 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)
NameTypeDescription
pitchnumberDegrees.
yawnumberDegrees.
rollnumberDegrees.

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])
NameTypeDescription
filestringAbsolute with ':', else <settings_path>sounds\.
volumeoptionalnumber0 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
NameTypeDescription
namestring
defaultoptionalstringDefault "0".
flagsoptionalintegerFCVAR_* 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)
NameTypeDescription
namestring
fnfunctionfn(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() -> table

Hit 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])
NameTypeDescription
textstring
teamoptionalbooleantrue 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() -> string

Reads Windows clipboard text, or "".

engine.set_clipboard

engine.set_clipboard(text)
NameType
textstring

Copies text to the Windows clipboard.

engine.exec

engine.exec(command)
NameTypeDescription
commandstringLike "+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
NameType
namestring

Reads a cvar as a number.

Unknown cvars read as 0.

engine.get_cvar_string

engine.get_cvar_string(name) -> string
NameType
namestring

Reads a cvar as a string, "" if missing.

engine.set_cvar

engine.set_cvar(name, value)
NameTypeDescription
namestringTruncated to 127 characters.
valuenumber | stringNumeric 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() -> string

Per-game data folder (configs, sounds, scripts), ending in a backslash.

Empty string before initialisation.

engine.set_thirdperson

engine.set_thirdperson(enabled)
NameType
enabledboolean

Toggles thirdperson, same as the menu checkbox.

Changes the menu setting; unload doesn't restore it.

engine.is_thirdperson

engine.is_thirdperson() -> boolean

Live view state; false while dead or spectating, even if enabled.

Fields

engine.local_weapon() table

NameTypeDescription
idinteger
namestringLike "ak47"; "unknown" if unnamed.
clipintegerRounds in the magazine.
in_reloadboolean
shots_firedintegerConsecutive shots in current spray.
spreadnumberPredicted spread cone.
accuracynumber
next_attacknumberPrimary attack countdown, seconds; <= 0 fires.
rangenumberMax bullet distance, world units.
silencedbooleanSilencer on (M4A1, USP).
reserveintegerRounds in reserve. nil until the game sends them (only when they change).
max_reserveintegerMost it can carry in reserve.
can_attackbooleanCan fire this command.
next_secondary_attacknumberLike next_attack, for alt fire.
is_grenadeboolean
is_sniperboolean
is_pistolboolean
is_knifeboolean
punchAngleRecoil kick right now; the bullet leaves at twice it.
engine ยท Lua API ยท xhook