How to Enable OneSync on FiveM

  • 9 min read
  • Updated
  • ESAGAMES Team

This guide covers turning on OneSync, the Cfx.re sync system behind every large FiveM server. You can do it from txAdmin or in server.cfg. Then raise your slot count within the Cfx.re rules and update your scripts for entity ownership, scope and state bags. Common errors and their fixes are covered at the end.

OneSync is the custom sync system Cfx.re built on top of GTA Online's code. With it off, the server only relays traffic between players. With it on, the server is state-aware: it tracks entities, decides who owns them and only sends each player what's near them. That raises the number of slots a server can hold and lets you run logic on the server instead of trusting clients.

The modern mode is often called OneSync Infinity. Players and entities outside a focus zone around each player are culled, which is how large servers stay playable. On FiveM for GTAV Enhanced, this big mode is the only mode. Enabling OneSync takes one setting, but it changes how scripts must find players and entities, so this guide covers both.

You can do all of this on your own server, as shown below. Our FiveM server hosting comes with txAdmin ready to use, a web game panel with file manager and console, NVMe storage and always-on Anti-DDoS in Frankfurt.

What you'll need

  • A current recommended FXServer artifact.
  • A server license key from the Cfx.re Portal (sv_licenseKey).
  • Access to txAdmin Settings → FXServer, or to server.cfg on a vanilla server.
  • A Cfx.re Element Club Argentum subscription or higher if you want more than 48 slots.
  • Scripts that are OneSync-compatible, or time to update them.

Enable OneSync on a FiveM server, step by step

  1. Step 1: Update FXServer and set your license key

    Run a current recommended server artifact. Cfx.re asks for the latest artifact when you raise the slot cap, and new OneSync options only land in new builds. Every server also needs a license key from the Cfx.re Portal (free to register), set with sv_licenseKey in server.cfg.

    # server.cfg
    sv_licenseKey your_key_from_portal_cfx_re
  2. Step 2: Enable OneSync in txAdmin

    If you use txAdmin, set OneSync only in txAdmin. Open Settings → FXServer, reveal the advanced options if needed, set OneSync to On (recommended), save and restart the server. txAdmin passes the value to FXServer at launch itself. It comments out any onesync line it finds in server.cfg, and it won't accept OneSync in the Startup Arguments field.

  3. Step 3: Or enable it in server.cfg (no txAdmin)

    On a vanilla FXServer, add set onesync on to server.cfg, as in the official example config. You can also pass it on the command line before +exec. The convar takes on, legacy or off. Legacy is a compatibility mode for old scripts that expect every player to exist on every client. Cfx.re doesn't recommend it because of performance issues and graphical glitches.

    # server.cfg
    set onesync on
    sv_maxclients 48
    
    # or on the command line (Linux)
    bash ~/FXServer/server/run.sh +set onesync on +exec server.cfg
  4. Step 4: Set your player slots

    Slots come from sv_maxclients, which accepts values up to 2048. Bigger values need OneSync, and anything above 64 needs OneSync set to on, not legacy. OneSync is free up to 48 slots. Going past 48 needs a Cfx.re Element Club Argentum subscription or a higher tier. How far beyond that you can go depends on your tier. Raise sv_maxclients on the latest artifact and restart.

    sv_maxclients 48    # free limit; more needs Element Club Argentum or higher
  5. Step 5: Restart and confirm it's active

    OneSync is a startup setting, so do a full server restart, not just a resource restart. To confirm the mode, read the convar from any server script. Related options such as onesync_enableInfinity (on by default) can only be set at startup too.

    -- any server-side script
    print('OneSync mode: ' .. GetConvar('onesync', 'off'))
  6. Step 6: Fix player loops in your scripts

    With OneSync, a client only knows about players in its scope, roughly 424 units around it by default. Old loops over player indexes 0–31 break. On the client, use GetActivePlayers() for nearby players. On the server, use GetPlayers() for everyone online. GetPlayerFromServerId can return -1 when that player isn't in scope, so check for it.

    -- client: players in your scope
    for _, player in ipairs(GetActivePlayers()) do
      local ped = GetPlayerPed(player)
    end
    
    -- server: everyone online
    for _, src in ipairs(GetPlayers()) do
      print(GetPlayerName(src))
    end
  7. Step 7: Handle entity ownership

    Every networked entity is owned by one client. When it goes out of range or the owner leaves, it migrates to someone else or gets removed. Handles are local to each client, so pass network IDs between machines and check them with NetworkDoesEntityExistWithNetworkId. For entities that must persist, create them on the server and set an orphan mode that keeps them. To stop clients spawning things, use entity lockdown (the sv_entityLockdown convar or per routing bucket).

    -- server-side vehicle that survives its owner leaving
    local veh = CreateVehicleServerSetter(GetHashKey('blista'), 'automobile', x, y, z, heading)
    SetEntityOrphanMode(veh, 2) -- 2 = keep entity
  8. Step 8: Use state bags instead of custom sync events

    State bags attach key/value data to entities, players or the whole server, and OneSync syncs them for you. By default, state set by the server replicates and state set by a client doesn't. Set top-level keys directly. Editing a nested table in place won't replicate. Set sv_stateBagStrictMode true if only the server should be able to write state.

    -- server
    Entity(veh).state.fuel = 80
    Player(source).state.job = 'mechanic'
    GlobalState.weather = 'RAIN'
    
    -- client
    local fuel = Entity(veh).state.fuel

Keep a OneSync server fast

  • Let culling do its job

    Distance culling is on by default and cuts the data each player receives. Avoid scripts that force huge culling radii. Cfx.re marks the culling natives as deprecated with known issues.

  • Control NPC population

    onesync_population (on by default) is what spawns ambient peds and traffic. If your server doesn't need them, turn it off globally or per routing bucket with SetRoutingBucketPopulationEnabled to cut entity load.

  • Use routing buckets

    Buckets split the world into separate instances, for example character selection, races or mini-games. Each bucket can have its own lockdown mode and population rules.

  • Avoid scope events

    playerEnteredScope and playerLeftScope fire once per nearby player on every change, so their cost grows with crowd size. Cfx.re recommends state bag change handlers instead.

Common problems & fixes

My "set onesync on" line got commented out

txAdmin did that on purpose. OneSync must only be set in txAdmin's Settings → FXServer page. Set it there and restart.

"You cannot set OneSync in Startup Arguments."

txAdmin rejects onesync in the Startup Arguments field. Remove it there and use the OneSync select box below it instead.

The server is stuck at 48 slots

More than 48 slots needs Element Club Argentum or higher. Update to the latest artifact, raise sv_maxclients within your tier and restart the server.

Scripts only see a few players / GetPlayerFromServerId returns -1

Clients only know players in their scope. Do player-wide logic on the server with GetPlayers(), and use state bags or server events to share data.

Vehicles or props vanish when players drive away

Their owner moved out of range or left, and the entity was cleaned up. Create persistent entities on the server and use SetEntityOrphanMode(entity, 2).

No traffic or pedestrians

Population is off. Check that onesync_population isn't set to false and that population isn't disabled for the player's routing bucket.

State bag changes don't sync

Client-set state isn't replicated by default, nested table edits never replicate, and strict mode blocks client writes. Set top-level keys from the server.

Frequently asked questions

What is OneSync in FiveM?

OneSync is Cfx.re's server-side sync system for FiveM. The server tracks entities and players, routes data based on distance and lets you create and control entities from the server. It's also what lets a server go beyond small slot counts.

How do I enable OneSync in txAdmin?

Go to Settings → FXServer, show the advanced options, set OneSync to On (recommended), save and restart. Don't put onesync in server.cfg or Startup Arguments when using txAdmin. It comments the server.cfg line out and won't accept it in Startup Arguments.

How do I enable OneSync without txAdmin?

Add set onesync on to your server.cfg, or start FXServer with +set onesync on before +exec server.cfg, then restart the server.

Is OneSync free?

Yes, up to 48 slots. Using more than 48 slots needs a Cfx.re Element Club Argentum subscription or a higher tier from the Cfx.re Portal. How many slots you get depends on the tier.

How many players can a OneSync server hold?

sv_maxclients goes up to 2048, the ceiling for OneSync Infinity. In practice, your slot count is limited by your Cfx.re tier and by how efficient your scripts are, not by OneSync itself.

Should I use OneSync On or Legacy?

Use On. Legacy only exists for old scripts that expect every player on every client. Cfx.re doesn't recommend it because of performance issues and graphical glitches, and it can't be used above 64 slots.

Will my existing scripts break?

Scripts that loop over player indexes, pass entity handles between clients or rely on far-away players being loaded often need changes. Switch to GetActivePlayers/GetPlayers, network IDs and state bags, then test on a staging copy first.

Fixes for when it goes wrong

Knowledge-base fixes that pair with this guide — the errors people hit after setup.

More guides

Skip the troubleshooting

Managed, protected hosting in Frankfurt — we handle the Linux, the network and the DDoS so you don't have to.