How citizenfx/fivem works
Purpose and deliverables
Cfx.re is a native modification and multiplayer framework for Rockstar RAGE games: FiveM (GTA V), RedM (RDR2), and FXServer. It ships a launcher/injected client, a modular dedicated server, script runtimes and resource hosting, plus FXDK tooling. Core implementation is C++ with managed, Lua, JavaScript/TypeScript layers.
Process entry points and bootstrap
The Windows client launcher starts update/install, game selection, cache validation, and executable loading/injection. The server launcher starts the component-hosted server process. Client core dynamically loads platform-specific components and exposes a shared object/event model.
• code/client/launcher/Main.cpp
• code/client/citicore/ComponentLoader.cpp
• code/server/launcher/src/Main.cpp
Component platform and game boundary
Components are independently declared through component.json/Lua metadata and loaded into client or server hosts. citicore provides component identity/loading, console, lifecycle modes, security, and shared event/hooking primitives. Game-specific component families (*-five, *-rdr3, *-ny) bind into RAGE internals using hooks, patches, allocators, virtual filesystems, rendering, and scripting interfaces; this is the critical unsupported-game-binary boundary.
• code/client/citicore/ComponentLoader.h
• code/client/shared/Hooking.h
• code/components/gta-core-five/src/GameInit.cpp
Client runtime flow
Launcher prepares/loads the selected game, then core components initialize game integration, networking, resource mounts, and UI. Client resources are downloaded/cached and mounted into VFS/RAGE devices; game-specific networking translates server synchronization into native game entities and state. The same shape has GTA V, RDR3, and legacy NY variants.
• code/components/citizen-resources-client/src/ResourceCache.cpp
• code/components/vfs-core/src/VFSManager.cpp
• code/components/gta-net-five/src/CloneManager.cpp
Resource and scripting model
A ResourceManager owns resource discovery, metadata, dependency loading, start/stop lifecycle, events, state bags, and RPC configuration. The scripting core exposes resource callbacks, filesystem permissions, native invocation, serialization, profiler support, and script-host contracts. Language adapters host Lua, Mono/.NET, and Node/V8 runtimes; resources communicate across this boundary via events, exports/function references, MessagePack, and state bags.
• code/components/citizen-resources-core/include/ResourceManager.h
• code/components/citizen-scripting-core/src/ResourceScriptingComponent.cpp
• code/components/citizen-scripting-node/src/NodeScriptRuntime.cpp
FXServer networking and authority
Server startup creates an instance and network listeners, then citizen-server-impl manages client admission/identity, HTTP endpoints, resource file streaming, packet dispatch, events, and replicated game state. ENet/game packets flow through handlers into server game state and resource scripts; HTTP serves server/resource metadata and files. Client/server packet schemas are centralized separately.
• code/components/citizen-server-main/src/ServerInstance.cpp
• code/components/citizen-server-impl/src/GameServer.cpp
• code/components/net-packet/include/StateBag.h
UI, voice, and integrations
NUI embeds Chromium/CEF for client and resource web UIs, with internal RPC, custom schemes, native callbacks, and rendering/input bridges. Voice uses a bundled Mumble client/server path. Optional platform integrations include Discord presence and Steam/license identity providers.
• code/components/nui-core/src/NUIApp.cpp
• code/components/nui-resources/src/ResourceUI.cpp
• code/components/voip-mumble/src/MumbleClient.cpp
Build, packaging, and developer tooling
Premake-based native builds generate the componentized binaries; CI produces Windows and Alpine/Linux server artifacts. Runtime distributions are assembled under data/ using component manifests. FXDK combines native SDK/game-process components with a Node/React desktop-style shell for project, server, and world-editor workflows.
• code/premake5.lua
• code/tools/ci/build_server_docker_alpine.sh
• ext/sdk/resources/sdk-root/shell/src/backend/shell-backend.ts
Main entry points: GameServer.cpp Game Server Implementation · ComponentLoader.cpp Client Component Loader · GameInit.cpp Game Integration · ResourceManager.h Resource Manager
Components 21
Client Runtime
- Windows Client Launcher · Updates, selects a game, validates cache, and injects the client.
code/client/launcher/Main.cpp - Client Component Loader · Discovers and loads platform-specific client components.
code/client/citicore/ComponentLoader.cpp - citicore Platform · Provides lifecycle, console, security, events, and component identity.
code/client/citicore/ComponentLoader.h - Hooking Primitives · Hooks and patches unsupported RAGE game binaries.
code/client/shared/Hooking.h - Game Integration · Game-family components initialize RAGE bindings and game services.
code/components/gta-core-five/src/GameInit.cpp - Client Resource Cache · Downloads and caches server resources.
code/components/citizen-resources-client/src/ResourceCache.cpp - VFS & Resource Mounts · Mounts resource content into game-visible devices.
code/components/vfs-core/src/VFSManager.cpp - Game Sync / Clone Manager · Maps replicated server state into native game entities.
code/components/gta-net-five/src/CloneManager.cpp
FXServer
- Server Launcher · Starts the component-hosted FXServer process.
code/server/launcher/src/Main.cpp - Server Instance · Creates the server instance and network listeners.
code/components/citizen-server-main/src/ServerInstance.cpp - Game Server Implementation · Handles admission, packet dispatch, HTTP, streaming, events, and replication.
code/components/citizen-server-impl/src/GameServer.cpp - Packet Schemas & State Bags · Shared client/server state replication and packet contracts.
code/components/net-packet/include/StateBag.h
Resources & Scripts
- Resource Manager · Discovers resources and manages dependencies, lifecycle, events, RPC, and state.
code/components/citizen-resources-core/include/ResourceManager.h - Scripting Core · Provides native calls, permissions, callbacks, serialization, and host contracts.
code/components/citizen-scripting-core/src/ResourceScriptingComponent.cpp - Lua / Mono / Node Runtimes · Hosts resource scripts through language-specific adapters.
code/components/citizen-scripting-node/src/NodeScriptRuntime.cpp
UI, Voice & Tooling
- NUI / Chromium · Provides CEF UI, RPC, schemes, native callbacks, rendering, and input bridges.
code/components/nui-core/src/NUIApp.cpp - Resource Web UI · Connects resource-defined web interfaces to NUI.
code/components/nui-resources/src/ResourceUI.cpp - Mumble Voice · Bundled Mumble client/server voice path.
code/components/voip-mumble/src/MumbleClient.cpp - FXDK Shell · Node-based desktop shell for projects, servers, and world editing.
ext/sdk/resources/sdk-root/shell/src/backend/shell-backend.ts
Build & Distribution
- Premake Build · Generates builds for the componentized native binaries.
code/premake5.lua - Alpine Server Build · Produces Linux/Alpine server artifacts.
code/tools/ci/build_server_docker_alpine.sh
Connections 23
- Windows Client Launcher → Client Component Loader: loads
- Client Component Loader → citicore Platform: hosts
- citicore Platform → Hooking Primitives: uses
- Hooking Primitives → Game Integration: binds RAGE
- Client Component Loader → Client Resource Cache: initializes
- Client Resource Cache → VFS & Resource Mounts: mounts cached files
- Game Integration → Game Sync / Clone Manager: provides game interfaces
- Server Launcher → Server Instance: starts
- Server Instance → Game Server Implementation: hosts
- Game Server Implementation → Packet Schemas & State Bags: replicates
- Game Server Implementation → Resource Manager: runs resources
- Resource Manager → Scripting Core: creates script hosts
- Scripting Core → Lua / Mono / Node Runtimes: adapts
- Game Server Implementation → Client Resource Cache: streams resources
- Packet Schemas & State Bags → Game Sync / Clone Manager: synchronizes entities
- Resource Manager → Resource Web UI: serves UI resources
- Resource Web UI → NUI / Chromium: renders in
- Game Integration → NUI / Chromium: bridges rendering/input
- Game Server Implementation → Mumble Voice: coordinates voice
- Premake Build → Windows Client Launcher: builds distribution
- Premake Build → Server Launcher: builds distribution
- Alpine Server Build → Server Launcher: packages Linux artifact
- FXDK Shell → Server Instance: manages local servers