Tworzenie Własnego Licznika Prędkości w FiveM: Przewodnik po Skryptach Lua

Odkryj, jak za pomocą prostego skryptu Lua dodać funkcjonalny licznik prędkości do swojego serwera FiveM.

Najważniejsze Informacje

Podstawy Skryptowania Lua: Zrozumiesz kluczowe elementy skryptu Lua dla FiveM, w tym pętle, wątki i natywne funkcje GTA V/FiveM do pobierania danych o pojeździe.
Wyświetlanie Prędkości: Nauczysz się, jak pobrać prędkość pojazdu, przeliczyć ją na KM/H lub MPH i wyświetlić na ekranie gracza przy użyciu prostych funkcji tekstowych.
Rozszerzalność: Dowiesz się, jak rozbudować podstawowy skrypt o dodatkowe funkcje, takie jak wskaźnik paliwa, obrotomierz (RPM) czy zaawansowany interfejs użytkownika (NUI).

Wprowadzenie do Skryptów Lua w FiveM

Dlaczego potrzebujesz licznika prędkości?

FiveM, popularna modyfikacja do Grand Theft Auto V, pozwala na tworzenie niestandardowych serwerów multiplayer z własnymi zasadami i funkcjami. Jednym z najczęściej dodawanych elementów, szczególnie na serwerach RolePlay (RP), jest licznik prędkości (speedometer). Wyświetla on aktualną prędkość pojazdu, w którym znajduje się gracz, co zwiększa immersję i realizm rozgrywki.

Skrypty w FiveM tworzy się głównie w języku Lua. Jest to lekki i wydajny język skryptowy, idealny do dodawania niestandardowych funkcjonalności. Poniżej znajdziesz szczegółowy przykład prostego skryptu Lua, który implementuje podstawowy licznik prędkości, wraz z wyjaśnieniem jego działania i możliwościami rozbudowy.

Przykład interfejsu HUD z licznikiem prędkości w FiveM

Przykładowy, bardziej rozbudowany interfejs HUD (Heads-Up Display) w FiveM, zawierający licznik prędkości.

Podstawowy Skrypt Licznika Prędkości (Lua)

Krok po kroku: Tworzenie Twojego pierwszego licznika

Aby Twój skrypt działał w FiveM, potrzebujesz dwóch głównych plików: manifestu zasobu (fxmanifest.lua lub __resource.lua) oraz pliku z logiką skryptu po stronie klienta (client.lua).

Plik Manifestu (`fxmanifest.lua`)

Ten plik informuje FiveM o Twoim zasobie, jego zależnościach i plikach skryptowych. Utwórz plik fxmanifest.lua w folderze swojego zasobu (np. my_speedometer) i wklej poniższy kod:


-- Definiuje wersję manifestu (zalecana 'cerulean' lub nowsza)
fx_version 'cerulean'
-- Określa grę, dla której jest zasób
game 'gta5'

-- Informuje, że zasób jest tylko po stronie klienta
client_only 'yes' -- Można pominąć, jeśli planujesz logikę serwerową

-- Wskazuje plik(i) skryptu klienta do załadowania
client_scripts {
    'client.lua'
}

-- Opcjonalnie: Możesz dodać opis i wersję
description 'Prosty licznik prędkości dla FiveM'
version '1.0.0'

Uwaga: Starsze serwery mogą używać __resource.lua i starszej wersji manifestu (44febabe-d386-4d18-afbe-5e627f4af937). Format fxmanifest.lua jest nowszy i zalecany.

Plik Skryptu Klienckiego (`client.lua`)

To serce naszego licznika. Tutaj znajduje się logika pobierania prędkości i wyświetlania jej na ekranie. Utwórz plik client.lua w tym samym folderze co manifest i wklej poniższy kod:


-- Plik: client.lua
-- Prosty skrypt licznika prędkości dla FiveM

-- Ustawienie: Czy wyświetlać w KM/H (true) czy MPH (false)
local useKmh = true 
-- Ustawienie: Pozycja tekstu na ekranie (X, Y - od 0.0 do 1.0)
local textPositionX = 0.85
local textPositionY = 0.95

-- Tworzenie nowego wątku, aby skrypt działał w tle
Citizen.CreateThread(function()
    -- Nieskończona pętla, która będzie działać cały czas
    while true do
        -- Czekaj minimalny czas (0 ms) przed kolejną iteracją.
        -- WAŻNE: Zapobiega zamrożeniu gry i nadmiernemu użyciu CPU.
        Citizen.Wait(0) 

        -- Pobierz identyfikator (Ped) lokalnego gracza
        local playerPed = PlayerPedId() 

        -- Sprawdź, czy gracz siedzi w jakimkolwiek pojeździe
        if IsPedInAnyVehicle(playerPed, false) then
            -- Pobierz identyfikator (uchwyt) pojazdu, w którym jest gracz
            local vehicle = GetVehiclePedIsIn(playerPed, false)

            -- Sprawdź, czy pojazd faktycznie istnieje w świecie gry i nie jest zniszczony
            if DoesEntityExist(vehicle) and not IsEntityDead(vehicle) then
                -- Pobierz prędkość pojazdu. Zwracana jest w metrach na sekundę (m/s).
                local velocity = GetEntitySpeed(vehicle)
                
                -- Przelicz prędkość na wybraną jednostkę
                local speed
                local unitText
                if useKmh then
                    speed = velocity * 3.6 -- Przelicznik m/s na km/h
                    unitText = "KM/H"
                else
                    speed = velocity * 2.2369 -- Przelicznik m/s na mph
                    unitText = "MPH"
                end

                -- Zaokrąglij prędkość do najbliższej liczby całkowitej
                local speedToDisplay = math.floor(speed + 0.5) -- Używamy math.floor(x + 0.5) do poprawnego zaokrąglenia

                -- === Wyświetlanie tekstu na ekranie ===
                -- Używamy natywnych funkcji GTA V do rysowania tekstu
                
                -- Ustawienia czcionki i wyglądu
                SetTextFont(4) -- Wybór czcionki (0-7)
                SetTextScale(0.5, 0.5) -- Rozmiar tekstu (szerokość, wysokość)
                SetTextColour(255, 255, 255, 255) -- Kolor tekstu (R, G, B, Alpha) - biały
                SetTextOutline() -- Dodaj obrys do tekstu dla lepszej czytelności
                -- SetTextDropShadow() -- Opcjonalnie: dodaj cień
                
                -- Przygotowanie tekstu do wyświetlenia
                SetTextEntry("STRING") -- Informuje grę, że będziemy dodawać tekst
                -- Dodaj tekst do bufora. Używamy operatora konkatenacji '..' do połączenia stringów i liczby.
                AddTextComponentString("Prędkość: " .. speedToDisplay .. " " .. unitText) 
                
                -- Narysuj przygotowany tekst na ekranie w określonej pozycji (X, Y)
                DrawText(textPositionX, textPositionY) 
            end
        else
            -- Jeśli gracz nie jest w pojeździe, czekaj dłużej (np. 500 ms),
            -- aby niepotrzebnie nie sprawdzać co klatkę. Optymalizacja.
             Citizen.Wait(500) 
        end
    end
end)

-- Opcjonalnie: Dodanie komendy do przełączania jednostek
RegisterCommand("togglespeedunit", function()
    useKmh = not useKmh
    local currentUnit = "KM/H"
    if not useKmh then
        currentUnit = "MPH"
    end
    -- Wyświetl powiadomienie w grze (wymaga zasobu z powiadomieniami, np. es_extended lub qb-core, lub użyj print)
    print("Jednostka prędkości zmieniona na: " .. currentUnit) 
    -- TriggerEvent('chat:addMessage', { args = { 'System', 'Jednostka prędkości zmieniona na: ' .. currentUnit } }) -- Przykład dla starszych chatów
end, false) -- false oznacza, że komenda nie jest dostępna dla innych graczy (tylko lokalnie)

Wyjaśnienie Kluczowych Funkcji (`client.lua`):

Citizen.CreateThread(function() ... end): Tworzy osobny wątek dla skryptu, zapobiegając blokowaniu głównego wątku gry.
while true do ... Citizen.Wait(X) ... end: Standardowa pętla w skryptach FiveM. Citizen.Wait(0) oznacza minimalne opóźnienie (wykonanie co klatkę), a Citizen.Wait(500) to półsekundowe opóźnienie dla optymalizacji, gdy gracz nie jest w pojeździe.
PlayerPedId(): Zwraca identyfikator postaci gracza.
IsPedInAnyVehicle(ped, includeEntering): Sprawdza, czy postać jest w pojeździe.
GetVehiclePedIsIn(ped, lastVehicle): Zwraca identyfikator pojazdu, w którym jest postać.
DoesEntityExist(entity) / IsEntityDead(entity): Sprawdzają, czy dany obiekt (np. pojazd) istnieje i nie jest zniszczony.
GetEntitySpeed(entity): Zwraca prędkość obiektu w metrach na sekundę (m/s).
math.floor(x + 0.5): Poprawny sposób na zaokrąglenie liczby do najbliższej całkowitej w Lua.
SetText...() / AddTextComponentString() / DrawText(x, y): Natywne funkcje GTA V służące do rysowania tekstu na ekranie. Współrzędne X i Y są znormalizowane (od 0.0 do 1.0), gdzie (0.0, 0.0) to lewy górny róg, a (1.0, 1.0) to prawy dolny róg.
RegisterCommand('nazwa', funkcja, restricted): Rejestruje komendę czatu, którą gracz może wpisać (np. /togglespeedunit).

Instalacja Skryptu na Serwerze FiveM

Jak uruchomić Twój nowy licznik?

Stwórz Folder Zasobu: W katalogu resources Twojego serwera FiveM utwórz nowy folder, np. [scripts]/my_speedometer (użycie nawiasów kwadratowych pomaga w organizacji).
Utwórz Pliki: Wewnątrz folderu my_speedometer stwórz dwa pliki: fxmanifest.lua i client.lua.
Wklej Kody: Skopiuj i wklej odpowiednie kody (podane powyżej) do tych plików.
Dodaj do Konfiguracji Serwera: Otwórz plik server.cfg (lub inny główny plik konfiguracyjny serwera, np. resources.cfg) i dodaj linię, która uruchomi Twój zasób:
```
ensure my_speedometer
```
Upewnij się, że nazwa (my_speedometer) jest taka sama jak nazwa folderu, który utworzyłeś. Umieść tę linię razem z innymi zasobami (ensure nazwa_zasobu).
Zrestartuj Serwer: Zrestartuj swój serwer FiveM, aby zmiany zostały załadowane.
Testuj w Grze: Wejdź na serwer i wsiądź do dowolnego pojazdu. W prawym dolnym rogu ekranu (lub w miejscu zdefiniowanym przez textPositionX, textPositionY) powinien pojawić się tekst z aktualną prędkością. Możesz też wpisać /togglespeedunit w czacie, aby zmienić jednostkę.

Porównanie Metod Wyświetlania Licznika

Tekst vs. Interfejs Graficzny (NUI)

Podstawowy skrypt wykorzystuje natywne funkcje do rysowania tekstu. Jest to najprostsze i często wystarczające rozwiązanie. Jednak bardziej zaawansowane liczniki używają technologii NUI (Native UI), która pozwala na tworzenie interfejsów za pomocą HTML, CSS i JavaScript. Poniższy wykres radarowy porównuje te podejścia.

Jak widać na wykresie, proste wyświetlanie tekstu jest najłatwiejsze do zaimplementowania i zazwyczaj bardzo wydajne. Jednak NUI oferuje znacznie większe możliwości konfiguracji wyglądu, estetyki oraz integracji wielu funkcji w jednym, spójnym interfejsie (np. prędkość, paliwo, mapa, status postaci). Wybór zależy od potrzeb Twojego serwera i umiejętności.

Mapa Myśli: Komponenty Skryptu Licznika Prędkości

Struktura i możliwości rozbudowy

Poniższa mapa myśli wizualizuje kluczowe elementy tworzenia i rozwijania skryptu licznika prędkości w FiveM przy użyciu Lua.

mindmap root["Licznik Prędkości FiveM (Lua)"] id1["Podstawy Skryptu"] id1a["Manifest (fxmanifest.lua)
Definicja zasobu"] id1b["Wątek Klienta (Citizen.CreateThread)
Asynchroniczne działanie"] id1c["Główna Pętla (while true do)
Ciągłe sprawdzanie"] id1d["Optymalizacja (Citizen.Wait)
Zapobieganie obciążeniu CPU"] id1e["Natywne Funkcje GTA V/FiveM
Interakcja ze światem gry"] id2["Funkcje Podstawowe"] id2a["Pobieranie ID Gracza (PlayerPedId)"] id2b["Sprawdzanie Stanu Gracza (IsPedInAnyVehicle)"] id2c["Pobieranie ID Pojazdu (GetVehiclePedIsIn)"] id2d["Pobieranie Prędkości (GetEntitySpeed)
Wartość w m/s"] id2e["Konwersja Jednostek
KM/H (metry/sek * 3.6)
MPH (metry/sek * 2.2369)"] id2f["Wyświetlanie Tekstu (DrawText)
Prosty interfejs"] id3["Możliwości Rozszerzenia"] id3a["Przełączanie Jednostek (KM/H / MPH)
Komenda lub klawisz"] id3b["Wskaźnik Paliwa (GetVehicleFuelLevel)"] id3c["Obrotomierz (RPM - GetVehicleCurrentRPM)"] id3d["Wskaźnik Biegów (GetVehicleCurrentGear)"] id3e["Stan Silnika (GetVehicleEngineHealth)"] id3f["Pasy Bezpieczeństwa"] id3g["Tempomat (Cruise Control)"] id3h["Kierunkowskazy / Światła"] id3i["Interfejs Graficzny (NUI)
HTML, CSS, JavaScript
Bardziej estetyczny wygląd"] id4["Instalacja"] id4a["Struktura Folderów (resources/nazwa_zasobu)"] id4b["Pliki (fxmanifest.lua, client.lua)"] id4c["Konfiguracja Serwera (server.cfg)
Komenda 'ensure nazwa_zasobu'"]

Mapa myśli pokazuje, że zaczynając od prostego skryptu, masz szerokie możliwości jego rozbudowy. Możesz dodawać kolejne wskaźniki (paliwo, RPM, biegi) lub całkowicie zmienić sposób prezentacji danych, wykorzystując NUI do stworzenia unikalnego HUD-a dla Twojego serwera.

Zaawansowane Możliwości: Interfejs Graficzny NUI

Tworzenie wizualnie atrakcyjnych liczników

Chociaż nasz podstawowy skrypt używa prostego tekstu, wiele popularnych liczników prędkości w FiveM wykorzystuje NUI (Native UI). Pozwala to deweloperom na tworzenie interfejsów użytkownika za pomocą technologii webowych: HTML do struktury, CSS do stylizacji i JavaScript do dynamicznej interakcji.

Przykład licznika prędkości stworzonego przy użyciu NUI

Przykład bardziej złożonego HUD-a wykorzystującego NUI (HTML/CSS/JS) do wyświetlania prędkości, mapy i statusu gracza.

Jak działa NUI?

Struktura HTML: Tworzysz plik HTML (np. html/index.html), który definiuje strukturę Twojego licznika (np. divy na prędkość, paliwo, RPM).
Stylizacja CSS: Używasz CSS (np. html/style.css) do nadania wyglądu elementom HTML (kolory, czcionki, pozycjonowanie, animacje).
Logika JavaScript: W pliku JavaScript (np. html/script.js) odbierasz dane wysłane z Twojego skryptu Lua (np. aktualną prędkość) i aktualizujesz odpowiednie elementy HTML na stronie.
Komunikacja Lua ↔ NUI: Twój skrypt Lua (client.lua) nadal pobiera dane (prędkość, paliwo itp.), ale zamiast rysować tekst za pomocą DrawText, wysyła te dane do interfejsu NUI za pomocą funkcji SendNUIMessage. JavaScript w NUI nasłuchuje na te wiadomości i aktualizuje interfejs.
Manifest: Musisz zadeklarować pliki NUI w fxmanifest.lua za pomocą dyrektywy ui_page i files.

Tworzenie interfejsów NUI jest bardziej złożone niż używanie DrawText, ale daje niemal nieograniczone możliwości w projektowaniu wyglądu i funkcjonalności Twojego HUD-a. Wiele gotowych skryptów dostępnych na forach FiveM lub GitHub wykorzystuje właśnie NUI.

Tabela Porównawcza: Tekst vs NUI

Kluczowe różnice w podejściach

Poniższa tabela podsumowuje główne różnice między tworzeniem licznika prędkości za pomocą natywnych funkcji tekstowych Lua a wykorzystaniem interfejsu NUI.

Cecha	Podstawowy Tekst (Lua Natives)	Zaawansowany NUI (HTML/CSS/JS)
Wygląd	Prosty tekst, ograniczone opcje formatowania (czcionka, kolor, rozmiar, obrys).	Pełna kontrola nad wyglądem (obrazy, ikony, niestandardowe czcionki, animacje, układy).
Wydajność	Zazwyczaj bardzo wysoka, minimalne obciążenie.	Może być nieco niższa, zależna od złożoności interfejsu i optymalizacji kodu JS/CSS. Nieprawidłowo napisany NUI może obciążać klienta.
Łatwość Implementacji	Bardzo łatwa, wymaga znajomości tylko podstaw Lua i natywnych funkcji FiveM.	Znacznie trudniejsza, wymaga znajomości HTML, CSS, JavaScript oraz mechanizmów komunikacji Lua ↔ NUI.
Możliwości Konfiguracji	Ograniczone do zmiany tekstu, pozycji, koloru, jednostki.	Bardzo duże: zmiana motywów, ukrywanie/pokazywanie elementów, dynamiczne style, konfiguracja przez użytkownika.
Dodatkowe Funkcje	Możliwe do dodania (paliwo, RPM), ale wyświetlane jako osobne linie tekstu.	Łatwa integracja wielu wskaźników (prędkość, paliwo, RPM, mapa, status postaci, pasy, światła) w jednym spójnym i graficznym interfejsie.

Wideo Tutorial: Tworzenie Licznika

Zobacz, jak to zrobić krok po kroku

Poniższy film (w języku angielskim) pokazuje proces tworzenia prostego licznika prędkości w FiveM przy użyciu Lua. Może on stanowić dobre uzupełnienie przedstawionego kodu i wyjaśnień, wizualizując niektóre kroki i koncepcje.

Film instruktażowy pokazujący tworzenie skryptu licznika prędkości w FiveM.

Najczęściej Zadawane Pytania (FAQ)

Odpowiedzi na popularne wątpliwości

Jak zmienić jednostkę z KM/H na MPH w podstawowym skrypcie? +

W dostarczonym podstawowym skrypcie client.lua znajdź linię:

local useKmh = true

Zmień wartość true na false:

local useKmh = false

Alternatywnie, możesz użyć komendy /togglespeedunit w grze (jeśli została dodana do skryptu), aby dynamicznie przełączać jednostki.

Jak zmienić pozycję tekstu prędkości na ekranie? +

W skrypcie `client.lua` znajdź linie definiujące pozycję X i Y:

local textPositionX = 0.85
local textPositionY = 0.95

Zmień wartości `0.85` (oś X, pozioma) i `0.95` (oś Y, pionowa), aby przesunąć tekst. Wartości mieszczą się w zakresie od 0.0 do 1.0. Na przykład, (0.5, 0.5) umieści tekst na środku ekranu, a (0.01, 0.95) w lewym dolnym rogu.

Czy ten prosty skrypt obciąża serwer? Jak go zoptymalizować? +

Podstawowy skrypt jest bardzo lekki i działa tylko po stronie klienta, więc nie obciąża bezpośrednio serwera. Obciążenie po stronie klienta (gracza) jest minimalne dzięki użyciu `Citizen.Wait(0)` w pętli i dłuższego `Citizen.Wait(500)`, gdy gracz nie jest w pojeździe.

Dalsze optymalizacje mogłyby obejmować:

Zwiększenie czasu oczekiwania w głównej pętli (np. `Citizen.Wait(100)` zamiast `Citizen.Wait(0)`), co zmniejszy częstotliwość aktualizacji, ale może sprawić, że licznik będzie mniej płynny.
Dodanie warunku sprawdzającego, czy prędkość faktycznie się zmieniła przed aktualizacją tekstu (choć przy tak prostym skrypcie zysk wydajności będzie znikomy).
Unikanie skomplikowanych obliczeń lub wywołań funkcji wewnątrz pętli, jeśli nie są konieczne w każdej klatce.

W praktyce, dla tak prostego skryptu, domyślne optymalizacje (użycie `Citizen.Wait`) są w zupełności wystarczające.

Jak dodać wskaźnik paliwa lub RPM do podstawowego skryptu? +

Aby dodać wskaźnik paliwa lub RPM, musisz zmodyfikować pętlę w `client.lua`:

Pobierz dane: Wewnątrz warunku `if DoesEntityExist(vehicle)...` dodaj linie pobierające poziom paliwa i RPM:

local fuelLevel = GetVehicleFuelLevel(vehicle) -- Zwraca poziom paliwa (liczba zmiennoprzecinkowa)
local rpm = GetVehicleCurrentRpm(vehicle) -- Zwraca RPM jako ułamek (0.0 do 1.0+)

Przygotuj tekst: Zmodyfikuj linię `AddTextComponentString`, aby zawierała nowe informacje. Możesz wyświetlić je w tej samej linii lub w osobnych:

-- Przykład: wszystko w jednej linii
AddTextComponentString(string.format("Prędkość: %d %s | Paliwo: %.0f%% | RPM: %.2f", speedToDisplay, unitText, fuelLevel, rpm * 100)) 

-- Przykład: w osobnych liniach (trzeba dodać drugi DrawText z inną pozycją Y)
-- DrawText 1:
AddTextComponentString("Prędkość: " .. speedToDisplay .. " " .. unitText)
DrawText(textPositionX, textPositionY)
-- DrawText 2:
SetTextEntry("STRING")
AddTextComponentString(string.format("Paliwo: %.0f%% | RPM: %.2f", fuelLevel, rpm * 100))
DrawText(textPositionX, textPositionY + 0.03) -- Przesunięcie w dół

Pamiętaj, że `GetVehicleCurrentRpm` zwraca wartość znormalizowaną (często 0.0-1.0), więc możesz ją pomnożyć przez odpowiedni czynnik (np. 100 lub 10000), aby uzyskać bardziej czytelną wartość. Formatowanie tekstu za pomocą `string.format` jest często wygodniejsze przy wielu zmiennych.

Czy mogę użyć HTML/CSS do stworzenia ładniejszego licznika? +

Tak, jest to możliwe i bardzo popularne w FiveM. Wykorzystuje się do tego mechanizm NUI (Native UI). Wymaga to stworzenia plików HTML, CSS i JavaScript, które będą definiować wygląd i zachowanie licznika. Skrypt Lua (`client.lua`) będzie wtedy odpowiedzialny za pobieranie danych (prędkość, paliwo itp.) i wysyłanie ich do interfejsu NUI za pomocą funkcji `SendNUIMessage`. JavaScript w plikach NUI odbierze te dane i zaktualizuje odpowiednie elementy na ekranie.

Jest to bardziej zaawansowane podejście, ale daje znacznie większe możliwości personalizacji wyglądu. Wiele gotowych, darmowych i płatnych skryptów HUD/liczników dostępnych w społeczności FiveM wykorzystuje właśnie NUI.