Umbra

Un overlay esterno per THE FINALS su Linux.

Legge la memoria del gioco da un processo separato, disegna una finestra trasparente click-through sopra di esso, e fornisce un aim assist e un triggerbot. Nulla viene iniettato nel gioco e nulla viene mai scritto di ritorno; lo strumento legge la memoria e muove il mouse, e questo è tutto.

Costruito da zero su Linux: ogni offset di gioco in questo repository è stato derivato osservando il processo in esecuzione, non copiato da un dump SDK pubblicato.

https://github.com/user-attachments/assets/674baa52-3006-4767-a263-29178bed3a31

Requisiti

• SFML 3.x: non 2.x, la vecchia API è stata rimossa
• ImGui-SFML, compilato contro SFML 3
• libX11 e libXext, CMake 3.16+, un compilatore C++17
• X11 o XWayland. Il Wayland puro non funzionerà: l'overlay necessita di XShape per il click-through e il polling degli hotkey globali, e Wayland nega deliberatamente entrambi a un processo esterno. Qualsiasi desktop va bene; X11 è il requisito, non un particolare DE.
• Il gioco in esecuzione sotto Proton o Wine, in modalità Windowed piuttosto che Fullscreen, così che l'overlay possa disegnarci sopra

Arch / CachyOS

sudo pacman -S --needed base-devel cmake sfml libx11 libxext
paru -S imgui-sfml

Ubuntu 24.04+ / Debian 13+

sudo apt install build-essential cmake libsfml-dev libx11-dev libxext-dev
pkg-config --modversion sfml-graphics    # deve essere 3.x

ImGui-SFML non è impacchettato lì e deve essere compilato dal sorgente.

REQUIREMENTS.md copre il resto: compilare SFML 3 e ImGui-SFML dal sorgente, gli header del kernel per il modulo, Secure Boot, ptrace_scope, e come verificare una configurazione funzionante.

Testato su

CachyOS                kernel 7.1.2-3-cachyos, compilato con clang 22.1.6
KDE Plasma 6.7.2       sessione Wayland, overlay in esecuzione tramite XWayland
SFML 3.1.0             CMake 4.3.4, GCC 16.1.1
Intel UHD + RTX 4060   gioco sotto Proton, Windowed

Due parti di questo meritano di essere evidenziate, perché sono i casi scomodi:

• È una sessione Wayland. L'overlay non gira nativamente su Wayland e non ne ha bisogno: il gioco gira sotto XWayland e così anche l'overlay, e il click-through X11 e gli hotkey funzionano normalmente al suo interno. Se sei su Wayland, questa è la configurazione che funziona.
• Il kernel è compilato con clang, il che è insolito ed è ciò per cui esiste il rilevamento della toolchain del modulo. Su un kernel GCC il modulo prende l'altro ramo, che è il caso comune ma il meno testato qui.

Questa è la macchina di sviluppo, quindi è l'unica configurazione effettivamente verificata. Altre distribuzioni, desktop e kernel compilati con GCC dovrebbero funzionare e non sono testati.

Build

chmod +x build.sh run.sh   # un download zip rimuove il bit eseguibile
./build.sh                 # configura e compila
./build.sh clean           # da una directory di build pulita

Il binario viene scritto in build/TheFinals.

CMake memorizza il percorso sorgente assoluto nella sua cache, quindi una directory di build spostata o rinominata smette di funzionare. build.sh se ne accorge e riconfigura da solo, quindi spostare il progetto non è qualcosa a cui devi pensare.

Modulo kernel (opzionale, più furtivo)

kmod/ compila un piccolo modulo che rende lo strumento considerevolmente più silenzioso sul sistema. È del tutto opzionale: senza di esso tutto funziona comunque, usando i fallback in userspace indicati sotto.

• Le letture di memoria passano attraverso access_process_vm() nello spazio kernel, quindi ptrace_scope non si applica. Lo strumento non necessita di sudo, nulla deve agganciarsi al gioco, e yama non deve essere allentato per l'intero sistema.
• L'input del mouse viene iniettato nel puntatore reale invece che in un dispositivo virtuale uinput. Senza il modulo lo strumento deve crearne uno, e un dispositivo di input virtuale è enumerabile: appare in /proc/bus/input/devices per chiunque voglia guardare. Con il modulo non c'è alcun dispositivo extra.

cd kmod && make
sudo insmod suite_kmod.ko

Un modulo deve essere compilato con lo stesso compilatore del kernel in cui viene caricato. Il Makefile lo legge dalla configurazione del kernel stesso e imposta la toolchain da solo, quindi un semplice make è corretto sia su un kernel GCC che su uno clang:

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

Sovrascrivi con make LLVM=0 o make LLVM=1 se mai sbaglia. Se gli header del kernel mancano, lo segnala e stampa il comando di installazione per la tua distribuzione.

Con Secure Boot abilitato un modulo non firmato non verrà caricato: firmalo, disabilita Secure Boot, o semplicemente salta il modulo.

Caricalo prima di avviare lo strumento; il backend viene scelto una volta, all'avvio.

Conferma quale backend è attivo nel menu, o nel log:

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

Scarica con sudo rmmod suite_kmod.

Esecuzione

Imposta prima il gioco in modalità Windowed. In Fullscreen il gioco possiede il display completamente e nulla può disegnarci sopra, quindi l'overlay funzionerà correttamente e sarà comunque invisibile.

L'overlay trova la finestra del gioco e ne replica posizione e dimensione, ricontrollando man mano, quindi segue la finestra se la sposti o la ridimensioni, e si adatta a qualsiasi risoluzione.

./run.sh                # trova il PID del gioco da solo
./run.sh 12345          # oppure forniscine uno
./run.sh -q             # silenzioso: solo poche righe di stato

Avvialo quando vuoi, anche al menu. Ri-risolve i suoi oggetti quando una partita inizia o finisce, quindi non necessita di riavvio tra i round.

Controlli

Le impostazioni vengono modificate nel menu e salvate in settings.cfg quando lo strumento esce, quindi riparte come l'hai lasciato.

Funzionalità

ESP

Riquadri, scheletri, nomi, barre della salute, distanza e snapline. I colori della squadra distinguono le squadre, e un cursore master di opacità governa tutto ciò che viene disegnato.

Lo scheletro è composto dalla gerarchia di ossa della mesh stessa, quindi segue l'animazione piuttosto che approssimarla da una capsula.

Aim assist

Tira verso un bersaglio mentre il pulsante del mouse scelto è tenuto premuto.

• Selezione del bersaglio: un cursore di bias tra "più vicino a me" e "più vicino al mirino", così puoi prendere il giocatore dietro quello più vicino puntandolo.
• Smoothing: una modalità divisore e una modalità inerzia (EMA).
• Adesività: mantiene il bersaglio corrente a meno che uno sfidante non sia chiaramente migliore, invece di saltare tra due nemici ad angoli simili.
• Selezione dell'osso: testa, petto, corpo o gambe, mirato all'articolazione reale quando lo scheletro si risolve.
• Predizione: anticipa un bersaglio in movimento tramite la sua velocità. Senza questo l'aim trascina una testa in movimento di una quantità costante, perché la posizione che gli è stata data è già vecchia di un frame quando il mouse si muove.
• Quick scope: rilascia l'aim nell'istante in cui spari, così il rinculo di un cecchino è tuo da gestire piuttosto che qualcosa contro cui l'assist combatte. Si ri-arma alla successiva pressione di ADS, o dopo un ritardo se ne imposti uno. Richiede l'aim tenuto sul tasto destro del mouse, poiché il colpo deve essere un pulsante diverso dall'aim.

Triggerbot

Spara quando il mirino è sul bersaglio.

• Con l'aim assist attivo, spara solo quando il mirino ha raggiunto il punto esatto verso cui l'aim sta tirando.
• Da solo, funziona dallo scheletro (un osso scelto, o qualsiasi osso), o dal riquadro della capsula.
• La tolleranza scala con la dimensione del bersaglio sullo schermo, quindi un'unica impostazione si comporta allo stesso modo a bruciapelo e attraverso la mappa. Una tolleranza fissa in pixel non può: a distanza pochi pixel coprono un'intera testa, da vicino sono una scheggia di una.
• Ritardo di armamento (dopo che il pulsante viene premuto), ritardo di reazione (dopo che il mirino atterra), durata del clic e cooldown sono tutti regolabili.

Visibilità

I giocatori che non vengono attualmente disegnati dal gioco sono barrati e attenuati, e l'aim assist e il triggerbot possono ciascuno essere istruiti a ignorarli.

Questo è derivato dal timestamp di rendering del motore stesso, quindi è conservativo per natura: il gioco culla su un bounding box, che è più grande del giocatore, e le query di occlusione sono in ritardo di un frame o due. Aspettati che un nemico sia marcato visibile leggermente prima che superi completamente un angolo. Il cursore di tolleranza controlla quanto velocemente qualcuno esce dalla visibilità dopo aver perso la linea di vista.

Offset

Ogni indirizzo specifico del gioco vive in offsets.cfg, letto all'avvio dalla directory di lavoro o da un livello sopra di essa.

Lo strumento rifiuta di avviarsi senza di esso e nomina qualsiasi cosa mancante. Questo è deliberato: un offset che è silenziosamente zero produce uno schermo vuoto senza spiegazione, che è molto peggio da diagnosticare di un fallimento chiaro.

Un aggiornamento del gioco li sposta. Quando ciò accade lo strumento si avvia ma non trova nulla. Ri-deriva gli offset e copia il nuovo offsets.cfg qui. Non è necessaria alcuna ricompilazione.

Struttura

README.md             questo file
REQUIREMENTS.md       dipendenze e come installarle
LICENSE               GPL-2.0
build.sh              script di build
run.sh                launcher
banner.txt            banner di avvio
offsets.cfg           offset del gioco (richiesti)
CMakeLists.txt
src/
  main.cpp              punto di ingresso, finestra overlay, loop di rendering
  mem.hpp               letture di memoria del processo
  cheat.hpp             thread di lettura, elenco entità
  render.hpp            disegno ESP, aim assist, triggerbot, menu
  global.hpp            stato condiviso tra thread di lettura e rendering
  structs.hpp           tipi del motore e proiezione mondo-schermo
  skeleton.hpp          composizione della gerarchia di ossa
  settings.hpp          caricamento e salvataggio di settings.cfg
  vmouse.hpp            output del mouse
  offsets.hpp           costanti fisse del layout del motore
  runtime_offsets.hpp   caricatore di offsets.cfg
  gobjects_direct.hpp   decodifica dell'array di oggetti
kmod/
  suite_kmod.c          modulo kernel: letture di memoria e iniezione del mouse
  suite_kmod.h          contratto ioctl condiviso
  Makefile

settings.cfg viene creato la prima volta che lo strumento esce.

Risoluzione dei problemi

offsets.cfg not found: esegui dalla directory del progetto, o tieni il file accanto al binario.

offsets.cfg is present but incomplete: gli offset che nomina sono zero. Il gioco molto probabilmente è stato aggiornato; ri-derivali.

Non appare nulla sullo schermo, ma il log sembra sano: il gioco è probabilmente in Fullscreen, che non permette a nulla di disegnarci sopra. Passalo alla modalità Windowed. La riga di log game window at X,Y WxH - overlay will match conferma che l' overlay ha trovato e replicato la finestra.

L'overlay cattura i tuoi clic del mouse: libXext mancava quando hai compilato, quindi il click-through è escluso dalla compilazione. Il passo di configurazione avvisa di questo; cerca XShape click-through: enabled. Installa libxext/libxext-dev e ricompila.

Overlay nel posto sbagliato, o clic che non passano: l'overlay necessita di X11. Sotto Wayland, forza XWayland:

DISPLAY=:0 WAYLAND_DISPLAY= ./run.sh

Gioco non trovato: passa il PID direttamente. Sotto Proton il processo è Discovery-d.exe e il thread corretto è GameThread.

Nulla viene disegnato durante una partita: gli offset sono obsoleti dopo un aggiornamento del gioco.

L'aim assist non fa nulla: controlla che il menu riporti un backend del mouse. Se "visible only" è abilitato e ogni nemico è dietro copertura, deliberatamente non c'è bersaglio.

Il modulo kernel non si compila: deve essere compilato con la stessa toolchain del tuo kernel in esecuzione. Su un kernel compilato con clang: make LLVM=1.

Una nota sul rischio

Questo legge la memoria di un altro processo e inietta input del mouse. Non modifica il gioco, ma usarlo in una partita online viola i termini di servizio del gioco e può costarti l'account. È una tua decisione; prendila consapevolmente.

Licenza

GNU General Public License, versione 2. Vedi LICENSE.

Puoi usare, studiare, modificare e ridistribuire questo. Se distribuisci una versione modificata devi fornire il suo sorgente sotto la stessa licenza, così chiunque lo riceva mantiene le stesse libertà. Non c'è garanzia.

GPLv2 piuttosto che v3 deliberatamente: il modulo kernel in kmod/ è un modulo kernel Linux, il kernel è solo GPL-2.0, e MODULE_LICENSE("GPL") significa versione 2. Licenziare l'intero progetto allo stesso modo mantiene lo strumento userspace e il modulo compatibili tra loro e con il kernel, senza alcuna divisione di cui preoccuparsi.

Copyright © 2026 Ymsniper.