> ## Documentation Index > Fetch the complete documentation index at: https://docs.fenixstudios.net/llms.txt > Use this file to discover all available pages before exploring further. # Fnx PVP Lobbies > Complete public, numbered, and private lobby configuration and API reference. > 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 ```cfg theme={null} 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. | ```txt theme={null} 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 ```