Umbra

An external overlay for THE FINALS on Linux.

It reads the game's memory from a separate process, draws a transparent click-through window on top of it, and provides an aim assist and a triggerbot. Nothing is injected into the game and nothing is ever written back; the tool reads memory and moves the mouse, and that is all.

Built from scratch on Linux: every game offset in this repository was derived by observing the running process, not copied from a published SDK dump.

https://github.com/user-attachments/assets/858e94f2-762b-4c26-877f-fb490e66e42b

Requirements

• raylib 5.0+ for the window and drawing
• libX11 and libXext, CMake 3.16+, a C++17 compiler
• Dear ImGui and rlImGui are vendored in third_party/; nothing to install
• X11 or XWayland. Pure Wayland will not work: the overlay needs XShape for click-through and global hotkey polling, and Wayland deliberately gives an external process neither. Any desktop is fine; X11 is the requirement, not a particular DE.
• The game running under Proton or Wine, in Windowed mode rather than Fullscreen, so the overlay can draw over it

Arch / CachyOS

sudo pacman -S --needed base-devel cmake raylib libx11 libxext

Ubuntu 24.04+ / Debian 13+

sudo apt install build-essential cmake libraylib-dev libx11-dev libxext-dev
pkg-config --modversion raylib           # must be 5.0 or newer

Older releases package a raylib too old to build against; build it from source if pkg-config reports below 5.0.

REQUIREMENTS.md covers the rest: building raylib from source, kernel headers for the module, Secure Boot, ptrace_scope, and how to verify a working setup.

Tested on

CachyOS                kernel 7.1.2-3-cachyos, built with clang 22.1.6
KDE Plasma 6.7.2       Wayland session, overlay running through XWayland
raylib 6.0             CMake 4.3.4, GCC 16.1.1
Intel UHD + RTX 4060   game under Proton, Windowed

Two parts of that are worth calling out, because they are the awkward cases:

• It is a Wayland session. The overlay does not run on Wayland natively and it does not need to: the game runs under XWayland and so does the overlay, and X11 click-through and hotkeys work normally inside it. If you are on Wayland, this is the configuration that works.
• The kernel is clang-built, which is unusual and is what the module's toolchain detection exists for. On a GCC kernel the module takes the other branch, which is the common case but the less exercised one here.

This is the development machine, so it is the only configuration actually verified. Other distributions, desktops and GCC-built kernels are expected to work and are untested.

Build

chmod +x build.sh run.sh   # a zip download drops the executable bit
./build.sh                 # configure and build
./build.sh clean           # from a fresh build directory

The binary is written to build/TheFinals.

CMake stores the absolute source path in its cache, so a build directory carried across a move or rename stops working. build.sh notices and reconfigures on its own, so moving the project is not something you have to think about.

Kernel module (optional, stealthier)

kmod/ builds a small module that makes the tool considerably quieter on the system. It is entirely optional: without it everything still works, using the userspace fallbacks noted below.

• Memory reads go through access_process_vm() in kernel space, so ptrace_scope does not apply. The tool needs no sudo, nothing has to attach to the game, and yama does not have to be loosened for the whole system.
• Mouse input is injected into the real pointer instead of a virtual uinput device. Without the module the tool must create one, and a virtual input device is enumerable: it shows up in /proc/bus/input/devices for anything that cares to look. With the module there is no extra device at all.

cd kmod && make
sudo insmod suite_kmod.ko

A module must be built with the same compiler as the kernel it loads into. The Makefile reads that from the kernel's own config and sets the toolchain itself, so plain make is correct on a GCC kernel and on a clang one alike:

  kernel   7.1.2-3-cachyos
  toolchain clang (LLVM=1)

Override with make LLVM=0 or make LLVM=1 if it ever guesses wrong. If the kernel headers are missing it says so and prints the install command for your distribution.

With Secure Boot enabled an unsigned module will not load: sign it, disable Secure Boot, or simply skip the module.

Load it before starting the tool; the backend is chosen once, at startup.

Confirm which backend is live in the menu, or in the log:

[mem] kernel backend: /dev/suite_kmod
[vmouse] kernel injection into the real pointer

Unload with sudo rmmod suite_kmod.

Run

Set the game to Windowed mode first. In Fullscreen the game owns the display outright and nothing can draw over it, so the overlay will be running correctly and still be invisible.

The overlay finds the game's window and matches its position and size, rechecking as you go, so it follows the window if you move or resize it, and adapts to any resolution.

./run.sh                # finds the game PID by itself
./run.sh 12345          # or give it one
./run.sh -q             # quiet: a few status lines only, no update check

Start it whenever you like, including at the menu. It re-resolves its objects when a match begins or ends, so it does not need restarting between rounds.

On start it also asks GitHub whether a newer release is out, and if there is one it says so, with a link. It never downloads or changes anything, and the tool does not wait for the answer.

Controls

Settings are edited in the menu and saved to settings.cfg when the tool exits, so it comes back the way you left it.

Features

ESP

Boxes, skeletons, names, health bars, distance and snaplines. Squad colours distinguish teams, and a master opacity slider governs everything drawn.

The skeleton is composed from the mesh's own bone hierarchy, so it follows the animation rather than approximating from a capsule.

Spectators are left out. The game lists them with the players, but they carry no health, so a box on one reads 0 HP, and the game never draws them, so there is nothing to see or hit. A switch in the ESP tab shows them anyway. The sonar and the off-screen pins never do, and the aim assist and triggerbot pass over them unless told otherwise in the Aim tab.

Off-screen indicators

Anyone behind you, beside you or past the edge of the screen gets a pin along the window's edge, in their squad's colour, pointing their way. In front of you a pin points exactly where the player projects onto your view, through the same projection as the ESP's boxes and lines. Behind you it goes by bearing, so someone straight behind you is straight down and the pin holds still. Each pin holds the player's class (L, M or H), with a band round its back for their health, the distance behind it, and a small up or down marker when they are a floor or more above or below you. Far pins are smaller and fainter.

With snaplines drawn from the crosshair (a switch beside Snaplines in the ESP tab), every pin sits on its own player's line. Players in nearly the same direction get their pins nudged apart, just far enough that neither the pins nor their distances overlap.

Ring radius starts at its top, where the pins run along the window's border. Lower, they sit on a ring around the crosshair instead, one that flattens against the edges of the screen where it would cross them.

Inside a set distance the pin flickers neon green, faster the closer the player gets, while its rim keeps the squad's colour. Radius, size, range, opacity, the flicker distance and its slowest and fastest rates are all in the menu's Off-screen tab. Opacity sets how solid the whole indicator is, flicker and text included, and Far opacity how much of that the farthest pins keep.

Sonar

A radar in a window of its own, so it can sit beside the game or on a second screen rather than over the view. It turns with you: up is always the way you are facing, and you are the marker at the centre.

• Squad colours, the same ones the ESP draws, so a squad reads the same in both. Squadmates and spectators are left out; the sonar is for what you cannot see.
• Class letters in each blip, L, M or H, or plain dots to read it at a glance.
• Range is centre to rim, in metres. Anyone past it is not drawn at all, so nothing piles up against the edge, and optional rings at a third and two thirds give the distance a scale.
• Where you put it: drag it anywhere, resize it from the corner, then lock it in place. Position, size and opacity are all remembered.

It has its own tab in the menu.

Aim assist

Pulls toward a target while the chosen mouse button is held.

• Target selection: a bias slider between "closest to me" and "closest to the crosshair", so you can take the player behind the nearest one by pointing at him.
• Smoothing: a divisor mode and an inertia (EMA) mode.
• Stickiness: keeps the current target unless a challenger is clearly better, instead of hopping between two enemies at similar angles.
• Bone selection: head, chest, body or legs, aimed at the real joint when the skeleton resolves.
• Prediction: leads a moving target by its velocity. Without this the aim trails a moving head by a constant amount, because the position it was given is already a frame old by the time the mouse moves.
• Curved pull: approaches the target on an arc rather than a straight line, since a dead-straight path is a shape no hand draws. Layers over either smoothing mode: it sets the shape of the path, smoothing still sets the rate. Lateral and vertical curvature, arc direction and a per-frame jitter are all adjustable. Off by default. (After Witschel and Wressnegger, EuroSec 2020.)
• Quick scope: releases the aim the instant you fire, so a sniper's recoil is yours to ride rather than something the assist fights. It re-arms on the next ADS press, or after a delay if you set one. Needs the aim held on right mouse, since the shot has to be a different button from the aim.
• Pause after a kill: when the player the aim is pulling onto dies, the aim stops instead of moving on to the next closest one. It re-arms on the next press of the aim button, or after a delay if you set one. Off by default.

Triggerbot

Fires when the crosshair is on target.

• With the aim assist active, it fires only when the crosshair has reached the exact point the aim is pulling toward.
• On its own, it works from the skeleton (a chosen bone, or any bone), or from the capsule box.
• Tolerance scales with the target's on-screen size, so one setting behaves the same point-blank and across the map. A fixed pixel tolerance cannot: at range a few pixels span a whole head, up close they are a sliver of one.
• Arm delay (after the button goes down), reaction delay (after the crosshair lands), click duration and cooldown are all adjustable.

Visibility

Players who are not currently being drawn by the game are crossed out and faded, and the aim assist and triggerbot can each be told to ignore them.

This is derived from the engine's own render timestamp, so it is conservative by nature: the game culls on a bounding box, which is larger than the player, and occlusion queries lag a frame or two. Expect an enemy to be marked visible slightly before he fully clears a corner. The tolerance slider controls how quickly someone drops out of visible after breaking line of sight.

Offsets

Every game-specific address lives in offsets.cfg, read at startup from the working directory or one level above it.

The tool refuses to start without it, or without the few offsets nothing works without: the controller and pawn that point at each other, the player list, each player's pawn, where a pawn stands, and a camera (the camera manager's POV, or the controller's rotation). It names whichever are missing.

Every other offset belongs to one feature, and an empty one turns off only that feature. The tool lists what is off when it starts. Nothing is left silently zero, because a zero offset still reads something: the object's vtable pointer, which for the squad is the same on every pawn, so every player looks like your squadmate and the screen stays empty with no explanation.

The spectator flag can hide the whole lobby when it is wrong rather than empty, so it is checked against the match while it runs, ignored when it contradicts it, and the log says so. When players are listed but none is drawn, the log says what removed them, squadmates included.

Some of the offsets describe the engine's object array rather than a member: where the module keeps its address, the two keys that unscramble it, and how its entries are laid out. With those the tool reads its way to the player and starts at once. Without them it falls back to scanning the game's memory for the same thing, which works but costs seconds at every start and again after each match.

A game update moves these. When that happens the tool starts but finds nothing. Re-derive the offsets and copy the new offsets.cfg here. No rebuild is needed.

Layout

README.md             this file
REQUIREMENTS.md       dependencies and how to install them
LICENSE               GPL-2.0
build.sh              build script
run.sh                launcher
banner.txt            startup banner
offsets.cfg           game offsets (required)
CMakeLists.txt
src/
  main.cpp              entry point, overlay window, render loop
  mem.hpp               process memory reads
  cheat.hpp             reader thread, entity list
  render.hpp            ESP drawing, aim assist, triggerbot, menu
  global.hpp            state shared between reader and render threads
  structs.hpp           engine types and world-to-screen projection
  skeleton.hpp          bone hierarchy composition
  settings.hpp          settings.cfg load and save
  vmouse.hpp            mouse output
  offsets.hpp           fixed engine layout constants
  runtime_offsets.hpp   offsets.cfg loader
  gobjects_direct.hpp   object array decoding
kmod/
  suite_kmod.c          kernel module: memory reads and mouse injection
  suite_kmod.h          shared ioctl contract
  Makefile

settings.cfg is created the first time the tool exits.

Troubleshooting

offsets.cfg not found: run from the project directory, or keep the file beside the binary.

offsets.cfg is present but incomplete: the offsets it names are zero. The game has most likely updated; re-derive them.

Nothing appears on screen, but the log looks healthy: the game is probably in Fullscreen, which lets nothing draw over it. Switch it to Windowed mode. The log line game window at X,Y WxH - overlay will match confirms the overlay found and matched the window.

The overlay eats your mouse clicks: libXext was missing when you built, so click-through is compiled out. The configure step warns about this; look for XShape click-through: enabled. Install libxext/libxext-dev and rebuild.

Overlay in the wrong place, or clicks not passing through: the overlay needs X11. Under Wayland, force XWayland:

DISPLAY=:0 WAYLAND_DISPLAY= ./run.sh

Game not found: pass the PID directly. Under Proton the process is Discovery-d.exe and the correct thread is GameThread.

Nothing drawn during a match: offsets are stale after a game update.

Aim assist does nothing: check that the menu reports a mouse backend. If "visible only" is enabled and every enemy is behind cover, there is deliberately no target.

Kernel module will not build: it must be compiled with the same toolchain as your running kernel. On a clang-built kernel: make LLVM=1.

A note on risk

This reads another process's memory and injects mouse input. It does not modify the game, but using it in an online match is against the game's terms of service and can cost you the account. That is your decision to make; make it knowingly.

License

GNU General Public License, version 2. See LICENSE.

You may use, study, modify and redistribute this. If you distribute a modified version you must ship its source under the same licence, so everyone who receives it keeps the same freedoms. There is no warranty.

GPLv2 rather than v3 deliberately: the kernel module in kmod/ is a Linux kernel module, the kernel is GPL-2.0-only, and MODULE_LICENSE("GPL") means version 2. Licensing the whole project the same way keeps the userspace tool and the module compatible with each other and with the kernel, with no split to reason about.

Copyright © 2026 Ymsniper.