1 of 100

CS2 Lua API

Overview

Official lua API documentation for fatality.win

Introduction

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 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.

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: Visual Studio Code, Notepad++, 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.

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);

Now, let's break down this example script:

Defining a callback function

Most of your scripting will run within several callbacks 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.

local function on_present_queue()
end

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 drawing layer. 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:

local d = draw.surface;

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 draw.fonts. To access a font, either use dot syntax, or treat it like a dictionary:

d.font = draw.fonts['gui_main'];

Drawing text

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

Invoke the add_text 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.

d:add_text(draw.vec2(50, 50),
        'Hello drawing! My first script speaking brev.',
         draw.color.white()
    );

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 add method on events.present_queue.

events.present_queue:add(on_present_queue);

Result

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

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:

Creating Libraries

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

API

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));

Instances

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)

Usage:

Arguments

Name

Type

Description

Returns

Nothing.

Example

get_screen_size

Method

Returns client window screen size.

Arguments

None.

Returns

Type

Description

Example

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

Example

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

Example

is_null

Method

Returns whether the channel is stubbed.

Arguments

None.

Returns

Example

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

Example

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

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

Returns

Type

Description

Example

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

Returns

Example

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

Mods

Usage: mods.{mod_name}

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

events

Field

Type: events_t

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

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.

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

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

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.

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).

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.

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.

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.

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 .

obj

Type:

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 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

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

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

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

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.

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

Arguments

Returns

Nothing.

Example

for_each_z

Loops the entities in the reverse order.

Arguments

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: chandle<type>

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

avatar

Type: texture

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.

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

cs2_grenade_projectile

This type represents a grenade projectile.

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_grenade_type

Returns the grenade type.

Arguments

None.

Returns

Type

Description

int

Grenade type.

Example

local type = gren:get_grenade_type();

ccsweapon_base_vdata

This type represents a weapon's static data.

__index

Attemps to search for a field in this class.

Arguments

Returns

Example

cfiring_mode

Firing mode information.

values_arr

Type: <type>

Values.

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).

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.

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.

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.

control_id

This type represents a control ID.

__call

Constructs the ID structure.

Arguments

Returns

Example

id

Type: int

Hashed representation of the ID.

id_string

Type: string

Normal representation of the ID.

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.

user_t

This type represents basic user information.

avatar

Type:

User's avatar. May be nil.

username

Type: string

User's username.

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).

notification_system

This type represents a notification system.

add

Adds a notification to the list.

Arguments

Returns

Nothing.

Example

notification

This type represents a notification item.

__call

Constructs the notification.

Arguments

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

selectable

This type represents a selectable control.

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

__call

Constructs the selectable.

Arguments

Name

Type

Description

id

Control ID.

str

string

Text string.

Returns

Type

Description

selectable

Selectable object.

Example

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

button

This type represents a button control.

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

__call

Constructs the button.

Arguments

Returns

Example

color_picker

This type represents a color picker control.

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

__call

Constructs the color picker.

Arguments

Returns

Example

get_value

Returns color picker' value.

layout

This type represents a layout control.

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

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.

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);

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.

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

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);

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);

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 input context. Using other methods will not make any sense, as the information will be outdated.

cursor

Returns current cursor position.

Arguments

None.

Returns

Type

Description

Cursor position.

Example

local cur = gui.input:cursor();

cursor_prev

Returns previous cursor position.

Arguments

None.

Returns

Type

Description

Previous cursor position.

Example

local prev = gui.input:cursor_prev();

cursor_delta

Delta value between previous and current cursor positions.

Arguments

None.

Returns

Type

Description

Cursor delta.

Example

local delta = gui.input:cursor_delta();

did_cursor_move

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

Arguments

None.

Returns

Type

Description

bool

true if moved.

Example

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

did_wheel_move

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

Arguments

None.

Returns

Type

Description

bool

true if moved.

Example

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

did_process_mouse

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

Arguments

None.

Returns

Type

Description

bool

true if processed.

Example

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

button_released

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

Arguments

None.

Returns

Type

Description

bool

true if released.

Example

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

wheel_delta

Returns the amount of rows scrolled this input.

Arguments

None.

Returns

Type

Description

float

Rows scrolled.

Example

local scroll = gui.input:wheel_delta();

is_mouse_up

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

Arguments

Name

Type

Description

mb

Mouse button.

Returns

Type

Description

bool

true if depressed.

Example

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

is_mouse_down

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

Arguments

Name

Type

Description

mb

Mouse button.

Returns

Type

Description

bool

true if pressed.

Example

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

is_mouse_clicked

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

Arguments

Name

Type

Description

mb

Mouse button.

Returns

Type

Description

bool

true if clicked.

Example

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

is_mouse_released

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

Arguments

Name

Type

Description

mb

Mouse button.

Returns

Type

Description

bool

true if released.

Example

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

did_process_key

Returns true if any key's state had changed.

Arguments

None.

Returns

Type

Description

bool

true if state changed.

Example

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

is_key_up

Returns true if a key is up (depressed).

Arguments

Name

Type

Description

k

int

Virtual key.

Returns

Type

Description

bool

true if depressed.

Example

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

is_key_down

Returns true if a key is down (pressed).

Arguments

Name

Type

Description

k

int

Virtual key.

Returns

Type

Description

bool

true if pressed.

Example

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

is_key_clicked

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

Arguments

Name

Type

Description

k

int

Virtual key.

Returns

Type

Description

bool

true if clicked.

Example

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

is_key_released

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

Arguments

Name

Type

Description

k

int

Virtual key.

Returns

Type

Description

bool

true if released.

Example

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

rect

__call

Constructor

Creates a new rectangle.

Arguments

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

None.

2. Single value.

Name

Type

Description

value

float

Mins XY, maxs XY value.

3. Single vector.

Name

Type

Description

value

Mins vector, maxs vector.

4. Double value.

Name

Type

Description

x

float

Mins/maxs X coordinate.

y

float

Mins/maxs Y coordinate.

5. Double vector.

Name

Type

Description

mins

Mins vector.

maxs

Maxs vector.

6. Four values.

Name

Type

Description

x0

float

Mins X coordinate.

y0

float

Mins Y coordinate.

x1

float

Maxs X coordinate.

y1

float

Maxs Y coordinate.

Returns

Type

Description

rect

New rectangle.

Example

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

mins

Field

Type: vec2

Mins (top-left) vector.

maxs

Field

Type: vec2

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

value

float

New width.

Returns

1. Get width.

Type

Description

float

Width.

2. Set width.

Type

Description

rect

New rectangle with changed width.

Example

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

height

Method

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

Arguments

1. Get height.

None.

2. Set height.

Name

Type

Description

value

float

New height.

Returns

1. Get height.

Type

Description

float

Height.

2. Set height.

Type

Description

rect

New rectangle with changed height.

Example

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

size

Method

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

Arguments

1. Get size.

None.

2. Set size.

Name

Type

Description

value

New size.

Returns

1. Get size.

Type

Description

Size.

2. Set size.

Type

Description

rect

New rectangle with changed size.

Example

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

explode

Method

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

Arguments

Name

Type

Description

value

Explode size.

Returns

Type

Description

rect

Exploded rectangle.

Example

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

half_width

Method

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

Arguments

None.

Returns

Type

Description

rect

Rectangle with halved width.

Example

local half = rect:half_width();

translate

Method

Translates (moves) this rectangle by vector coordinates.

Arguments

Name

Type

Description

value

Translation amount.

Returns

Type

Description

rect

Translated rectangle.

Example

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

margin_left

Method

Move rectangle from the left by given amount.

Arguments

Name

Type

Description

value

float

Margin amount.

Returns

Type

Description

rect

Moved rectangle.

Example

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

margin_right

Method

Move rectangle from the right by given amount.

Arguments

Name

Type

Description

value

float

Margin amount.

Returns

Type

Description

rect

Moved rectangle.

Example

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

margin_top

Method

Move rectangle from the top by given amount.

Arguments

Name

Type

Description

value

float

Margin amount.

Returns

Type

Description

rect

Moved rectangle.

Example

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

margin_bottom

Method

Move rectangle from the bottom by given amount.

Arguments

Name

Type

Description

value

float

Margin amount.

Returns

Type

Description

rect

Moved rectangle.

Example

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

padding_left

Method

Adds the value to the left side of the rectangle.

Arguments

Name

Type

Description

value

float

Padding amount.

Returns

Type

Description

rect

Resized rectangle.

Example

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

padding_right

Method

Adds the value to the right side of the rectangle.

Arguments

Name

Type

Description

value

float

Padding amount.

Returns

Type

Description

rect

Resized rectangle.

Example

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

padding_top

Method

Adds the value to the top side of the rectangle.

Arguments

Name

Type

Description

value

float

Padding amount.

Returns

Type

Description

rect

Resized rectangle.

Example

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

padding_bottom

Method

Adds the value to the bottom side of the rectangle.

Arguments

Name

Type

Description

value

float

Padding amount.

Returns

Type

Description

rect

Resized rectangle.

Example

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

shrink

Method

Shrinks (implodes) the rectangle by given amount.

Arguments

Name

Type

Description

value

float

Shrink value.

Returns

Type

Description

rect

Resized rectangle.

Example

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

expand

Method

Expands (explodes) the rectangle by given amount.

Arguments

Name

Type

Description

value

float

Expand value.

Returns

Type

Description

rect

Resized rectangle.

Example

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

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

other

Vector to check against.

2. Rectangle variant.

Name

Type

Description

other

rect

Rectangle to check against.

Returns

Type

Description

bool

true if other object is in bounds of this rectangle.

Example

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

overlaps

Method

Returns true if the other rectangle overlaps with this rectangle.

Arguments

Name

Type

Description

other

rect

Rectangle to check against.

Returns

Type

Description

bool

true if other rectangle overlaps with this rectangle.

Example

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

intersect

Method

Intersects this rectangle with another rectangle.

Arguments

Name

Type

Description

other

rect

Rectangle to intersect with.

Returns

Type

Description

rect

Intersected rectangle.

Example

local intersected = rect:intersect(another_rect);

tl

Method

Returns top-left vector.

Arguments

None.

Returns

Type

Description

Top-left vector.

Example

local tl = rect:tl();

tr

Method

Returns top-right vector.

Arguments

None.

Returns

Type

Description

Top-right vector.

Example

local tr = rect:tr();

br

Method

Returns bottom-right vector.

Arguments

None.

Returns

Type

Description

Bottom-right vector.

Example

local br = rect:br();

bl

Method

Returns bottom-left vector.

Arguments

None.

Returns

Type

Description

Bottom-left vector.

Example

local bl = rect:bl();

center

Method

Returns center point of this rectangle.

Arguments

None.

Returns

Type

Description

Center point.

Example

local center = rect:center();

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

r

float

Radians value.

Returns

Type

Description

Point on the ellipsis.

Example

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

floor

Method

Returns floored rectangle.

Arguments

None.

Returns

Type

Description

rect

Floored rectangle.

Example

local floored = rect:floor();

ceil

Method

Returns ceiled rectangle.

Arguments

None.

Returns

Type

Description

rect

Ceiled rectangle.

Example

local ceiled = rect:ceil();

round

Method

Returns rounded rectangle.

Arguments

None.

Returns

Type

Description

rect

Rounded rectangle.

Example

local rounded = rect:round();

is_zero

Method

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

Arguments

None.

Returns

Type

Description

bool

true if this is a zero rectangle.

Example

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

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));

CS2 Lua API

Overview

Official lua API documentation for fatality.win​

Introduction

Creating scripts

Welcome to the basics of scripting with our API.

Basic Concepts

Documentation Overview

Labels:

Argument and return lists

Types

Rules﻿

You Control the Lua State﻿

Prioritize Safety﻿

Keep the Software Usable﻿

First Steps

Fire up a text editor﻿

Writing your first script﻿

Defining a callback function﻿

Accessing drawing layer﻿

Setting a font﻿

Drawing text﻿

Registering a callback﻿

Result﻿

Adding UI

Adding UI﻿

Creating a control﻿

Constructing the row﻿

Adding the row to a group﻿

Using the value﻿

Creating Libraries

API

Global Functions

print﻿

Arguments

error﻿

Arguments

Instances

event_t

add﻿

remove﻿

Game

global_vars﻿

engine﻿

input﻿

input_system﻿

game_ui_funcs﻿

global_vars_t

real_time﻿

frame_count﻿

abs_frame_time﻿

max_clients﻿

ticks_this_frame﻿

frame_time﻿

cur_time﻿

tick_fraction﻿

tick_count﻿

map_path﻿

map_name﻿

cengine_client

get_last_timestamp﻿

get_last_server_tick﻿

in_game﻿

is_connected﻿

get_netchan﻿

client_cmd﻿

get_screen_size﻿

cnet_chan

get_address﻿

is_loopback﻿

is_null﻿

get_latency﻿

ccsgo_input

in_third_person﻿

get_view_angles﻿

set_view_angles﻿

cinput_system

vk_to_button_code﻿

cgame_ui_funcs

get_binding_for_button_code﻿

Official lua API documentation for fatality.win

Rules

You Control the Lua State

Prioritize Safety

Keep the Software Usable

Fire up a text editor

Writing your first script

Defining a callback function

Accessing drawing layer

Setting a font

Drawing text

Registering a callback

Result

Adding UI

Creating a control

Constructing the row

Adding the row to a group

Using the value

print

error

add

remove

global_vars

engine

input

input_system

game_ui_funcs

real_time

frame_count

abs_frame_time

max_clients

ticks_this_frame

frame_time

cur_time

tick_fraction

tick_count

map_path

map_name

get_last_timestamp

get_last_server_tick

in_game

is_connected

get_netchan

client_cmd

get_screen_size

get_address

is_loopback

is_null

get_latency

in_third_person

get_view_angles

set_view_angles

vk_to_button_code

get_binding_for_button_code

find

name

description

flags

value

events

add_listener

accessor

__index

__newindex

get_back_buffer

get_back_buffer_downsampled

get_shared_texture

inset

outset

center

rounding

tl

tr

bl

br

t

l

r

b

all