Hello, fellow developer!

In this section, you'll find Lua examples that you can use to learn about our API. Please note that these examples don't cover the entirety of the API itself, so you'll have to do some exploration by yourself!

Welcome to the Publishing Tool documentation.

• Creating a script: Step By Step Guide

• Using branches: Branches

• Using libraries: Libraries & Dependencies

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.

Encapsulates the plane information in the trace object.

normal

FieldRead only

Type: Vector

pos

FieldRead only

Type: Vector

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.

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

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.

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.

WIREFRAME

Field

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

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.

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 onPresentQueue()
    local d = draw.surface;
    d.font = draw.fonts['gui_main'];
    d:AddText(draw.Vec2(50, 50),
        'Hello drawing! My first script speaking.',
         draw.Color.White()
    );
end

events.presentQueue:Add(onPresentQueue);

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. presentQueue doesn’t provide any parameters, so our function doesn’t need any either.

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:

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:

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.

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 .

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

Libraries allow users to write pre-written, reusable code that can be imported anywhere, at any time. This is useful if you often reuse portions of your code in multiple scripts, or if you wish to compartmentalize your scripts and have a cleaner code base.

In Fatality, libraries are divided into two categories: Local libraries and Cloud libraries. Local libraries are located in your fatality/scripts/lib folder and may only be used by other local scripts, meanwhile cloud libraries are similar to cloud scripts and can be shared and imported by any other cloud script through the workshop. Despite that difference, libraries follow the same code structure:

-- Usually, a 'module' table is created and all of your libraries contents go into it.
local M = {}

-- You can export functions.
function M.MyFunction()
    print('Call from my library')
end

-- Or constants.
M.MyValue = 979

-- Or any other value.
M.MenuElement = gui.Checkbox('external_checkbox')

-- At the end of every library, make sure to return the contents you wanna export!
return M

You may then import said library from another file using either its file name or identifier.

-- In another file.
local my_library = require('library')

my_library.MyFunction() -- Prints 'Call from my library'

print(my_library.MyValue) -- Prints '979'

gui.ctx:Find('lua>elements a'):Add(my_library.MenuElement) -- Adds a new checkbox

Welcome to the basics of scripting with our API.

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

Basic Concepts

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

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

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

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

Field Function Method Constructor Read only Insecure only Overridable

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

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.

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

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

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.

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.

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

1. Navigate to Builds and find the approved build.

2. Click Set to branch

3. Select Default branch

4. Click Save

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

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

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 (seeStep By Step Guide).

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

• The Library ID is a unique identifier used by scripts to reference your library.

• Without it, other publishers cannot include your library as a dependency.

You can create and assign a Library ID in the General tab:

Once published and approved, your library becomes available for others to use as a dependency.

When your script references a library, the library is automatically loaded alongside your script at runtime.

To add a library dependency:

1. Go to the Dependencies tab.

2. Click Add dependency.

3. Find the library you want to reference and click Add.

4. The library will appear in your dependencies list.

It is recommended to reference a specific version of a library rather than always pulling the latest. This ensures your script continues to work even if the library author publishes breaking changes later.

Represents a convar used by the game.

name

FieldRead only

Type: string

description

FieldRead only

Type: string

flags

FieldRead only

Type: int

FieldRead only

Type: <type>

The value of the convar represented in its type

Rounding

Last modified: 03 January 2025

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

TL

Field

Round top-left corner.

TR

Field

Round top-right corner.

BL

Field

Round bottom-left corner.

Field

Round bottom-right corner.

Field

Round both of the top corners. This produces the same result as using bit.bor(draw.Rounding.TL, draw.Rounding.TR).

Field

Round both of the left corners. This produces the same result as using bit.bor(draw.Rounding.TL, draw.Rounding.BL).

Field

Round both of the right corners. This produces the same result as using bit.bor(draw.Rounding.TR, draw.Rounding.BR).

Field

Round both of the bottom corners. This produces the same result as using bit.bor(draw.Rounding.BL, draw.Rounding.BR).

Field

Round all corners. This produces the same result as using bit.bor(draw.Rounding.TL, draw.Rounding.TR, draw.Rounding.BL, draw.Rounding.BR).

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.

DOWN

Field

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

LEFT

Field

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

Field

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

This type represents a CBaseAnimGraph class.

This type represents a grenade projectile.

GetGrenadeType

Method

Returns the grenade type.

Arguments

None.

Returns

Example

In our Lua API, we give users the ability to make their own custom menu controls. Here's an example on how to make a simple counter:

With that, you'll have an extremely simple counter that you can click on to increment.

Workshop allows you to publish, advertise, and earn from your items. It provides a broad set of features for both publishers and end users, making the storefront easy to use and reliable to manage.

Before publishing, it's important to understand the key concepts used in Workshop:

• Storefront - the main Workshop UI where users search, view, subscribe to, or purchase items;

• Publishing Tool - the area where item authors create, update, and manage their entries in the storefront;

• Item

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

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.

Trivial one-line scripts, spam items, commonly made items that don't provide anything new or submissions with no truly meaningful functionality are not allowed. Workshop content should be fresh and interesting for the users, so all items must undergo a quality assurance to ensure they're not polluting the workshop with junk content.

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.

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.

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.

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.

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.

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:

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

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

Method

Adds a callback to the event.

Arguments

This type represents the game's command input system.

FieldRead only

Type: bool

true

This type represents the game's control input system.

Method

Converts a virtual key to button code.

Arguments

This type represents the game's UI functions.

Method

Returns the binding name for a button code.

Arguments

Usage:

This type represents the game's cvar system.

Method

Get the game's cvar under this name.

Arguments

Describes the ray type used by the tracing methods.

Method

Changes the shape of the ray to a box/hull, using the specified mins and maxs.

Arguments

Defines a custom filter for TraceRay.

Field

Type: boolean

Ignores all player entities when true.

Field

Type: boolean

Ignores all game entities except players when true

This type encapsulates all penetration data returned from FireBullet.

Field

The damage done by the weapon.

Field

The hitgroup that was hit. May be invalid.

Method

Returns one of the bullet impacts.

Arguments

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

Method

Adds a game event to the listener.

Arguments

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

Field

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

Field

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

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 .

FieldRead only

Type:

Pointer to a GPU object. If this object is not created, this field will be nil

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

Field

Adds a 1px shadow to font glyphs.

Field

Adds a 1px outline to font glyphs.

Represents an entity entry.

Field

Type: <type>

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

Field

Type: bool

true

This type represents a weapon's static data.

Function

Attemps to search for a field in this class.

Arguments

Firing mode information.

values_arr

FieldRead only

Type: <type>

Values.

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

This enum represents the firing mode for a weapon.

PRIMARY_MODE

Field

Primary mode (usually left mouse button).

SECONDARY_MODE

Field

Secondary mode (usually right mouse button).

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('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.ControlID and pass the desired ID, or just pass a simple string instead.

Then, create the checkbox by calling gui.Checkbox and passing the ID you've chosen.

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

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

You may also create both the control and the checkbox, or any other menu element, at the same time using gui.MakeControlEasy !

local cb, row = gui.MakeControlEasy('my_checkbox', 'My checkbox', 'checkbox')

Adding the row to a group

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

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

Then call its Add method to include your row:

That's it!

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:

Usage:

game.globalVars.{field}

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

m_flRealTime

Field

Type: float

Time passed since the game start, in seconds.

Field

Type: int

Amount of frames rendered since the game start.

Field

Type: float

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

Field

Type: int

Maximum amount of clients on the current server.

Field

Type: int

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

Field

Type: float

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

Field

Type: float

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

Field

Type: float

Current tick's fractional value.

Field

Type: int

Ticks passed since the server's game start.

Field

Type: string

Relative path to current loaded map's file.

Field

Type: string

Name of the currently loaded map.

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

GetBackBuffer

Method

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

Arguments

None.

Returns

Example

Method

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

Arguments

None.

Returns

Example

Method

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

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

TL

Field

Draw top-left corner.

TR

Field

Draw top-right corner.

BL

Field

Draw bottom-left corner.

Field

Draw bottom-right corner.

Field

Draw top line.

Field

Draw left line.

Field

Draw right line.

Field

Draw bottom line.

Field

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

Field

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

Field

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

Field

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

Field

Draw the entire glow around the shape.

Field

Draw glow except for the bottom line.

Field

Draw glow except for the top line.

Field

Draw glow except for the right line.

Field

Draw glow except for the left line.

This type represents an SVG texture object.

__call

Constructor

Constructs an SVG texture.

Arguments

Returns

Example

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

__call

Constructor

Constructs a font object.

Arguments

Returns

Example

This type represents a CCSWeaponBase entity.

GetDefIndex

Method

Returns the weapon definition index.

Arguments

None.

Returns

Example

Method

Returns the weapon type.

Arguments

None.

Returns

Example

Method

Returns the weapon static data.

Arguments

None.

Returns

Example

This type represents an entity list.

ForEach

Method

Loops the entities.

Arguments

Returns

Nothing.

Example

Method

Loops the entities in the reverse order.

Arguments

Returns

Nothing.

Example

In this tutorial you’ll create and publish a script to the Storefront. The same flow applies to Libraries and Configs.

Go to Workshop -> Manage Items and click Create new item.

Fill out:

• Title

• Game (the supported title your script targets)

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.

Function

Prints text to game's console. Automatically inserts a space between parameters.

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

Method

Returns address string of the remote machine.

Arguments

None.

Returns

Encapsulates all tracing information returned by the tracing methods.

FieldRead only

Type:

FieldRead only

Type:

Usage:

This type encapsulates some entity querying functionalities. If you wish to loop for players, controllers, dropped items or projectiles, go .

Function

Loops for all entities with a given class.

Arguments

Last modified: 03 January 2025

This type represents a safe way to access maps.

Function

Returns an object by key.

Arguments

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

Field

Type: number

Method

Returns the value.

Arguments

None.

Returns

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

Field

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

Field

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

This type represents a glyph object.

FieldRead only

Type: int

Character codepoint.

Field

This type represents basic user information.

FieldRead only

Type: ?

User's avatar. May be nil.

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

globalVars

Field

Type: CGlobalVarsBase

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

engine

Field

Type: CEngineClient

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

Field

Type: CCSGOInput

This service exposes the command input system.

Field

Type: CInputSystem

This service exposes the control input system.

Field

Type: CGameUIFuncs

This service exposes the game's UI functions.

Field

Type: CPhysicsQueryInterface

This service exposes the game's tracing functions.

Field

Type: CGameEntitySystem

This service exposes some of the game's entity list functions.

Method

Plays a game sound.

Arguments

Returns

Nothing.

Example

Method

Creates a particle effect.

attachment and owner are optional.

Arguments

Returns

Example

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

GetLastTimestamp

Method

Returns last timestamp, in seconds.

Arguments

None.

Returns

Example

Method

Returns last server tick number.

Arguments

None.

Returns

Example

Method

Returns whether the client is currently in game.

Arguments

None.

Returns

Example

Method

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

Arguments

None.

Returns

Example

Method

Returns the Network Channel used for network communication.

Arguments

None.

Returns

Example

Method

Executes a client-sided console command.

Arguments

Returns

Nothing.

Example

Method

Returns client window screen size.

Arguments

None.

Returns

Example

Represents a particle instance created by game.CreateParticle.

IsValid

Method

Returns true if the particle is still valid.

Arguments

None.

Returns

Example

Method

Expires the particle immediately.

Arguments

None.

Returns

Nothing.

Example

Method

Sets a control point.

Arguments

Returns

Nothing.

Example

Method

Initializes the particle snapshot positions.

Arguments

Returns

Nothing.

Example

Method

Sets an entity attachment for a control point.

Arguments

Returns

Nothing.

Example

Field

Type: number

The remaining particle lifetime in seconds.

You can read or write this value.

FireBullet

Function

Simulates a bullet fired from a specific weapon.

Arguments