QBCore Frameworkqbcore.netCommunity docs
On this page

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

  1. Download from git-scm.com
  2. Run installer with default settings
  3. Verify installation: git --version

Step 2: Download & Setup FiveM Server

Get FiveM Server Files

Create Project Directory

mkdir fivem-server
cd fivem-server

Download 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.sh from 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

  1. Open the FiveM client on the development machine.
  2. Press F8 to open its console.
  3. Enter connect 127.0.0.1:30120 for a server on the same machine.
  4. For a separate host, use its configured reachable address and port; localhost refers 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.js

Your First Custom Resource

Let's create a simple "Hello World" resource:

Create Resource Directory

mkdir -p hello-world/client hello-world/server
cd hello-world

Create 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-world

Test Your Resource

  1. Restart your server or use refresh and ensure hello-world in server console
  2. Connect to your server
  3. Type /hello in chat
  4. 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-world

refresh 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

  1. Efficient Event Usage: Don't spam server events
  2. Proper Threading: Use Wait() in loops to prevent blocking
  3. Resource Cleanup: Clean up blips, entities, and events
  4. Minimal Database Queries: Cache frequently accessed data
  5. 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

Essential Documentation

Community & Support

Common Issues & Solutions

Server Won't Start

Problem: Server crashes or won't start Solutions:

  • Check server.cfg syntax 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:30120 for local testing

Resource Errors

Problem: Custom resources not working Solutions:

  • Check fxmanifest.lua syntax
  • 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?

  1. Practice: Experiment with the code examples and create variations
  2. Explore: Browse existing QBCore resources to understand different patterns
  3. Build: Start your first real project - maybe a custom job or activity
  4. Connect: Join the QBCore community and share your progress
  5. 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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website