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:

local Counter = {} do
  -- Create the metatable for this control.
  Counter.__index = gui.LuaControlProto()

  -- Specify any initial data. This is propagated to any LuaControl initialized with this metatable.
  Counter.__index.initialData = {
    counter = 0
  }

  -- Override any methods you wish.
  function Counter.__index:onRender(contents, scrollbar, mins, maxs)
    contents:AddRectFilled(draw.Rect(mins, maxs), draw.color.White())

    contents.font = draw.fonts['gui_bold']
    contents:AddText(mins + draw.Vec2(5, 5), tostring(self.data.counter), draw.color.Black())
    contents.font = nil
  end

  function Counter.__index:onMouseDown(key)
    if key == gui.MouseButton.LEFT then
      self.data.counter = self.data.counter + 1
      self:LockInput() -- Makes sure you can't drag the menu while clicking.
    end
  end

  function Counter.__index:onMouseUp(key)
    if key == gui.MouseButton.LEFT then
      self:UnlockInput() -- Makes sure you can drag menu again after clicking.
    end
  end

  function Counter.create(id, initialValue)
    local control = gui.LuaControl(id, Counter.__index, draw.Vec2(), draw.Vec2(0, 24)) do
      control.sizeToParentW = true -- Resizes the control to the width of the container.
      control.data.counter = initialValue or 0
      control.margin = draw.Rect(3, 7, 3, 7) -- Default control margin
    end

    return control
  end
end

gui.ctx:find('lua>elements a'):add(Counter.create('counter'))

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

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

local bb = adapter:GetBackBuffer();

GetBackBufferDownsampled

Method

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

Arguments

None.

Returns

Example

local ds = adapter:GetBackBufferDownsampled();

GetSharedTexture

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

local shared = adapter:GetSharedTexture();

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!

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

Firing mode information.

values_arr

FieldRead only

Type: <type>

Values.

Official lua API documentation for ​

Encapsulates the plane information in the trace object.

normal

FieldRead only

Type: Vector

pos

FieldRead only

Type:

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 for usage details.

Represents a convar used by the game.

name

FieldRead only

Type: string

description

FieldRead only

Type: string

FieldRead only

Type: int

FieldRead only

Type: <type>

The value of the convar represented in its type

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

Field

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

This type represents a CBaseAnimGraph class.

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.

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.

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:

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

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.

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

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;

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 type represents the game's UI functions.

Method

Returns the binding name for a button code.

Arguments

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

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

Last modified: 03 January 2025

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

Field

Round top-left corner.

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

Method

Adds a game event to the listener.

Arguments

Defines a custom filter for TraceRay.

Field

Type: boolean

Ignores all player entities when true.

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

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

This type represents a glyph object.

FieldRead only

Type: int

Character codepoint.

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

Represents an entity entry.

Field

Type: <type>

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

This type represents an entity list.

Method

Loops the entities.

Arguments

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.

This type represents a grenade projectile.

Method

Returns the grenade type.

Arguments

None.

Returns

This type represents a weapon's static data.

Function

Attemps to search for a field in this class.

Arguments

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.

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

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:

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:

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

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. Automatically inserts a space between parameters.

Arguments

Example

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.

Example

Function

Unpacks a table of elements.

Example

Function

Delays a callback by a certain amount of time, in seconds.

Example

Function

Special function, it's called whenever the script unloads. Isn't called in case of errors.

None.

Example

This type represents an SVG texture object.

__call

Constructor

Constructs an SVG texture.

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 a font object. Internally, this type uses GDI library to rasterize font glyphs.

__call

Constructor

Constructs a font object.

Arguments

Returns

Example

Encapsulates all tracing information returned by the tracing methods.

FieldRead only

Type:

FieldRead only

Last modified: 03 January 2025

This type represents a safe way to access maps.

Function

Returns an object by key.

Arguments

Usage:

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

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

Field

Draw top-left corner.

Field

This type represents an entity handle.

Field

Type: number

Method

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

Field

Type: number

Method

Usage:

This type represents the game's cvar system.

Method

Get the game's cvar under this name.

Welcome to the Publishing Tool documentation.

• Creating a script: Step By Step Guide

• Using branches: Branches

• Using libraries: Libraries & Dependencies

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

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.

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

FireBullet

Function

Simulates a bullet fired from a specific weapon.

Arguments

Returns

Example

Function

Scales up the damage from a weapon given a hitgroup and, optionally, a player.

Arguments

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.

This table represents an internal entity list.

players

Field

Type: EntityList_t<C_CSPlayerPawn>

Player pawns.

controllers

Field

Type: <>

Player controllers.

Field

Type: <>

Items (held).

Field

Type: <>

Dropped items.

Field

Type: <>

Grenade projectiles.

Function

Returns the local player's pawn.

Arguments

None.

Returns

Example

Function

Returns the local player's controller.

Arguments

None.

Returns

Example

This type represents a control ID.

__call

Constructor

Constructs the ID structure.

Arguments

Returns

Example

FieldRead only

Type: int

Hashed representation of the ID.

FieldRead only

Type: string

Normal representation of the ID.

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

Create the item

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

Fill out:

• Title

• Game (the supported title your script targets)

• Item type (Script / Library / Config)

Open the Builds tab and click Upload new build.

Fill out:

• Version (use semantic versioning like 1.0.0 if possible)

• Changelog (short, factual)

• File upload (your .lua file or a .zip

Click Save. The build is created in the Draft state.

Click Submit for review. The build state changes to Under review.

After moderation approves it, you’ll get a notification and the state changes to Approved.

Click Set to branch and choose Default.

This makes the approved build the version users receive when they add your script to their library.

If your script needs restricted APIs (e.g. FFI, filesystem, clipboard), enable the required Capabilities so users can grant permission.

In Builds -> Capabilities (right side), select only what you need and click Save.

Open the General tab and complete all fields in the Release Checklist.

When the checklist is complete, click Submit for review on the item. After moderation approves it, the item is automatically published on the Storefront and users can purchase or subscribe.

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

Branches can hold any builds - both verified and unverified.

To assign a build to a branch:

1. Go to the Builds tab.

2. Find the build you want to assign.

3. Click Set branch.

4. Select the branch and submit.

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

This type represents the game's control input system.

VKToButtonCode

Method

Converts a virtual key to button code.

Arguments

Returns

Example

This type represents basic user information.

avatar

FieldRead only

Type: Texture?

User's avatar. May be nil.

FieldRead only

Type: string

User's username.

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

Upload a new build & wait for approval

Check Upload a build 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 .

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

Constructor

Constructs animated texture.

Arguments

1. From file.

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

Constructor

Constructs a font object.

Arguments

1. From file.

This type represents a texture object.

Constructor

Constructs an instance of this type.

Arguments

1. From file.

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

Method

Returns last timestamp, in seconds.

Arguments

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.

This type represents a notification system.

Method

Adds a notification to the list.

Arguments

This enum represents the observer modes available in the game.

Field

Represents no observer mode (not spectating anyone).

Field

This type represents the GUI context.

Method

Finds a control by ID.

Arguments

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

This enum represents mouse buttons.

Field

Left mouse button.

Field