Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Libraries are not yet supported, but will be available soon.
In this section, the most common renderer types are listed, that are not particularly bound to a specific part of the renderer.
This enum represents the observer modes available in the game.
Represents no observer mode (not spectating anyone).
Represents a fixed camera position.
Represents observing from the perspective of the player being spectated.
Represents a chase camera that follows the player being spectated.
Represents a free-roaming camera.
Represents an automatically directed camera, typically controlled by the game or server.
This enum is used to toggle rendering modes.
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 rendering. This means that the polygons will no longer be filled with color, nor texture sampling will ever work.
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.
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.
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);
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:
local group = gui.ctx:find('lua>elements a');
Then call its add
method to include your row:
group:add(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:
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:
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.
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
Returns
Nothing.
Example
name
string
Event name.
mods.events:add_listener('round_end');
This table exposes various internal services and global objects used by Fatality, and also provides a way to retrieve any additional services you need.
Field
Type:
This service exposes global variables used by the game, such as frame time or current server time.
Field
Type:
This service exposes the engine client, which includes commonly used engine-related functions.
Field
Type:
This service exposes the command input system.
Field
Type:
This service exposes the control input system.
Field
Type:
This service exposes the game's UI functions.
Usage:
game.global_vars.{field}
An instance of this type provides a way to read several global variables that are used by the game. Changing any of the values is not and will never be supported.
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 enum is used to determine the outline mode for outlined shapes.
Inset outlining. This means that the outline will be inside the shape (+1px from top-left, -1px from bottom-right).
Outset outlining. This means that the outline will be outside of the shape (-1px from top-left, +1px from bottom-right).
Center outlining. This means that the outline will match the shape size.
This type represents the game's control input system.
Method
Converts a virtual key to button code.
Arguments
vk
int
Virtual key.
Returns
int
Button code.
Example
local button = game.input_system:vk_to_button_code(0x41); -- 'A'
This type represents the game's UI functions.
Method
Returns the binding name for a button code.
Arguments
code
int
Button code.
Returns
string
Binding.
Example
local bind = game.game_ui_funcs:get_binding_for_button_code(code);
This enum determines how to align the text when drawing it.
Align left. It will mean that the text position's X coordinate is located at the left side of the text area.
Align center. It will mean that the text position's X (or Y) coordinate is located at the center of the text area.
Align right. It will mean that the text position's X coordinate is located at the right side of the text area.
Align top. It will mean that the text position's Y coordinate is located at the top side of the text area.
Align bottom. It will mean that the text position's Y coordinate is located at the bottom side of the text area.
Last modified: 03 January 2025
This enum is used to determine the rounding for rounded shapes.
Round top-left corner.
Round top-right corner.
Round bottom-left corner.
Round bottom-right corner.
Round both of the top corners. This produces the same result as using bit.bor(draw.rounding.tl, draw.rounding.tr)
.
Round both of the left corners. This produces the same result as using bit.bor(draw.rounding.tl, draw.rounding.bl)
.
Round both of the right corners. This produces the same result as using bit.bor(draw.rounding.tr, draw.rounding.br)
.
Round both of the bottom corners. This produces the same result as using bit.bor(draw.rounding.bl, draw.rounding.br)
.
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 type represents an entity list.
Never save any entities you get from this list if you don't know what you are doing! You may be left with dangling pointers, which will inevitably lead to a crash.
Loops the entities.
Arguments
Name
Type
Description
fn
function(entity_entry_t)
Function callback.
Returns
Nothing.
Example
entities.players:for_each(function (entry)
-- ...
end);
Loops the entities in the reverse order.
Arguments
Name
Type
Description
fn
function(entity_entry_t)
Function callback.
Returns
Nothing.
Example
entities.players:for_each_z(function (entry)
-- ...
end);
This enum represents the category classification for weapons in the game.
Represents weapons or items that don't fit into any specific category.
Represents melee weapons, such as knives or other close-combat tools.
Represents secondary weapons, such as pistols.
Represents submachine guns (SMGs).
Represents rifles, including assault rifles and sniper rifles.
Represents heavy weapons, such as machine guns and shotguns.
Event usertype. An instance of this type can be found in events
.
Method
Adds a callback to the event.
Arguments
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);
Method
Removes a callback from the event.
Arguments
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)
This enum determines which flags a font object should possess. Setting those flags is only possible during type construction.
Adds a 1px shadow to font glyphs.
Adds a 1px outline to font glyphs.
Enable antialiasing on font glyphs. This flag only works on GDI fonts.
Disable DPI scaling on this font. By default, font glyphs will be scaled in accordance to the global DPI scale.
Disable glyph kerning on this font.
Enables a strong hinting algorithm for rasterization. Only works on FreeType fonts.
Enables a light hinting algorithm for rasterization. Only works on FreeType fonts.
This enum is used to determine shadow direction for add_shadow_line
method.
The darkest side of the shadow will be at the bottom.
The darkest side of the shadow will be at the top.
The darkest side of the shadow will be on the left side.
The darkest side of the shadow will be on the right side.
Usage:
This type represents the game's cvar system.
Method
Get the game's cvar under this name.
Arguments
Name
Type
Description
name
string
Var name.
Returns
Type
Description
Convar object.
Example
local sv_quantize_movement_input = game.cvar:find('sv_quantize_movement_input')
if not sv_quantize_movement_input then
error('sv_quantize_movement_input not found')
end
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.
...
...
Values to print in the console.
Example
print('Hello world!', 123); -- prints out "Hello world! 123" to the console
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.
text
string
Read for documentation.
Example
error('Can't recover from this one! Error: ' .. tostring(123));
This type represents a rendering adapter used within the rendering system.
Returns a back buffer texture. May return a blank or outdated texture, if the back buffer texture was not updated.
Arguments
None.
Returns
Example
Returns a 4x down sampled version of the back buffer texture.
Arguments
None.
Returns
Example
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 type represents a CCSWeaponBase
entity.
Returns the absolute origin (the one that is used for rendering).
Arguments
None.
Returns
Example
Returns the weapon ID.
Arguments
None.
Returns
Example
Returns the weapon type.
Arguments
None.
Returns
Example
Returns the weapon static data.
Arguments
None.
Returns
Example
This type represents a special structure that references a certain field in the entity object.
Do not ever store an instance of this type anywhere but in a scope of an event because entity might be removed.
Returns the value.
Arguments
None.
Returns
Example
Sets the value.
Arguments
Returns
Nothing.
Example
This type represents the game's command input system.
Field
Read only
Type: bool
true
if currently in the third person.
Method
Returns current camera view angles.
Arguments
None.
Returns
Example
Method
Sets new camera view angles.
Arguments
Returns
Nothing.
Example
Represents an entity entry.
Type: <type>
Entity instance. Type depends on the list you get it from.
Type: bool
true
if the client had received any updates to this entity at least once.
Type:
Entity's handle. You may store this elsewhere if you need to have global access to an entity.
Type:
This field is only available on entries that use cs2_player_controller
type.
Player's profile picture. Will be nil
if was yet to be initialized.
Type
Description
Back buffer texture pointer.
local bb = adapter:get_back_buffer();
Type
Description
Downsampled back buffer texture pointer.
local ds = adapter:get_back_buffer_downsampled();
Type
Description
Shared texture pointer.
local shared = adapter:get_shared_texture();
Type
Description
<type>
Value.
local health = player.m_iHealth:get();
Name
Type
Description
value
<type>
Value.
player.m_iHealth:set(50); -- won't really do anything with the health
Name
Type
Description
name
string
Field name.
Type
Description
Accessor instance.
local price = wpn_data.m_nPrice;
local price = wpn_data['m_nPrice']; -- this also works
View angles.
local ang = game.input:get_view_angles();
ang
View angles.
game.input:set_view_angles(math.vec3(0, 0, 0));
Name
Type
Description
sv
string
SVG text.
h
float
Target height. Defaults to 0
, and 0
means that there will be no automatic downscale.
Type
Description
svg_texture
SVG texture object.
local lightning = draw.svg_texture([[
<svg width="800px" height="800px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M9.55563 13.3232L9.43584 13.3123C7.90803 13.1735 7.14412 13.104 6.90146 12.5814C6.65881 12.0588 7.09869 11.4304 7.97846 10.1736L11.5612 5.05544C12.1424 4.22517 12.433 3.81003 12.6836 3.89831C12.9342 3.98658 12.9005 4.4922 12.8331 5.50343L12.6299 8.55194C12.5685 9.47214 12.5379 9.93224 12.8023 10.2419C13.0667 10.5515 13.5259 10.5933 14.4444 10.6768L14.5642 10.6877C16.092 10.8265 16.8559 10.896 17.0985 11.4186C17.3412 11.9412 16.9013 12.5696 16.0215 13.8264L12.4388 18.9446C11.8576 19.7748 11.567 20.19 11.3164 20.1017C11.0658 20.0134 11.0995 19.5078 11.1669 18.4966L11.3701 15.4481C11.4315 14.5279 11.4621 14.0678 11.1977 13.7581C10.9333 13.4485 10.4741 13.4067 9.55563 13.3232Z" fill="#ffffff"/>
<path d="M18.5 4L17 6H19L17.5 8" stroke="#ffffff" stroke-opacity="0.6" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M6.5 16L5 18H7L5.5 20" stroke="#ffffff" stroke-opacity="0.6" stroke-linecap="round" stroke-linejoin="round"/>
</svg>
]], 24);
Type
Description
Origin.
local org = wep:get_abs_origin();
Type
Description
Weapon ID.
local wep_id = wep:get_id();
Type
Description
Weapon type.
local type = wep:get_type();
Type
Description
Weapon data.
local data = wep:get_data();
Name
Type
Description
name
string
System font name (example: 'Arial').
size
float
Font height, in pixels.
fl
Font flags. Use bit
library to construct them. Defaults to 0
.
mi
int
Starting codepoint. Defaults to 0
.
ma
int
Ending codepoint. Defaults to 255
(entire ASCII code page).
weight
int
Font weight. Defaults to 400
(regular).
Type
Description
font_gdi
Font object.
local sys_font = draw.font_gdi('Calibri', 14);
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
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
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.
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
, or any of its child types.
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.
Provides a way to interface with a Network Channel's class.
Method
If the current channel is null
, this function will return nil
instead.
Returns address string of the remote machine.
Arguments
None.
Returns
Type
Description
string?
IP-address or Steam Server Address.
Example
local chan = game.engine:get_netchan();
if chan and not chan:is_null() then
print(chan:get_address());
end
Method
If the current channel is null
, this function will return nil
instead.
Returns whether the current channel is connected to the local machine (loopback address).
Arguments
None.
Returns
Type
Description
bool?
true
if connected to the local machine.
Example
local chan = game.engine:get_netchan();
if chan and not chan:is_null() and chan:is_loopback() then
print('Connected to localhost!');
end
Method
Returns whether the channel is stubbed.
Arguments
None.
Returns
Type
Description
bool
true
if current channel is a dummy channel.
Example
local chan = game.engine:get_netchan();
if not chan or chan:is_null() then
print('Not connected!');
end
Method
If the current channel is null
, this function will return nil
instead.
Returns current latency to the remote server (in seconds).
Arguments
None.
Returns
Type
Description
float?
Latency (in seconds).
Example
local chan = game.engine:get_netchan();
if chan and not chan:is_null() then
print('Current latency: ' .. tostring(math.round(chan:get_latency() * 1000.0)) .. 'ms');
end
This enum is used to determine which parts of the glow around the shape should get rendered.
Draw top-left corner.
Draw top-right corner.
Draw bottom-left corner.
Draw bottom-right corner.
Draw top line.
Draw left line.
Draw right line.
Draw bottom line.
Draw all the left side shapes. This includes both left corners and the line.
Draw all the right side shapes. This includes both right corners and the line.
Draw all the top side shapes. This includes both top corners and the line.
Draw all the bottom side shapes. This includes both bottom corners and the line.
Draw the entire glow around the shape.
Draw glow except for the bottom line.
Draw glow except for the top line.
Draw glow except for the right line.
Draw glow except for the left line.
This type represents an entity handle.
Returns the entity, or nil
if nothing found.
Arguments
None.
Returns
Type
Description
<type>
Entity instance.
Example
local ent = handle:get();
Returns true
if the handle is valid.
Arguments
None.
Returns
Type
Description
bool
true
if valid.
Example
if handle:valid() then
-- ...
end
Returns true
if the handle links to a client-side entity.
Arguments
None.
Returns
Type
Description
bool
true
if client-sided.
Example
if handle:is_clientside() then
-- ...
end
This type represents a managed object. You cannot create an instance of this type directly.
Every object, that inherits from this type, must be create
d before use. The rendering system will only create them automatically, if you happen to lose a device object (e.g. minimize the game window, and then restore it) and only if you add your objects to manage table in draw
.
Type: ptr
Pointer to a GPU object. If this object is not created, this field will be nil
. You can use the value of this field to pass it to command
directly for example, or if you (for whatever reason we don't recommend you doing) want to have a direct control over the pointer - cast it to FFI's cdata
.
Creates a managed object in GPU memory.
You should create()
an object only once. Invoking this method after the object was created will be meaningless.
Arguments
None.
Returns
Nothing.
Example
tex:create();
Destroys a managed object in GPU memory.
Never destroy a GPU object if it is being used in rendering (for example, when you have pushed some shape that uses a texture, and then destroyed that texture). This will lead to undefined behavior, and most likely, **crash the game **.
Arguments
None.
Returns
Nothing.
Example
font:destroy();
This type represents basic user information.
Type: texture?
User's avatar. May be nil
.
Type: string
User's username.
This enum represents the weapon type in the game.
Represents a knife-type weapon.
Represents a pistol-type weapon.
Represents a submachine gun-type weapon.
Represents a rifle-type weapon.
Represents a shotgun-type weapon.
Represents a sniper rifle-type weapon.
Represents a machine gun-type weapon.
Represents a C4 explosive.
Represents a taser weapon.
Represents a grenade-type weapon.
Represents a stackable item-type weapon.
Represents fists as a weapon type.
Represents a breach charge-type weapon.
Represents a bump mine-type weapon.
Represents a tablet-type weapon.
Represents a melee-type weapon.
Represents a shield-type weapon.
Represents a zone repulsor-type weapon.
Represents an unknown weapon type.
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++.
Type: <type>
Value holder. Use as the source value, or override it to change internally.
Now that you’ve covered the essentials, it’s time to start scripting.
Feel free to use any text editor you prefer: , , or even a simple Notepad.
Local scripts are located here: <CS2_Directory>/game/csgo/fatality/scripts
. You may notice there's also a lib
directory, but we’ll get to that later.
Create a new file ending with .lua
, and begin your work on the script.
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:
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.
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:
This type represents a base game entity.
This type may be returned for any other abstract entity class, but internally will point to the correct type.
Function
Attemps to search for a field in this class.
Arguments
Returns
Example
Function
Returns schema class name.
Returns
Example
Function
Safe-casts the entity to cs2_weapon_base_gun, returns nil if not a weapon_base_gun
Returns
Example
Function
Safe-casts the entity to cs2_weapon_base, returns nil if not a weapon_base
Returns
Example
Function
Safe-casts the entity to cs2_player_pawn, returns nil if not a player_pawn
Returns
Example
Function
Safe-casts the entity to cs2_player_controller, returns nil if not a player_controller
Returns
Example
This type represents a font object. Internally, this type uses FreeType library to rasterize font glyphs.
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
Usage:
gui.{func_or_field}
This table exposes the GUI system of the software.
Type:
GUI context.
Type:
Notification system.
Type:
Input context.
Wraps a control into a layout consisting of a label and that specific control. You should add this new control to groupboxes if you want your control to be displayed nicely. Additionally, you can add any extra controls to the returned one - those will get stacked to the left side of your initial control.
Arguments
Returns
Example
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
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
This type represents a layout control.
This type represents an abstract control with a container.
Name
Type
Description
name
string
Field name.
Type
Description
Accessor instance or pointer accessor instance
local health = player.m_iHealth;
local health = player['m_iHealth']; -- this also works
Type
Description
string
Name. Returns nil
when failed.
local name = entity:get_class_name()
Type
Description
cs2_weapon_base_gun?
Casted entity. Returns nil
if the cast failed.
local gun = entity:to_weapon_base_gun()
Type
Description
cs2_weapon_base?
Casted entity. Returns nil
if the cast failed.
local wpn = entity:to_weapon_base()
Type
Description
cs2_player_pawn?
Casted entity. Returns nil
if the cast failed.
local pawn = entity:to_player_pawn()
Type
Description
cs2_player_controller?
Casted entity. Returns nil
if the cast failed.
local controller = entity:to_player_controller()
float
Timestamp, in seconds.
local last_time = game.engine:get_last_timestamp();
int
Server tick number.
local server_tick = game.engine:get_last_server_tick();
bool
In-game status.
if game.engine:in_game() then
print("I'm in game!");
end
bool
true
if connected.
if game.engine:is_connected() then
print("I'm connected!");
end
Network channel, or nil
if does not exist.
local chan = game.engine:get_netchan();
cmd
string
Command to execute.
bool
unrestricted
Whether should the execution preserve any restrictions. Defaults to false
.
game.engine:client_cmd('say Hello!');
int
Width.
int
Height.
local w, h = game.engine:get_screen_size();
Name
Type
Description
key
string
Object key.
Type
Description
<type>
Object.
local main_font = draw.fonts['gui_main'];
-- this also works
local main_font_2 = draw.fonts.gui_main;
Name
Type
Description
key
string
Object key.
obj
<type>
Object.
draw.fonts['my_font'] = my_font;
-- this also works
draw.fonts.my_font = my_font;
Name
Type
Description
path
string
Path to a ttf/otf file.
size
float
Font height, in pixels.
fl
Font flags. Use bit
library to construct them. Defaults to 0
.
mi
int
Starting codepoint. Defaults to 0
.
ma
int
Ending codepoint. Defaults to 255
(entire ASCII code page).
Name
Type
Description
mem
Pointer to a font file in memory.
sz
int
Font file size, in bytes.
size
float
Font height, in pixels.
fl
Font flags. Use bit
library to construct them. Defaults to 0
.
mi
int
Starting codepoint. Defaults to 0
.
ma
int
Ending codepoint. Defaults to 255
(entire ASCII code page).
Name
Type
Description
mem
Pointer to a font file in memory.
sz
int
Font file size, in bytes.
size
float
Font height, in pixels.
fl
Font flags. Use bit
library to construct them. Defaults to 0
.
pairs
table[{int, int}...]
Min/max pairs. This is a standard array, consisting of {int, int} pairs.
Type
Description
font
Font object.
local cool_font = draw.font('myfont.ttf', 16);
Name
Type
Description
text
string
Label value.
c
Control object.
Type
Description
Layout object.
local row = gui.make_control('Hello checkbox!', my_cb);
Name
Type
Description
id
ID.
Type
Description
spacer
Spacer instance.
local sp = gui.spacer(gui.control_id('my_id'));
Name
Type
Description
id
Control ID.
str
string
Text string.
Type
Description
selectable
Selectable object.
local sel = gui.selectable(id, 'Hello!');
This type represents the GUI context.
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');
Field
Type: user_t
User's basic information.
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.
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.
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);
This type represents a groupbox control.
local function on_present_queue()
local d = draw.surface;
d.font = draw.fonts['gui_main'];
d:add_text(draw.vec2(50, 50),
'Hello drawing! My first script speaking.',
draw.color.white()
);
end
events.present_queue:add(on_present_queue);
local function on_present_queue()
end
local d = draw.surface;
d.font = draw.fonts['gui_main'];
d:add_text(draw.vec2(50, 50),
'Hello drawing! My first script speaking brev.',
draw.color.white()
);
events.present_queue:add(on_present_queue);
This type represents a texture object.
Constructs an instance of this type.
Passing an invalid pointer, a or memory region that is smaller than the size will result in a crash.
Arguments
1. From file.
Name
Type
Description
path
string
Path to a valid texture file.
2. From memory.
Name
Type
Description
data
Pointer to texture file data in memory.
sz
int
Size of the texture file data.
3. From RGBA data.
Name
Type
Description
data
Pointer to RGBA data in memory.
w
int
Width.
h
int
Height (row count).
p
int
Pitch (row width). This is the amount of bytes per row.
Returns
Type
Description
texture
Texture object.
Example
local tex = draw.texture('funny_meme.png');
Type: bool
Set to true
if this is an instance of animated_texture
.
Returns size of this texture.
Arguments
None.
Returns
Type
Description
Texture dimensions.
Example
local sz = tex:get_size();
This type is an animated texture. This texture type only supports animated GIF types, and does not support APNG.
If you pass an unsupported type, it will instead work exactly like texture
type, meaning controlling frames and looping will be meaningless.
Using this type for texture atlases is possible, although highly unrecommended. It will produce extra texture objects in memory, and overall will be much slower. Instead, it is advised to construct an actual texture atlas, use texture
type, and use texture mapping.
Constructs animated texture.
Passing an invalid pointer, a or memory region that is smaller than the size will result in a crash.
Arguments
1. From file.
Name
Type
Description
path
string
Path to the texture file.
2. From memory.
Name
Type
Description
data
Pointer to texture file data in memory.
sz
int
Size of the texture file data.
Returns
Type
Description
animated_texture
Animated texture instance.
Example
local gif = draw.animated_texture('funny_gif.gif');
Type: bool
If set to false
, will not loop the animation automatically. Defaults to true
.
Reset loop to run from the first frame.
Arguments
None.
Returns
Nothing.
Example
gif:reset_loop();
Set a specific frame on the animation. If looping is enabled, will continue the cycle from the passed frame. Otherwise, will display a specific frame of the animation.
Arguments
Name
Type
Description
frame
int
Frame number. Invalid frame numbers will be clamped.
Returns
Nothing.
Example
gif:set_frame(5);
Returns amount of frames in the animation.
Arguments
None.
Returns
Type
Description
int
Frame count.
Example
local frames = gif:get_frame_count();
gif:set_frame(frames - 2); -- set to the last frame
This table represents an internal entity list.
Never store any entities in the global scope! Any entity might get deleted, and you will no longer have a valid instance of that entity, which will inevitably lead to a crash. If you need to globally store an entity somewhere, we strongly recommend you store an instance of chandle
, and use it's get
method to retrieve the entity again, when needed.
Type: entity_list_t<cs2_player_pawn>
Player pawns.
Type: entity_list_t<cs2_player_controller>
Player controllers.
Type: entity_list_t<cs2_weapon_base>
Items (held).
Type: entity_list_t<cs2_weapon_base>
Dropped items.
Type: entity_list_t<cs2_grenade_projectile>
Grenade projectiles.
Returns the local player's pawn.
Arguments
None.
Returns
Type
Description
Pawn.
Example
local lp = entities.get_local_pawn();
Returns the local player's controller.
Arguments
None.
Returns
Type
Description
Controller.
Example
local lp_ctrl = entities.get_local_controller();
This type represents a color picker control.
Constructs the color picker.
Arguments
Name
Type
Description
id
Control ID.
allow_alpha
bool
Whether to enable alpha channel. Defaults to true
.
Returns
Type
Description
color_picker
Color picker object.
Example
local picker = gui.color_picker(id);
Returns color picker' value.
Arguments
None.
Returns
Type
Description
Value data.
Example
local val = picker:get_value():get();
This table describes the rendering system of the software.
All types and enums described in the child sections must be prefixed with draw.
. This is done so specific types are not confused with others, such as the separate color
types present in rendering and the game.
Field
Read only
Type:
Rendering adapter.
Field
Read only
Type: float
Rendering frame time. An alias to .
Field
Read only
Type: float
Time, in seconds. An alias to .
Field
Read only
Type: float
Global DPI scale.
Field
Read only
Type:
Display area size (viewport dimensions). will return exactly the same values. Overriding any of this vector's values will lead to an undefined behavior.
Field
Read only
Type:
A string to map of all managed textures. You can query and push textures with custom IDs. When you add a texture to this map, it will be automatically destroyed and recreated when required (such as when DX11 device gets lost).
Field
Read only
Type:
A string to map of all managed fonts. You can query and push fonts with custom IDs. When you add a font to this map, it will be automatically destroyed and recreated when required (such as when DX11 device gets lost).
Field
Read only
Type:
A string to map of all managed shader. You can query and push shader with custom IDs. When you add a shader to this map, it will be automatically destroyed and recreated when required (such as when DX11 device gets lost).
Field
Read only
Type:
The layer you can render on.
Name
Type
Description
ctrl
Control to add.
container:add(my_control);
Name
Type
Description
ctrl
Control to remove.
container:remove(my_control);
Name
Type
Description
id
string
Control ID.
Type
Description
<control>?
Casted control. Returns nil
if the control was not found, or casting failed.
local some_cb = container:find('some_cb');
Name
Type
Description
id
Control ID.
str
string
Label string.
col
Label color. Defaults to nil
.
bold
bool
Whether to use bold font. Defaults to false
.
Type
Description
label
Label object.
local lab = gui.label(id, 'Hello!');
Name
Type
Description
str
string
New text.
lab:set_text('New hello!');
Type
Description
Origin.
local org = wep:get_abs_origin();
Type
Description
int
Grenade type.
local type = gren:get_grenade_type();
This type represents a shader. HLSL documentation
Rendering system uses Shader Version 4 (ps_4_0).
The constant buffer fields are the following:
Name
Type
Description
mvp
float4x4
Projection matrix.
tex
float2
Texture dimensions.
time
float
Render time (NOT the frame time).
alpha
float
Global opacity override.
The input fields are the following:
Name
Type
Description
pos
float4
Vertex position on screen (x,y,z over w). Register: SV_POSITION
.
col
float4
Vertex color tint (r, g, b, a). Register: COLOR0
.
uv
float2
UV coordinates (u, v). Register: TEXCOORD0
.
The bound objects are the following:
Name
Type
Description
sampler0
sampler
Texture sampler.
texture0
Texture2D
Texture object.
Template:
cbuffer cb : register(b0) {
float4x4 mvp;
float2 tex;
float time;
float alpha;
};
struct PS_INPUT {
float4 pos : SV_POSITION;
float4 col : COLOR0;
float2 uv : TEXCOORD0;
};
sampler sampler0;
Texture2D texture0;
Constructs a shader.
Arguments
Name
Type
Description
src
string
Shader source code.
Returns
Type
Description
shader
Shader object.
Example
local blur = draw.shader([[
// define constant buffer.
cbuffer cb : register(b0) {
float4x4 mvp;
float2 tex;
float time;
float alpha;
};
// define input.
struct PS_INPUT {
float4 pos : SV_POSITION;
float4 col : COLOR0;
float2 uv : TEXCOORD0;
};
// use texture sampler and texture.
sampler sampler0;
Texture2D texture0;
float4 main(PS_INPUT inp) : SV_Target {
float radius = 2.0; // blur radius
float2 inv_size = 1.0 / tex.xy; // inversed size of the texture
float weight = 0.0; // total weight
float4 color = 0.0; // total color
// perform a gaussian blur
for (float x = -radius; x <= radius; x += 1.0)
{
for (float y = -radius; y <= radius; y += 1.0)
{
float2 coord = inp.uv + float2(x, y) * inv_size;
color += texture0.Sample(sampler0, coord) * exp(-((x * x + y * y) / (2.0 * radius * radius)));
weight += exp(-((x * x + y * y) / (2.0 * radius * radius)));
}
}
// average the color
color /= weight;
color.a *= inp.col.a; // apply alpha modulation
return color;
}
]]);
In this section, the most common gui types are listed, that are not particularly bound to a specific part of the gui.
There are a number of events that Fatality provides to use in the API - from various hooks, to in-game events. Each event entry is an object of event_t
. This table documents events to be used by your scripts.
Field
Invoked each time the game queues a frame for rendering. This is the only permitted location for drawing on screen.
Arguments
None.
Field
Invoked every time the game progresses onto another frame stage. This event is called before the game handles a new frame stage.
Arguments
stage
Current frame stage.
Field
Invoked every time game starts the scene rendering process. This event is called before the game's function runs.
Arguments
None.
Field
Invoked every time game starts scene rendering process. This event is called after the game's function runs.
Arguments
setup
View setup information.
Field
Invoked every time the game sets up the view. This event is called before the game's function runs.
Arguments
None.
Field
Invoked every time the game sets up the view information. This event is called after the game's function runs.
Arguments
None.
Field
Invoked every time the game internally overrides view information. You are free to change whatever you like in the provided view setup.
Arguments
Name
Type
Description
setup
View setup information.
Field
Invoked every time a game event fires.
Arguments
event
Game event.
Field
Invoked every time the game processes mouse/controller input. This is a good place to alter mouse movement, if needed.
Arguments
type
Type of the input.
value
Input value.
Field
Invoked every time the GUI processes input.
Arguments
msg
int
System message.
w
int
WPARAM.
l
int
LPARAM.
This type represents a CCSPlayerController
class.
Returns true
if this player is an enemy to the local player.
Arguments
None.
Returns
Type
Description
bool
true
if an enemy.
Example
if player:is_enemy() then
-- ...
end
Returns the sanitized player name.
Arguments
None.
Returns
Type
Description
string
Player's name.
Example
local name = player:get_name();
Returns the pawn attached to this controller.
Arguments
None.
Returns
Type
Description
Pawn instance.
Example
local pawn = ctrl:get_pawn();
Returns the active weapon.
Arguments
None.
Returns
Type
Description
Weapon instance.
Example
local wep = player:get_active_weapon();
Returns the observer pawn used for this controller.
Arguments
None.
Returns
Type
Description
Entity.
Example
local obs_pawn = ctrl:get_observer_pawn();
Returns the pawn this controller is currently observing.
Arguments
None.
Returns
Type
Description
Entity.
Example
local obs = ctrl:get_observer_target();
Returns the current observer mode.
Arguments
None.
Returns
Type
Description
Observer mode.
Example
local mode = ctrl:get_observer_mode();
This type represents a text input control.
Constructs the text input.
Arguments
Name
Type
Description
id
ID.
Returns
Type
Description
text_input
Text input instance.
Example
local sp = gui.text_input(gui.control_id('my_id'));
Type: string
Placeholder text.
Type: string
Value.
Sets the new text.
Arguments
Name
Type
Description
str
string
New value.
Returns
Nothing.
Example
input:set_value('Hello!');
This type represents a slider control.
Constructs the slider.
Arguments
Format Table
Formatting uses standard printf
syntax.
Passing invalid format will lead to an undefined behavior.
1. Single Formatting.
2. Multi Formatting.
Returns
Example
Returns slider' value.
Arguments
None.
Returns
Example
This type represents a combo box control.
Value bits are toggled in order of selectables. That means if the first element is toggled, so will be the first bit, etc.
Constructs the combo box.
Arguments
Returns
Example
Type: bool
If set to true
, the checkbox will be able to toggle multiple selectables.
Returns combo box' value.
Arguments
None.
Returns
Example
This type represents a value data used by some control types.
Returns the value.
Arguments
None.
Returns
Example
Returns the value disrgarding any active keybinds.
Arguments
None.
Returns
Example
Sets the value.
Arguments
Returns
Nothing.
Example
Returns true
if there's any active hotkeys.
Arguments
None.
Returns
Example
Disables all active hotkeys. This allows you to override the value.
Arguments
None.
Returns
Nothing.
Example
Type
Description
<type>
Value.
ctrl:get_value():get();
Type
Description
<type>
Value.
ctrl:get_value():get_direct();
Name
Type
Description
val
<type>
Value.
ctrl:get_value():set(123);
Type
Description
bool
true
if any hotkey is active.
if ctrl:get_value():get_hotkey_state() then
-- ...
end
ctrl:get_value():disable_hotkeys();
Name
Type
Description
id
ID.
Type
Description
checkbox
Checkbox instance.
local cb = gui.checkbox(gui.control_id('my_id'));
Type
Description
Value data.
local val = cb:get_value():get();
Name
Type
Description
val
bool
New value.
cb:set_value(true);
Name
Type
Description
id
Control ID.
low
float
Minimum value.
high
float
Maximum value.
fmt
table[...]
Format. Defaults to {'%.0f'}
.
step
float
Step value. Defaults to 1.0
.
Type
Description
string
Format string.
Name
Type
Description
min
float?
Minimal value.
add
float?
Add step.
fmt
string
Format string.
Type
Description
slider
Slider object.
local slider = gui.slider(id, 0, 100, {'%.0f%%'});
Type
Description
Value data.
local val = slider:get_value():get();
Name
Type
Description
id
ID.
Type
Description
combo_box
Combo box instance.
local cb = gui.combo_box(gui.control_id('my_id'));
Type
Description
Value data.
local val = cb:get_value():get();
This type represents a bitset value.
Maximal bit number for this type is 63. Setting or getting any bits outside of that range will cause a crash.
Resets the value.
Arguments
None.
Returns
Nothing.
Example
bits:reset();
Returns the raw value.
Arguments
None.
Returns
Type
Description
int
Raw value.
Example
local raw = bits:get_raw();
Sets the raw value.
Arguments
Name
Type
Description
val
int
Raw value.
Returns
Nothing.
Example
bits:set_raw(long_long_value);
Returns true
if no bits are set.
Arguments
None.
Returns
Type
Description
bool
true
if no bits are set.
Example
if bits:none() then
-- ...
end
Enables a bit.
Arguments
Name
Type
Description
bit
int
Bit number.
Returns
Nothing.
Example
bits:set(5); -- set bit #5 (same as bit.bor(val, bit.lshift(1, 5)))
Disables a bit.
Arguments
Name
Type
Description
bit
int
Bit number.
Returns
Nothing.
Example
bits:unset(5);
Returns bit state.
Arguments
Name
Type
Description
bit
int
Bit number.
Returns
Type
Description
bool
Bit status.
Example
if bits:get(5) then
-- ...
end
Toggles bit state.
Arguments
Name
Type
Description
bit
int
Bit number.
Returns
Nothing.
Example
bits:toggle(5);
This type is used to determine text alignment.
Creates text_params
instance with vertical alignment.
Arguments
Name
Type
Description
v
Vertical alignment.
Returns
Type
Description
text_params
Created text params.
Example
local align_top = draw.text_params.with_v(draw.text_alignment.top);
Creates text_params
instance with horizontal alignment.
Arguments
Name
Type
Description
h
Horizontal alignment.
Returns
Type
Description
text_params
Created text params.
Example
local align_right = draw.text_params.with_h(draw.text_alignment.right);
Creates text_params
instance with line alignment.
Arguments
Name
Type
Description
line
Line alignment.
Returns
Type
Description
text_params
Created text params.
Example
local lines_center = draw.text_params.with_line(draw.text_alignment.center);
Creates text_params
instance with vertical and horizontal alignments.
Arguments
Name
Type
Description
v
Vertical alignment.
h
Horizontal alignment.
Returns
Type
Description
text_params
Created text params.
Example
local align_bottom_right = draw.text_params.with_vh(draw.text_alignment.bottom, draw.text_alignment.right);
Creates text_params
instance with vertical alignment and line alignment.
Arguments
Name
Type
Description
v
Vertical alignment.
line
Line alignment.
Returns
Type
Description
text_params
Created text params.
Example
local align = draw.text_params.with_vline(draw.text_alignment.bottom, draw.text_alignment.center);
Creates text_params
instance with horizontal alignment and line alignment.
Arguments
Name
Type
Description
h
Horizontal alignment.
line
Line alignment.
Returns
Type
Description
text_params
Created text params.
Example
local align = draw.text_params.with_hline(draw.text_alignment.center, draw.text_alignment.center);
Creates text_params
instance with vertical, horizontal and line alignments.
Arguments
Name
Type
Description
v
Vertical alignment.
h
Horizontal alignment.
line
Line alignment.
Returns
Type
Description
text_params
Created text params.
Example
local align = draw.text_params.with_vhline(draw.text_alignment.center, draw.text_alignment.center, draw.text_alignment.center);
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.
Type: ptr
Texture pointer. You can get one from an instance of texture
type by accessing obj
field. Passing invalid data to this field WILL result in a crash. For a safer way, please use set_texture
.
Type: Type: ptr
Fragment shader (aka Pixel Shader in DirectX terms) pointer. You can get one from an instance of shader
type by accessing obj
field. Passing invalid data to this field WILL result in a crash. For a safer way, please use set_shader
.
Type: rect?
Clip rectangle used for scissor testing. If this is set to nil
, will not clip anything.
It is advised to instead use layer's override_clip_rect
method. While you can pass custom rect to this field, you will lose information about previous clip rects set before. Using that method will make sure to intersect the previous rect with the one you pass and produce a probably more expected result.
Type: rect?
UV rect used for texture mapping. If this field is set to nil
, will use 0, 0, 1, 1
rectangle to map the texture. You can learn more about texture mapping in the tutorial section.
Type: float
Global opacity override. Defaults to 1
, but if you set anything else - will modulate opacity of every next shape you will render.
Type: float
Shape rotation. Not all shapes support this field. The value is set in degrees, not radians.
Type: bool
If set to true
, will apply tesselation to shapes.
Type: bool
If set to true
, will ignore global DPI scale. This is set to true
by default, but you are free to change it to false
if you are trying to render some custom UI elements.
Type: bool
Only useful when using shaders. If set to true
, will not update back buffer texture. This can be used if you need the very same texture data, as when applying several shaders to the back buffer.
Type: bool
If set to true
, will capture back buffer (as long as chained_call
is set to false
). The name of this field is quite misleading due to the fact that in the CS:GO version of Fatality, it was used to configure if the rendering system should also downsample the captured backbuffer into another texture. In DirectX11, this operation is much faster, so it is done regardless.
Type: bool
An alias to only_downsampled
.
Type: bool
If set to true
, will use a separate texture sampler that supports tiling. By default, all textures are stretched, but if you enable this option - their tiling and stretch will be fully configurable by the uv_rect
field.
Type: render_mode
Rendering mode. You can read more about it in the type's documentation.
Sets a texture in a safe manner.
Arguments
Name
Type
Description
tex
Texture object.
Returns
Nothing.
Example
cmd:set_texture(my_tex);
Sets a fragment shader in a safe manner.
Arguments
Name
Type
Description
sh
[shader
]
Shader object.
Returns
Nothing.
Example
cmd:set_shader(my_shader);
Creates a new 2D vector instance.
Arguments
1. Default vector (0, 0).
None.
2. Single value.
3. XY values.
Returns
Example
Type: float
X coordinate.
Type: float
Y coordinate.
Returns floored variant of this vector.
Arguments
None.
Returns
Example
Returns ceiled variant of this vector.
Arguments
None.
Returns
Example
Returns rounded variant of this vector.
Arguments
None.
Returns
Example
Returns length of this vector.
Arguments
None.
Returns
Example
Returns squared length of this vector.
Arguments
None.
Returns
Example
Returns distance to another vector.
Arguments
Returns
Example
Returns squared distance to another vector.
Arguments
Returns
Example
This type represents a C_CSPlayerPawn
class.
Returns true
if the game will draw this player on screen.
Arguments
None.
Returns
Example
Returns true
if left-hand mode is enabled.
Arguments
None.
Returns
Example
Returns the absolute origin (the one that is used for rendering).
Arguments
None.
Returns
Example
Returns the absolute angles (the one that is used for rendering).
Arguments
None.
Returns
Example
Method
Returns the absolute velocity.
Arguments
None.
Returns
Example
Sets the new absolute origin.
Arguments
Returns
Nothing.
Example
Sets new absolute angles.
Arguments
Returns
Nothing.
Example
Method
Sets new absolute velocity.
Arguments
Returns
Nothing.
Example
Returns true
if the player is alive.
Arguments
None.
Returns
Example
Returns true
if this player is an enemy to the local player.
Arguments
None.
Returns
Example
Returns whether this player is an enemy to another entity.
Arguments
Returns
Example
Returns the active weapon.
Arguments
None.
Returns
Example
Returns the sanitized player name.
Arguments
None.
Returns
Example
Returns the player's view offset (eye location relative to the player's origin).
Arguments
None.
Returns
Example
Returns the player's eye position.
Arguments
None.
Returns
Example
Name
Type
Description
value
float
X and Y coordinates.
Name
Type
Description
x
float
X coordinate.
y
float
Y coordinate.
Type
Description
vec2
New vector.
local vec = draw.vec2(5, 10);
Type
Description
vec2
Floored variant.
local fl = vec:floor();
Type
Description
vec2
Ceiled variant.
local ceiled = vec:ceil();
Type
Description
vec2
Rounded variant.
local rounded = vec:round();
Type
Description
float
Length.
local len = vec:len();
Type
Description
float
Length.
local len = vec:len_sqr();
Name
Type
Description
other
vec2
Other vector.
Type
Description
float
Distance.
local dist = vec1:dist(vec2);
Name
Type
Description
other
vec2
Other vector.
Type
Description
float
Distance.
local dist = vec1:dist_sqr(vec2);
Type
Description
bool
true
if will.
if player:should_draw() then
-- ...
end
Type
Description
bool
true
if left-handed.
if player:is_left_handed() then
-- ...
end
Type
Description
Origin.
local org = player:get_abs_origin();
Type
Description
Angles.
local ang = player:get_abs_angles();
Type
Description
Velocity.
local vel = player:get_abs_velocity();
Name
Type
Description
vec
New origin.
player:set_abs_origin(my_vec);
Name
Type
Description
ang
New angles.
player:set_abs_angles(my_ang);
Name
Type
Description
vel
New velocity.
player:set_abs_velocity(my_vel);
Type
Description
bool
true
if alive.
if player:is_alive() then
-- ...
end
Type
Description
bool
true
if an enemy.
if player:is_enemy() then
-- ...
end
Name
Type
Description
ent
Other entity.
Type
Description
bool
true
if an enemy.
if player:is_enemy_to(other_player) then
-- ...
end
Type
Description
Weapon instance.
local wep = player:get_active_weapon();
Type
Description
string
Player's name.
local name = player:get_name();
Type
Description
View offset.
local vo = player:get_view_offset();
Type
Description
Eye position.
local eyes = player:get_eye_pos();
This enum determines the current control's type.
You can only construct types that are listed below in the navigation, and only if those have a constructor.
Default control. You are very unlikely to ever stumble upon this type.
Button control.
Checkbox control.
Child tab control. Only possible to find within tab_layout
controls.
Color picker control.
Combo box control.
Default control with a container. You are very unlikely to ever stumble upon this type.
Groupbox control.
Hotkey input control.
HSB slider (Saturation/Brightness box, Hue slider and Opacity slider).
Label control.
Layout control.
Listbox control.
Loading spinner.
Notification item control. One of the types in the core UI framework, never actually used within Fatality.
Basic popup window.
Basic selectable item.
Slider item. This type doesn't tell the internal value type used.
Spacer control.
Horizontal or vertical tab.
A variant of layout
that is used specifically to operate tabs.
A variant of layout
that is used specifically to operate weapon tabs.
Text input control.
A variant of button that looks like button, but works like a checkbox.
Basic window control.
Basic widget control.
Settings control.
Image control.
This type represents an abstract GUI control.
Type: int
Control ID.
Type: string
String representation of control's ID. This may be empty for some controls.
Type: bool
Control's visibility state.
Type: control?
Parent control. Might be nil
on some controls.
Type:
Control's type.
Type: bool
If set to true
, will mark this control to the inactive state.
Type: string
Tooltip replacement to show when control is inactive.
Type:
Label color override for inactive controls.
Type: string
Tooltip text.
Type: table[string]
Alias list for this control. Used in search box to support different naming (e.g. if a user searches for "Double tap", will find "Rapid fire" instead).
Returns true
if any of the control's hotkeys are active.
Arguments
None.
Returns
Example
Changes visibility state for this control.
Calling this method on controls that are located in layouts with large amount of other controls will inevitably cause performance issues due to auto-stacking.
Arguments
Returns
Nothing.
Example
Adds a callback to this control.
Arguments
Returns
Nothing.
Example
Attempts to downcast the control to the correct type.
Due to Lua engine's limitations, it is impossible to automatically downcast variables. Usually there is no need to call this method, unless you found some control that wasn't somehow already cast to the desired type. find()
methods automatically perform the cast to the correct type.
Arguments
None.
Returns
Example
Resets control's state. This action is usually required if you change control's value directly by interacting with .
You also should call this method on layouts if you add multiple controls into them.
Arguments
None.
Returns
Nothing.
Example
Type
Description
bool
true
if any hotkey is active.
if ctrl:get_hotkey_state() then
-- ...
end
Name
Type
Description
val
bool
Visibility state.
ctrl:set_visible(false);
Name
Type
Description
cbk
function
Callback.
ctrl:add_callback(function ()
print('Callback invoked!');
end);
Type
Description
<control>
New type, if any.
local checkbox = maybe_checkbox:cast();
ctrl:reset();
This table extends the existing math
table that is a part of Lua.
Function
Calculates angles between 2 vectors.
Arguments
src
Source vector.
dst
Destination vector.
Returns
Angles.
Example
local ang = math.calc_angle(vec1, vec2);
Function
Normalizes an angle.
Arguments
angle
float
Input angle.
Returns
float
Normalized angle.
Example
local norm = math.angle_normalize(560);
Function
Approaches an angle over time.
Arguments
from
Start angle.
to
End angle.
speed
float
Approach speed.
Returns
Delta angle.
Example
local ang = math.approach_angles(from, to, 1.0 / game.global_vars.frametime);
Function
Returns a point on the edge of a box.
Arguments
mins
Box mins.
maxs
Box maxs.
dir
Point direction (angle).
radius
float
Area radius.
Returns
Point.
Example
local point = math.edge_point(mins, maxs, dir, 5);
Function
Linear interpolation.
Arguments
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);
Function
Calculates angles from a vector.
Arguments
forward
Source vector.
up
Up vector. Defaults to nil
.
Returns
Angles.
Example
local ang = math.vector_angles(fw);
Function
Transforms a point in the game world onto the viewport.
Arguments
xyz
Point in the world.
round
bool
Whether should round the output. Defaults to true
.
Returns
Point on the viewport.
Example
local point = math.world_to_screen(game_point);
Function
Clamps a value between min and max.
Arguments
n
float
Value.
lower
float
Lowest value.
upper
float
Highest value.
Returns
float
Clamped value.
Example
local x = math.clamp(50, 5, 25); -- 25
Function
Maps the value from one range to another range.
Arguments
val
float
Value.
a
float
Lowest source value.
b
float
Highest source value.
c
float
Lowest destination value.
d
float
Highest destination value.
Returns
float
Mapped value.
Example
local mapped = math.remap_val(0.5, 0, 1, 0, 100); -- 50
Function
Maps the value from one range to another range. Additionally, clamps the value based on the source range.
Arguments
val
float
Value.
a
float
Lowest source value.
b
float
Highest source value.
c
float
Lowest destination value.
d
float
Highest destination value.
Returns
float
Mapped value.
Example
local mapped = math.remap_val_clamped(5, 0, 1, 0, 100); -- 100
Function
An alias to draw.vec2()
.
Example
local vec = math.vec2(5, 5);
Function
An alias to vector()
.
Example
local vec = math.vec3(5, 12, 5);
This type represents a CCSWeaponBaseGun
class.
Returns the absolute origin (the one that is used for rendering).
Arguments
None.
Returns
Type
Description
Origin.
Example
local org = wep:get_abs_origin();
Returns the maximal player speed when holding this weapon.
Arguments
None.
Returns
Type
Description
float
Max speed, in UPS.
Example
local spd = wep:get_max_speed();
Returns the current inaccuracy value.
Arguments
Name
Type
Description
mode
Weapon mode.
Returns
Type
Description
float
Inaccuracy value.
Example
local inacc = wep:get_inaccuracy(csweapon_mode.primary_mode);
Returns the current spread value.
Arguments
Name
Type
Description
mode
Weapon mode.
Returns
Type
Description
float
Inaccuracy value.
Example
local spread = wep:get_spread(csweapon_mode.primary_mode);
Returns the weapon ID.
Arguments
None.
Returns
Type
Description
Weapon ID.
Example
local wep_id = wep:get_id();
Returns the weapon type.
Arguments
None.
Returns
Type
Description
Weapon type.
Example
local type = wep:get_type();
Returns the weapon static data.
Arguments
None.
Returns
Type
Description
Weapon data.
Example
local data = wep:get_data();
Returns true
if this weapon is a firearm.
Arguments
None.
Returns
Type
Description
bool
true
if a firearm.
Example
if wep:is_gun() then
-- ...
end
Returns true
if you can attack with this weapon.
Arguments
None.
Returns
Type
Description
bool
true
if can attack.
Example
if wep:is_attackable() then
-- ...
end
Returns true
if this weapon has a secondary attack mode.
Arguments
None.
Returns
Type
Description
bool
true
if has the secondary attack mode.
Example
if wep:has_secondary_attack() then
-- ...
end
Returns true
if this weapon has spread (e.g. knives do not have any spread).
Arguments
None.
Returns
Type
Description
bool
true
if has spread.
Example
if wep:has_spread() then
-- ...
end
This table exposes various utility functions.
Encode a string to Base64 format.
Arguments
Name
Type
Description
str
string
Source string.
Returns
Type
Description
string
Base64-encoded string.
Example
local enc = utils.base64_encode('Hello!'); -- SGVsbG8h
Decode Base64-encoded string.
Arguments
Name
Type
Description
str
string
Base64-encoded string.
Returns
Type
Description
string
Source string.
Example
local dec = utils.base64_decode('SGVsbG8h'); -- Hello!
Returns current time as UNIX timestamp.
Arguments
None.
Returns
Type
Description
int
Timestamp.
Example
local ts = utils.get_unix_time();
Returns MURMUR2-hashed string.
Arguments
Name
Type
Description
str
string
Source string.
Returns
Type
Description
int
Hash.
Example
local hash = utils.murmur2('Hello');
Returns FNV1A-hashed string.
Arguments
Name
Type
Description
str
string
Source string.
Returns
Type
Description
int
Hash.
Example
local hash = utils.fnv1a('Hello');
Returns an address to an export in an image.
Arguments
Name
Type
Description
mod
string
Image to look in.
exp
string
Export symbol.
Returns
Type
Description
int
Address, or 0
on failure.
Example
local message_box = utils.find_export('user32.dll', 'MessageBoxA');
Searches for a code pattern in an image.
Arguments
Name
Type
Description
mod
string
Image to search in.
pattern
string
Code pattern.
Returns
Type
Description
int
Address, or 0
on failure.
Example
local something = utils.find_pattern('engine2.dll', 'DE AD ? ? ? ? BE EF');
Returns current clipboard content.
Arguments
None.
Returns
Type
Description
string
Clipboard content.
Example
local clip = utils.clipboard_get();
Sets new clipboard content.
Arguments
Name
Type
Description
str
string
New content.
Returns
Nothing.
Example
utils.clipboard_set('Hello!');
This type represents the base class for font types. You cannot create an instance of this type. Instead, use the children types.
Type: float
Font height, in pixels.
Type: float
Font ascent value, in pixels.
Type: float
Font descent value, in pixels.
Type: float
Font line gap, in pixels.
Type: float
Font kerning gap, in pixels.
Type: float
Font outline opacity (0
to 1
). Defaults to 0.45
.
Type:
Font flags. Use bit
library to read flags.
Type: int
Glyph Y offset, in pixels. Will alter the location of a glyph in the atlas. Changing this value after the font was created is meaningless.
Type: int
Glyph X offset, in pixels. Will alter the location of a glyph in the atlas. Changing this value after the font was created is meaningless.
Type: font_base
Fallback font to use, in case a glyph is not found in this font. Is it useful when one font does not have codepoints for specific symbols, that are present in another font, but you still want to prefer this font's glyphs over other font.
Type:
Shadow color. Only R, G, B values are used.
Returns character width, included with kerning.
Arguments
Returns
Example
Returns kerning value for a single character. If kerning is disabled, will instead return kerning gap.
Arguments
Returns
Example
Returns text area size.
Arguments
Returns
Example
Wraps text to meet the desired width. Wrapping is done by breaking text by words and inserting line breaks in between. If one of the words is longer than the target width, will instead use that word's width.
Arguments
Returns
Example
Returns glyph information for a character.
Arguments
Returns
Example
Returns a texture atlas that contains the provided glyph.
Arguments
Returns
Example
Name
Type
Description
left
int
Previous character codepoint.
right
int
Current character codepoint.
Type
Description
float
Distance, in pixels.
local w = font:get_kerned_char_width(prev_cp, cp);
Name
Type
Description
cp
int
Codepoint.
Type
Description
float
Kerning value, in pixels.
local k = font:get_kerning(cp);
Name
Type
Description
text
string
Text.
skip_scaling
bool
If set to true
, will skip global DPI scaling. Defaults to false
.
til_newline
bool
Calculate size only until a line break is met. Defaults to false
.
Type
Description
Text area size.
local sz = font:get_text_size('Hello!');
Name
Type
Description
text
string
Text to wrap.
width
float
Target width.
Type
Description
string
Wrapped text.
local shorter = font:wrap_text('This is some very long text!', 50);
Name
Type
Description
codepoint
int
Codepoint.
Type
Description
Glyph information.
local glyph = font:get_glyph(cp);
Name
Type
Description
gl
Character glyph.
Type
Description
int
Texture pointer, or nil
if not found.
local atlas = font:get_texture(glyph);
This enum represents the unique identifier for various weapons in the game.
Represents no weapon.
Represents a Desert Eagle.
Represents the Dual Berettas.
Represents a Five-SeveN.
Represents a Glock-18.
Represents an AK-47.
Represents an AUG.
Represents an AWP.
Represents a FAMAS.
Represents a G3SG1.
Represents a Galil AR.
Represents an M249.
Represents an M4A4.
Represents a MAC-10.
Represents a P90.
Represents a zone repulsor device.
Represents an MP5-SD.
Represents a UMP-45.
Represents an XM1014.
Represents a PP-Bizon.
Represents a MAG-7.
Represents a Negev.
Represents a Sawed-Off.
Represents a Tec-9.
Represents a Zeus x27 taser.
Represents a P2000.
Represents an MP7.
Represents an MP9.
Represents a Nova.
Represents a P250.
Represents a shield.
Represents a SCAR-20.
Represents an SG 553.
Represents an SSG 08.
Represents the Golden Knife.
Represents the default knife.
Represents a flashbang.
Represents an HE grenade.
Represents a smoke grenade.
Represents a Molotov.
Represents a decoy grenade.
Represents an incendiary grenade.
Represents a C4 explosive.
Represents a health shot.
Represents the Terrorist knife.
Represents the M4A1-S.
Represents the USP-S.
Represents a CZ75-Auto.
Represents an R8 Revolver.
Represents a tactical awareness grenade.
Represents fists.
Represents a breach charge.
Represents a tablet.
Represents a generic melee weapon.
Represents an axe.
Represents a hammer.
Represents a spanner (wrench).
Represents a ghost knife.
Represents a firebomb grenade.
Represents a diversion device.
Represents a fragmentation grenade.
Represents a snowball.
Represents a bump mine.
Represents a Bayonet.
Represents the Classic Knife.
Represents a Flip Knife.
Represents a Gut Knife.
Represents a Karambit.
Represents an M9 Bayonet.
Represents a Huntsman Knife.
Represents a Falchion Knife.
Represents a Bowie Knife.
Represents a Butterfly Knife.
Represents a Shadow Daggers.
Represents a Paracord Knife.
Represents a Survival Knife.
Represents an Ursus Knife.
Represents a Navaja Knife.
Represents a Nomad Knife.
Represents a Stiletto Knife.
Represents a Talon Knife.
Represents a Skeleton Knife.
Represents a Kukri Knife.
This type is a common 3D vector (x, y, z).
Type: float
X coordinate.
Type: float
Y coordinate.
Type: float
Z coordinate.
Constructs a vector.
Arguments
1. Default vector (0, 0, 0).
None.
2. Single value.
Name
Type
Description
value
float
X and Y coordinates.
3. XYZ values.
Name
Type
Description
x
float
X coordinate.
y
float
Y coordinate.
z
float
Z coordinate.
Returns
Type
Description
vector
Vector.
Example
local vec = vector(5, 25, 12);
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
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)));
Returns squared distance to another vector.
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)));
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)));
Returns squared 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
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)));
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);
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
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();
Returns squared 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_sqr();
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();
Returns squared 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_sqr();
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);
Constructor
Creates a new rectangle.
Arguments
1. Default rectangle (0, 0 position; 0, 0 size).
None.
2. Single value.
3. Single vector.
4. Double value.
5. Double vector.
6. Four values.
Returns
Example
Field
Type:
Mins (top-left) vector.
Field
Type:
Maxs (bottom-right) vector.
Method
Either returns rectangle's width, or sets a new width.
Arguments
1. Get width.
None.
2. Set width.
Returns
1. Get width.
2. Set width.
Example
Method
Either returns rectangle's height, or sets a new height.
Arguments
1. Get height.
None.
2. Set height.
Returns
1. Get height.
2. Set height.
Example
Method
Either returns rectangle's size, or sets a new size.
Arguments
1. Get size.
None.
2. Set size.
Returns
1. Get size.
2. Set size.
Example
Method
Explodes the rectangle by given vector (increase size from center into all directions by coordinates in the vector).
Arguments
Returns
Example
Method
Returns a rectangle with half of the width of this rectangle.
Arguments
None.
Returns
Example
Method
Translates (moves) this rectangle by vector coordinates.
Arguments
Returns
Example
Method
Move rectangle from the left by given amount.
Arguments
Returns
Example
Method
Move rectangle from the right by given amount.
Arguments
Returns
Example
Method
Move rectangle from the top by given amount.
Arguments
Returns
Example
Method
Move rectangle from the bottom by given amount.
Arguments
Returns
Example
Method
Adds the value to the left side of the rectangle.
Arguments
Returns
Example
Method
Adds the value to the right side of the rectangle.
Arguments
Returns
Example
Method
Adds the value to the top side of the rectangle.
Arguments
Returns
Example
Method
Adds the value to the bottom side of the rectangle.
Arguments
Returns
Example
Method
Shrinks (implodes) the rectangle by given amount.
Arguments
Returns
Example
Method
Expands (explodes) the rectangle by given amount.
Arguments
Returns
Example
Method
Returns true
if this rectangle contains either vector or another rectangle.
Arguments
1. Vector variant.
2. Rectangle variant.
Returns
Example
Method
Returns true
if the other rectangle overlaps with this rectangle.
Arguments
Returns
Example
Method
Intersects this rectangle with another rectangle.
Arguments
Returns
Example
Method
Returns top-left vector.
Arguments
None.
Returns
Example
Method
Returns top-right vector.
Arguments
None.
Returns
Example
Method
Returns bottom-right vector.
Arguments
None.
Returns
Example
Method
Returns bottom-left vector.
Arguments
None.
Returns
Example
Method
Returns center point of this rectangle.
Arguments
None.
Returns
Example
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
Returns
Example
Method
Returns floored rectangle.
Arguments
None.
Returns
Example
Method
Returns ceiled rectangle.
Arguments
None.
Returns
Example
Method
Returns rounded rectangle.
Arguments
None.
Returns
Example
Method
Returns true
if both mins and maxs are equal to 0.
Arguments
None.
Returns
Example
value
float
Mins XY, maxs XY value.
value
Mins vector, maxs vector.
x
float
Mins/maxs X coordinate.
y
float
Mins/maxs Y coordinate.
mins
Mins vector.
maxs
Maxs vector.
x0
float
Mins X coordinate.
y0
float
Mins Y coordinate.
x1
float
Maxs X coordinate.
y1
float
Maxs Y coordinate.
rect
New rectangle.
local my_rect = draw.rect(50, 50, 150, 150);
value
float
New width.
float
Width.
rect
New rectangle with changed width.
local half_width = rect:width(rect:width() * 0.5);
value
float
New height.
float
Height.
rect
New rectangle with changed height.
local half_height = rect:height(rect:height() * 0.5);
value
New size.
Size.
rect
New rectangle with changed size.
local half_size = rect:size(rect:size() * draw.vec2(0.5, 0.5));
value
Explode size.
rect
Exploded rectangle.
local exp = rect:explode(draw.vec2(6, 6)); -- will subtract -3,-3 from mins and add 3,3 to maxs
rect
Rectangle with halved width.
local half = rect:half_width();
value
Translation amount.
rect
Translated rectangle.
local rect = draw.rect(50, 50, 150, 150);
local translated = rect:translate(draw.vec2(5, 5)); -- mins/maxs will be 55,55 and 155,155
value
float
Margin amount.
rect
Moved rectangle.
local new = rect:margin_left(5); -- moves to the right by 5px
value
float
Margin amount.
rect
Moved rectangle.
local new = rect:margin_right(5); -- moves to the left by 5px
value
float
Margin amount.
rect
Moved rectangle.
local new = rect:margin_top(5); -- moves to the bottom by 5px
value
float
Margin amount.
rect
Moved rectangle.
local new = rect:margin_bottom(5); -- moves to the top by 5px
value
float
Padding amount.
rect
Resized rectangle.
local new = rect:padding_left(5); -- adds 5 to mins x
value
float
Padding amount.
rect
Resized rectangle.
local new = rect:padding_right(5); -- adds 5 to maxs x
value
float
Padding amount.
rect
Resized rectangle.
local new = rect:padding_top(5); -- adds 5 to mins y
value
float
Padding amount.
rect
Resized rectangle.
local new = rect:padding_bottom(5); -- adds 5 to maxs y
value
float
Shrink value.
rect
Resized rectangle.
local shrinked = rect:shrink(5); -- adds 5,5 to mins and subtracts 5,5 from maxs
value
float
Expand value.
rect
Resized rectangle.
local expanded = rect:expand(5); -- subtracts 5,5 from mins and adds 5,5 to maxs
other
Vector to check against.
other
rect
Rectangle to check against.
bool
true
if other object is in bounds of this rectangle.
if rect:contains(cursor_pos) then
-- ...
end
other
rect
Rectangle to check against.
bool
true
if other rectangle overlaps with this rectangle.
if rect:overlaps(another_rect) then
-- ...
end
other
rect
Rectangle to intersect with.
rect
Intersected rectangle.
local intersected = rect:intersect(another_rect);
Top-left vector.
local tl = rect:tl();
Top-right vector.
local tr = rect:tr();
Bottom-right vector.
local br = rect:br();
Bottom-left vector.
local bl = rect:bl();
Center point.
local center = rect:center();
r
float
Radians value.
Point on the ellipsis.
local point = rect:circle(rad(250)); -- returns point on the 250th degree
rect
Floored rectangle.
local floored = rect:floor();
rect
Ceiled rectangle.
local ceiled = rect:ceil();
rect
Rounded rectangle.
local rounded = rect:round();
bool
true
if this is a zero rectangle.
if rect:is_zero() then
-- ...
end
This type represents the GUI input context.
Returns current cursor position.
Arguments
None.
Returns
Example
Returns previous cursor position.
Arguments
None.
Returns
Example
Delta value between previous and current cursor positions.
Arguments
None.
Returns
Example
Returns true
if the cursor did move since the last input.
Arguments
None.
Returns
Example
Returns true
if mouse scroll wheel did move since the last input.
Arguments
None.
Returns
Example
Returns true
if any mouse key's state had changed.
Arguments
None.
Returns
Example
Returns true
if any key was released since the last input.
Arguments
None.
Returns
Example
Returns the amount of rows scrolled this input.
Arguments
None.
Returns
Example
Returns true
if the mouse key is up (depressed).
Arguments
Returns
Example
Returns true
if the mouse key is down (pressed).
Arguments
Returns
Example
Returns true
if the mouse key is clicked (switched from depressed to pressed state).
Arguments
Returns
Example
Returns true
if the mouse key is released (switched from pressed to depressed state).
Arguments
Returns
Example
Returns true
if any key's state had changed.
Arguments
None.
Returns
Example
Returns true
if a key is up (depressed).
Arguments
Returns
Example
Returns true
if a key is down (pressed).
Arguments
Returns
Example
Returns true
if a key is clicked (switched from depressed to pressed state).
Arguments
Returns
Example
Returns true
if a key is released (switched from pressed to depressed state).
Arguments
Returns
Example
Type
Description
Cursor position.
local cur = gui.input:cursor();
Type
Description
Previous cursor position.
local prev = gui.input:cursor_prev();
Type
Description
Cursor delta.
local delta = gui.input:cursor_delta();
Type
Description
bool
true
if moved.
if gui.input:did_cursor_move() then
-- ...
end
Type
Description
bool
true
if moved.
if gui.input:did_wheel_move() then
-- ...
end
Type
Description
bool
true
if processed.
if gui.input:did_process_mouse() then
-- ...
end
Type
Description
bool
true
if released.
if gui.input:button_released() then
-- ...
end
Type
Description
float
Rows scrolled.
local scroll = gui.input:wheel_delta();
Name
Type
Description
mb
Mouse button.
Type
Description
bool
true
if depressed.
if gui.input:is_mouse_up(gui.mouse_button.left) then
-- ...
end
Name
Type
Description
mb
Mouse button.
Type
Description
bool
true
if pressed.
if gui.input:is_mouse_down(gui.mouse_button.left) then
-- ...
end
Name
Type
Description
mb
Mouse button.
Type
Description
bool
true
if clicked.
if gui.input:is_mouse_clicked(gui.mouse_button.left) then
-- ...
end
Name
Type
Description
mb
Mouse button.
Type
Description
bool
true
if released.
if gui.input:is_mouse_released(gui.mouse_button.left) then
-- ...
end
Type
Description
bool
true
if state changed.
if gui.input:did_process_key() then
-- ...
end
Name
Type
Description
k
int
Virtual key.
Type
Description
bool
true
if depressed.
if gui.input:is_key_up(0x41) then -- 0x41 = "A"
-- ...
end
Name
Type
Description
k
int
Virtual key.
Type
Description
bool
true
if pressed.
if gui.input:is_key_down(0x41) then -- 0x41 = "A"
-- ...
end
Name
Type
Description
k
int
Virtual key.
Type
Description
bool
true
if clicked.
if gui.input:is_key_clicked(0x41) then -- 0x41 = "A"
-- ...
end
Name
Type
Description
k
int
Virtual key.
Type
Description
bool
true
if released.
if gui.input:is_key_released(0x41) then -- 0x41 = "A"
-- ...
end
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.
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);
Returns a white, opaque color.
Arguments
None.
Returns
Type
Description
color
Color object.
Example
local white = draw.color.white();
Returns a white, transparent color.
Arguments
None.
Returns
Type
Description
color
Color object.
Example
local white_t = draw.color.white_transparent();
Returns a black, opaque color.
Arguments
None.
Returns
Type
Description
color
Color object.
Example
local black = draw.color.black();
Returns a black, transparent color.
Arguments
None.
Returns
Type
Description
color
Color object.
Example
local black_t = draw.color.black_transparent();
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);
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);
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
Returns integer representation of this color (RGBA format)
Arguments
None.
Returns
Type
Description
int
RGBA color.
Example
local num = col:rgba();
Returns integer representation of this color (ARGB format)
Arguments
None.
Returns
Type
Description
int
ARGB color.
Example
local num = col:argb();
Returns integer representation of this color (BGRA format)
Arguments
None.
Returns
Type
Description
int
BGRA color.
Example
local num = col:bgra();
Returns integer representation of this color (ABGR format)
Arguments
None.
Returns
Type
Description
int
ABGR color.
Example
local num = col:abgr();
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);
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);
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);
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);
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);
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);
Returns red color value.
Arguments
None.
Returns
Type
Description
int
Color value.
Example
local r = col:get_r();
Returns green color value.
Arguments
None.
Returns
Type
Description
int
Color value.
Example
local g = col:get_g();
Returns blue color value.
Arguments
None.
Returns
Type
Description
int
Color value.
Example
local b = col:get_b();
Returns opacity color value.
Arguments
None.
Returns
Type
Description
int
Color value.
Example
local a = col:get_a();
Return hue value of the color.
Arguments
None.
Returns
Type
Description
int
Hue (0
to 359
).
Example
local hue = col:h();
Returns saturation value of the color.
Arguments
None.
Returns
Type
Description
float
Saturation (0
to 1
).
Example
local saturation = col:s();
Returns brightness value of the color.
Arguments
None.
Returns
Type
Description
float
Brightness (0
to 1
).
Example
local brightness = col:v();
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);
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.
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.
Type: font_base
Font to use with add_text
. If nothing has been set, no text will get rendered.
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.
Type: bool
If set to true
, will skip global DPI scale. Defaults to true
.
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));
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));
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));
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));
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)
});
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)
});
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);
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)
});
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);
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);
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);
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));
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
);
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
);
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
);
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
);
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
);
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
);
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)
);
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
);
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);
Adds text.
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));
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));