Only this pageAll pages
Powered by GitBook
Couldn't generate the PDF for 108 pages, generation stopped at 100.
Extend with 50 more pages.
1 of 100

CS2 Lua API

Loading...

Introduction

Loading...

Loading...

Loading...

Loading...

API

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Overview

Official lua API documentation for fatality.win​

Creating Libraries

Libraries are not yet supported, but will be available soon.

Types

In this section, the most common renderer types are listed, that are not particularly bound to a specific part of the renderer.

Use the left menu (or hamburger menu on mobile) to navigate between types.

convar

Represents a convar used by the game.

name

FieldRead only

Type: string


description

FieldRead only

Type: string


flags

FieldRead only

Type: int


value

FieldRead only

Type: <type>

The value of the convar represented in its type

observer_mode_t

This enum represents the observer modes available in the game.


none

Represents no observer mode (not spectating anyone).


fixed

Represents a fixed camera position.


in_eye

Represents observing from the perspective of the player being spectated.


chase

Represents a chase camera that follows the player being spectated.


roaming

Represents a free-roaming camera.


directed

Represents an automatically directed camera, typically controlled by the game or server.

csweapon_mode

This enum represents the firing mode for a weapon.

primary_mode

Primary mode (usually left mouse button).


secondary_mode

Secondary mode (usually right mouse button).

render_mode

This enum is used to toggle rendering modes.

normal

Normal, opaque rendering. All polygons will get filled with color, and texture sampling will be fully supported. This is the default mode to render shapes in layer.


wireframe

Wireframe rendering. This means that the polygons will no longer be filled with color, nor texture sampling will ever work.

Adding UI

Adding UI

Now that you know the basics, let’s extend our script by allowing the user to toggle the text. We can do this by adding a control to the menu.

Creating a control

Let’s start by creating a simple checkbox:

local cb = gui.checkbox(gui.control_id('my_checkbox'));

Each control has a unique ID, which the UI framework uses to distinguish controls within containers. It’s very important that your control’s ID doesn’t conflict with others, as that could result in a broken state or worse.

To create the ID, call gui.control_id and pass the desired ID.

Then, create the checkbox by calling gui.checkbox and passing the ID structure you've created.

Constructing the row

By default, controls are typically placed in rows - layouts that stack elements in a specific manner. We provide a simple helper function - gui.make_control.

local row = gui.make_control('My checkbox', cb);

Adding the row to a group

With the control and row ready, let’s add them to a group.

To view group and control IDs, you can enable Debug mode in the SCRIPTS tab.

In this example, we'll use the lua>elements a group. First, locate that group in the global context:

local group = gui.ctx:find('lua>elements a');

Then call its add method to include your row:

group:add(row);

That's it!

It is very important to call reset() method if you add multiple controls, so the layout will stack everything correctly.

Using the value

Next, let’s modify our previous script so the text only appears if the checkbox is checked. Wrap your drawing code in an if statement before rendering the text:

if cb:get_value():get() then

and close it after.

The final script should look something like this:

local cb = gui.checkbox(gui.control_id('my_checkbox'));
local row = gui.make_control('My checkbox', cb);
local group = gui.ctx:find('lua>elements a');
group:add(row);

local function on_present_queue()
    if cb:get_value():get() then
        local d = draw.surface;
        d.font = draw.fonts['gui_main'];
        d:add_text(draw.vec2(50, 50),
            'Hello drawing! My first script speaking.',
            draw.color.white()
        );
    end
end

events.present_queue:add(on_present_queue);

And here's the result:

Mods

Usage: mods.{mod_name}

This table exposes several mods (short for Module, not Modification), that Fatality uses to operate.

events

Field

Type:

Event manager. Use this mod if you want to listen to more in-game events.

events_t

Usage: mods.events.{method}

This module lets you manage custom in-game event listener.

Please note that the game server knows which events you are listening to. Internally, we only listen to events that will get sent to the client anyway in one way or another. If you decide to listen to something the server generally does not expect, it may cause issues on official servers.

add_listener

Method

Adds a game event to the listener.

Internally we listen to the following events:

  • bullet_impact

  • weapon_fire

  • bomb_beginplant

  • bomb_abortplant

  • bomb_planted

  • bomb_defused

  • bomb_exploded

  • round_start

  • game_newmap

  • map_shutdown

Adding those events to the listener is not needed.

Arguments

Name
Type
Description

Returns

Nothing.

Example

name

string

Event name.

mods.events:add_listener('round_end');

events_t

Game

Usage: game.{interface_or_function}

This table exposes various internal services and global objects used by Fatality, and also provides a way to retrieve any additional services you need.

global_vars

Field

Type:

This service exposes global variables used by the game, such as frame time or current server time.


engine

Field

Type:

This service exposes the engine client, which includes commonly used engine-related functions.


input

Field

Type:

This service exposes the command input system.


input_system

Field

Type:

This service exposes the control input system.


game_ui_funcs

Field

Type:

This service exposes the game's UI functions.

global_vars_t

Usage:

game.global_vars.{field}

Usage: game.global_vars.{field}

An instance of this type provides a way to read several global variables that are used by the game. Changing any of the values is not and will never be supported.

real_time

Field

Type: float

Time passed since the game start, in seconds.


frame_count

Field

Type: int

Amount of frames rendered since the game start.


abs_frame_time

Field

Type: float

Absolute (averaged) frame time. It is calculated over a set of previous frame times, and should not be used for anything that requires accurate frame time like animation.


max_clients

Field

Type: int

Maximum amount of clients on the current server.


ticks_this_frame

Field

Type: int

Amount of ticks passed during the currently rendered frame. Any value above 1 might indicate a stall during rendering.


frame_time

Field

Type: float

Time, in which a previous frame was rendered. May be used for animation or by any other means that require accurate frame time.


cur_time

Field

Type: float

Time passed since the server's game start. This does not indicate the accurate time on the server, although in several events it might be synced by the software.


tick_fraction

Field

Type: float

Current tick's fractional value.


tick_count

Field

Type: int

Ticks passed since the server's game start.


map_path

Field

Type: string

Relative path to current loaded map's file.


map_name

Field

Type: string

Name of the currently loaded map.

outline_mode

This enum is used to determine the outline mode for outlined shapes.

inset

Inset outlining. This means that the outline will be inside the shape (+1px from top-left, -1px from bottom-right).


outset

Outset outlining. This means that the outline will be outside of the shape (-1px from top-left, +1px from bottom-right).


center

Center outlining. This means that the outline will match the shape size.

cinput_system

Usage: game.input_system:{method}

This type represents the game's control input system.

vk_to_button_code

Method

Converts a virtual key to button code.

Arguments

Name
Type
Description

vk

int

Virtual key.

Returns

Type
Description

int

Button code.

Example

local button = game.input_system:vk_to_button_code(0x41); -- 'A'

cgame_ui_funcs

Usage: game.game_ui_funcs:{method}

This type represents the game's UI functions.

get_binding_for_button_code

Method

Returns the binding name for a button code.

Arguments

Name
Type
Description

code

int

Button code.

Returns

Type
Description

string

Binding.

Example

local bind = game.game_ui_funcs:get_binding_for_button_code(code);

text_alignment

This enum determines how to align the text when drawing it.

left and top, as well as right and bottom are interchangeable. It means that if you use left for vertical alignment, it will produce exactly the same result as using top, and vice versa. top/bottom are here only for the sake of convenience and readability.

left

Align left. It will mean that the text position's X coordinate is located at the left side of the text area.


center

Align center. It will mean that the text position's X (or Y) coordinate is located at the center of the text area.


right

Align right. It will mean that the text position's X coordinate is located at the right side of the text area.


top

Align top. It will mean that the text position's Y coordinate is located at the top side of the text area.


bottom

Align bottom. It will mean that the text position's Y coordinate is located at the bottom side of the text area.

rounding

rounding

Last modified: 03 January 2025

This enum is used to determine the rounding for rounded shapes.

tl

Round top-left corner.


tr

Round top-right corner.


bl

Round bottom-left corner.


br

Round bottom-right corner.


t

Round both of the top corners. This produces the same result as using bit.bor(draw.rounding.tl, draw.rounding.tr).


l

Round both of the left corners. This produces the same result as using bit.bor(draw.rounding.tl, draw.rounding.bl).


r

Round both of the right corners. This produces the same result as using bit.bor(draw.rounding.tr, draw.rounding.br).


b

Round both of the bottom corners. This produces the same result as using bit.bor(draw.rounding.bl, draw.rounding.br).


all

Round all corners. This produces the same result as using bit.bor(draw.rounding.tl, draw.rounding.tr, draw.rounding.bl, draw.rounding.br).

entity_list_t

This type represents an entity list.

Never save any entities you get from this list if you don't know what you are doing! You may be left with dangling pointers, which will inevitably lead to a crash.

for_each

Loops the entities.

Arguments

Name

Type

Description

fn

function(entity_entry_t)

Function callback.

Returns

Nothing.

Example

entities.players:for_each(function (entry)
    -- ...
end);

for_each_z

Loops the entities in the reverse order.

Arguments

Name

Type

Description

fn

function(entity_entry_t)

Function callback.

Returns

Nothing.

Example

entities.players:for_each_z(function (entry)
    -- ...
end);

Instances

csweapon_category

This enum represents the category classification for weapons in the game.

other

Represents weapons or items that don't fit into any specific category.


melee

Represents melee weapons, such as knives or other close-combat tools.


secondary

Represents secondary weapons, such as pistols.


smg

Represents submachine guns (SMGs).


rifle

Represents rifles, including assault rifles and sniper rifles.


heavy

Represents heavy weapons, such as machine guns and shotguns.

event_t

Event usertype. An instance of this type can be found in events.

add

Method

Adds a callback to the event.

Arguments

Name
Type
Description

fn

function

Callback function. Arguments that are accepted by the function are dictated by the event instance.

Returns

Nothing.

Example

events.present_queue:add(function ()
    -- will be called every time game queues a frame for rendering
end);

remove

Method

Removes a callback from the event.

Arguments

Name
Type
Description

fn

function

Callback function, that was earlier passed to the add() function.

Returns

Nothing.

Example

local function on_present()
    if some_condition then
        events.present_queue:remove(on_present)
    end
end

events.present_queue:add(on_present)

font_flags

This enum determines which flags a font object should possess. Setting those flags is only possible during type construction.


shadow

Adds a 1px shadow to font glyphs.


outline

Adds a 1px outline to font glyphs.


anti_alias

Enable antialiasing on font glyphs. This flag only works on GDI fonts.


no_dpi

Disable DPI scaling on this font. By default, font glyphs will be scaled in accordance to the global DPI scale.


no_kern

Disable glyph kerning on this font.


mono

Enables a strong hinting algorithm for rasterization. Only works on FreeType fonts.


light

Enables a light hinting algorithm for rasterization. Only works on FreeType fonts.

shadow_dir

This enum is used to determine shadow direction for add_shadow_line method.

up

The darkest side of the shadow will be at the bottom.


down

The darkest side of the shadow will be at the top.


left

The darkest side of the shadow will be on the left side.


right

The darkest side of the shadow will be on the right side.

ccvar

Usage:

Usage: game.cvar:{method}

This type represents the game's cvar system.

find

Method

Get the game's cvar under this name.

Arguments

Name

Type

Description

name

string

Var name.

Returns

Type

Description

Convar object.

Example

local sv_quantize_movement_input = game.cvar:find('sv_quantize_movement_input')
if not sv_quantize_movement_input then
    error('sv_quantize_movement_input not found')
end

Global Functions

Below is a list of all global functions. By “global”, we mean these functions do not require a preceding namespace - so you can call them directly, unlike other functions.

print

Function

Prints text to game's console.

Arguments

Name
Type
Description

...

...

Values to print in the console.

Example

print('Hello world!', 123); -- prints out "Hello world! 123" to the console


error

Function

Prints an error text to game's console, and shuts down the script. Try to avoid using this function - use it only if an error happens which you can't recover from.

Arguments

Name
Type
Description

text

string

Read for documentation.

Example

error('Can't recover from this one! Error: ' .. tostring(123));

Adapter

This type represents a rendering adapter used within the rendering system.

get_back_buffer

Returns a back buffer texture. May return a blank or outdated texture, if the back buffer texture was not updated.

Arguments

None.

Returns

Example


get_back_buffer_downsampled

Returns a 4x down sampled version of the back buffer texture.

Arguments

None.

Returns

Example


get_shared_texture

Returns a shared texture. This texture usually replicates the down sampled back buffer texture, although it is updated automatically ONCE before the rendering on the layer starts.

Arguments

None.

Returns

Example

svg_texture

This type represents an SVG texture object.

This type inherits type. All of its base methods and fields are also available in this type.

Passing invalid SVG data to the constructor will cause a crash. We will fix this issue in future updates.

__call

Constructs an SVG texture.

Arguments

Returns

Example

cs2_weapon_base

This type represents a CCSWeaponBase entity.

This type inherits type. All of its base methods and fields are also available in this type.

get_abs_origin

Returns the absolute origin (the one that is used for rendering).

Arguments

None.

Returns

Example

get_id

Returns the weapon ID.

Arguments

None.

Returns

Example

get_type

Returns the weapon type.

Arguments

None.

Returns

Example

get_data

Returns the weapon static data.

Arguments

None.

Returns

Example

font_gdi

This type represents a font object. Internally, this type uses GDI library to rasterize font glyphs.

This type inherits type. All of its base methods and fields are also available in this type.

__call

Constructs a font object.

Arguments

Returns

Example

schema_accessor_t

This type represents a special structure that references a certain field in the entity object.

You can check the returned type by using type() function.

Do not ever store an instance of this type anywhere but in a scope of an event because entity might be removed.

get

Returns the value.

Arguments

None.

Returns

Example

set


Sets the value.

Arguments

Returns

Nothing.

Example

ccsweapon_base_vdata

This type represents a weapon's static data.

__index

Attemps to search for a field in this class.

Arguments

Returns

Example

glyph_t

This type represents a glyph object.

codepoint

Type: int

Character codepoint.


size

Type:

Glyph dimensions.


offset

Type:

Glyph offset.


uv

Type:

UV rect on the texture atlas.

ccsgo_input

Usage: game.input.{field_or_method}

This type represents the game's command input system.

in_third_person

FieldRead only

Type: bool

true if currently in the third person.


get_view_angles

Method

Returns current camera view angles.

Arguments

None.

Returns

Type
Description

Example


set_view_angles

Method

Sets new camera view angles.

Arguments

Name
Type
Description

Returns

Nothing.

Example

entity_entry_t

Represents an entity entry.

entity

Type: <type>

Entity instance. Type depends on the list you get it from.


had_dataupdate

Type: bool

true if the client had received any updates to this entity at least once.


handle

Type:

Entity's handle. You may store this elsewhere if you need to have global access to an entity.


avatar

Type:

This field is only available on entries that use cs2_player_controller type.

Player's profile picture. Will be nil if was yet to be initialized.

Type

Description

ptr

Back buffer texture pointer.

local bb = adapter:get_back_buffer();

Type

Description

ptr

Downsampled back buffer texture pointer.

local ds = adapter:get_back_buffer_downsampled();

Type

Description

ptr

Shared texture pointer.

local shared = adapter:get_shared_texture();

Type

Description

<type>

Value.

local health = player.m_iHealth:get();

Name

Type

Description

value

<type>

Value.

player.m_iHealth:set(50); -- won't really do anything with the health

Name

Type

Description

name

string

Field name.

Type

Description

schema_accessor_t

Accessor instance.

local price = wpn_data.m_nPrice;
local price = wpn_data['m_nPrice']; -- this also works

vector

View angles.

local ang = game.input:get_view_angles();

ang

vector

View angles.

game.input:set_view_angles(math.vec3(0, 0, 0));
convar
print

Name

Type

Description

sv

string

SVG text.

h

float

Target height. Defaults to 0, and 0 means that there will be no automatic downscale.

Type

Description

svg_texture

SVG texture object.

local lightning = draw.svg_texture([[
<svg width="800px" height="800px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M9.55563 13.3232L9.43584 13.3123C7.90803 13.1735 7.14412 13.104 6.90146 12.5814C6.65881 12.0588 7.09869 11.4304 7.97846 10.1736L11.5612 5.05544C12.1424 4.22517 12.433 3.81003 12.6836 3.89831C12.9342 3.98658 12.9005 4.4922 12.8331 5.50343L12.6299 8.55194C12.5685 9.47214 12.5379 9.93224 12.8023 10.2419C13.0667 10.5515 13.5259 10.5933 14.4444 10.6768L14.5642 10.6877C16.092 10.8265 16.8559 10.896 17.0985 11.4186C17.3412 11.9412 16.9013 12.5696 16.0215 13.8264L12.4388 18.9446C11.8576 19.7748 11.567 20.19 11.3164 20.1017C11.0658 20.0134 11.0995 19.5078 11.1669 18.4966L11.3701 15.4481C11.4315 14.5279 11.4621 14.0678 11.1977 13.7581C10.9333 13.4485 10.4741 13.4067 9.55563 13.3232Z" fill="#ffffff"/>
<path d="M18.5 4L17 6H19L17.5 8" stroke="#ffffff" stroke-opacity="0.6" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M6.5 16L5 18H7L5.5 20" stroke="#ffffff" stroke-opacity="0.6" stroke-linecap="round" stroke-linejoin="round"/>
</svg>
]], 24);
texture

Type

Description

vector

Origin.

local org = wep:get_abs_origin();

Type

Description

weapon_id

Weapon ID.

local wep_id = wep:get_id();

Type

Description

csweapon_type

Weapon type.

local type = wep:get_type();

Type

Description

ccsweapon_base_vdata

Weapon data.

local data = wep:get_data();
base_entity

Name

Type

Description

name

string

System font name (example: 'Arial').

size

float

Font height, in pixels.

fl

font_flags

Font flags. Use bit library to construct them. Defaults to 0.

mi

int

Starting codepoint. Defaults to 0.

ma

int

Ending codepoint. Defaults to 255 (entire ASCII code page).

weight

int

Font weight. Defaults to 400 (regular).

Type

Description

font_gdi

Font object.

local sys_font = draw.font_gdi('Calibri', 14);
font_base
vec2
vec2
rect
chandle<type>
texture

Creating scripts

Welcome to the basics of scripting with our API.

Fatality’s API is designed to mirror the software’s internal structure, giving you substantial control over its subsystems. Some features that could cause instability or damage are restricted.

Basic Concepts

Our scripting engine uses LuaJIT 2.1 (with minor customizations). It’s fully compatible with Lua 5.1 and includes some Lua 5.2 enhancements.

The standard libraries baselib, bit, ffi, math, string and table are available. Note that the ffi library is only available if the Allow insecure option is enabled. Refer to the official Lua documentation for more details.

If we ever modify any standard functions, we will document those changes to keep you informed.

Documentation Overview

Throughout the API reference, you’ll encounter various labels used to describe a certain method or a field.

Labels:

Field Function Method Constructor Read only Insecure only

All the possible labels are listed above.

  • Field: this label indicates that the item is a standard field. It's type will be explained just below the name.

  • Function: this label indicates that the item is a function, which you call using a dot syntax (obj.fn()).

  • Method: this label indicates that the item is a method, which is also a function, but it's advised to call it with the colon syntax (obj:fn()).

  • Constructor: this label indicates that the item is a constructor definition. You don't have to call any field in particular, but instead you must invoke the type itself (example: vector has __call, meaning you should invoke it like this: vector()).

  • Read Only: this label indicates that the item is read only, and it's value cannot be changed. Typically, this restriction does not extend to any child elements.

  • Insecure only: this label indicates that the item is only available if the insecure mode is turned on.

Argument and return lists

Arguments and return values are listed in the exact order you must supply or capture them. For instance, if a parameter is shown first, it is to be passed as the first argument to the function. The same goes for return values: the first listed value will be placed in the first variable you declare, and so on.

Types

Some type descriptions have special symbols in place:

  • type? means that the type might be nil.

  • type<other> means that inner methods or fields will use other type.

  • <other> means that the type will be either other, or any of its child types.

Rules

To keep your scripts safe and easy to use, we have quite a lot of safety measures in place. But, due to how specific stuff works, we are unable to fully make it as safe as possible. Therefore, here are some notes you should know before writing scripts:

You Control the Lua State

You may replace or override API functions, but you’re responsible for maintaining stable behavior. If you encounter any bugs in the default API (excluding FFI), please report them so we can address the issue.

Prioritize Safety

Using FFI grants you extensive freedom. Keep in mind that scripts which could harm users in any way are disallowed and will be removed. Whenever possible, rely on the provided API or request additional functionality if you need something not currently offered. Custom “script loaders” are strictly disallowed.

Keep the Software Usable

Avoid hiding unrelated UI elements, obstructing user input, or interfering with the overall user experience. Scripts that disrupt functionality or harass users risk removal from the Workshop.

cnet_chan

Provides a way to interface with a Network Channel's class.

get_address

Method

If the current channel is null, this function will return nil instead.

Returns address string of the remote machine.

Arguments

None.

Returns

Type

Description

string?

IP-address or Steam Server Address.

Example

local chan = game.engine:get_netchan();
if chan and not chan:is_null() then
    print(chan:get_address());
end

is_loopback


Method

If the current channel is null, this function will return nil instead.

Returns whether the current channel is connected to the local machine (loopback address).

Arguments

None.

Returns

Type

Description

bool?

true if connected to the local machine.

Example

local chan = game.engine:get_netchan();
if chan and not chan:is_null() and chan:is_loopback() then
    print('Connected to localhost!');
end

is_null

Method

Returns whether the channel is stubbed.

Arguments

None.

Returns

Type

Description

bool

true if current channel is a dummy channel.

Example

local chan = game.engine:get_netchan();
if not chan or chan:is_null() then
    print('Not connected!');
end

get_latency

Method

If the current channel is null, this function will return nil instead.

Returns current latency to the remote server (in seconds).

Arguments

None.

Returns

Type

Description

float?

Latency (in seconds).

Example

local chan = game.engine:get_netchan();
if chan and not chan:is_null() then
    print('Current latency: ' .. tostring(math.round(chan:get_latency() * 1000.0)) .. 'ms');
end

glow_parts

This enum is used to determine which parts of the glow around the shape should get rendered.

tl

Draw top-left corner.


tr

Draw top-right corner.


bl

Draw bottom-left corner.


br

Draw bottom-right corner.


t

Draw top line.


l

Draw left line.


r

Draw right line.


b

Draw bottom line.


all_left

Draw all the left side shapes. This includes both left corners and the line.


all_right

Draw all the right side shapes. This includes both right corners and the line.


all_top

Draw all the top side shapes. This includes both top corners and the line.


all_bottom

Draw all the bottom side shapes. This includes both bottom corners and the line.


all

Draw the entire glow around the shape.


no_bottom

Draw glow except for the bottom line.


no_top

Draw glow except for the top line.


no_right

Draw glow except for the right line.


no_left

Draw glow except for the left line.

chandle

This type represents an entity handle.

You can also compare this type using a == operator.

get

Returns the entity, or nil if nothing found.

Arguments

None.

Returns

Type

Description

<type>

Entity instance.

Example

local ent = handle:get();

valid

Returns true if the handle is valid.

Arguments

None.

Returns

Type

Description

bool

true if valid.

Example

if handle:valid() then
    -- ...
end

is_clientside

Returns true if the handle links to a client-side entity.

Arguments

None.

Returns

Type

Description

bool

true if client-sided.

Example

if handle:is_clientside() then
    -- ...
end

Managed

This type represents a managed object. You cannot create an instance of this type directly.

Every object, that inherits from this type, must be created before use. The rendering system will only create them automatically, if you happen to lose a device object (e.g. minimize the game window, and then restore it) and only if you add your objects to manage table in draw.

obj

Type: ptr

Pointer to a GPU object. If this object is not created, this field will be nil. You can use the value of this field to pass it to command directly for example, or if you (for whatever reason we don't recommend you doing) want to have a direct control over the pointer - cast it to FFI's cdata.


create

Creates a managed object in GPU memory.

You should create() an object only once. Invoking this method after the object was created will be meaningless.

Arguments

None.

Returns

Nothing.

Example

tex:create();

destroy

Destroys a managed object in GPU memory.

Never destroy a GPU object if it is being used in rendering (for example, when you have pushed some shape that uses a texture, and then destroyed that texture). This will lead to undefined behavior, and most likely, **crash the game **.

Arguments

None.

Returns

Nothing.

Example

font:destroy();

control_id

This type represents a control ID.

__call

Constructs the ID structure.

Arguments

Name

Type

Description

id

string

ID.

Returns

Type

Description

control_id

ID structure.

Example

local id = gui.control_id('my_id');

id

Type: int

Hashed representation of the ID.


id_string

Type: string

Normal representation of the ID.

user_t

This type represents basic user information.

avatar

Type: texture?

User's avatar. May be nil.


username

Type: string

User's username.

csweapon_type

This enum represents the weapon type in the game.

knife

Represents a knife-type weapon.


pistol

Represents a pistol-type weapon.


submachinegun

Represents a submachine gun-type weapon.


rifle

Represents a rifle-type weapon.


shotgun

Represents a shotgun-type weapon.


sniper_rifle

Represents a sniper rifle-type weapon.


machinegun

Represents a machine gun-type weapon.


c4

Represents a C4 explosive.


taser

Represents a taser weapon.


grenade

Represents a grenade-type weapon.


stackableitem

Represents a stackable item-type weapon.


fists

Represents fists as a weapon type.


breachcharge

Represents a breach charge-type weapon.


bumpmine

Represents a bump mine-type weapon.


tablet

Represents a tablet-type weapon.


melee

Represents a melee-type weapon.


shield

Represents a shield-type weapon.


zone_repulsor

Represents a zone repulsor-type weapon.


unknown

Represents an unknown weapon type.

vector4d

This type is a common 4D vector (x, y, z, w).

x

Field

Type: float


y

Field

Type: float


z

Field

Type: float


w

Field

Type: float

ref_holder_t

This type acts as a proxy for reference variables that are used internally. Since Lua is a value-only language, it does not support references. Instead, an instance of this type is used to preserve interoperability with C++.

Note that <type> indicates the specific type this instance holds. For example, if you see ref_holder_t<float>, it means the val field holds a float value and will only accept float values when it’s updated.

val

Type: <type>

Value holder. Use as the source value, or override it to change internally.

notification_system

This type represents a notification system.

add

Adds a notification to the list.

Arguments

Name

Type

Description

notif

Notification object.

Returns

Nothing.

Example

notif:add(my_notification);

First Steps

Now that you’ve covered the essentials, it’s time to start scripting.

Fire up a text editor

Feel free to use any text editor you prefer: , , or even a simple Notepad.

Local scripts are located here: <CS2_Directory>/game/csgo/fatality/scripts. You may notice there's also a lib directory, but we’ll get to that later.

Create a new file ending with .lua, and begin your work on the script.

.ljbc format cannot be loaded from local sources.

Writing your first script

A typical “Hello world!” example can be a bit trivial, so let’s try something slightly more advanced instead.

Now, let's break down this example script:

Defining a callback function

Most of your scripting will run within we provide. Each event has its own signature, so pay attention to the parameters your callback function should accept. present_queue doesn’t provide any parameters, so our function doesn’t need any either.

Defining something local is optional, although recommended for clearer scope management.

Accessing drawing layer

With the callback function defined, let’s actually render something on the screen!

To do this, you first need to access the . We provide a single drawing layer that’s safe to use within the game thread. Due to how the game functions internally, it’s strongly discouraged to call game functions in other threads. Luckily all of our events run in the game thread.

This setup allows you not only to draw but also to query information on player health or other entities.

To access the layer, simply reference the surface field in the draw table:

You don't have to store it in a variable, but it would be nicer if you don't have to type out draw.surface every time, right?

Setting a font

After retrieving the layer, you must set a font object before drawing any text on the screen. This is purely for performance reasons, so you don’t have to pass a heavy font object every time you draw text.

All fonts are stored in . To access a font, either use dot syntax, or treat it like a dictionary:

Drawing text

With the font set, it’s time to draw some text.

Invoke the method on the layer. Notice that it’s called using the colon syntax: obj:fn(), because it’s a method.

You can also invoke methods with a dot syntax, as long as you provide the object in the first argument. Both calls: obj:fn() and obj.fn(obj) are identical.

Registering a callback

Now that you’ve created your first callback, you need to register it so Fatality knows to invoke it. This is done by calling the method on .

Result

That's it! If you've done everything correctly, you should see something like this:

base_entity

This type represents a base game entity.

This type may be returned for any other abstract entity class, but internally will point to the correct type.

__index

Function

Attemps to search for a field in this class.

Arguments

Returns

Example


get_class_name

Function

Returns schema class name.

Returns

Example


to_weapon_base_gun

Function

Safe-casts the entity to cs2_weapon_base_gun, returns nil if not a weapon_base_gun

Returns

Example


to_weapon_base

Function

Safe-casts the entity to cs2_weapon_base, returns nil if not a weapon_base

Returns

Example


to_player_pawn

Function

Safe-casts the entity to cs2_player_pawn, returns nil if not a player_pawn

Returns

Example


to_player_controller

Function

Safe-casts the entity to cs2_player_controller, returns nil if not a player_controller

Returns

Example

font

This type represents a font object. Internally, this type uses FreeType library to rasterize font glyphs.

This type inherits type. All of its base methods and fields are also available in this type.

__call

Constructs a font object.

Passing an invalid pointer, a or memory region that is smaller than the size will result in a crash.

Arguments

1. From file.

1. From memory.

1. From memory, with codepoint pairs.

Returns

Example

Gui

Usage:

gui.{func_or_field}

Usage: gui.{func_or_field}

This table exposes the GUI system of the software.

All types and enums described in the child sections must be prefixed with gui..

ctx

Type:

GUI context.


notify

Type:

Notification system.


input

Type:

Input context.


make_control

Wraps a control into a layout consisting of a label and that specific control. You should add this new control to groupboxes if you want your control to be displayed nicely. Additionally, you can add any extra controls to the returned one - those will get stacked to the left side of your initial control.

Arguments

Returns

Example

cengine_client

Usage: game.engine:{method}

An instance of this type provides a way to interface with Source 2's Engine-to-Client service.

get_last_timestamp

Method

Returns last timestamp, in seconds.

Arguments

None.

Returns

Type
Description

Example


get_last_server_tick

Method

Returns last server tick number.

Arguments

None.

Returns

Type
Description

Example


in_game

Method

Returns whether the client is currently in game.

Arguments

None.

Returns

Type
Description

Example


is_connected

Method

Returns whether the client is currently connected to a game server.

Arguments

None.

Returns

Type
Description

Example


get_netchan

Method

Returns the Network Channel used for network communication.

Arguments

None.

Returns

Type
Description

Example


client_cmd

Method

Executes a client-sided console command.

Arguments

Name
Type
Description

Returns

Nothing.

Example


get_screen_size

Method

Returns client window screen size.

Arguments

None.

Returns

Type
Description

Example

accessor

accessor

Last modified: 03 January 2025

This type represents a safe way to access maps.

Note that <type> indicates the specific type this instance holds. accessor<texture> for example means that get will return an instance of texture, and set will only accept the type texture as it's obj parameter.

__index

Returns an object by key.

Arguments

Returns

Example


__newindex

Sets an object by key.

Arguments

Returns

Nothing.

Example

spacer

This type represents a spacer control.

This type inherits type. All of its base methods and fields are also available in this type.

__call

Constructs the spacer.

Arguments

Returns

Example

layout

This type represents a layout control.

This type inherits type. All of its base methods and fields are also available in this type.

control_container

This type represents an abstract control with a container.

This type inherits type. All of its base methods and fields are also available in this type.

This type inherits type. All of its base methods and fields are also available in this type.

selectable

This type represents a selectable control.

This type inherits type. All of its base methods and fields are also available in this type.

__call

Constructs the selectable.

Arguments

Returns

Example

Name

Type

Description

name

string

Field name.

Type

Description

schema_accessor_t

Accessor instance or pointer accessor instance

local health = player.m_iHealth;
local health = player['m_iHealth']; -- this also works

Type

Description

string

Name. Returns nil when failed.

local name = entity:get_class_name()

Type

Description

cs2_weapon_base_gun?

Casted entity. Returns nil if the cast failed.

local gun = entity:to_weapon_base_gun()

Type

Description

cs2_weapon_base?

Casted entity. Returns nil if the cast failed.

local wpn = entity:to_weapon_base()

Type

Description

cs2_player_pawn?

Casted entity. Returns nil if the cast failed.

local pawn = entity:to_player_pawn()

Type

Description

cs2_player_controller?

Casted entity. Returns nil if the cast failed.

local controller = entity:to_player_controller()

float

Timestamp, in seconds.

local last_time = game.engine:get_last_timestamp();

int

Server tick number.

local server_tick = game.engine:get_last_server_tick();

bool

In-game status.

if game.engine:in_game() then
    print("I'm in game!");
end

bool

true if connected.

if game.engine:is_connected() then
    print("I'm connected!");
end

cnet_chan

Network channel, or nil if does not exist.

local chan = game.engine:get_netchan();

cmd

string

Command to execute.

bool

unrestricted

Whether should the execution preserve any restrictions. Defaults to false.

game.engine:client_cmd('say Hello!');

int

Width.

int

Height.

local w, h = game.engine:get_screen_size();

Name

Type

Description

key

string

Object key.

Type

Description

<type>

Object.

local main_font = draw.fonts['gui_main'];

-- this also works
local main_font_2 = draw.fonts.gui_main;

Name

Type

Description

key

string

Object key.

obj

<type>

Object.

draw.fonts['my_font'] = my_font;

-- this also works
draw.fonts.my_font = my_font;
notification

Name

Type

Description

path

string

Path to a ttf/otf file.

size

float

Font height, in pixels.

fl

font_flags

Font flags. Use bit library to construct them. Defaults to 0.

mi

int

Starting codepoint. Defaults to 0.

ma

int

Ending codepoint. Defaults to 255 (entire ASCII code page).

Name

Type

Description

mem

ptr

Pointer to a font file in memory.

sz

int

Font file size, in bytes.

size

float

Font height, in pixels.

fl

font_flags

Font flags. Use bit library to construct them. Defaults to 0.

mi

int

Starting codepoint. Defaults to 0.

ma

int

Ending codepoint. Defaults to 255 (entire ASCII code page).

Name

Type

Description

mem

ptr

Pointer to a font file in memory.

sz

int

Font file size, in bytes.

size

float

Font height, in pixels.

fl

font_flags

Font flags. Use bit library to construct them. Defaults to 0.

pairs

table[{int, int}...]

Min/max pairs. This is a standard array, consisting of {int, int} pairs.

Type

Description

font

Font object.

local cool_font = draw.font('myfont.ttf', 16);
font_base

Name

Type

Description

text

string

Label value.

c

control

Control object.

Type

Description

layout

Layout object.

local row = gui.make_control('Hello checkbox!', my_cb);
context
notification_system
context_input

Name

Type

Description

id

control_id

ID.

Type

Description

spacer

Spacer instance.

local sp = gui.spacer(gui.control_id('my_id'));
control
control_container
control
container

Name

Type

Description

id

control_id

Control ID.

str

string

Text string.

Type

Description

selectable

Selectable object.

local sel = gui.selectable(id, 'Hello!');
control

context

This type represents the GUI context.

find

Finds a control by ID.

Arguments

Name

Type

Description

id

string

Control ID.

Returns

Type

Description

<control>?

Casted control. Returns nil if the control was not found, or casting failed.

Example

local some_cb = ctx:find('some_cb');

user

Field

Type: user_t

User's basic information.

mouse_button

This enum represents mouse buttons.

left

Left mouse button.


right

Right mouse button.


middle

Middle (scroll wheel) mouse button


back

"Back" mouse button (side button 1).


forward

"Forward" mouse button (side button 2).

Types

In this section, you’ll find the most common types that aren’t tied to any specific service or module.

Use the left menu (or hamburger menu on mobile) to navigate between enums.

ptr

This type is a literal pointer.

To preserve interoperability with C++, several functions return void* as the type, which then get converted to light_userdata. Since you can’t directly cast FFI types to light_userdata, we’ve introduced a specialized type helping with this conversion.

Before you convert your pointer to one that is supported by the API, you need to cast it to uintptr_t. This can be done in the following manner:

local ptr_num = ffi.cast('uintptr_t', ptr_cdata);

Then, you can use the cast value in this type's constructor.

__call

Converts a number to pointer.

Arguments

Name

Type

Description

num

int

Pointer, as number.

Returns

Type

Description

ptr

Pointer, as light_userdata.

Example

-- cast to number first
local ptr_num = ffi.cast('uintptr_t', ptr_cdata);

-- then cast to light_userdata
local ptr_ld = ptr(ptr_num);

group

This type represents a groupbox control.

This type inherits control_container type. All of its base methods and fields are also available in this type.

cfiring_mode

Firing mode information.

values_arr

Type: <type>

Values.

local function on_present_queue()
    local d = draw.surface;
    d.font = draw.fonts['gui_main'];
    d:add_text(draw.vec2(50, 50),
        'Hello drawing! My first script speaking.',
         draw.color.white()
    );
end

events.present_queue:add(on_present_queue);
local function on_present_queue()
end
local d = draw.surface;
d.font = draw.fonts['gui_main'];
d:add_text(draw.vec2(50, 50),
        'Hello drawing! My first script speaking brev.',
         draw.color.white()
    );
events.present_queue:add(on_present_queue);
Visual Studio Code
Notepad++
several callbacks
drawing layer
draw.fonts
add_text
add
events.present_queue
My first lua

texture

This type represents a texture object.

This type inherits managed type. All of its base methods and fields are also available in this type.

Supported texture formats are:

  • JPEG (.jpg, .jpeg) - 12 bpc/arithmetic are not supported.

  • PNG (.png)

  • TGA (.tga)

  • BMP (.bmp) - 1 bpp and RLE variants are not supported.

  • PSD (.psd) - composited view only, no extra channels, 8/16 bpc

  • GIF (.gif) - only first frame, for animated gifs use animated_texture

  • HDR (.hdr)

  • PIC (.pic)

  • PNM (.pnm, .ppm, .pgm) - PPM and PGM are binary only

__call

Constructs an instance of this type.

Passing an invalid pointer, a or memory region that is smaller than the size will result in a crash.

Arguments

1. From file.

Name

Type

Description

path

string

Path to a valid texture file.

2. From memory.

Name

Type

Description

data

Pointer to texture file data in memory.

sz

int

Size of the texture file data.

3. From RGBA data.

Name

Type

Description

data

Pointer to RGBA data in memory.

w

int

Width.

h

int

Height (row count).

p

int

Pitch (row width). This is the amount of bytes per row.

Returns

Type

Description

texture

Texture object.

Example

local tex = draw.texture('funny_meme.png');

is_animated

Type: bool

Set to true if this is an instance of animated_texture.


get_size

Returns size of this texture.

Arguments

None.

Returns

Type

Description

Texture dimensions.

Example

local sz = tex:get_size();

animated_texture

This type is an animated texture. This texture type only supports animated GIF types, and does not support APNG.

This type inherits texture type. All of its base methods and fields are also available in this type.

If you pass an unsupported type, it will instead work exactly like texture type, meaning controlling frames and looping will be meaningless.

Using this type for texture atlases is possible, although highly unrecommended. It will produce extra texture objects in memory, and overall will be much slower. Instead, it is advised to construct an actual texture atlas, use texture type, and use texture mapping.

__call

Constructs animated texture.

Passing an invalid pointer, a or memory region that is smaller than the size will result in a crash.

Arguments

1. From file.

Name

Type

Description

path

string

Path to the texture file.

2. From memory.

Name

Type

Description

data

Pointer to texture file data in memory.

sz

int

Size of the texture file data.

Returns

Type

Description

animated_texture

Animated texture instance.

Example

local gif = draw.animated_texture('funny_gif.gif');

should_loop

Type: bool

If set to false, will not loop the animation automatically. Defaults to true.


Reset loop to run from the first frame.

Arguments

None.

Returns

Nothing.

Example

gif:reset_loop();

set_frame

Set a specific frame on the animation. If looping is enabled, will continue the cycle from the passed frame. Otherwise, will display a specific frame of the animation.

Frame count starts from 0.

Arguments

Name

Type

Description

frame

int

Frame number. Invalid frame numbers will be clamped.

Returns

Nothing.

Example

gif:set_frame(5);

get_frame_count

Returns amount of frames in the animation.

Arguments

None.

Returns

Type

Description

int

Frame count.

Example

local frames = gif:get_frame_count();
gif:set_frame(frames - 2); -- set to the last frame

Entities

This table represents an internal entity list.

Never store any entities in the global scope! Any entity might get deleted, and you will no longer have a valid instance of that entity, which will inevitably lead to a crash. If you need to globally store an entity somewhere, we strongly recommend you store an instance of chandle, and use it's get method to retrieve the entity again, when needed.

players

Type: entity_list_t<cs2_player_pawn>

Player pawns.


controllers

Type: entity_list_t<cs2_player_controller>

Player controllers.


items

Type: entity_list_t<cs2_weapon_base>

Items (held).


dropped_items

Type: entity_list_t<cs2_weapon_base>

Dropped items.


projectiles

Type: entity_list_t<cs2_grenade_projectile>

Grenade projectiles.


get_local_pawn

Returns the local player's pawn.

Arguments

None.

Returns

Type

Description

Pawn.

Example

local lp = entities.get_local_pawn();

get_local_controller

Returns the local player's controller.

Arguments

None.

Returns

Type

Description

Controller.

Example

local lp_ctrl = entities.get_local_controller();

notification

This type represents a notification item.

__call

Constructs the notification.

Arguments

Name

Type

Description

hdr

string

Header (title).

txt

string

Text (body).

ico

Icon. Defaults to nil.

Returns

Type

Description

notification

Notification object.

Example

local notif = gui.notification('Hello', 'Lua works!');

image

This type represents an image control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the image.

Arguments

Name

Type

Description

id

ID.

tex

Texture.

Returns

Type

Description

image

Image instance.

Example

local img = gui.image(gui.control_id('my_id'));

button

This type represents a button control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the button.

Arguments

Name

Type

Description

id

Control ID.

str

string

Text string.

Returns

Type

Description

button

Button object.

Example

local btn = gui.button(id, 'Hello!');

color_picker

This type represents a color picker control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the color picker.

Arguments

Name

Type

Description

id

Control ID.

allow_alpha

bool

Whether to enable alpha channel. Defaults to true.

Returns

Type

Description

color_picker

Color picker object.

Example

local picker = gui.color_picker(id);

get_value

Returns color picker' value.

Arguments

None.

Returns

Type

Description

Value data.

Example

local val = picker:get_value():get();

Draw

Usage: draw.{func_or_field}

This table describes the rendering system of the software.

All types and enums described in the child sections must be prefixed with draw.. This is done so specific types are not confused with others, such as the separate color types present in rendering and the game.

adapter

FieldRead only

Type:

Rendering adapter.


frame_time

FieldRead only

Type: float

Rendering frame time. An alias to .


time

FieldRead only

Type: float

Time, in seconds. An alias to .


scale

FieldRead only

Type: float

Global DPI scale.


display

FieldRead only

Type:

Display area size (viewport dimensions). will return exactly the same values. Overriding any of this vector's values will lead to an undefined behavior.


textures

FieldRead only

Type:

A string to map of all managed textures. You can query and push textures with custom IDs. When you add a texture to this map, it will be automatically destroyed and recreated when required (such as when DX11 device gets lost).

Built-in textures:

  • gui_loading: loading spinner

  • gui_user_avatar: current user's profile picture. May be nil if you don't have any avatar set

  • gui_icon_up: up chevron

  • gui_icon_down: down chevron

  • gui_icon_copy: copy icon

  • gui_icon_paste: paste icon

  • gui_icon_add: add icon

  • gui_icon_search: search icon

  • gui_icon_settings: settings icon (a cogwheel)

  • gui_icon_bug: bug icon

  • gui_icon_key.N: keyboard/mouse key icons. Replace N with the char code of a required button

  • icon_rage: RAGE tab icon

  • icon_legit: LEGIT tab icon

  • icon_visuals: VISUALS tab icon

  • icon_misc: MISC tab icon

  • icon_scripts: LUA tab icon

  • icon_skins: SKINS tab icon

  • icon_cloud: cloud icon

  • icon_file: file icon

  • icon_refresh: refresh icon

  • icon_save: save icon

  • icon_configs: "Configs" popup icon

  • icon_keys: keyboard icon

  • icon_info: "About" popup icon

  • icon_close: close icon (cross)

  • icon_load: load icon

  • icon_import: import icon

  • icon_export: export icon

  • icon_delete: delete icon

  • icon_autoload: "Autoload" icon

  • icon_allow_insecure: "Allow insecure" icon

  • icon_cloud_upd: cloud update icon

  • player_texture: player preview texture


fonts

FieldRead only

Type:

A string to map of all managed fonts. You can query and push fonts with custom IDs. When you add a font to this map, it will be automatically destroyed and recreated when required (such as when DX11 device gets lost).

Built-in fonts:

  • gui_debug: Verdana, 13px

  • gui_title: Figtree ExtraBold, 23px

  • gui_main: Figtree Medium, 14px

  • gui_main_shadow: Figree Medium, 14px, with shadow

  • gui_main_fb: Segoe UI Semibold, 14px

  • gui_bold: Figtree ExtraBold, 14px

  • gui_bold_fb: Segoe UI Black, 14px

  • gui_semi_bold: Figtree SemiBold, 14px

  • gui_semi_bold_fb: Segoe UI Bold, 14px


shaders

FieldRead only

Type:

A string to map of all managed shader. You can query and push shader with custom IDs. When you add a shader to this map, it will be automatically destroyed and recreated when required (such as when DX11 device gets lost).

Build-in shaders:

  • blur_f: gaussian blur shader


surface

FieldRead only

Type:

The layer you can render on.

container

This type represents an abstract container.

add

Adds a control to the container.

Arguments

Returns

Nothing.

Example


remove

Removes a control from the container.

Arguments

Returns

Nothing.

Example


find

Finds a control by ID.

Arguments

Returns

Example

label

This type represents a label control.

This type inherits type. All of its base methods and fields are also available in this type.

__call

Constructs the label.

Arguments

Returns

Example


set_text

Sets the new text.

Arguments

Returns

Nothing.

Example

cs2_grenade_projectile

This type represents a grenade projectile.

This type inherits type. All of its base methods and fields are also available in this type.

get_abs_origin

Returns the absolute origin (the one that is used for rendering).

Arguments

None.

Returns

Example


get_grenade_type

Returns the grenade type.

Arguments

None.

Returns

Example

Name

Type

Description

ctrl

control

Control to add.

container:add(my_control);

Name

Type

Description

ctrl

control

Control to remove.

container:remove(my_control);

Name

Type

Description

id

string

Control ID.

Type

Description

<control>?

Casted control. Returns nil if the control was not found, or casting failed.

local some_cb = container:find('some_cb');
ptr
ptr
vec2
ptr
cs2_player_pawn
cs2_player_controller
texture?
control_id
texture
control_id
control_id
value_param<color>

adapter
global_vars_t.frame_time
global_vars_t.real_time
vec2
cengine_client:get_screen_size
accessor<texture>
texture
accessor<font_base>
font_base
accessor<shader>
shader
layer

Name

Type

Description

id

control_id

Control ID.

str

string

Label string.

col

color?

Label color. Defaults to nil.

bold

bool

Whether to use bold font. Defaults to false.

Type

Description

label

Label object.

local lab = gui.label(id, 'Hello!');

Name

Type

Description

str

string

New text.

lab:set_text('New hello!');
control

Type

Description

vector

Origin.

local org = wep:get_abs_origin();

Type

Description

int

Grenade type.

local type = gren:get_grenade_type();
base_entity

shader

This type represents a shader. HLSL documentation

This type inherits managed type. All of its base methods and fields are also available in this type.

Only fragment shaders (aka Pixel Shaders) are supported.

Rendering system uses Shader Version 4 (ps_4_0).

HLSL structures

The constant buffer fields are the following:

Name

Type

Description

mvp

float4x4

Projection matrix.

tex

float2

Texture dimensions.

time

float

Render time (NOT the frame time).

alpha

float

Global opacity override.

The input fields are the following:

Name

Type

Description

pos

float4

Vertex position on screen (x,y,z over w). Register: SV_POSITION.

col

float4

Vertex color tint (r, g, b, a). Register: COLOR0.

uv

float2

UV coordinates (u, v). Register: TEXCOORD0.

The bound objects are the following:

Name

Type

Description

sampler0

sampler

Texture sampler.

texture0

Texture2D

Texture object.

Template:

cbuffer cb : register(b0) {
    float4x4 mvp;
    float2 tex;
    float time;
    float alpha;
};

struct PS_INPUT {
    float4 pos : SV_POSITION;
    float4 col : COLOR0;
    float2 uv : TEXCOORD0;
};

sampler sampler0;
Texture2D texture0;

__call

Constructs a shader.

Arguments

Name

Type

Description

src

string

Shader source code.

Returns

Type

Description

shader

Shader object.

Example

local blur = draw.shader([[

// define constant buffer.
cbuffer cb : register(b0) {
    float4x4 mvp;
    float2 tex;
    float time;
    float alpha;
};

// define input.
struct PS_INPUT {
    float4 pos : SV_POSITION;
    float4 col : COLOR0;
    float2 uv : TEXCOORD0;
};

// use texture sampler and texture.
sampler sampler0;
Texture2D texture0;

float4 main(PS_INPUT inp) : SV_Target {
    float radius = 2.0; // blur radius
    float2 inv_size = 1.0 / tex.xy; // inversed size of the texture
    float weight = 0.0; // total weight
    float4 color = 0.0; // total color

    // perform a gaussian blur
    for (float x = -radius; x <= radius; x += 1.0)
    {
        for (float y = -radius; y <= radius; y += 1.0)
        {
            float2 coord = inp.uv + float2(x, y) * inv_size;
            color += texture0.Sample(sampler0, coord) * exp(-((x * x + y * y) / (2.0 * radius * radius)));
            weight += exp(-((x * x + y * y) / (2.0 * radius * radius)));
        }
    }

    // average the color
    color /= weight;
    color.a *= inp.col.a; // apply alpha modulation
    return color;
}
]]);

Types

In this section, the most common gui types are listed, that are not particularly bound to a specific part of the gui.

Use the left menu (or hamburger menu, if you are on mobile) to navigate between types.

Events

Usage: events.{event_name}

There are a number of events that Fatality provides to use in the API - from various hooks, to in-game events. Each event entry is an object of event_t. This table documents events to be used by your scripts.

You are not required to remove events when your script unloads. It is done automatically by the API engine.

present_queue

Field

Invoked each time the game queues a frame for rendering. This is the only permitted location for drawing on screen.

Arguments

None.


frame_stage_notify

Field

Invoked every time the game progresses onto another frame stage. This event is called before the game handles a new frame stage.

Arguments

Name
Type
Description

stage

Current frame stage.


render_start_pre

Field

Invoked every time game starts the scene rendering process. This event is called before the game's function runs.

Arguments

None.


render_start_post

Field

Invoked every time game starts scene rendering process. This event is called after the game's function runs.

Arguments

Name
Type
Description

setup

View setup information.


setup_view_pre

Field

Invoked every time the game sets up the view. This event is called before the game's function runs.

Arguments

None.


setup_view_post

Field

Invoked every time the game sets up the view information. This event is called after the game's function runs.

You can retrieve the view information from game.view_render service.

Arguments

None.


override_view

Field

Invoked every time the game internally overrides view information. You are free to change whatever you like in the provided view setup.

Arguments

Name

Type

Description

setup

View setup information.


event

Field

Invoked every time a game event fires.

We do not listen to every single event that exists in the game. If you need something that we don't listen to, please use mods.events

Arguments

Name
Type
Description

event

Game event.


handle_input

Field

Invoked every time the game processes mouse/controller input. This is a good place to alter mouse movement, if needed.

Arguments

Name
Type
Description

type

Type of the input.

value

Input value.


input

Field

Invoked every time the GUI processes input.

Arguments

Name
Type
Description

msg

int

System message.

w

int

WPARAM.

l

int

LPARAM.

cs2_player_controller

This type represents a CCSPlayerController class.

This type inherits base_entity type. All of its base methods and fields are also available in this type.

is_enemy

Returns true if this player is an enemy to the local player.

Arguments

None.

Returns

Type

Description

bool

true if an enemy.

Example

if player:is_enemy() then
    -- ...
end

get_name

Returns the sanitized player name.

Arguments

None.

Returns

Type

Description

string

Player's name.

Example

local name = player:get_name();

get_pawn

Returns the pawn attached to this controller.

Arguments

None.

Returns

Type

Description

Pawn instance.

Example

local pawn = ctrl:get_pawn();

get_active_weapon

Returns the active weapon.

Arguments

None.

Returns

Type

Description

Weapon instance.

Example

local wep = player:get_active_weapon();

get_observer_pawn

Returns the observer pawn used for this controller.

Arguments

None.

Returns

Type

Description

Entity.

Example

local obs_pawn = ctrl:get_observer_pawn();

get_observer_target

Returns the pawn this controller is currently observing.

Arguments

None.

Returns

Type

Description

Entity.

Example

local obs = ctrl:get_observer_target();

get_observer_mode

Returns the current observer mode.

Arguments

None.

Returns

Type

Description

Observer mode.

Example

local mode = ctrl:get_observer_mode();

text_input

This type represents a text input control.

This type inherits control type. All of its base methods and fields are also available in this type.

__call

Constructs the text input.

Arguments

Name

Type

Description

id

ID.

Returns

Type

Description

text_input

Text input instance.

Example

local sp = gui.text_input(gui.control_id('my_id'));

placeholder

Type: string

Placeholder text.


value

Type: string

Value.


set_value

Sets the new text.

Arguments

Name

Type

Description

str

string

New value.

Returns

Nothing.

Example

input:set_value('Hello!');

checkbox

This type represents a checkbox control.

This type inherits type. All of its base methods and fields are also available in this type.

__call

Constructs the checkbox.

Arguments

Returns

Example


get_value

Returns checkbox' value.

Arguments

None.

Returns

Example


set_value

Sets checkbox' value.

It is advised to use this method instead of 's method.

Arguments

Returns

Nothing.

Example

slider

This type represents a slider control.

This type inherits type. All of its base methods and fields are also available in this type.

__call

Constructs the slider.

Arguments

Format Table

Format table can either be a single string with the desired format, or multiple elements with different minimum actuators. You have to pass multiple values in the descendant order, starting from the highest value to the lowest value. min and add values are both optional, but it makes no sense to leave either of them out.

Formatting uses standard printf syntax.

Passing invalid format will lead to an undefined behavior.

1. Single Formatting.

2. Multi Formatting.

Returns

Example


get_value

Returns slider' value.

Arguments

None.

Returns

Example

combo_box

This type represents a combo box control.

This type inherits type. All of its base methods and fields are also available in this type.

add method expects an instance of . Passing other control types will not add them to the list.

Value bits are toggled in order of selectables. That means if the first element is toggled, so will be the first bit, etc.

__call

Constructs the combo box.

Arguments

Returns

Example


allow_multiple

Type: bool

If set to true, the checkbox will be able to toggle multiple selectables.


get_value

Returns combo box' value.

Arguments

None.

Returns

Example

value_param

This type represents a value data used by some control types.

Note, that this part: <type> is used to designate what exact type the instance of this type is holding. For example, when it says value_param<bool>, it means that get will return a bool value, and set will accept only the type bool as it's val parameter.

get

Returns the value.

Arguments

None.

Returns

Example

get_direct

Returns the value disrgarding any active keybinds.

Arguments

None.

Returns

Example

set

Sets the value.

It is advised to use set_value method of the control, if any.

Arguments

Returns

Nothing.

Example

get_hotkey_state

Returns true if there's any active hotkeys.

Arguments

None.

Returns

Example

disable_hotkeys

Disables all active hotkeys. This allows you to override the value.

Arguments

None.

Returns

Nothing.

Example

Type

Description

<type>

Value.

ctrl:get_value():get();

Type

Description

<type>

Value.

ctrl:get_value():get_direct();

Name

Type

Description

val

<type>

Value.

ctrl:get_value():set(123);

Type

Description

bool

true if any hotkey is active.

if ctrl:get_value():get_hotkey_state() then
    -- ...
end
ctrl:get_value():disable_hotkeys();
client_frame_stage
cview_setup
cview_setup
game_event_t
input_type_t
ref_holder_t<float>
Documentation
cs2_player_pawn
cs2_weapon_base_gun
base_entity
base_entity
observer_mode_t
control_id

Name

Type

Description

id

control_id

ID.

Type

Description

checkbox

Checkbox instance.

local cb = gui.checkbox(gui.control_id('my_id'));

Type

Description

value_param<bool>

Value data.

local val = cb:get_value():get();

Name

Type

Description

val

bool

New value.

cb:set_value(true);
control
value_param
set

Name

Type

Description

id

control_id

Control ID.

low

float

Minimum value.

high

float

Maximum value.

fmt

table[...]

Format. Defaults to {'%.0f'}.

step

float

Step value. Defaults to 1.0.

Type

Description

string

Format string.

Name

Type

Description

min

float?

Minimal value.

add

float?

Add step.

fmt

string

Format string.

Type

Description

slider

Slider object.

local slider = gui.slider(id, 0, 100, {'%.0f%%'});

Type

Description

value_param<float>

Value data.

local val = slider:get_value():get();
control
Documentation

Name

Type

Description

id

control_id

ID.

Type

Description

combo_box

Combo box instance.

local cb = gui.combo_box(gui.control_id('my_id'));

Type

Description

value_param<bits>

Value data.

local val = cb:get_value():get();
control_container
selectable

bits

This type represents a bitset value.

Maximal bit number for this type is 63. Setting or getting any bits outside of that range will cause a crash.

reset

Resets the value.

Arguments

None.

Returns

Nothing.

Example

bits:reset();

get_raw

Returns the raw value.

Arguments

None.

Returns

Type

Description

int

Raw value.

Example

local raw = bits:get_raw();

set_raw

Sets the raw value.

Arguments

Name

Type

Description

val

int

Raw value.

Returns

Nothing.

Example

bits:set_raw(long_long_value);

none

Returns true if no bits are set.

Arguments

None.

Returns

Type

Description

bool

true if no bits are set.

Example

if bits:none() then
    -- ...
end

set

Enables a bit.

Arguments

Name

Type

Description

bit

int

Bit number.

Returns

Nothing.

Example

bits:set(5); -- set bit #5 (same as bit.bor(val, bit.lshift(1, 5)))

unset

Disables a bit.

Arguments

Name

Type

Description

bit

int

Bit number.

Returns

Nothing.

Example

bits:unset(5);

get

Returns bit state.

Arguments

Name

Type

Description

bit

int

Bit number.

Returns

Type

Description

bool

Bit status.

Example

if bits:get(5) then
    -- ...
end

toggle

Toggles bit state.

Arguments

Name

Type

Description

bit

int

Bit number.

Returns

Nothing.

Example

bits:toggle(5);

text_params

This type is used to determine text alignment.

Line alignment only makes sense if you have multiple lines in your text. By default, all next lines will start from the left side of the text. You can change this behavior by using one of the functions that take line as a parameter. For example, if you pass right to the line alignment, all next lines will start from the right side. Text alignment will remain as dictated by v and h parameters.

with_v

Creates text_params instance with vertical alignment.

Arguments

Name

Type

Description

v

Vertical alignment.

Returns

Type

Description

text_params

Created text params.

Example

local align_top = draw.text_params.with_v(draw.text_alignment.top);

with_h

Creates text_params instance with horizontal alignment.

Arguments

Name

Type

Description

h

Horizontal alignment.

Returns

Type

Description

text_params

Created text params.

Example

local align_right = draw.text_params.with_h(draw.text_alignment.right);

with_line

Creates text_params instance with line alignment.

Arguments

Name

Type

Description

line

Line alignment.

Returns

Type

Description

text_params

Created text params.

Example

local lines_center = draw.text_params.with_line(draw.text_alignment.center);

with_vh

Creates text_params instance with vertical and horizontal alignments.

Arguments

Name

Type

Description

v

Vertical alignment.

h

Horizontal alignment.

Returns

Type

Description

text_params

Created text params.

Example

local align_bottom_right = draw.text_params.with_vh(draw.text_alignment.bottom, draw.text_alignment.right);

with_vline

Creates text_params instance with vertical alignment and line alignment.

Arguments

Name

Type

Description

v

Vertical alignment.

line

Line alignment.

Returns

Type

Description

text_params

Created text params.

Example

local align = draw.text_params.with_vline(draw.text_alignment.bottom, draw.text_alignment.center);

with_hline

Creates text_params instance with horizontal alignment and line alignment.

Arguments

Name

Type

Description

h

Horizontal alignment.

line

Line alignment.

Returns

Type

Description

text_params

Created text params.

Example

local align = draw.text_params.with_hline(draw.text_alignment.center, draw.text_alignment.center);

with_vhline

Creates text_params instance with vertical, horizontal and line alignments.

Arguments

Name

Type

Description

v

Vertical alignment.

h

Horizontal alignment.

line

Line alignment.

Returns

Type

Description

text_params

Created text params.

Example

local align = draw.text_params.with_vhline(draw.text_alignment.center, draw.text_alignment.center, draw.text_alignment.center);

command

This type is used to change render command parameters.

Be cautious when changing stuff in an instance of this type. Passing invalid data to texture or frag_shader, or not restoring some changes after you're done drawing can lead to undefined behavior, and more likely, a crash. If you are not sure how to operate this type, take a look into examples.

texture

Type: ptr

Texture pointer. You can get one from an instance of texture type by accessing obj field. Passing invalid data to this field WILL result in a crash. For a safer way, please use set_texture.


frag_shader

Type: Type: ptr

Fragment shader (aka Pixel Shader in DirectX terms) pointer. You can get one from an instance of shader type by accessing obj field. Passing invalid data to this field WILL result in a crash. For a safer way, please use set_shader.


clip_rect

Type: rect?

Clip rectangle used for scissor testing. If this is set to nil, will not clip anything.

It is advised to instead use layer's override_clip_rect method. While you can pass custom rect to this field, you will lose information about previous clip rects set before. Using that method will make sure to intersect the previous rect with the one you pass and produce a probably more expected result.


uv_rect

Type: rect?

UV rect used for texture mapping. If this field is set to nil, will use 0, 0, 1, 1 rectangle to map the texture. You can learn more about texture mapping in the tutorial section.


alpha

Type: float

Global opacity override. Defaults to 1, but if you set anything else - will modulate opacity of every next shape you will render.


rotation

Type: float

Shape rotation. Not all shapes support this field. The value is set in degrees, not radians.


anti_alias

Type: bool

If set to true, will apply tesselation to shapes.

As of now, not every shape supports tesselation, but it is advised to have it enabled at all times anyway. It will produce much better result anyway.


ignore_scaling

Type: bool

If set to true, will ignore global DPI scale. This is set to true by default, but you are free to change it to false if you are trying to render some custom UI elements.


chained_call

Type: bool

Only useful when using shaders. If set to true, will not update back buffer texture. This can be used if you need the very same texture data, as when applying several shaders to the back buffer.

Please note that capturing back buffer is a rather slow operation. It is better to not capture it too often. Back buffer is automatically captured to the only layer you can use anyway, and it is better to use that one instead, to make sure rendering happens as fast as it is possible.


only_downsampled

Type: bool

If set to true, will capture back buffer (as long as chained_call is set to false). The name of this field is quite misleading due to the fact that in the CS:GO version of Fatality, it was used to configure if the rendering system should also downsample the captured backbuffer into another texture. In DirectX11, this operation is much faster, so it is done regardless.


capture_back_buffer

Type: bool

An alias to only_downsampled.


is_tile

Type: bool

If set to true, will use a separate texture sampler that supports tiling. By default, all textures are stretched, but if you enable this option - their tiling and stretch will be fully configurable by the uv_rect field.


mode

Type: render_mode

Rendering mode. You can read more about it in the type's documentation.


set_texture

Sets a texture in a safe manner.

Arguments

Name

Type

Description

tex

Texture object.

Returns

Nothing.

Example

cmd:set_texture(my_tex);

set_shader

Sets a fragment shader in a safe manner.

Arguments

Name

Type

Description

sh

[shader]

Shader object.

Returns

Nothing.

Example

cmd:set_shader(my_shader);

vec2

__call

Creates a new 2D vector instance.

Arguments

1. Default vector (0, 0).

None.

2. Single value.

3. XY values.

Returns

Example


x

Type: float

X coordinate.


y

Type: float

Y coordinate.


floor

Returns floored variant of this vector.

Arguments

None.

Returns

Example


Returns ceiled variant of this vector.

Arguments

None.

Returns

Example


round

Returns rounded variant of this vector.

Arguments

None.

Returns

Example


len

Returns length of this vector.

Arguments

None.

Returns

Example


len_sqr

Returns squared length of this vector.

This method is de-facto faster than the non-squared variant. Use it, if you need extra performance.

Arguments

None.

Returns

Example


dist

Returns distance to another vector.

Arguments

Returns

Example


dist_sqr

Returns squared distance to another vector.

This method is de-facto faster than the non-squared variant. Use it, if you need extra performance.

Arguments

Returns

Example

cs2_player_pawn

This type represents a C_CSPlayerPawn class.

This type inherits type. All of its base methods and fields are also available in this type.

should_draw

Returns true if the game will draw this player on screen.

Arguments

None.

Returns

Example


is_left_handed

Returns true if left-hand mode is enabled.

Arguments

None.

Returns

Example


get_abs_origin

Returns the absolute origin (the one that is used for rendering).

Arguments

None.

Returns

Example


get_abs_angles

Returns the absolute angles (the one that is used for rendering).

Arguments

None.

Returns

Example


get_abs_velocity

Method

Returns the absolute velocity.

Arguments

None.

Returns

Example


set_abs_origin

Sets the new absolute origin.

Arguments

Returns

Nothing.

Example


set_abs_angles

Sets new absolute angles.

Arguments

Returns

Nothing.

Example


set_abs_velocity

Method

Sets new absolute velocity.

Arguments

Returns

Nothing.

Example


is_alive

Returns true if the player is alive.

Arguments

None.

Returns

Example


is_enemy

Returns true if this player is an enemy to the local player.

Arguments

None.

Returns

Example


is_enemy_to

Returns whether this player is an enemy to another entity.

Arguments

Returns

Example


get_active_weapon

Returns the active weapon.

Arguments

None.

Returns

Example


get_name

Returns the sanitized player name.

Arguments

None.

Returns

Example


get_view_offset

Returns the player's view offset (eye location relative to the player's origin).

Arguments

None.

Returns

Example


get_eye_pos

Returns the player's eye position.

Arguments

None.

Returns

Example

Name

Type

Description

value

float

X and Y coordinates.

Name

Type

Description

x

float

X coordinate.

y

float

Y coordinate.

Type

Description

vec2

New vector.

local vec = draw.vec2(5, 10);

Type

Description

vec2

Floored variant.

local fl = vec:floor();

Type

Description

vec2

Ceiled variant.

local ceiled = vec:ceil();

Type

Description

vec2

Rounded variant.

local rounded = vec:round();

Type

Description

float

Length.

local len = vec:len();

Type

Description

float

Length.

local len = vec:len_sqr();

Name

Type

Description

other

vec2

Other vector.

Type

Description

float

Distance.

local dist = vec1:dist(vec2);

Name

Type

Description

other

vec2

Other vector.

Type

Description

float

Distance.

local dist = vec1:dist_sqr(vec2);
text_alignment
text_alignment
text_alignment
text_alignment
text_alignment
text_alignment
text_alignment
text_alignment
text_alignment
text_alignment
text_alignment
text_alignment
texture

Type

Description

bool

true if will.

if player:should_draw() then
    -- ...
end

Type

Description

bool

true if left-handed.

if player:is_left_handed() then
    -- ...
end

Type

Description

vector

Origin.

local org = player:get_abs_origin();

Type

Description

vector

Angles.

local ang = player:get_abs_angles();

Type

Description

vector

Velocity.

local vel = player:get_abs_velocity();

Name

Type

Description

vec

vector

New origin.

player:set_abs_origin(my_vec);

Name

Type

Description

ang

vector

New angles.

player:set_abs_angles(my_ang);

Name

Type

Description

vel

vector

New velocity.

player:set_abs_velocity(my_vel);

Type

Description

bool

true if alive.

if player:is_alive() then
    -- ...
end

Type

Description

bool

true if an enemy.

if player:is_enemy() then
    -- ...
end

Name

Type

Description

ent

base_entity

Other entity.

Type

Description

bool

true if an enemy.

if player:is_enemy_to(other_player) then
    -- ...
end

Type

Description

cs2_weapon_base_gun

Weapon instance.

local wep = player:get_active_weapon();

Type

Description

string

Player's name.

local name = player:get_name();

Type

Description

vector

View offset.

local vo = player:get_view_offset();

Type

Description

vector

Eye position.

local eyes = player:get_eye_pos();
base_entity

control_type

This enum determines the current control's type.

You can only construct types that are listed below in the navigation, and only if those have a constructor.

default

Default control. You are very unlikely to ever stumble upon this type.


button

Button control.


checkbox

Checkbox control.


child_tab

Child tab control. Only possible to find within tab_layout controls.


color_picker

Color picker control.


combo_box

Combo box control.


control_container

Default control with a container. You are very unlikely to ever stumble upon this type.


group

Groupbox control.


hotkey

Hotkey input control.


hsv_slider

HSB slider (Saturation/Brightness box, Hue slider and Opacity slider).


label

Label control.


layout

Layout control.


list

Listbox control.


loading

Loading spinner.


notification_control

Notification item control. One of the types in the core UI framework, never actually used within Fatality.


popup

Basic popup window.


selectable

Basic selectable item.


slider

Slider item. This type doesn't tell the internal value type used.


spacer

Spacer control.


tab

Horizontal or vertical tab.


tabs_layout

A variant of layout that is used specifically to operate tabs.


weapon_tabs_layout

A variant of layout that is used specifically to operate weapon tabs.


text_input

Text input control.


toggle_button

A variant of button that looks like button, but works like a checkbox.


window

Basic window control.


widget

Basic widget control.


settings

Settings control.


image

Image control.

control

This type represents an abstract GUI control.

id

Type: int

Control ID.


id_string

Type: string

String representation of control's ID. This may be empty for some controls.


is_visible

Type: bool

Control's visibility state.


parent

Type: control?

Parent control. Might be nil on some controls.


type

Type:

Control's type.


inactive

Type: bool

If set to true, will mark this control to the inactive state.


inactive_text

Type: string

Tooltip replacement to show when control is inactive.


inactive_color

Type:

Label color override for inactive controls.


tooltip

Type: string

Tooltip text.


aliases

Type: table[string]

Alias list for this control. Used in search box to support different naming (e.g. if a user searches for "Double tap", will find "Rapid fire" instead).


get_hotkey_state

Returns true if any of the control's hotkeys are active.

Arguments

None.

Returns

Example


set_visible

Changes visibility state for this control.

Calling this method on controls that are located in layouts with large amount of other controls will inevitably cause performance issues due to auto-stacking.

Arguments

Returns

Nothing.

Example


add_callback

Adds a callback to this control.

Arguments

Returns

Nothing.

Example


cast

Attempts to downcast the control to the correct type.

Due to Lua engine's limitations, it is impossible to automatically downcast variables. Usually there is no need to call this method, unless you found some control that wasn't somehow already cast to the desired type. find() methods automatically perform the cast to the correct type.

Arguments

None.

Returns

Example


reset

Resets control's state. This action is usually required if you change control's value directly by interacting with .

You also should call this method on layouts if you add multiple controls into them.

Arguments

None.

Returns

Nothing.

Example

Type

Description

bool

true if any hotkey is active.

if ctrl:get_hotkey_state() then
    -- ...
end

Name

Type

Description

val

bool

Visibility state.

ctrl:set_visible(false);

Name

Type

Description

cbk

function

Callback.

ctrl:add_callback(function ()
    print('Callback invoked!');
end);

Type

Description

<control>

New type, if any.

local checkbox = maybe_checkbox:cast();
ctrl:reset();
control_type
color
value_param

Math

Usage: math.{func}

This table extends the existing math table that is a part of Lua.

calc_angle

Function

Calculates angles between 2 vectors.

Arguments

Name
Type
Description

src

Source vector.

dst

Destination vector.

Returns

Type
Description

Angles.

Example

local ang = math.calc_angle(vec1, vec2);

angle_normalize

Function

Normalizes an angle.

Arguments

Name
Type
Description

angle

float

Input angle.

Returns

Type
Description

float

Normalized angle.

Example

local norm = math.angle_normalize(560);

approach_angles

Function

Approaches an angle over time.

Arguments

Name
Type
Description

from

Start angle.

to

End angle.

speed

float

Approach speed.

Returns

Type
Description

Delta angle.

Example

local ang = math.approach_angles(from, to, 1.0 / game.global_vars.frametime);

edge_point

Function

Returns a point on the edge of a box.

Arguments

Name
Type
Description

mins

Box mins.

maxs

Box maxs.

dir

Point direction (angle).

radius

float

Area radius.

Returns

Type
Description

Point.

Example

local point = math.edge_point(mins, maxs, dir, 5);

lerp

Function

Linear interpolation.

Arguments

Name
Type
Description

t1

float

Start value.

t2

float

End value.

progress

float

Interpolation amount.

Returns

Type

Description

float

Interpolated value.

Example

local mid = math.lerp(0, 100, 0.5);

vector_angles

Function

Calculates angles from a vector.

Arguments

Name
Type
Description

forward

Source vector.

up

Up vector. Defaults to nil.

Returns

Type
Description

Angles.

Example

local ang = math.vector_angles(fw);

world_to_screen

Function

Transforms a point in the game world onto the viewport.

Arguments

Name
Type
Description

xyz

Point in the world.

round

bool

Whether should round the output. Defaults to true.

Returns

Type
Description

Point on the viewport.

Example

local point = math.world_to_screen(game_point);

clamp

Function

Clamps a value between min and max.

Arguments

Name
Type
Description

n

float

Value.

lower

float

Lowest value.

upper

float

Highest value.

Returns

Type
Description

float

Clamped value.

Example

local x = math.clamp(50, 5, 25); -- 25

remap_val

Function

Maps the value from one range to another range.

Arguments

Name
Type
Description

val

float

Value.

a

float

Lowest source value.

b

float

Highest source value.

c

float

Lowest destination value.

d

float

Highest destination value.

Returns

Type
Description

float

Mapped value.

Example

local mapped = math.remap_val(0.5, 0, 1, 0, 100); -- 50

remap_val_clamped

Function

Maps the value from one range to another range. Additionally, clamps the value based on the source range.

Arguments

Name
Type
Description

val

float

Value.

a

float

Lowest source value.

b

float

Highest source value.

c

float

Lowest destination value.

d

float

Highest destination value.

Returns

Type
Description

float

Mapped value.

Example

local mapped = math.remap_val_clamped(5, 0, 1, 0, 100); -- 100

vec2

Function

An alias to draw.vec2().

Example

local vec = math.vec2(5, 5);

vec3

Function

An alias to vector().

Example

local vec = math.vec3(5, 12, 5);

cs2_weapon_base_gun

This type represents a CCSWeaponBaseGun class.

This type inherits base_entity type. All of its base methods and fields are also available in this type.

get_abs_origin

Returns the absolute origin (the one that is used for rendering).

Arguments

None.

Returns

Type

Description

Origin.

Example

local org = wep:get_abs_origin();

get_max_speed

Returns the maximal player speed when holding this weapon.

Arguments

None.

Returns

Type

Description

float

Max speed, in UPS.

Example

local spd = wep:get_max_speed();

get_inaccuracy

Returns the current inaccuracy value.

Arguments

Name

Type

Description

mode

Weapon mode.

Returns

Type

Description

float

Inaccuracy value.

Example

local inacc = wep:get_inaccuracy(csweapon_mode.primary_mode);

get_spread

Returns the current spread value.

Arguments

Name

Type

Description

mode

Weapon mode.

Returns

Type

Description

float

Inaccuracy value.

Example

local spread = wep:get_spread(csweapon_mode.primary_mode);

get_id

Returns the weapon ID.

Arguments

None.

Returns

Type

Description

Weapon ID.

Example

local wep_id = wep:get_id();

get_type

Returns the weapon type.

Arguments

None.

Returns

Type

Description

Weapon type.

Example

local type = wep:get_type();

get_data

Returns the weapon static data.

Arguments

None.

Returns

Type

Description

Weapon data.

Example

local data = wep:get_data();

is_gun

Returns true if this weapon is a firearm.

Arguments

None.

Returns

Type

Description

bool

true if a firearm.

Example

if wep:is_gun() then
    -- ...
end

is_attackable

Returns true if you can attack with this weapon.

Arguments

None.

Returns

Type

Description

bool

true if can attack.

Example

if wep:is_attackable() then
    -- ...
end

has_secondary_attack

Returns true if this weapon has a secondary attack mode.

Arguments

None.

Returns

Type

Description

bool

true if has the secondary attack mode.

Example

if wep:has_secondary_attack() then
    -- ...
end

has_spread

Returns true if this weapon has spread (e.g. knives do not have any spread).

Arguments

None.

Returns

Type

Description

bool

true if has spread.

Example

if wep:has_spread() then
    -- ...
end
vector
vector
vector
vector
vector
vector
vector
vector
vector
vector
vector
vector
vector
vector
vec2
vector
csweapon_mode
csweapon_mode
weapon_id
csweapon_type
ccsweapon_base_vdata

Utils

Usage: utils.{function}

This table exposes various utility functions.


base64_encode

Encode a string to Base64 format.

Arguments

Name

Type

Description

str

string

Source string.

Returns

Type

Description

string

Base64-encoded string.

Example

local enc = utils.base64_encode('Hello!'); -- SGVsbG8h

base64_decode

Decode Base64-encoded string.

Arguments

Name

Type

Description

str

string

Base64-encoded string.

Returns

Type

Description

string

Source string.

Example

local dec = utils.base64_decode('SGVsbG8h'); -- Hello!

get_unix_time

Returns current time as UNIX timestamp.

Arguments

None.

Returns

Type

Description

int

Timestamp.

Example

local ts = utils.get_unix_time();

murmur2

Returns MURMUR2-hashed string.

Arguments

Name

Type

Description

str

string

Source string.

Returns

Type

Description

int

Hash.

Example

local hash = utils.murmur2('Hello');

fnv1a

Returns FNV1A-hashed string.

Arguments

Name

Type

Description

str

string

Source string.

Returns

Type

Description

int

Hash.

Example

local hash = utils.fnv1a('Hello');

find_export

Returns an address to an export in an image.

Arguments

Name

Type

Description

mod

string

Image to look in.

exp

string

Export symbol.

Returns

Type

Description

int

Address, or 0 on failure.

Example

local message_box = utils.find_export('user32.dll', 'MessageBoxA');

find_pattern

Searches for a code pattern in an image.

Arguments

Name

Type

Description

mod

string

Image to search in.

pattern

string

Code pattern.

Returns

Type

Description

int

Address, or 0 on failure.

Example

local something = utils.find_pattern('engine2.dll', 'DE AD ? ? ? ? BE EF');

clipboard_get

Returns current clipboard content.

Arguments

None.

Returns

Type

Description

string

Clipboard content.

Example

local clip = utils.clipboard_get();

clipboard_set

Sets new clipboard content.

Arguments

Name

Type

Description

str

string

New content.

Returns

Nothing.

Example

utils.clipboard_set('Hello!');

font_base

This type represents the base class for font types. You cannot create an instance of this type. Instead, use the children types.

This type inherits type. All of its base methods and fields are also available in this type.

Definitions:

  • codepoint: Unicode representation of the character.

  • kerning: a distance between two characters.

  • glyph: visual representation of a character.

height

Type: float

Font height, in pixels.


ascent

Type: float

Font ascent value, in pixels.


descent

Type: float

Font descent value, in pixels.


line_gap

Type: float

Font line gap, in pixels.


kerning_gap

Type: float

Font kerning gap, in pixels.


outline_alpha

Type: float

Font outline opacity (0 to 1). Defaults to 0.45.


flags

Type:

Font flags. Use bit library to read flags.


y_offset

Type: int

Glyph Y offset, in pixels. Will alter the location of a glyph in the atlas. Changing this value after the font was created is meaningless.


x_offset

Type: int

Glyph X offset, in pixels. Will alter the location of a glyph in the atlas. Changing this value after the font was created is meaningless.


fallback_font

Type: font_base

Fallback font to use, in case a glyph is not found in this font. Is it useful when one font does not have codepoints for specific symbols, that are present in another font, but you still want to prefer this font's glyphs over other font.


dropshadow_color

Type:

Shadow color. Only R, G, B values are used.


get_kerned_char_width

Returns character width, included with kerning.

Arguments

Returns

Example


get_kerning

Returns kerning value for a single character. If kerning is disabled, will instead return kerning gap.

Arguments

Returns

Example


get_text_size

Returns text area size.

Arguments

Returns

Example


wrap_text

Wraps text to meet the desired width. Wrapping is done by breaking text by words and inserting line breaks in between. If one of the words is longer than the target width, will instead use that word's width.

Arguments

Returns

Example


get_glyph

Returns glyph information for a character.

Arguments

Returns

Example


get_texture

Returns a texture atlas that contains the provided glyph.

Arguments

Returns

Example

Name

Type

Description

left

int

Previous character codepoint.

right

int

Current character codepoint.

Type

Description

float

Distance, in pixels.

local w = font:get_kerned_char_width(prev_cp, cp);

Name

Type

Description

cp

int

Codepoint.

Type

Description

float

Kerning value, in pixels.

local k = font:get_kerning(cp);

Name

Type

Description

text

string

Text.

skip_scaling

bool

If set to true, will skip global DPI scaling. Defaults to false.

til_newline

bool

Calculate size only until a line break is met. Defaults to false.

Type

Description

vec2

Text area size.

local sz = font:get_text_size('Hello!');

Name

Type

Description

text

string

Text to wrap.

width

float

Target width.

Type

Description

string

Wrapped text.

local shorter = font:wrap_text('This is some very long text!', 50);

Name

Type

Description

codepoint

int

Codepoint.

Type

Description

glyph_t

Glyph information.

local glyph = font:get_glyph(cp);

Name

Type

Description

gl

glyph_t

Character glyph.

Type

Description

int

Texture pointer, or nil if not found.

local atlas = font:get_texture(glyph);
managed
font_flags
color

weapon_id

This enum represents the unique identifier for various weapons in the game.

none

Represents no weapon.


deagle

Represents a Desert Eagle.


elite

Represents the Dual Berettas.


fiveseven

Represents a Five-SeveN.


glock

Represents a Glock-18.


ak47

Represents an AK-47.


aug

Represents an AUG.


awp

Represents an AWP.


famas

Represents a FAMAS.


g3sg1

Represents a G3SG1.


galilar

Represents a Galil AR.


m249

Represents an M249.


m4a1

Represents an M4A4.


mac10

Represents a MAC-10.


p90

Represents a P90.


zone_repulsor

Represents a zone repulsor device.


mp5sd

Represents an MP5-SD.


ump45

Represents a UMP-45.


xm1014

Represents an XM1014.


bizon

Represents a PP-Bizon.


mag7

Represents a MAG-7.


negev

Represents a Negev.


sawedoff

Represents a Sawed-Off.


tec9

Represents a Tec-9.


taser

Represents a Zeus x27 taser.


hkp2000

Represents a P2000.


mp7

Represents an MP7.


mp9

Represents an MP9.


nova

Represents a Nova.


p250

Represents a P250.


shield

Represents a shield.


scar20

Represents a SCAR-20.


sg556

Represents an SG 553.


ssg08

Represents an SSG 08.


knifegg

Represents the Golden Knife.


knife

Represents the default knife.


flashbang

Represents a flashbang.


hegrenade

Represents an HE grenade.


smokegrenade

Represents a smoke grenade.


molotov

Represents a Molotov.


decoy

Represents a decoy grenade.


incgrenade

Represents an incendiary grenade.


c4

Represents a C4 explosive.


healthshot

Represents a health shot.


knife_t

Represents the Terrorist knife.


m4a1_silencer

Represents the M4A1-S.


usp_silencer

Represents the USP-S.


cz75a

Represents a CZ75-Auto.


revolver

Represents an R8 Revolver.


tagrenade

Represents a tactical awareness grenade.


fists

Represents fists.


breachcharge

Represents a breach charge.


tablet

Represents a tablet.


melee

Represents a generic melee weapon.


axe

Represents an axe.


hammer

Represents a hammer.


spanner

Represents a spanner (wrench).


knife_ghost

Represents a ghost knife.


firebomb

Represents a firebomb grenade.


diversion

Represents a diversion device.


fraggrenade

Represents a fragmentation grenade.


snowball

Represents a snowball.


bumpmine

Represents a bump mine.


knife_bayonet

Represents a Bayonet.


knife_css

Represents the Classic Knife.


knife_flip

Represents a Flip Knife.


knife_gut

Represents a Gut Knife.


knife_karambit

Represents a Karambit.


knife_m9bayonet

Represents an M9 Bayonet.


knife_tactical

Represents a Huntsman Knife.


knife_falchion

Represents a Falchion Knife.


knife_survival_bowie

Represents a Bowie Knife.


knife_butterfly

Represents a Butterfly Knife.


knife_push

Represents a Shadow Daggers.


knife_cord

Represents a Paracord Knife.


knife_canis

Represents a Survival Knife.


knife_ursus

Represents an Ursus Knife.


knife_gypsy_jackknife

Represents a Navaja Knife.


knife_outdoor

Represents a Nomad Knife.


knife_stiletto

Represents a Stiletto Knife.


knife_widowmaker

Represents a Talon Knife.


knife_skeleton

Represents a Skeleton Knife.


knife_kukri

Represents a Kukri Knife.

vector

This type is a common 3D vector (x, y, z).

This type supports operations, such as +, -, /, * and ==.

x

Type: float

X coordinate.

y

Type: float

Y coordinate.

z

Type: float

Z coordinate.


__call

Constructs a vector.

Arguments

1. Default vector (0, 0, 0).

None.

2. Single value.

Name

Type

Description

value

float

X and Y coordinates.

3. XYZ values.

Name

Type

Description

x

float

X coordinate.

y

float

Y coordinate.

z

float

Z coordinate.

Returns

Type

Description

vector

Vector.

Example

local vec = vector(5, 25, 12);

is_zero

Returns true if this vector is within tolerance range.

Arguments

Name

Type

Description

tolerance

float

Max allowed tolerance. Defaults to 0.01.

Returns

Type

Description

bool

true if ranges between -tolerance and tolerance.

Example

local vec = vector(0, 0.1, 0.5);
print(tostring(vec:is_zero(1))); -- will print 'true', because every value fits in the range of -1 and 1

dist

Returns distance to another vector.

Arguments

Name

Type

Description

other

vector

Vector to calculate distance against.

Returns

Type

Description

float

Distance to other vector.

Example

local vec1 = vector(0, 0, 0);
local vec2 = vector(1, 1, 5);
print(tostring(vec1:dist(vec2)));

dist_sqr

Returns squared distance to another vector.

This method is de-facto faster than the non-squared variant. Use it, if you need extra performance.

Arguments

Name

Type

Description

other

vector

Vector to calculate distance against.

Returns

Type

Description

float

Squared distance to other vector.

Example

local vec1 = vector(0, 0, 0);
local vec2 = vector(1, 1, 5);
print(tostring(vec1:dist_sqr(vec2)));

dist_2d

Returns 2D (only x and y values) distance to another vector.

Arguments

Name

Type

Description

other

vector

Vector to calculate distance against.

Returns

Type

Description

float

Distance to other vector.

Example

local vec1 = vector(0, 0, 0);
local vec2 = vector(1, 1, 5);
print(tostring(vec1:dist_2d(vec2)));

dist_2d_sqr

Returns squared 2D (only x and y values) distance to another vector.

This method is de-facto faster than the non-squared variant. Use it, if you need extra performance.

Arguments

Name

Type

Description

other

vector

Vector to calculate distance against.

Returns

Type

Description

float

Squared distance to other vector.

Example

local vec1 = vector(0, 0, 0);
local vec2 = vector(1, 1, 5);
print(tostring(vec1:dist_2d_sqr(vec2)));

cross

Returns a cross product to another vector.

Arguments

Name

Type

Description

other

vector

Vector to calculate cross product against.

Returns

Type

Description

vector

Cross product.

Example

local vec1 = vector(0, 0, 0);
local vec2 = vector(1, 1, 5);
local cross = vec1:cross(vec2);

is_valid

Returns true if all values in this vector are finite.

Arguments

None.

Returns

Type

Description

bool

true if values are finite.

Example

local vec = vector(5, 1, 6);
if vec:is_valid() then
    -- ...
end

length

Returns length of this vector.

Arguments

None.

Returns

Type

Description

float

Length of this vector.

Example

local vec = vector(5, 1, 6);
local length = vec:length();

length_sqr

Returns squared length of this vector.

This method is de-facto faster than the non-squared variant. Use it, if you need extra performance.

Arguments

None.

Returns

Type

Description

float

Length of this vector.

Example

local vec = vector(5, 1, 6);
local length = vec:length_sqr();

length_2d

Returns 2D length of this vector.

Arguments

None.

Returns

Type

Description

float

Length of this vector.

Example

local vec = vector(5, 1, 6);
local length = vec:length_2d();

length_2d_sqr

Returns squared 2D length of this vector.

This method is de-facto faster than the non-squared variant. Use it, if you need extra performance.

Arguments

None.

Returns

Type

Description

float

Length of this vector.

Example

local vec = vector(5, 1, 6);
local length = vec:length_2d_sqr();

dot

Returns dot product of 2 vectors.

Arguments

Name

Type

Description

other

vector

Vector to calculate dot product against.

Returns

Type

Description

float

Dot product.

Example

local vec1 = vector(0, 0, 0);
local vec2 = vector(1, 1, 5);
local dot = vec1:dot(vec2);

rect

__call

Constructor

Creates a new rectangle.

Arguments

1. Default rectangle (0, 0 position; 0, 0 size).

None.

2. Single value.

Name
Type
Description

3. Single vector.

Name
Type
Description

4. Double value.

Name
Type
Description

5. Double vector.

Name
Type
Description

6. Four values.

Name
Type
Description

Returns

Type
Description

Example


mins

Field

Type:

Mins (top-left) vector.


maxs

Field

Type:

Maxs (bottom-right) vector.


width

Method

Either returns rectangle's width, or sets a new width.

Arguments

1. Get width.

None.

2. Set width.

Name
Type
Description

Returns

1. Get width.

Type
Description

2. Set width.

Type
Description

Example


height

Method

Either returns rectangle's height, or sets a new height.

Arguments

1. Get height.

None.

2. Set height.

Name
Type
Description

Returns

1. Get height.

Type
Description

2. Set height.

Type
Description

Example


size

Method

Either returns rectangle's size, or sets a new size.

Arguments

1. Get size.

None.

2. Set size.

Name
Type
Description

Returns

1. Get size.

Type
Description

2. Set size.

Type
Description

Example


explode

Method

Explodes the rectangle by given vector (increase size from center into all directions by coordinates in the vector).

Arguments

Name
Type
Description

Returns

Type
Description

Example


half_width

Method

Returns a rectangle with half of the width of this rectangle.

Arguments

None.

Returns

Type
Description

Example


translate

Method

Translates (moves) this rectangle by vector coordinates.

Arguments

Name
Type
Description

Returns

Type
Description

Example


margin_left

Method

Move rectangle from the left by given amount.

Arguments

Name
Type
Description

Returns

Type
Description

Example


margin_right

Method

Move rectangle from the right by given amount.

Arguments

Name
Type
Description

Returns

Type
Description

Example


margin_top

Method

Move rectangle from the top by given amount.

Arguments

Name
Type
Description

Returns

Type
Description

Example


margin_bottom

Method

Move rectangle from the bottom by given amount.

Arguments

Name
Type
Description

Returns

Type
Description

Example


padding_left

Method

Adds the value to the left side of the rectangle.

Arguments

Name
Type
Description

Returns

Type
Description

Example


padding_right

Method

Adds the value to the right side of the rectangle.

Arguments

Name
Type
Description

Returns

Type
Description

Example


padding_top

Method

Adds the value to the top side of the rectangle.

Arguments

Name
Type
Description

Returns

Type
Description

Example


padding_bottom

Method

Adds the value to the bottom side of the rectangle.

Arguments

Name
Type
Description

Returns

Type
Description

Example


shrink

Method

Shrinks (implodes) the rectangle by given amount.

Arguments

Name
Type
Description

Returns

Type
Description

Example


expand

Method

Expands (explodes) the rectangle by given amount.

Arguments

Name
Type
Description

Returns

Type
Description

Example


contains

Method

Returns true if this rectangle contains either vector or another rectangle.

Rectangle overload will return true ONLY of entire other rectangle is within the bounds of this one.

Arguments

1. Vector variant.

Name
Type
Description

2. Rectangle variant.

Name
Type
Description

Returns

Type
Description

Example


overlaps

Method

Returns true if the other rectangle overlaps with this rectangle.

Arguments

Name
Type
Description

Returns

Type
Description

Example


intersect

Method

Intersects this rectangle with another rectangle.

Arguments

Name
Type
Description

Returns

Type
Description

Example


tl

Method

Returns top-left vector.

Arguments

None.

Returns

Type
Description

Example


tr

Method

Returns top-right vector.

Arguments

None.

Returns

Type
Description

Example


br

Method

Returns bottom-right vector.

Arguments

None.

Returns

Type
Description

Example


bl

Method

Returns bottom-left vector.

Arguments

None.

Returns

Type
Description

Example


center

Method

Returns center point of this rectangle.

Arguments

None.

Returns

Type
Description

Example


circle

Method

Treats this rectangle as an ellipsis and returns point on it. Note, that this "ellipsis" will be perfect with no modified curvature (basically if this rectangle is a box - you will get a point on a perfect circle).

Arguments

Name
Type
Description

Returns

Type
Description

Example


floor

Method

Returns floored rectangle.

Arguments

None.

Returns

Type
Description

Example


ceil

Method

Returns ceiled rectangle.

Arguments

None.

Returns

Type
Description

Example


round

Method

Returns rounded rectangle.

Arguments

None.

Returns

Type
Description

Example


is_zero

Method

Returns true if both mins and maxs are equal to 0.

Arguments

None.

Returns

Type
Description

Example

value

float

Mins XY, maxs XY value.

value

vec2

Mins vector, maxs vector.

x

float

Mins/maxs X coordinate.

y

float

Mins/maxs Y coordinate.

mins

vec2

Mins vector.

maxs

vec2

Maxs vector.

x0

float

Mins X coordinate.

y0

float

Mins Y coordinate.

x1

float

Maxs X coordinate.

y1

float

Maxs Y coordinate.

rect

New rectangle.

local my_rect = draw.rect(50, 50, 150, 150);

value

float

New width.

float

Width.

rect

New rectangle with changed width.

local half_width = rect:width(rect:width() * 0.5);

value

float

New height.

float

Height.

rect

New rectangle with changed height.

local half_height = rect:height(rect:height() * 0.5);

value

vec2

New size.

vec2

Size.

rect

New rectangle with changed size.

local half_size = rect:size(rect:size() * draw.vec2(0.5, 0.5));

value

vec2

Explode size.

rect

Exploded rectangle.

local exp = rect:explode(draw.vec2(6, 6)); -- will subtract -3,-3 from mins and add 3,3 to maxs

rect

Rectangle with halved width.

local half = rect:half_width();

value

vec2

Translation amount.

rect

Translated rectangle.

local rect = draw.rect(50, 50, 150, 150);
local translated = rect:translate(draw.vec2(5, 5)); -- mins/maxs will be 55,55 and 155,155

value

float

Margin amount.

rect

Moved rectangle.

local new = rect:margin_left(5); -- moves to the right by 5px

value

float

Margin amount.

rect

Moved rectangle.

local new = rect:margin_right(5); -- moves to the left by 5px

value

float

Margin amount.

rect

Moved rectangle.

local new = rect:margin_top(5); -- moves to the bottom by 5px

value

float

Margin amount.

rect

Moved rectangle.

local new = rect:margin_bottom(5); -- moves to the top by 5px

value

float

Padding amount.

rect

Resized rectangle.

local new = rect:padding_left(5); -- adds 5 to mins x

value

float

Padding amount.

rect

Resized rectangle.

local new = rect:padding_right(5); -- adds 5 to maxs x

value

float

Padding amount.

rect

Resized rectangle.

local new = rect:padding_top(5); -- adds 5 to mins y

value

float

Padding amount.

rect

Resized rectangle.

local new = rect:padding_bottom(5); -- adds 5 to maxs y

value

float

Shrink value.

rect

Resized rectangle.

local shrinked = rect:shrink(5); -- adds 5,5 to mins and subtracts 5,5 from maxs

value

float

Expand value.

rect

Resized rectangle.

local expanded = rect:expand(5); -- subtracts 5,5 from mins and adds 5,5 to maxs

other

vec2

Vector to check against.

other

rect

Rectangle to check against.

bool

true if other object is in bounds of this rectangle.

if rect:contains(cursor_pos) then
    -- ...
end

other

rect

Rectangle to check against.

bool

true if other rectangle overlaps with this rectangle.

if rect:overlaps(another_rect) then
    -- ...
end

other

rect

Rectangle to intersect with.

rect

Intersected rectangle.

local intersected = rect:intersect(another_rect);

vec2

Top-left vector.

local tl = rect:tl();

vec2

Top-right vector.

local tr = rect:tr();

vec2

Bottom-right vector.

local br = rect:br();

vec2

Bottom-left vector.

local bl = rect:bl();

vec2

Center point.

local center = rect:center();

r

float

Radians value.

vec2

Point on the ellipsis.

local point = rect:circle(rad(250)); -- returns point on the 250th degree

rect

Floored rectangle.

local floored = rect:floor();

rect

Ceiled rectangle.

local ceiled = rect:ceil();

rect

Rounded rectangle.

local rounded = rect:round();

bool

true if this is a zero rectangle.

if rect:is_zero() then
    -- ...
end
vec2
vec2

context_input

This type represents the GUI input context.

You can use cursor, is_mouse_up, is_mouse_down, is_key_up and is_key_down methods outside context. Using other methods will not make any sense, as the information will be outdated.

cursor

Returns current cursor position.

Arguments

None.

Returns

Example


cursor_prev

Returns previous cursor position.

Arguments

None.

Returns

Example


cursor_delta

Delta value between previous and current cursor positions.

Arguments

None.

Returns

Example


did_cursor_move

Returns true if the cursor did move since the last input.

Arguments

None.

Returns

Example


did_wheel_move

Returns true if mouse scroll wheel did move since the last input.

Arguments

None.

Returns

Example



did_process_mouse

Returns true if any mouse key's state had changed.

Arguments

None.

Returns

Example



button_released

Returns true if any key was released since the last input.

Arguments

None.

Returns

Example



wheel_delta

Returns the amount of rows scrolled this input.

Arguments

None.

Returns

Example


is_mouse_up

Returns true if the mouse key is up (depressed).

Arguments

Returns

Example


is_mouse_down

Returns true if the mouse key is down (pressed).

Arguments

Returns

Example


is_mouse_clicked

Returns true if the mouse key is clicked (switched from depressed to pressed state).

Arguments

Returns

Example


is_mouse_released

Returns true if the mouse key is released (switched from pressed to depressed state).

Arguments

Returns

Example


did_process_key

Returns true if any key's state had changed.

Arguments

None.

Returns

Example


is_key_up

Returns true if a key is up (depressed).

Arguments

Returns

Example


is_key_down

Returns true if a key is down (pressed).

Arguments

Returns

Example


is_key_clicked

Returns true if a key is clicked (switched from depressed to pressed state).

Arguments

Returns

Example


is_key_released

Returns true if a key is released (switched from pressed to depressed state).

Arguments

Returns

Example

Type

Description

vec2

Cursor position.

local cur = gui.input:cursor();

Type

Description

vec2

Previous cursor position.

local prev = gui.input:cursor_prev();

Type

Description

vec2

Cursor delta.

local delta = gui.input:cursor_delta();

Type

Description

bool

true if moved.

if gui.input:did_cursor_move() then
    -- ...
end

Type

Description

bool

true if moved.

if gui.input:did_wheel_move() then
    -- ...
end

Type

Description

bool

true if processed.

if gui.input:did_process_mouse() then
    -- ...
end

Type

Description

bool

true if released.

if gui.input:button_released() then
    -- ...
end

Type

Description

float

Rows scrolled.

local scroll = gui.input:wheel_delta();

Name

Type

Description

mb

mouse_button

Mouse button.

Type

Description

bool

true if depressed.

if gui.input:is_mouse_up(gui.mouse_button.left) then
    -- ...
end

Name

Type

Description

mb

mouse_button

Mouse button.

Type

Description

bool

true if pressed.

if gui.input:is_mouse_down(gui.mouse_button.left) then
    -- ...
end

Name

Type

Description

mb

mouse_button

Mouse button.

Type

Description

bool

true if clicked.

if gui.input:is_mouse_clicked(gui.mouse_button.left) then
    -- ...
end

Name

Type

Description

mb

mouse_button

Mouse button.

Type

Description

bool

true if released.

if gui.input:is_mouse_released(gui.mouse_button.left) then
    -- ...
end

Type

Description

bool

true if state changed.

if gui.input:did_process_key() then
    -- ...
end

Name

Type

Description

k

int

Virtual key.

Type

Description

bool

true if depressed.

if gui.input:is_key_up(0x41) then -- 0x41 = "A"
    -- ...
end

Name

Type

Description

k

int

Virtual key.

Type

Description

bool

true if pressed.

if gui.input:is_key_down(0x41) then -- 0x41 = "A"
    -- ...
end

Name

Type

Description

k

int

Virtual key.

Type

Description

bool

true if clicked.

if gui.input:is_key_clicked(0x41) then -- 0x41 = "A"
    -- ...
end

Name

Type

Description

k

int

Virtual key.

Type

Description

bool

true if released.

if gui.input:is_key_released(0x41) then -- 0x41 = "A"
    -- ...
end
input

color

color

Last modified: 03 January 2025

This type is a color used within the rendering system.

Do not mistake this type with color that is used in game! While these types are interchangeable internally, they are NOT in the API.

__call

Creates a new color instance.

Arguments

1. Default color (translucent black).

None.

2. Integer colors.

Name

Type

Description

r

int

Red color (0 to 255).

g

int

Green color (0 to 255).

b

int

Blue color (0 to 255).

a

int

Opacity (0 to 255). Defaults to 255.

3. Hex string.

Name

Type

Description

hex

string

Hex string. Formats are: #rrggbbaa, #rrggbb, #rgba and #rgb.

Returns

Type

Description

color

Color object.

Example

local white = draw.color(255, 255, 255);

white

Returns a white, opaque color.

Arguments

None.

Returns

Type

Description

color

Color object.

Example

local white = draw.color.white();

white_transparent

Returns a white, transparent color.

Arguments

None.

Returns

Type

Description

color

Color object.

Example

local white_t = draw.color.white_transparent();

black

Returns a black, opaque color.

Arguments

None.

Returns

Type

Description

color

Color object.

Example

local black = draw.color.black();

black_transparent

Returns a black, transparent color.

Arguments

None.

Returns

Type

Description

color

Color object.

Example

local black_t = draw.color.black_transparent();

percent

Returns a red-to-green color, depending on the provided percent.

Arguments

Name

Type

Description

p

float

Percentile (0 to 1).

a

float

Opacity. Defaults to 1.

Returns

Type

Description

color

Color object.

Example

local yellow = draw.color.percent(0.5);

gray

Returns a black-to-white color, depending on the provided percent.

Arguments

Name

Type

Description

b

float

Percentile (0 to 1).

a

float

Opacity. Defaults to 1.

Returns

Type

Description

color

Color object.

Example

local gray = draw.color.gray(0.5);

interpolate

Interpolates two colors.

Arguments

Name

Type

Description

a

color

Starting color.

b

color

Ending color.

t

float

Interpolation percentile.

Returns

Type

Description

color

Color object.

Example

local a = draw.color.white();
local b = draw.color.black();
local i = draw.color.interpolate(a, b, 0.5); -- gray

rgba

Returns integer representation of this color (RGBA format)

Arguments

None.

Returns

Type

Description

int

RGBA color.

Example

local num = col:rgba();

argb

Returns integer representation of this color (ARGB format)

Arguments

None.

Returns

Type

Description

int

ARGB color.

Example

local num = col:argb();

bgra

Returns integer representation of this color (BGRA format)

Arguments

None.

Returns

Type

Description

int

BGRA color.

Example

local num = col:bgra();

abgr

Returns integer representation of this color (ABGR format)

Arguments

None.

Returns

Type

Description

int

ABGR color.

Example

local num = col:abgr();

darken

Returns darker variant of this color.

Arguments

Name

Type

Description

value

float

Modulation amount (0 to 1).

Returns

Type

Description

color

Darker color.

Example

local darker = col:darken(0.5);

mod_a

Modulate opacity of the color. This will take existing opacity, and multiply it by whatever value you provide. It is useful if you want to modulate same color in steps, instead of setting the accurate opacity number.

Arguments

1. Float variant.

Name

Type

Description

value

float

Opacity modulation (0 to 1).

2. Integer variant.

Name

Type

Description

value

int

Opacity modulation (0 to 255).

Returns

Type

Description

color

Modulated color.

Example

local half_opacity = col:mod_a(0.5);

r

Override red and return new color.

Arguments

Name

Type

Description

value

float

New value.

Returns

Type

Description

color

New color.

Example

local full_red = col:r(1);

g

Override green and return new color.

Arguments

Name

Type

Description

value

float

New value.

Returns

Type

Description

color

New color.

Example

local full_green = col:g(1);

b

Override blue and return new color.

Arguments

Name

Type

Description

value

float

New value.

Returns

Type

Description

color

New color.

Example

local full_blue = col:b(1);

a

Override opacity and return new color.

Arguments

Name

Type

Description

value

float

New value.

Returns

Type

Description

color

New color.

Example

local full_opacity = col:a(1);

get_r

Returns red color value.

Arguments

None.

Returns

Type

Description

int

Color value.

Example

local r = col:get_r();

get_g

Returns green color value.

Arguments

None.

Returns

Type

Description

int

Color value.

Example

local g = col:get_g();

get_b

Returns blue color value.

Arguments

None.

Returns

Type

Description

int

Color value.

Example

local b = col:get_b();

get_a

Returns opacity color value.

Arguments

None.

Returns

Type

Description

int

Color value.

Example

local a = col:get_a();

h

Return hue value of the color.

Arguments

None.

Returns

Type

Description

int

Hue (0 to 359).

Example

local hue = col:h();

s

Returns saturation value of the color.

Arguments

None.

Returns

Type

Description

float

Saturation (0 to 1).

Example

local saturation = col:s();

v

Returns brightness value of the color.

Arguments

None.

Returns

Type

Description

float

Brightness (0 to 1).

Example

local brightness = col:v();

hsv

Construct new color from provided HSB values.

Arguments

Name

Type

Description

hue

int

Hue (0 to 359).

saturation

float

Saturation (0 to 1).

brightness

float

Brightness (0 to 1).

alpha

float

Override opacity of the source color. Must be either left out, or provided 0 to 1 value.

Returns

Type

Description

color

New color.

Example

local new_col = col:hsv(250, 0.5, 0.1);

Layer

A layer is a type that is used to store render commands, as well as vertex and index data. This is the only way to push shapes and control rendering state.

g

Type: command

The next render command to be pushed to the queue. This is the object you want to change to, for example, set a texture, or change rendering modes.


font

Type: font_base

Font to use with add_text. If nothing has been set, no text will get rendered.


tex_sz

Type: vec2?

Texture dimensions. This value is only required if you are trying to render rounded shapes with a texture, so the rendering system will correctly map your UV coordinates to whatever shape you are rendering.


skip_dpi

Type: bool

If set to true, will skip global DPI scale. Defaults to true.


add_triangle_filled

Adds a filled triangle with a single color.

Arguments

Name

Type

Description

a

A point.

b

B point.

c

C point.

col

Shape color.

Returns

Nothing.

Example

layer:add_triangle_filled(
    draw.vec2(50, 50), draw.vec2(25, 75),
    draw.vec2(75, 75), draw.color(255, 255, 255));

add_quad_filled

Adds a filled quad with a single color.

Arguments

Name

Type

Description

tl

Top left point.

tr

Top right point.

br

Bottom right point.

bl

Bottom left point.

col

Shape color.

Returns

Nothing.

Example

layer:add_quad_filled(
    draw.vec2(50, 50), draw.vec2(100, 60),
    draw.vec2(100, 100), draw.vec2(30, 70),
    draw.color(255, 255, 255));

add_rect_filled

Adds a filled rectangle with a single color.

Arguments

Name

Type

Description

r

Rectangle.

col

Shape color.

Returns

Nothing.

Example

layer:add_rect_filled(draw.rect(50, 50, 150, 150), draw.color(255, 255, 255));

add_circle_filled

Adds a filled circle with a single color.

Arguments

Name

Type

Description

center

Center point.

radius

float

Circle radius.

c

Shape color.

segments

int

Circle segments. If set to 0, will attempt automatic segment deduction. Defaults to 0.

fill

float

Fill amount (clockwise, 0 to 1). Defaults to 1.

Returns

Nothing.

Example

layer:add_circle_filled(draw.vec2(50, 50), 10, draw.color(255, 255, 255));

add_triangle_filled_multicolor

Adds a filled, multicolor triangle.

Arguments

Name

Type

Description

a

A point.

b

B point.

c

C point.

cols

table[color, color, color]

Colors for each point. Colors go in the very same order as the parameter list.

Returns

Nothing.

Example

layer:add_triangle_filled_multicolor(
     draw.vec2(50, 50), draw.vec2(25, 75),
     draw.vec2(75, 75), {
        draw.color(255, 0, 0),
        draw.color(0, 255, 0),
        draw.color(0, 0, 255)
     });

add_rect_filled_multicolor

Adds a filled, multicolor rectangle.

Arguments

Name

Type

Description

r

Rectangle.

cols

table[color, color, color, color]

Colors for each corner of the rectangle, in clockwise order starting from top-left.

Returns

Nothing.

Example

layer:add_rect_filled_multicolor(
    draw.rect(50, 50, 150, 150), {
        draw.color(255, 0, 0),
        draw.color(0, 255, 0),
        draw.color(0, 0, 255),
        draw.color(255, 255, 0)
    });

add_circle_filled_multicolor

Adds a filled, multicolor circle.

Arguments

Name

Type

Description

center

Center point.

radius

float

Circle radius.

cols

table[color, color]

Colors for the gradient, starting with the inner and ending with the outer color.

segments

int

The number of segments to approximate the circle. Defaults to 36.

fill

float

The portion of the circle to fill, where 1.0 is a full circle. Defaults to 1.0.

Returns

Nothing.

Example

layer:add_circle_filled_multicolor(
    draw.vec2(100, 100), 50, {
        draw.color(255, 0, 0),
        draw.color(0, 0, 255)
    }, 36, 1.0);

add_quad_filled_multicolor

Adds a filled, multicolor quad.

Arguments

Name

Type

Description

tl

Top left point.

tr

Top right point.

br

Bottom right point.

bl

Bottom left point.

cols

table[color, color]

Colors for the gradient, applied from bottom to top.

Returns

Nothing.

Example

layer:add_quad_filled_multicolor(
    draw.vec2(50, 50), draw.vec2(150, 50),
    draw.vec2(150, 150), draw.vec2(50, 150), {
        draw.color(255, 0, 0),
        draw.color(0, 0, 255)
    });

add_pill_multicolor

Adds a multicolor pill shape.

Arguments

Name

Type

Description

mins

Top left point of the pill.

maxs

Bottom right point of the pill.

radius_min

float

The minimum radius of the pill's rounded edges.

radius_max

float

The maximum radius of the pill's rounded edges.

cols

table[color, color]

Colors for the gradient, applied from bottom to top.

segments

int

The number of segments for approximating rounded edges. Defaults to 16.

Returns

Nothing.

Example

layer:add_pill_multicolor(
    draw.vec2(50, 50), draw.vec2(150, 100),
    10, 20, {
        draw.color(255, 0, 0),
        draw.color(0, 0, 255)
    }, 16);

add_shadow_line

Adds a shadow line.

Arguments

Name

Type

Description

r

Bounding box for the shadow line.

dir

Shadow direction.

a

float

Max opacity. Defaults to 0.25.

Returns

Nothing.

Example

layer:add_shadow_line(
    draw.rect(50, 50, 150, 150), draw.shadow_dir.down, 0.25);

add_shadow_rect

Adds a shadowed rectangle.

Arguments

Name

Type

Description

r

Rectangle.

radius

float

Shadow distance, in pixels, outwards.

bg

bool

Whether to draw a background for the rectangle. Defaults to true.

a

float

Max opacity of the shadow. Defaults to 0.25.

Returns

Nothing.

Example

layer:add_shadow_rect(
    draw.rect(50, 50, 150, 150), 15, true, 0.25);

add_glow

Adds a glow box.

Arguments

Name

Type

Description

r

Box rectangle.

radius

float

Glow distance, in pixels, outwards.

c

Glow color.

parts

Parts of the glow to enable. Defaults to all.

Returns

Nothing.

Example

layer:add_glow(draw.rect(50, 50, 150, 150), 15, draw.color(255, 0, 0));

add_rect_filled_rounded

Adds a filled, rounded rectangle.

Arguments

Name

Type

Description

r

Rectangle.

c

Fill color.

amount

float

Rounding amount.

rnd

Rounding mode. Defaults to all.

Returns

Nothing.

Example

layer:add_rect_filled_rounded(
    draw.rect(50, 50, 150, 150),
    draw.color(255, 0, 0),
    10,
    draw.rounding.all
);

add_rect_filled_rounded_multicolor

Adds a filled, multicolor rounded rectangle.

Arguments

Name

Type

Description

r

Rectangle.

c

table[color, color, color, color]

Fill colors. Used clockwise, starting from top left.

amount

float

Rounding amount.

rnd

Rounding mode. Defaults to all.

Returns

Nothing.

Example

layer:add_rect_filled_rounded_multicolor(
    draw.rect(50, 50, 150, 150), {
        draw.color(255, 0, 0),
        draw.color(0, 255, 0),
        draw.color(0, 0, 255),
        draw.color(255, 255, 0)
    },
    10,
    draw.rounding.all
);

add_triangle

Adds a stroked triangle.

Arguments

Name

Type

Description

a

Point A.

b

Point B.

c

Point C.

col

Line color.

thickness

float

Line thickness. Defaults to 1.0.

mode

Outline mode. Defaults to inset.

Returns

Nothing.

Example

layer:add_triangle(
    draw.vec2(50, 50),
    draw.vec2(25, 75),
    draw.vec2(75, 75),
    draw.color(255, 0, 0),
    1.0,
    draw.outline_mode.inset
);

add_quad

Adds a stroked quad.

Arguments

Name

Type

Description

tl

Top-left point.

tr

Top-right point.

br

Bottom-right point.

bl

Bottom-left point.

c

Line color.

thickness

float

Line thickness. Defaults to 1.0.

mode

Outline mode. Defaults to inset.

Returns

Nothing.

Example

layer:add_quad(
    draw.vec2(50, 50),
    draw.vec2(150, 50),
    draw.vec2(150, 150),
    draw.vec2(50, 150),
    draw.color(255, 0, 0),
    1.0,
    draw.outline_mode.inset
);

add_rect

Adds a stroked rectangle.

Arguments

Name

Type

Description

r

Rectangle.

c

Line color.

thickness

float

Line thickness. Defaults to 1.0.

mode

Outline mode. Defaults to inset.

Returns

Nothing.

Example

layer:add_rect(
    draw.rect(50, 50, 150, 150),
    draw.color(255, 0, 0),
    1.0,
    draw.outline_mode.inset
);

add_circle

Adds a stroked circle.

Arguments

Name

Type

Description

center

Center point.

radius

float

Circle radius.

c

Line color.

segments

int

Circle segments. Defaults to 36.

fill

float

Fill amount. Defaults to 1.0.

thickness

float

Line thickness. Defaults to 1.0.

mode

Outline mode. Defaults to inset.

Returns

Nothing.

Example

layer:add_circle(
    draw.vec2(100, 100),
    50,
    draw.color(255, 0, 0),
    36,
    1.0,
    1.0,
    draw.outline_mode.inset
);

add_line

Adds a line.

Arguments

Name

Type

Description

a

Start point.

b

End point.

c

Line color.

thickness

float

Line thickness. Defaults to 1.0

Returns

Nothing.

Example

layer:add_line(
    draw.vec2(50, 50),
    draw.vec2(150, 150),
    draw.color(255, 0, 0)
);

add_line_multicolor

Adds a multicolor line.

Arguments

Name

Type

Description

a

Start point.

b

End point.

c

Start color.

c2

End color.

thickness

float

Line thickness. Defaults to 1.0.

Returns

Nothing.

Example

layer:add_line_multicolor(
    draw.vec2(50, 50),
    draw.vec2(150, 150),
    draw.color(255, 0, 0),
    draw.color(0, 0, 255),
    2.0
);

add_rect_rounded

Adds a rounded, filled rectangle.

Arguments

Name

Type

Description

r

Rectangle.

c

Line color.

amount

float

Rounding amount.

rnd

Rounding mode. Defaults to all.

thickness

float

Line thickness. Defaults to 1.0.

mode

Outline mode. Defaults to inset.

Returns

Nothing.

Example

layer:add_rect_rounded(draw.rect(50, 50, 150, 150),
    draw.color(255, 255, 255), 14);

add_text

Adds text.

If font wasn't set, this function will do nothing.

You can control the color while rendering the text. To change the color, add \fRRGGBBAA to the string. To reset the color, add \b.

Arguments

Name

Type

Description

p

Text origin point.

text

string

Text.

c

Text color.

params

Text aligning parameters. Defaults to nil.

Returns

Nothing.

Example

layer:add_text(draw.vec2(50, 50), 'Hello world!', draw.color(255, 255, 255));

override_clip_rect

Overrides clip rectangle with support of intersection.

Arguments

Name

Type

Description

r

New clip rect.

intersect

bool

Whether this function should intersect previous rect with the new one. Defaults to true.

Returns

Nothing.

Example

layer:override_clip_rect(draw.rect(50, 50, 150, 150));
vec2
vec2
vec2
color
vec2
vec2
vec2
vec2
color
rect
color
vec2
color
vec2
vec2
vec2
rect
vec2
vec2
vec2
vec2
vec2
vec2
vec2
rect
shadow_dir
rect
rect
color
glow_parts
rect
color
rounding
rect
rounding
vec2
vec2
vec2
color
outline_mode
vec2
vec2
vec2
vec2
color
outline_mode
rect
color
outline_mode
vec2
color
outline_mode
vec2
vec2
color
vec2
vec2
color
color
rect
color
rounding
outline_mode
vec2
color
text_params?
rect?