Wprowadzenie do skryptów Lua dla FiveM

Zasoby FiveM mogą używać CfxLua, zmodyfikowanego środowiska uruchomieniowego Lua 5.4, do skryptów klienckich i serwerowych. Obecny zasób zaczyna się od fxmanifest.lua, wymienia pliki, które każdy kontekst ładuje, i przechowuje autorytatywne decyzje, takie jak uprawnienia, pieniądze i ekwipunek na serwerze.

Utwórz minimalny zasób

Wewnątrz swojego server-data resources katalog, utwórz [local]/hello_fivem. Nawiasy grupują zasoby; sam zasób to hello_fivem katalogu.

fxmanifest.lua:

fx_version 'cerulean'
game 'gta5'

author 'Your name'
description 'Small CfxLua learning resource'
version '1.0.0'

client_script 'client.lua'
server_script 'server.lua'

client.lua:

RegisterCommand('mycoords', function()
    local coords = GetEntityCoords(PlayerPedId())
    print(('x=%.2f y=%.2f z=%.2f'):format(coords.x, coords.y, coords.z))
end, false)

server.lua:

AddEventHandler('onResourceStart', function(resourceName)
    if resourceName ~= GetCurrentResourceName() then
        return
    end

    print(('[%s] started'):format(resourceName))
end)

Manifest i zachowanie w czasie rzeczywistym są udokumentowane w oficjalnym referencje manifestu zasobu I przewodniku CfxLua.

Zrozum konteksty klienta i serwera

Skrypt klienta działa oddzielnie dla każdego połączonego gracza i może wywoływać natywne funkcje gry, takie jak PlayerPedId I GetEntityCoords. Skrypt serwera koordynuje wspólny stan, trwałość i autoryzację. Wartości dostarczone przez klienta są danymi wejściowymi, a nie dowodem.

Używać AddEventHandler dla zdarzeń, które powinny pozostać w jednym kontekście. Używaj RegisterNetEvent tylko wtedy, gdy zdarzenie musi przekroczyć granicę klienta/serwera. Oficjalny Przewodnik Bezpieczeństwo Zdarzeń wyjaśnia, dlaczego każda akcja sieciowa musi weryfikować bieżące uprawnienia i stan gracza po stronie serwera.

Unikaj blokowania harmonogramu

Skrypty CfxLua są planowane w sposób kooperacyjny. Pętla, która nigdy nie ustępuje, może zamrozić swój kontekst skryptu. Kiedy pętla musi czekać, użyj Wait z opóźnieniem odpowiednim do zadania i nie odpytuj bazy danych ani punktu końcowego HTTP co klatkę. Preferuj zdarzenia i zmiany stanu zamiast stałego odpytywania.

Używaj eksportów dla jasnej granicy zasobu

Eksport udostępnia nazwaną funkcję innemu zasobowi. Zdefiniuj ją jawnie i udokumentuj jej argumenty oraz wartość zwracaną:

exports('formatPlayerLabel', function(serverId, playerName)
    return ('[%d] %s'):format(serverId, playerName)
end)

Inny zasób Lua może ją wywołać jako exports.hello_fivem:formatPlayerLabel(id, name). Nie używaj eksportu do omijania kontroli uprawnień lub własności.

Uruchom i przetestuj zasób

1. Utwórz kopię zapasową zasobu, który zastępujesz, jeśli istnieje.
2. W konsoli serwera uruchom refresh a następnie ensure hello_fivem.
3. Sprawdź konsolę serwera pod kątem komunikatu o uruchomieniu.
4. Połącz się z serwerem deweloperskim, otwórz F8 i uruchom mycoords.
5. Uruchom ponownie serwer, aby potwierdzić, że zasób jest uwzględniony w normalnej kolejności uruchamiania.

Obsługiwane polecenia zasobów są wymienione w oficjalnym odniesieniu do poleceń serwera. Kontynuuj z oficjalnym pierwszym samouczkiem skryptu Lua przed dodaniem zależności frameworka lub bazy danych.