8 min read
FiveM development tutorial for beginners
Prerequisites: a local QBCore test server, a legitimate GTA V installation for the Windows client, and basic programming knowledge.
This guide introduces the development workflow from a local test server to a small custom FiveM resource. Verify changing framework and platform details against their current upstream source.
What You'll Learn: By the end of this tutorial, you'll have a fully functional FiveM server running QBCore framework and understand the fundamentals of FiveM development.
What is FiveM Development?
FiveM development involves creating custom game modes, servers, and modifications for Grand Theft Auto V using the FiveM modification framework. It allows developers to:
- Create Custom Servers: Build unique roleplay experiences
- Develop Resources: Custom scripts and game modifications
- Manage Communities: Admin tools and player management systems
- Monetize Projects: Create revenue through server donations
Why Choose QBCore for FiveM Development?
QBCore separates the core framework from qb-* resources. Inspect each repository manifest and source at the commit you deploy; architecture, maintenance activity, dependencies, and performance must be evaluated against your own server workload.
Prerequisites & Requirements
Before we begin, ensure you have:
System Requirements
Use a supported Windows or Linux server environment from the Cfx server setup guide. The FiveM client runs on Windows and requires a legitimate supported GTA V installation. A Linux server does not run the game client. Size CPU, RAM and storage for your selected resources and workload; this tutorial does not establish minimum production capacity.
Required Software
- FXServer: a recommended artifact build for your operating system
- Database: MariaDB or MySQL compatible with your selected QBCore recipe and oxmysql
- Code editor: VS Code with Lua Language Server, or another Lua-aware editor
- Git: for versioning your own resources
- Cfx.re account: for txAdmin account linking and a server registration key through the Cfx Portal
Knowledge Prerequisites
- Basic Programming: Understanding of variables and functions
- Command Line: Basic terminal/command prompt usage
- Text Editing: Comfortable with code editors
Important: Never use pirated or cracked versions of GTA V. FiveM requires a legitimate copy of the game.
Step 1: Setting Up Your Development Environment
Download & Install Required Software
Install Code Editor
Download and install VS Code with essential extensions:
- Lua Language Server for diagnostics
- A FiveM native reference extension if desired
- GitLens if you use Git in the editor
These are editor extensions, not shell commands.
Install Database Server
Install a supported MariaDB server and verify that the service is running. Use a dedicated database account for the development server; Apache and phpMyAdmin are not required by QBCore.
Install Git Version Control
- Download from git-scm.com
- Run installer with default settings
- Verify installation:
git --version
Step 2: Download & Setup FiveM Server
Get FiveM Server Files
Create Project Directory
mkdir fivem-server
cd fivem-serverDownload Server Files
Open the Windows artifact list, select the recommended build, and extract its archive into your server directory.
Get FiveM License Key
Sign in to the Cfx Portal with your Cfx.re account and register a server. Keep the resulting key private. A Steam account is not the server-key registration requirement.
Configure Basic Server
Use txAdmin's recipe deployer rather than constructing a partial QBCore stack by hand. Keep artifact binaries separate from the server-data directory created by txAdmin. The deployer writes the configuration and starts resources from that server-data directory.
Never commit your server key, database credentials, or txAdmin profile to your resource repository. Use a dedicated database account and keep the database private to the development host/network.
Step 3: Install QBCore Framework
Download QBCore
Launch the artifact without +exec server.cfg for the initial txAdmin setup:
- Windows: open the extracted
FXServer.exe(use the executable named by the Cfx guide for your game edition). - Linux: run
./run.shfrom the extracted artifact directory.
Open the local txAdmin URL printed by the process, enter its PIN and link your Cfx.re account. Follow the Cfx txAdmin setup.
Install Essential Resources
Select the QBCore recipe if it is available in the recipe list. Otherwise choose the remote recipe option and use the upstream QBCore recipe URL. Review the recipe source before deployment: it downloads the core, dependencies and resource set together.
A folder such as [qb] groups resources; qb-core is the actual resource folder inside it.
Do not clone the core directly into [qb-core] and then expect ensure qb-core to find it.
For a deliberate manual install, use the full installation guide.
Setup Database
Enter the database connection details requested by the deployer and a private server key. Review and run the recipe, then check the task log for successful database imports and downloads. If a step fails, resolve it before starting the server; don't continue with a half-installed stack.
Update Server Configuration
Review the generated server.cfg, resource paths, database connection and ensure order. Preserve
the selected recipe's dependencies; don't append names for resources that were never downloaded.
The recipe is a starting point, not evidence that third-party scripts are compatible.
Step 4: First Server Launch & Testing
Start Your Server
Use txAdmin's Save & Run Server action after the recipe completes. On later starts, launch the same artifact/txAdmin profile and use its console. Do not run another FXServer process against the same ports or data directory. For a manual server, follow the working-directory instructions in the Cfx vanilla server guide.
Connect to Your Server
- Open the FiveM client on the development machine.
- Press F8 to open its console.
- Enter
connect 127.0.0.1:30120for a server on the same machine. - For a separate host, use its configured reachable address and port;
localhostrefers to the client machine.
Success Indicators:
- Server starts without errors
- You can connect and spawn in-game
- Character creation system appears
- Resources installed by your selected recipe start without dependency errors
Step 5: Understanding FiveM Development Basics
Resource Structure
Every FiveM resource follows this structure:
resource-name/
├── fxmanifest.lua # Resource configuration
├── config.lua # Settings and options
├── server/
│ └── main.lua # Server-side code
├── client/
│ └── main.lua # Client-side code
├── shared/
│ └── shared.lua # Code available on both sides
└── html/ # UI files (optional)
├── index.html
├── style.css
└── script.jsYour First Custom Resource
Let's create a simple "Hello World" resource:
Create Resource Directory
mkdir -p hello-world/client hello-world/server
cd hello-worldCreate fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
name 'hello-world'
description 'My first FiveM resource'
author 'Your Name'
version '1.0.0'
client_scripts {
'client/main.lua'
}
server_scripts {
'server/main.lua'
}Create Server Script
Run the directory command from the deployed server-data resources directory (Git Bash or a Linux shell).
On Windows without that shell, create the same directories in Explorer. hello-world is a resource, not a bracketed category.
Create server/main.lua:
-- Server-side code runs on the server
print("^2[Hello World] ^7Server-side script loaded successfully!")
-- Register a server event
RegisterServerEvent('hello-world:serverTest')
AddEventHandler('hello-world:serverTest', function()
local playerName = GetPlayerName(source)
if not playerName then return end
print("^3[Hello World] ^7Server event triggered by player: " .. playerName)
end)
-- Register a command
RegisterCommand('hello', function(source, args, rawCommand)
if source == 0 then
print("^5[Hello World] ^7Hello from server console!")
else
TriggerClientEvent('hello-world:clientResponse', source, "Hello from server!")
end
end, false)Create Client Script
Create client/main.lua:
-- Client-side code runs on each player's game
print("^2[Hello World] ^7Client-side script loaded successfully!")
-- Register client event
RegisterNetEvent('hello-world:clientResponse')
AddEventHandler('hello-world:clientResponse', function(message)
print("^4[Hello World] ^7Received message: " .. message)
-- Show notification to player
SetNotificationTextEntry("STRING")
AddTextComponentString(message)
DrawNotification(false, false)
end)
-- Trigger server event when this client resource starts
AddEventHandler('onClientResourceStart', function(resourceName)
if resourceName == GetCurrentResourceName() then
TriggerServerEvent('hello-world:serverTest')
end
end)Add Resource to Server
Add to your server.cfg:
ensure hello-worldTest Your Resource
- Restart your server or use
refreshandensure hello-worldin server console - Connect to your server
- Type
/helloin chat - Check both server console and game for messages
Congratulations! You've created your first FiveM resource. This demonstrates the basic client-server architecture that powers all FiveM development.
Step 6: QBCore Integration Basics
Understanding QBCore Structure
The shared export obtains the core, but most Functions APIs belong to a specific execution side.
Do not paste a server GetPlayer call into a client file or client Notify into server code.
-- client/main.lua only
local QBCore = exports['qb-core']:GetCoreObject()
local PlayerData = QBCore.Functions.GetPlayerData()
QBCore.Functions.Notify('Hello!', 'success')Use QBCore.Functions.GetPlayer(source) inside a server handler where source identifies a
connected player. See client functions and
server functions.
Creating a QBCore Resource
Replace the previous client/server scripts with the following versions; do not append duplicate handlers.
Add dependency 'qb-core' to fxmanifest.lua, and start qb-core before hello-world.
Update client/main.lua:
local QBCore = exports['qb-core']:GetCoreObject()
RegisterNetEvent('hello-world:clientResponse')
AddEventHandler('hello-world:clientResponse', function(message)
-- Use QBCore notification instead of GTA notification
QBCore.Functions.Notify(message, "success", 3000)
end)Update server/main.lua:
local QBCore = exports['qb-core']:GetCoreObject()
RegisterCommand('hello', function(source, args, rawCommand)
if source == 0 then
print("^5[Hello World] ^7Hello from server console!")
else
local Player = QBCore.Functions.GetPlayer(source)
if Player then
local playerName = Player.PlayerData.charinfo.firstname .. " " .. Player.PlayerData.charinfo.lastname
TriggerClientEvent('hello-world:clientResponse', source, "Hello " .. playerName .. "!")
end
end
end, false)Step 7: Essential Development Tools & Tips
Debugging Tools
- Server/txAdmin console: server-side errors and print statements
- F8 console: client-side errors
- NUI developer tools: browser console and network failures for resource UIs
- Database logs: connection and query errors, without publishing credentials
Common Development Commands
Run these in the server/txAdmin console:
refresh
ensure hello-world
stop hello-world
restart hello-worldrefresh rescans manifests; it does not reload running scripts. ensure starts or restarts the
named resource. /car requires the installed QBCore permissions; custom commands such as /dev
are not guaranteed by the framework. See commands.
Performance Best Practices
- Efficient Event Usage: Don't spam server events
- Proper Threading: Use
Wait()in loops to prevent blocking - Resource Cleanup: Clean up blips, entities, and events
- Minimal Database Queries: Cache frequently accessed data
- Optimized Loops: Avoid unnecessary iterations
-- Bad: Blocking loop
while true do
-- This will freeze the server/client
DoSomething()
end
-- Good: Non-blocking loop with wait
CreateThread(function()
while true do
DoSomething()
Wait(1000) -- Wait 1 second between iterations
end
end)Step 8: Next Steps & Resources
Continue Learning
Lua Scripting for FiveM
⏱️ 45 mins | Master Lua programming specific to FiveM development
QBCore Architecture
⏱️ 30 mins | Understand QBCore's internal structure and design patterns
Advanced QBCore Features
⏱️ Varies | Jobs, inventory, UI development, and more
QBCore vs ESX Comparison
⏱️ 15 mins | Detailed framework comparison and migration guide
Essential Documentation
- QBCore Installation Guide - Detailed installation instructions
- QBCore Functions Reference - Complete API documentation
- Resource Development Guide - Advanced scripting techniques
- Database Schema - Understanding QBCore's data structure
Community & Support
- Cfx.re QBCore search - Community questions and answers
- QBCore Discord - Real-time help and discussions
- Support Page - Direct support channels and troubleshooting
Common Issues & Solutions
Server Won't Start
Problem: Server crashes or won't start Solutions:
- Check
server.cfgsyntax for errors - Verify MySQL connection string
- Ensure license key is valid
- Check resource dependencies
Can't Connect to Server
Problem: Connection timeout or failed Solutions:
- Verify server is running (check console)
- Check firewall settings (port 30120)
- Ensure IP address is correct
- Try
localhost:30120for local testing
Resource Errors
Problem: Custom resources not working Solutions:
- Check
fxmanifest.luasyntax - Verify file paths in manifest
- Look for Lua syntax errors in console
- Ensure resource is added to
server.cfg
Database Connection Issues
Problem: MySQL connection errors Solutions:
- Verify MySQL server is running
- Check connection string credentials
- Ensure database exists
- Import required SQL files
Congratulations! You've completed the FiveM Development Tutorial. You now have a solid foundation to start creating amazing FiveM servers and resources with QBCore framework.
What's Next?
- Practice: Experiment with the code examples and create variations
- Explore: Browse existing QBCore resources to understand different patterns
- Build: Start your first real project - maybe a custom job or activity
- Connect: Join the QBCore community and share your progress
- Level Up: Move on to intermediate tutorials for advanced features
Continue with Lua scripting, then build a server-authorized example in the QBCore scripting guide. The setup instructions are source-reviewed, not a report of a completed FiveM installation.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
