Enabling OneSync for More Than 32 Players

Overview

By default, FiveM operates in a peer-assisted relay mode that caps player count at 32. OneSync is a server-side entity synchronization system that replaces the default P2P model, enabling higher player counts and better state management. If your server needs more than 32 concurrent players, OneSync is mandatory.

OneSync Modes

There are three OneSync settings:

onesync legacy exists to ease migration from older script codebases. It carries significant performance overhead and should be treated as a temporary measure. New servers should always use onesync on.

Enabling OneSync

Add the following to server.cfg:

onesync on

Set this directive before your ensure statements. Restart the server after adding it.

Player Limit with OneSync

With onesync on, raise the player cap using sv_maxclients:

sv_maxclients 64

FiveM supports player counts well above 64 on appropriately resourced hardware, but your actual cap depends on server CPU, network bandwidth, and how resource-intensive your active scripts are. Running 128+ players requires careful profiling of server-side script tick rates.

For 64+ players, onesync on is mandatory. The engine will refuse to start with onesync off if sv_maxclients exceeds 32.

Impact on Scripts

OneSync changes how entities are synchronized. Key differences:

• Entity scope: Entities (vehicles, peds, objects) are only created on clients within a certain range. Scripts that assume all entities exist on all clients will break.
• GetClosestVehicle / GetAllVehicles: These native functions may not return entities outside a client's scope. Use server-side entity tracking or the statebag system instead.
• Server-side entity creation: With OneSync, it is possible (and encouraged) to create and manage entities entirely server-side.

Most well-maintained ESX and QBCore resources are OneSync-compatible. If a resource predates OneSync or is unmaintained, test it before deploying to production with onesync on.

Statebags

OneSync introduces statebags, a key-value store attached to entities and players that replicates to all clients in scope:

-- Server: set a statebag value on a player
Player(source).state:set('duty', true, true)

-- Client: read it
local onDuty = Player(GetPlayerServerId(PlayerId())).state.duty

Statebags are the recommended way to sync persistent per-player or per-entity state in a OneSync environment.

Verifying OneSync is Active

In the txAdmin console or server console, run:

onesync

The response should confirm the current mode. You can also check the server browser listing — OneSync servers are tagged differently in the cfx.re server directory.

Recommended server.cfg Snippet

onesync on
sv_maxclients 64

Place these directives near the top of server.cfg, after the endpoint lines and before sv_licenseKey.

Related

• Configuring Your Server with server.cfg
• Installing FiveM (FXServer) Dedicated Server
• Troubleshooting Common FiveM Server Errors