# 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](https://docs.fivem.net/docs/server-manual/setting-up-a-server/).
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](https://portal.cfx.re/)

### 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](https://mariadb.org/download/) 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 MySQL Server**:
    ```bash
    sudo apt update
    sudo apt install mysql-server
    sudo mysql_secure_installation
    ```

### Install Git Version Control

###

###

    1. Download from [git-scm.com](https://git-scm.com/download/win)
    2. Run installer with default settings
    3. Verify installation: `git --version`

###

    ```bash
    sudo apt install git
    git --version
    ```

## Step 2: Download & Setup FiveM Server

### Get FiveM Server Files

### Create Project Directory

```bash
mkdir fivem-server
cd fivem-server
```

### Download Server Files

###

###

    Open the [Windows artifact list](https://runtime.fivem.net/artifacts/fivem/build_server_windows/master/),
    select the recommended build, and extract its archive into your server directory.

###

    Open the [Linux artifact list](https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/),
    select the recommended build, and copy the full download URL for its `fx.tar.xz` archive.
    Download that file and extract it with `tar -xf fx.tar.xz` in your server directory.
    Artifact IDs change: do not paste a literal `[latest-build]` placeholder into a command.

### Get FiveM License Key

Sign in to the [Cfx Portal](https://portal.cfx.re/) 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](https://docs.fivem.net/docs/server-manual/setting-up-a-server-txadmin/).

### 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](https://raw.githubusercontent.com/qbcore-framework/txAdminRecipe/main/qbcore.yaml).
Review [the recipe source](https://github.com/qbcore-framework/txAdminRecipe/blob/0f4f6d96bf707ef9de123afd59a4233504befab1/qbcore.yaml)
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](/docs/installation).

### 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](https://docs.fivem.net/docs/server-manual/setting-up-a-server-vanilla/).

### 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

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

### Create fxmanifest.lua

```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`:

```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`:

```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`:
```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.

```lua
-- 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](/docs/api/client-functions) and
[server functions](/docs/api/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`:
```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`:
```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:

```text
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](/docs/api/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

```lua
-- 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

###
