Fnx PVP Lobbies - Fenix Studios Docs

Complete public, numbered, and private lobby configuration and API reference.

fnx-pvp-lobbies provides public, numbered, and private PVP lobbies with maps, loadouts, vehicles, respawning, permissions, stats, and leaderboards.

First installation

ensure oxmysql
ensure community_bridge

ensure fnx-pvp-panel
ensure fnx-pvp-killfeed
ensure fnx-pvp-lobbies

The resource creates its required database tables automatically. You do not need to import an SQL file.

First setup

Edit both public cfg files. Verify every ID reference: lobby weapon IDs must exist in ServerCfg.Weapons, map IDs in ServerCfg.Maps, and vehicle names must be valid GTA models.

Client configuration

Plugin

Key	Default	Explanation
`Plugin.id`	`"lobbies"`	Unique panel plugin ID.
`Plugin.labelKey`	`"plugins.lobbies.label"`	Title locale key.
`Plugin.descriptionKey`	`"plugins.lobbies.description"`	Description locale key.
`Plugin.icon`	`"fa-solid fa-people-group"`	Font Awesome icon.
`Plugin.resource`	`PVP_LOBBIES_RESOURCE`	Resource owning the plugin.
`Plugin.ui`	`"web/dist/index.html"`	Built NUI page.
`Plugin.order`	`30`	Panel sort position.
`Plugin.enabled`	`true`	Enables registration.

Commands

Each command has its own enabled and name. Commands with key mappings also have key and keyDescription.

Path	Default purpose/key
`Commands.open.enabled`	Enables the open command.
`Commands.open.name`	Open command name, default `lobbies`.
`Commands.runtime.enabled`	Enables the runtime-menu command/key.
`Commands.runtime.name`	Runtime command name, default `lobbymenu`.
`Commands.runtime.key`	Default runtime-menu key, `F5`.
`Commands.runtime.keyDescription`	Runtime keybind label.
`Commands.leave.enabled`	Enables the leave command/key.
`Commands.leave.name`	Leave command name, default `leavelobby`.
`Commands.leave.key`	Default leave key, `F6`.
`Commands.leave.keyDescription`	Leave keybind label.
`Commands.deleteVehicle.enabled`	Enables the vehicle-delete command/key.
`Commands.deleteVehicle.name`	Delete command name, default `deletelobbyvehicle`.
`Commands.deleteVehicle.key`	Default delete key, `K`.
`Commands.deleteVehicle.keyDescription`	Delete keybind label.
`Commands.heal.enabled`	Enables the heal command/key.
`Commands.heal.name`	Heal command name, default `lobbyheal`.
`Commands.heal.key`	Default heal key, `F1`.
`Commands.heal.keyDescription`	Heal keybind label.
`Commands.armor.enabled`	Enables the armor command/key.
`Commands.armor.name`	Armor command name, default `lobbyarmor`.
`Commands.armor.key`	Default armor key, `F2`.
`Commands.armor.keyDescription`	Armor keybind label.

Sections and actions

Key	Explanation
`Sections.maps`	Shows the map section.
`Sections.weapons`	Shows loadout selection.
`Sections.vehicles`	Shows vehicle selection.
`Sections.members`	Shows lobby members.
`Sections.settings`	Shows lobby settings.
`Actions.deleteVehicle.enabled`	Enables the delete-vehicle action.
`Actions.heal.enabled`	Enables healing.
`Actions.heal.duration`	Heal progress time in milliseconds.
`Actions.heal.cooldown`	Delay between heals in milliseconds.
`Actions.heal.health`	Target health; false restores maximum ped health.
`Actions.heal.canCancel`	Allows cancelling progress.
`Actions.heal.animation.dict`	Heal animation dictionary.
`Actions.heal.animation.clip`	Heal animation clip.
`Actions.heal.animation.flag`	GTA animation flag.
`Actions.armor.enabled`	Enables armor action.
`Actions.armor.duration`	Armor progress time in milliseconds.
`Actions.armor.cooldown`	Delay between armor uses in milliseconds.
`Actions.armor.amount`	Armor value applied.
`Actions.armor.canCancel`	Allows cancelling progress.
`Actions.armor.animation.dict`	Armor animation dictionary.
`Actions.armor.animation.clip`	Armor animation clip.
`Actions.armor.animation.flag`	GTA animation flag.

Runtime, death, respawn, and vehicles

Key	Explanation
`Runtime.closePanelOnJoin`	Closes panel after joining.
`Runtime.hud.enabled`	Enables lobby HUD.
`Runtime.deathEvents`	Enables built-in death handling.
`ClientCfg.Death`	Plugin overrides for panel death defaults; empty inherits all defaults.
`Respawn.manual`	Requires manual respawn input when true.
`Respawn.control`	GTA control ID; default `38` is E.
`Respawn.prompt`	Locale key for respawn prompt.
`Vehicles.vehicles`	Optional client vehicle allowlist/map. Empty does not add client restrictions.
`Vehicles.excludedVehicles`	Vehicle models always blocked.
`Vehicles.excludedClasses`	GTA vehicle class IDs blocked when their value is true.
`Vehicles.spawn.replacePrevious`	Deletes/replaces the player’s previous lobby vehicle.
`Vehicles.spawn.warpIntoVehicle`	Seats player after spawning.
`Vehicles.spawn.distance`	Spawn distance in game units.

Client hooks

Key	Arguments
`Events.OnLobbyJoin`	`payload`
`Events.OnLobbyLeave`	`payload`
`Events.OnLobbyTeleport`	`map`
`Events.OnLobbyLoadoutChanged`	`loadout`
`Events.OnLobbyVehicleSpawned`	`vehicle, model`
`Events.OnPlayerDeadInLobby`	`payload, lobby`
`Events.OnPlayerRespawnInLobby`	`lobby`
`Events.OnGameEventTriggered`	Optional callback or nil.

Server configuration

Inventory and joining

Key	Explanation
`Inventory.enabled`	Enables inventory management.
`Inventory.keepInventory`	Disables lobby inventory/loadout management and lets players keep items.
`Inventory.mode`	`auto`, `bridge`, or `native`.
`Inventory.weaponMetadata.enabled`	Gives weapon ammo/components inside weapon metadata instead of as separate inventory items.
`Inventory.weaponMetadata.durability`	Durability value written to weapon metadata when metadata mode is enabled.
`Inventory.weaponMetadata.ammo`	Stores configured ammo in weapon metadata and skips the separate ammo item grant.
`Inventory.weaponMetadata.components`	Stores selected components in weapon metadata and skips separate component item grants.
`Inventory.ammoRefill.enabled`	Enables automatic ammo refill checks.
`Inventory.ammoRefill.threshold`	Refill only when current ammo is below this fraction of configured ammo.
`Inventory.ammoRefill.respawn`	Checks/refills ammo after lobby respawn.
`Join.warning.enabled`	Enables inventory-change warning.
`Join.warning.holdSeconds`	Required hold time in seconds.
`Join.warning.timeoutSeconds`	Expiry time in seconds.

Rewards

ServerCfg.Rewards controls item/account rewards. Rewards are given independently from lobby loadouts, so they still work when Inventory.keepInventory is true.

Key	Explanation
`Rewards.kill.enabled`	Enables rewards for every kill.
`Rewards.kill.items`	Items/accounts given on kill.
`Rewards.killStreaks.enabled`	Enables killstreak rewards.
`Rewards.killStreaks.public`	When false, players need command-granted access before receiving streak rewards.
`Rewards.killStreaks.rewards[streak]`	Rewards given when the player reaches that streak value.
`reward.item`	Inventory item name given through the configured inventory bridge.
`reward.account`	Framework account name such as `bank`; requires a framework/account bridge.
`reward.amount`	Base reward amount. It is multiplied by the player’s reward multiplier.
`reward.metadata`	Optional item metadata passed to the inventory.

Logs

Each log category supports enabled, username, avatar, webhooks, and embed. webhooks is an array, so one category can send to multiple Discord webhooks. embed is a Lua function and can be fully customized per server.

Category	Sent when
`Logs.admin`	Admin/internal actions such as private panel, streak reward, or multiplier changes.
`Logs.kills`	A lobby kill is recorded. On large servers this can be noisy/rate-limited.
`Logs.join`	A player joins a lobby.
`Logs.exit`	A player exits, drops, or leaves a lobby, including kills/deaths.
`Logs.created`	A private lobby is created.
`Logs.deleted`	A private lobby is deleted.
`Logs.ban`	A lobby owner bans a member.
`Logs.kick`	A lobby owner kicks a member.
`Logs.inventoryStored`	A player’s inventory snapshot is stored before lobby loadout is applied.
`Logs.inventoryRestore`	A player’s original inventory and pending rewards are restored.

Lobby runtime

Key	Explanation
`Lobbies.bucketBase`	First public/private runtime bucket range base.
`Lobbies.numberedBucketBase`	First numbered-lobby bucket.
`Lobbies.numberedLobbyMin`	Lowest accepted lobby number.
`Lobbies.numberedLobbyMax`	Highest accepted lobby number.
`Lobbies.numberedLobbyMaxPlayers`	Capacity of each numbered lobby.
`Lobbies.returnBucket`	Bucket restored on leave.
`Lobbies.returnCoords`	Optional return `vec4`.
`Lobbies.privateIdStart`	Starting internal ID for private lobbies.
`Lobbies.defaultPrivateMaxPlayers`	Default private capacity.
`Lobbies.maxPrivatePlayers`	Maximum configurable private capacity.
`Lobbies.respawnSeconds`	Default death-to-respawn delay.
`Lobbies.defaultElo`	Starting lobby Elo.
`Lobbies.defaultWeapons`	Weapon IDs used as default selection.
`Lobbies.public`	Public lobby definitions.

Public lobby schema

Key	Explanation
`id`	Unique lobby ID.
`name`	Display name.
`description`	Menu description.
`image`	Menu image.
`weapons`	Allowed `ServerCfg.Weapons[].id` values; empty means unrestricted/all according to runtime handling.
`maps`	Allowed `ServerCfg.Maps[].id` values; empty means unrestricted/all.
`vehicles`	Allowed GTA vehicle model names; empty means no server list restriction.
`maxPlayers`	Lobby capacity.

Map schema

Key	Explanation
`ServerCfg.Maps[].id`	Unique ID referenced by lobbies.
`ServerCfg.Maps[].label`	Display name.
`ServerCfg.Maps[].image`	Menu image source.
`ServerCfg.Maps[].coords`	Teleport `vec4` and heading.

Weapon and component schema

Key	Explanation
`Weapons[].id`	Unique ID referenced by lobby lists.
`Weapons[].label`	Display name.
`Weapons[].hash`	GTA weapon hash.
`Weapons[].ammo`	Ammo issued.
`Weapons[].itemsData.weapon`	Inventory weapon item.
`Weapons[].itemsData.ammo`	Inventory ammo item, when required.
`Weapons[].components`	Selectable/issued component definitions.
`components[].id`	Unique component selection ID.
`components[].label`	Display name.
`components[].hash`	GTA component hash.
`components[].item`	Inventory component item.

Server commands

Key	Explanation
`Commands.joinNumberedLobby.active`	Enables numbered lobby command.
`.action`	Internal action name `joinNumberedLobby`.
`.name`	Command name `lobby`.
`.help`	Help description.
`.arguments`	Argument definitions; default requires numeric `number`.
`.argsrequired`	Requires arguments.
`.permission`	Bridge permission, default user.
`Commands.givePrivatePanel.active`	Enables permission grant command.
`.name`	Grant command name `giveprivatelobbypanel`.
`.help`	Grant help text.
`.arguments`	Target server-ID definition.
`.argsrequired`	Requires target.
`.permission`	Admin permission.
`.allowed`	Permission value written; true grants.
`Commands.removePrivatePanel.active`	Enables permission removal command.
`.name`	Remove command name `removeprivatelobbypanel`.
`.help`	Remove help text.
`.arguments`	Target server-ID definition.
`.argsrequired`	Requires target.
`.permission`	Admin permission.
`.allowed`	Permission value written; false removes.
`Commands.giveStreakRewards.active`	Enables streak reward access command.
`.action`	Internal action name `giveStreakRewards`.
`.name`	Command name `givelobbystreakrewards`.
`.permission`	Admin permission by default.
`Commands.setRewardMultiplier.active`	Enables reward multiplier command.
`.action`	Internal action name `setRewardMultiplier`.
`.name`	Command name `setlobbyrewardmultiplier`.
`.arguments`	Requires player ID and multiplier.
`.permission`	Admin permission by default.

Server hooks

Key	Arguments
`Events.OnLobbyCreated`	`lobby`
`Events.OnLobbyDestroyed`	`lobby, reason`
`Events.OnLobbyJoin`	`player, lobby`
`Events.OnLobbyLeave`	`player, lobby, dropped`
`Events.OnPlayerDeadInLobby`	`victim, killer, payload, lobby`
`Events.OnPlayerKillInLobby`	`killer, victim, payload, lobby`

Shared files

Private shared files contain internal bridge/constants. There is no public shared cfg.

Theme system

Every theme key controls a separate CSS variable:

Key	Controls
`colors.panelBg`	Main background.
`colors.panelBgStrong`	Dark background.
`colors.accent`	Primary accent.
`colors.accentStrong`	Strong accent.
`colors.accentSoft`	Transparent accent surface.
`colors.accentBorder`	Accent border.
`colors.progressFill`	Progress fill.
`colors.text`	Primary text.
`colors.mutedText`	Muted text.
`colors.subtleText`	More subtle text.
`colors.surface`	Normal surface.
`colors.surfaceStrong`	Strong surface.
`colors.surfaceSoft`	Soft surface.
`colors.surfaceHover`	Hovered surface.
`colors.controlBg`	Input/control background.
`colors.segmentedBg`	Segmented-control background.
`colors.selectionBg`	Selected-item background.
`colors.avatarBg`	Avatar background.
`colors.avatarBorder`	Avatar border.
`colors.ratingBg`	Rating block background.
`colors.ratingTrack`	Rating progress track.
`colors.mutedTextStrong`	Strong muted text.
`colors.softText`	Soft text.
`colors.disabledText`	Disabled text.
`colors.statText`	Statistic text.
`colors.scrollbarThumb`	Scrollbar thumb.
`colors.border`	Normal border.
`colors.borderStrong`	Strong border.
`colors.borderSelected`	Selected border.
`colors.overlay`	Modal overlay.
`colors.imageOverlay`	CSS image overlay/gradient.
`colors.success`	Success foreground.
`colors.successBg`	Success background.
`colors.danger`	Danger foreground.
`colors.dangerBg`	Danger background.
`colors.warning`	Warning foreground.
`colors.warningBg`	Warning background.
`colors.info`	Info foreground.
`colors.infoBg`	Info background.
`colors.ratingElite`	Elite tier.
`colors.ratingMaster`	Master tier.
`colors.ratingDiamond`	Diamond tier.
`colors.ratingPlatinum`	Platinum tier.
`colors.ratingGold`	Gold tier.
`colors.ratingSilver`	Silver tier.
`colors.ratingBase`	Base tier.
`radii.panel`	Panel radius.
`radii.card`	Card radius.
`radii.control`	Control radius.
`radii.mapCard`	Map-card radius.
`radii.mapImage`	Map-image radius.
`radii.pill`	Pill radius.
`fonts.body`	Body font stack.
`fonts.display`	Display font stack.

Developer info

Client exports

Export	Parameters	Returns / purpose
`OpenMenu`	none	Opens the lobby browser.
`CloseMenu`	none	Closes the lobby browser.
`OpenRuntimeMenu`	none	Opens the menu used while already inside a lobby.
`IsInLobby`	none	Returns whether the local player is in a PVP lobby.
`ReportDeath`	`payload`	Reports a local lobby death.
`CanReportDeath`	none	Returns whether a new death report is accepted.
`HandleDamageEvent`	`eventName, args`	Passes a game damage event into lobby death handling.

Server exports

Export	Parameters	Returns / purpose
`GetLeaderboardPage`	`request`	Returns the requested lobby leaderboard page.
`IsInLobby`	`source`	Returns whether the server player is inside a lobby.
`GetLobby`	`source`	Returns the lobby associated with the player.
`GetLeaderboardEntries`	`limit, sortMetric`	Returns lobby leaderboard entries with optional limit and sorting.

Common issues

Lobby content is missing

IDs must match exactly across public lobby, map, and weapon tables.

Vehicle is blocked

Check allowed vehicles, excludedVehicles, and every true entry in excludedClasses.

Inventory restore fails

Check inventory mode and all weapon/ammo/component item names.

Some selected weapons are not given

The resource applies each selected weapon as one package containing the weapon, its ammunition, and selected components. If the complete package does not fit, only that weapon is skipped. The player remains in the lobby, receives every other package that fits, and sees one notification with the number of skipped weapons.

Players enter the wrong instance

Ensure all bucket bases/ranges are unique across server resources.

Text shows broken characters

Save the cfg as UTF-8; some current descriptions show a mis-decoded em dash (â€”).

Common folders

Path	What it is for
`fxmanifest.lua`	FiveM manifest. It loads the resource files in the correct order.
`settings/public/client/cfg.lua`	Client settings that server owners are expected to edit.
`settings/public/server/cfg.lua`	Server settings that server owners are expected to edit.
`settings/private/**/_cfg.lua`	Internal/default settings. Do not edit unless you are modifying the resource itself.
`client/public/*.lua`	Public client API files and safe integration files.
`client/private/*.lua`	Internal client runtime code.
`server/public/*.lua`	Public server API files and exports.
`server/private/*.lua`	Internal server runtime code.
`shared/public/*.lua`	Shared public data or integration constants.
`shared/private/*.lua`	Shared internal helpers loaded by the resource.
`locales/*.json`	Locales for ui and game.
`web/dist/`	Built NUI files used in-game. Do not edit these by hand.

fnx-pvp-lobbies/
|-- client/
|   |-- private/
|   |   \-- _main.lua
|   \-- public/
|       \-- main.lua
|-- locales/
|   \-- *.json
|-- server/
|   |-- private/
|   |   |-- _database.lua
|   |   |-- _events.lua
|   |   |-- _inventory.lua
|   |   |-- _lobbies.lua
|   |   |-- _main.lua
|   |   |-- _maps.lua
|   |   |-- _runtime.lua
|   |   |-- _state.lua
|   |   \-- _stats.lua
|   \-- public/
|       \-- main.lua
|-- settings/
|   |-- private/
|   |   |-- client/
|   |   |   \-- _cfg.lua
|   |   \-- server/
|   |       \-- _cfg.lua
|   \-- public/
|       |-- client/
|       |   \-- cfg.lua
|       \-- server/
|           \-- cfg.lua
|-- shared/
|   \-- private/
|       \-- _main.lua
|-- web/
|   \-- dist/
\-- fxmanifest.lua

​First installation

​First setup

​Client configuration

​Plugin

​Commands

​Sections and actions

​Runtime, death, respawn, and vehicles

​Client hooks

​Server configuration

​Inventory and joining

​Rewards

​Logs

​Lobby runtime

​Public lobby schema

​Map schema

​Weapon and component schema

​Server commands

​Server hooks

​Shared files

​Theme system

​Developer info

​Client exports

​Server exports

​Common issues

​Lobby content is missing

​Vehicle is blocked

​Inventory restore fails

​Some selected weapons are not given

​Players enter the wrong instance

​Text shows broken characters

​Common folders