Goal: Create a script that displays a welcome message to each player when they join your FiveM server.
Prerequisites:
A working FiveM server
You need a server already set up and running. If you don’t have one, you’ll need to set that up first. This tutorial won’t cover server setup. Search for “FiveM server setup” for guidance.
A text editor
A code editor like Visual Studio Code (VS Code, highly recommended), Notepad++, or Sublime Text is strongly recommended. Regular Notepad (on Windows) can work, but it lacks features that make coding much easier. We’ll use terminology consistent with VS Code.
Basic File understanding
How create folders, how to create files.
Steps:.
Navigate to your Server's Resources Folder
Open the folder where your FiveM server is installed.
Inside that folder, find the server-data folder (this is the main data folder for your server, and its name might be different if you customized it during setup. If you have trouble, look for a folder containing server.cfg).
Inside server-data, locate the resources folder. This is where all your server’s scripts (resources) will go.
Create a New Resource Folder
Inside the resources folder, create a new folder. The name of this folder is important, as it will be the name of your resource. Let’s name it [local] for now.
Inside [local] folder create another folder. Let’s name this welcome-message. This is to organize better your resources.Good practice: Resource folder names should be lowercase and use hyphens (-) instead of spaces.
Create the __resource.lua File
Inside the welcome-message folder, create a new file named __resource.lua. The double underscores (__) are essential. This file tells FiveM about your resource.
Open __resource.lua in your text editor.
Write the Resource Manifest
This file tells FiveM what files your resource uses and other important information. Paste the following code into __resource.lua and save the file:
resource_manifest_version ’44febabe-d386-4d18-afbe-5e627f4af937′
client_script ‘client.lua’
server_script ‘server.lua’
resource_manifest_version: This line specifies the version of the resource manifest. The specific GUID (’44febabe-d386-4d18-afbe-5e627f4af937′) is a standard version and should generally be left as is. Newer versions exist, but this one is widely compatible.
client_script ‘client.lua’: This line tells FiveM that your resource has a client-side script named client.lua. Client scripts run on each player’s computer.
server_script ‘server.lua’: This line tells FiveM your script has a server side named ‘server.lua’. Server scripts run on your server computer.
Create the client.lua File
Inside the welcome-message folder (same place as __resource.lua), create a new file named client.lua.
Open client.lua in your text editor.
Write the Client-Side Script (in client.lua)
This script will handle displaying the welcome message on the player’s screen.
Paste the following code into client.lua and save:
Citizen.CreateThread(function()
while true do
Citizen.Wait(0)
if NetworkIsPlayerActive(PlayerId()) then
TriggerServerEvent(‘welcomeMessage:showWelcome’)
break
end
end
end)
Citizen.CreateThread(function() … end): This creates a new “thread.” Think of a thread as a separate part of your script that can run independently. FiveM uses threads extensively. Everything inside this function() … end block will be part of that thread.
while true do … end: This creates an infinite loop. The code inside this loop will keep running forever (or until the resource is stopped).
Citizen.Wait(0): This is crucial. It tells the thread to pause for a very short time (0 milliseconds). Without this, your loop would consume 100% of the CPU, causing massive lag and potentially crashing the server. Always include Citizen.Wait() in your loops.
if NetworkIsPlayerActive(PlayerId()) then … end: This checks if the player is fully connected to the server. PlayerId() gets the player’s unique ID. We only want to show the welcome message after the player has connected.
TriggerServerEvent(‘welcomeMessage:showWelcome’): This is how the client script communicates with server script. We will call server to show the message to client.
break: This exits the while loop. We only need to trigger the welcome message once per player.
Create the server.lua File
Inside the welcome-message folder (same place as __resource.lua), create a new file named server.lua.
Open server.lua in your text editor.
Write the Server-Side Script (in server.lua)
RegisterServerEvent(‘welcomeMessage:showWelcome’) AddEventHandler(‘welcomeMessage:showWelcome’, function()
local _source = source
TriggerClientEvent(‘chat:addMessage’, _source, {
color = {255, 255, 255},
multiline = true,
args = {“Server”, “Welcome to the server!”}
})
end)
RegisterServerEvent(‘welcomeMessage:showWelcome’): This is used to register the event, and to the server knows that event exists.
AddEventHandler(‘welcomeMessage:showWelcome’, function() … end): This is a fundamental part of FiveM scripting. It defines an event handler.
‘welcomeMessage:showWelcome’: This is the name of the event. It must match the name used in TriggerServerEvent in the client script. The colon (:) is a common convention for separating parts of an event name, but it’s not strictly required.
function() … end: This is the code that will be executed when the welcomeMessage:showWelcome event is triggered.
local _source = source: The source variable (automatically provided by FiveM) represents the player who triggered the event. We store it in a local variable _source. It’s good practice to use _source instead of source directly within event handlers.
TriggerClientEvent(‘chat:addMessage’, _source, { … }): This is the core of the welcome message. It uses FiveM’s built-in chat system.
* ‘chat:addMessage’: This is a built-in FiveM event that adds a message to the chat.
* _source: This specifies which player will receive the message (the player who connected).
* { … }: This is a Lua table containing the message details.color = {255, 255, 255}: This sets the text color to white (RGB values).
multiline = true: This allows the message to span multiple lines (if needed).
args = {“Server”, “Welcome to the server!”}: This is the most important part. It defines the actual message. The first element (“Server”) is the “sender” of the message (it will appear in the chat before the message). The second element (“Welcome to the server!”) is the message itself.
Add the Resource to Your server.cfg
Go back to your server-data folder (the one containing the resources folder).
Open the server.cfg file in your text editor.
Find a section where other resources are started. It will likely have lines like ensure mapmanager, ensure chat, etc.
Add the following line to start your new resource:
ensure welcome-message
Important: The resource name here (welcome-message) must match the name of the folder you created in step 2. Use ensure and not start.
Restart Your FiveM Server
Restart your FiveM server completely. This is necessary for the server to load the new resource. Simply typing restart welcome-message in the server console might work, but a full restart is more reliable for initial setup.
Test Your Script
Connect to your FiveM server.
If everything is set up correctly, you should see the “Welcome to the server!” message in the chat when you join.
Troubleshooting:
No message appears:
Double-check the spelling of all file names (__resource.lua, client.lua, server.lua) and folder names. Typos are the most common cause of errors.
Make sure you added ensure welcome-message to your server.cfg and restarted the server.
Check the server console for any error messages. FiveM usually provides helpful error messages if something goes wrong. Look for errors related to welcome-message.
Verify that the Citizen.Wait(0) is present in your client.lua loop.
Verify that you are registering and triggering the same event name.
Server crashes:
A missing Citizen.Wait(0) in a while true loop is the most likely culprit.
Check the server console for error messages.
Other issues:
Carefully review each step of the tutorial, making sure you haven’t missed anything.