Introductie tot Lua Scripting voor FiveM

FiveM bronnen kunnen CfxLua gebruiken, een aangepaste Lua 5.4 runtime, voor client- en serverscripts. Een huidige bron begint met fxmanifest.lua, geeft de bestanden weer die elke context laadt, en bewaart gezaghebbende beslissingen zoals permissies, geld en inventaris op de server.

Maak een minimale bron

Binnen je server-data resources directory, maak [local]/hello_fivem. De haakjes groeperen bronnen; de bron zelf is de hello_fivem directory.

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)

Het manifest en het runtimegedrag worden gedocumenteerd in de officiële resource manifest reference En CfxLua gids.

Begrijp client- en servercontexten

Een client-script draait apart voor elke verbonden speler en kan game-gerichte natives aanroepen zoals PlayerPedId En GetEntityCoords. Een server-script coördineert gedeelde staat, persistentie en autorisatie. Waarden die door een client worden geleverd, zijn invoer, geen bewijs.

Gebruik AddEventHandler voor gebeurtenissen die in één context moeten blijven. Gebruik RegisterNetEvent alleen wanneer een gebeurtenis de client/server-grens moet overschrijden. De officiële Beveilig je gebeurtenissen-gids legt uit waarom elke netwerkactie de huidige server-side toestemming en staat van de speler moet valideren.

Vermijd het blokkeren van de scheduler

CfxLua scripts worden coöperatief gepland. Een lus die nooit toegeeft, kan de scriptcontext bevriezen. Wanneer een lus moet wachten, gebruik dan Wait met een vertraging die past bij de taak, en poll niet elke frame een database of HTTP-endpoint. Geef de voorkeur aan events en statuswijzigingen boven permanente polling.

Gebruik exports voor een duidelijke resource-grens

Een export stelt een benoemde functie beschikbaar aan een andere resource. Definieer deze expliciet en documenteer de argumenten en retourwaarde:

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

Een andere Lua resource kan deze aanroepen als exports.hello_fivem:formatPlayerLabel(id, name). Gebruik een export niet om permissie- of eigendomscontroles te omzeilen.

Voer de resource uit en test deze

1. Maak een back-up van de resource die je vervangt, indien van toepassing.
2. Voer in de serverconsole uit refresh en dan ensure hello_fivem.
3. Controleer de serverconsole op het startbericht.
4. Maak verbinding met de ontwikkelserver, open F8 en voer uit mycoords.
5. Herstart de server om te bevestigen dat de resource is opgenomen in de normale opstartvolgorde.

De ondersteunde resourcecommando's worden vermeld in de officiële server-command referentie. Ga verder met de officiële eerste Lua script tutorial voordat je framework- of databaseafhankelijkheden toevoegt.