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

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

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.

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:

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:

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 and pass the desired ID.

Then, create the checkbox by calling 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 - .

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:

Then call its method to include your row:

That's it!

It is very important to call 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:

and close it after.

The final script should look something like this:

And here's the result:

Creating Libraries

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

Workshop

Guidelines

All items published on the Storefront must follow these guidelines to keep the Workshop safe, usable, and fair for everyone.

1. Provide meaningful descriptions

Your description should clearly explain what the item does, what it requires, and any limitations it may have. Do not use vague, misleading, or clickbait-style descriptions. End users should know exactly what they are getting before they subscribe to or purchase an item.

2. Maintain a minimum quality standard

Trivial one-line scripts, spam items, or submissions with no meaningful functionality are not allowed. All items must undergo basic quality assurance to ensure they work as described and do not pollute the Workshop with junk content.

3. Respect capability requests

Always use the provided APIs and tools in a way that respects user choice of permissions. Do not attempt to bypass or override capability restrictions. If your item does not need filesystem access, for example, you must not request it.

4. Practice fair market behavior

Artificial price dumping, manipulative pricing strategies, or exploitative sales tactics are not allowed. The Workshop should remain a healthy, competitive, and sustainable marketplace for all developers.

5. Do not publish malicious code

This includes malware, exploits, spyware, or any script designed to harm users or their systems. While beta branches exist for unverified testing, all items submitted to live must be safe and secure. Any attempt to sneak in harmful code will result in removal and possible bans.

6. Ensure compatibility with existing features

Scripts and configs must not intentionally disrupt core software features, other Workshop items, or the overall stability of the platform. If your item modifies functionality, it must do so safely and predictably.

7. Keep content respectful

Item names, descriptions, scripts, and configs must not contain harassment, hate speech, targeted attacks, or inappropriate material. All content must follow the same standards as the forum and community guidelines.

8. Maintain and update your items

If your script or config breaks due to updates in the core software or APIs, you are responsible for updating it. If you choose to stop maintaining an item, you must clearly mark it as deprecated so users are not misled.

9. Be transparent with monetization

Paid items must disclose exactly what features are included. You may not hide critical functionality behind unexpected paywalls or release crippled versions that require additional payment to work as advertised.

10. Respect licensing and attribution

If your item uses external code, libraries, or assets, you are responsible for ensuring that you follow their licensing terms. Proper credit must be given where required, and you may not repackage or sell work you do not have rights to.

Publishing Tool

Welcome to the Publishing Tool documentation.

Creating a script: Step By Step Guide
Using branches: Branches
Using libraries: Libraries & Dependencies

Updating Items

In order to update an item you need to follow these steps:

Upload a new build & wait for approval

Check on how to upload a build.

Set build active

Navigate to Builds and find the approved build.
Click Set to branch
Select Default branch
Click Save

After these actions are complete, your new build will be available for users instantly.

Builds are NOT automatically set to the Default branch upon approval! Once you get the notification that your build has been approved, proceed to set its branch to Default.

Additionally, you may want to test upcoming builds before they hit the Live item. For that, we recommend looking into .

Branches

Branches let you create separate versions of your items so users can test upcoming builds before they are pushed to the live Default branch.

Open the Branches tab to manage existing branches or create new ones:

Creating a branch

Click Add branch, enter a branch title, and confirm.

You can create as many branches as you need.

After a branch is created, you can:

Add users (they’ll be allowed to opt in).
Set a price (makes the branch public so anyone can purchase it).

Note: Adding users does not automatically enable the branch for them. It only gives them the option to join.

Managing Builds

Branches can hold any builds - both verified and unverified.

To assign a build to a branch:

Go to the Builds tab.
Find the build you want to assign.
Click Set branch.
Select the branch and submit.

This immediately makes that build available to anyone using the branch.

Libraries & Dependencies

Libraries are specialized items that are not visible in the Storefront. Instead, they are available for other publishers to reference inside their scripts.

Creating a Library

Creating a library works the same way as creating a script (see).

The only difference is that a library requires a Library ID.

Bundled Assets

If you want to include additional files with your script (e.g. sounds, images, or data), you can bundle them inside a ZIP archive with a defined structure.

The archive must contain a script.lua file in the root.
The archive must not contain a scripts/remote/ directory or any files inside it.

All bundled assets are automatically installed to a directory chosen by the API engine. See ws for usage details.

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

Example

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

Example

Instances

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

global_vars_t

Usage:

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

Returns

Type

Description

Example

cgame_ui_funcs

Usage: game.game_ui_funcs:{method}

This type represents the game's UI functions.

get_binding_for_button_code

Method

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:

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.

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.

outline_mode

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

inset

Field

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

outset

Field

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

center

Field

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

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/

shadow_dir

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

up

Field

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

render_mode

This enum is used to toggle rendering modes.

normal

Field

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.

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

Field

glyph_t

This type represents a glyph object.

codepoint

FieldRead only

font_flags

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

shadow

Field

Adds a 1px shadow to font glyphs.

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

cfiring_mode

Firing mode information.

values_arr

FieldRead only

secondary

Field

Represents secondary weapons, such as pistols.

smg

Field

Represents submachine guns (SMGs).

rifle

Field

Represents rifles, including assault rifles and sniper rifles.

heavy

Field

Represents heavy weapons, such as machine guns and shotguns.

observer_mode_t

This enum represents the observer modes available in the game.

none

Field

Represents no observer mode (not spectating anyone).

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.

user_t

This type represents basic user information.

avatar

FieldRead only

Type:

User's avatar. May be nil.

username

FieldRead only

Type: string

User's username.

notification_system

This type represents a notification system.

add

Method

Adds a notification to the list.

Arguments

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

Field

Type:

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 .

frag_shader

Field

Type: Type:

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 .

clip_rect

Field

Type:

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

Field

Type:

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.

Nothing.

Example

set_shader

Method

Sets a fragment shader in a safe manner.

Arguments

Returns

Nothing.

Example

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

Constructor

Creates a new color instance.

Arguments

1. Default color (translucent black).

None.

2. Integer colors.

3. Hex string.

Returns

Example

white

Function

Returns a white, opaque color.

Arguments

None.

Returns

Example

white_transparent

Function

Returns a white, transparent color.

Arguments

None.

Returns

Example

black

Function

Returns a black, opaque color.

Arguments

None.

Returns

Example

black_transparent

Function

Returns a black, transparent color.

Arguments

None.

Returns

Example

percent

Function

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

Arguments

Returns

Example

gray

Function

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

Arguments

Returns

Example

Method

Returns darker variant of this color.

Arguments

Returns

Example

mod_a

Method

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.

2. Integer variant.

Returns

Example

r

Method

Override red and return new color.

Arguments

Returns

Example

g

Method

Override green and return new color.

Arguments

Returns

Example

b

Method

Override blue and return new color.

Arguments

Returns

Example

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

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

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

FieldRead only

Type:

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

Field

Type:

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

tex_sz

Field

Method

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

Returns

Nothing.

Example

override_clip_rect

Method

Overrides clip rectangle with support of intersection.

Arguments

Returns

Nothing.

Example

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

Workshop

Guidelines

1. Provide meaningful descriptions

2. Maintain a minimum quality standard

3. Respect capability requests

4. Practice fair market behavior

5. Do not publish malicious code

6. Ensure compatibility with existing features

7. Keep content respectful

8. Maintain and update your items

9. Be transparent with monetization

10. Respect licensing and attribution

Publishing Tool

Updating Items

Upload a new build & wait for approval

Set build active

Branches

Creating a branch

Managing Builds

Libraries & Dependencies

Creating a Library

Bundled Assets

API

Global Functions

print﻿

Arguments

error﻿

Arguments

Instances

game

global_vars﻿

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﻿

cinput_system

vk_to_button_code﻿

cgame_ui_funcs

get_binding_for_button_code﻿

ccvar

find﻿

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

global_vars

real_time

frame_count

abs_frame_time

max_clients

ticks_this_frame

frame_time

cur_time

tick_fraction

tick_count

map_path

map_name

vk_to_button_code

get_binding_for_button_code

find

name

description

flags

value

events

inset

outset

center

up

normal

obj

codepoint

shadow

get_abs_origin

values_arr

primary_mode

other

melee

secondary

smg

rifle

heavy

none

avatar

username

add

Official lua API documentation for fatality.win

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