Fnx PVP Aimlab - Fenix Studios Docs

Complete installation, modes, hooks, theme, and API reference for fnx-pvp-aimlab.

fnx-pvp-aimlab provides instanced target-training modes with loadouts, records, Elo, and leaderboard integration.

First installation

ensure oxmysql
ensure community_bridge

ensure fnx-pvp-panel
ensure fnx-pvp-aimlab

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

First setup

Edit both public cfg files. For every mode, test player spawns, polygon, targets, timing, and inventory item names before opening it to players.

Client configuration

Plugin

Key	Default	Explanation
`ClientCfg.Plugin.id`	`"aimlab"`	Unique panel plugin ID.
`ClientCfg.Plugin.labelKey`	`"plugins.aimlab.label"`	Locale key for its title.
`ClientCfg.Plugin.descriptionKey`	`"plugins.aimlab.description"`	Locale key for its description.
`ClientCfg.Plugin.icon`	`"fa-solid fa-bullseye"`	Font Awesome icon class.
`ClientCfg.Plugin.resource`	`PVP_AIMLAB_RESOURCE`	Resource owning the plugin.
`ClientCfg.Plugin.ui`	`"web/dist/index.html"`	Built NUI page.
`ClientCfg.Plugin.order`	`45`	Panel sort position.
`ClientCfg.Plugin.enabled`	`true`	Enables plugin registration.

Commands and runtime

Key	Default	Explanation
`Commands.open.enabled`	`true`	Enables the open command.
`Commands.open.name`	`"aimlab"`	Command name without `/`.
`Commands.leave.enabled`	`true`	Enables the leave command/key.
`Commands.leave.name`	`"leaveaimlab"`	Leave command name.
`Commands.leave.key`	`"F6"`	Default FiveM key mapping.
`Commands.leave.keyDescription`	`"Leave Aimlab"`	Text in FiveM keybind settings.
`Runtime.closePanelOnJoin`	`true`	Closes the PVP panel after joining.
`Runtime.returnCoords`	`nil`	Optional client return `vec4`; nil uses server/default handling.

Client hooks

Key	Arguments	Called when
`Events.OnAimlabJoin`	`payload`	The player joins. Default code equips the current ox_inventory weapon.
`Events.OnAimlabLeave`	none	The player leaves.
`Events.OnAimlabHudOpen`	`payload`	The HUD opens.
`Events.OnAimlabHudUpdate`	`payload`	HUD data changes.
`Events.OnAimlabShot`	none	A tracked shot is fired.
`Events.OnAimlabTargetKill`	`payload`	A target is killed.
`Events.OnAimlabTargetMiss`	`payload`	A target is missed/expires.
`Events.OnGameEventTriggered`	event callback or `nil`	Optional raw game-event callback.

Server configuration

Inventory, join, and routing

Key	Default	Explanation
`Inventory.enabled`	bridge-dependent	Enables inventory snapshot/loadout handling.
`Inventory.keepInventory`	`false`	Disables Aimlab inventory/loadout management and lets players keep items.
`Inventory.mode`	`"auto"`	Inventory path: `auto`, `bridge`, or `native`.
`Inventory.weaponMetadata.enabled`	`true`	Gives weapon ammo/components inside weapon metadata instead of as separate inventory items.
`Inventory.weaponMetadata.durability`	`10000`	Durability value written to weapon metadata when metadata mode is enabled.
`Inventory.weaponMetadata.ammo`	`true`	Stores configured ammo in weapon metadata and skips the separate ammo item grant.
`Inventory.weaponMetadata.components`	`true`	Stores configured components in weapon metadata and skips separate component item grants.
`Join.warning.enabled`	bridge-dependent	Enables inventory-change confirmation.
`Join.warning.holdSeconds`	`1`	Seconds the confirmation must be held.
`Join.warning.timeoutSeconds`	`30`	Seconds before confirmation expires.
`Aimlab.returnCoords`	`nil`	Optional server return `vec4`.
`Aimlab.bucketBase`	`50000`	First Aimlab routing bucket; avoid overlaps.
`Aimlab.returnBucket`	`0`	Bucket restored on leave.
`Runtime.defaultElo`	`0`	Starting Aimlab Elo.
`Runtime.modes`	array	Available training modes.

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.join`	A player joins an Aimlab mode.
`Logs.exit`	A player exits or drops from Aimlab, including kills/shots.
`Logs.inventoryStored`	A player’s inventory snapshot is stored before Aimlab loadout is applied.
`Logs.inventoryRestore`	A player’s original inventory is restored.

Mode schema

Key	Type	Explanation
`id`	string	Unique mode ID used by runtime and records.
`labelKey`	string	Locale key for the mode name.
`descriptionKey`	string	Locale key for its description.
`image`	string	Menu image source.
`maxPlayers`	number	Maximum simultaneous players.
`respawnPoints`	vector4 array	Player positions and headings.
`area.type`	string	Area implementation; current modes use `poly`.
`area.points`	vector3 array	Polygon vertices in boundary order.
`area.thickness`	number	Vertical polygon depth/tolerance.
`area.debug`	boolean	Draws area debug information; disable in production.
`targetModel`	string	GTA ped model used for targets.
`targetPoints`	vector4 array	Target positions and headings.
`targetMode`	string	Behavior: configured modes use `grid`, `single`, or `single_roll`.
`respawnDelayMs`	number	Delay before a new target in milliseconds.
`targetLifetimeMs`	number	Time before a target counts as missed, in milliseconds.
`weapons`	array	Mode loadout choices.

Weapon schema

Key	Type	Explanation
`id`	string	Unique UI/runtime weapon ID.
`name`	string	GTA weapon name.
`hash`	hash	FiveM weapon hash.
`label`	string	Human-readable name.
`ammo`	number	Ammo issued.
`itemsData.weapon`	string	Inventory weapon item.
`itemsData.ammo`	string or `nil`	Inventory ammo item.
`itemsData.components`	array	Inventory component item names.

Server hooks

Key	Arguments	Called when
`Events.OnAimlabJoin`	`player, mode`	A player joins.
`Events.OnAimlabLeave`	`player, mode, dropped`	A player leaves or disconnects.
`Events.OnAimlabStat`	`player, kind, amount, payload, mode`	A statistic is accepted.
`Events.OnAimlabTargetKill`	`player, payload, mode`	A target kill is accepted.
`Events.OnAimlabTargetMiss`	`player, payload, mode`	A target miss is accepted.

Shared files

Private shared files contain internal constants and helpers. Aimlab has no public shared cfg.

Theme system

Colors accept CSS strings; radii are pixels; fonts are CSS font stacks.

Key	Controls
`colors.panelBg`	Main background.
`colors.panelBgStrong`	Darker background.
`colors.accent`	Primary highlight.
`colors.accentStrong`	Strong highlight.
`colors.text`	Primary text.
`colors.mutedText`	Secondary text.
`colors.surface`	Normal card surface.
`colors.surfaceStrong`	Strong card surface.
`colors.border`	Borders/separators.
`colors.overlay`	Modal overlay.
`colors.success`	Success foreground.
`colors.successBg`	Success background.
`colors.danger`	Error foreground.
`colors.dangerBg`	Error background.
`colors.warning`	Warning foreground.
`colors.warningBg`	Warning background.
`colors.info`	Information foreground.
`colors.infoBg`	Information background.
`radii.panel`	Panel radius.
`radii.card`	Card radius.
`radii.control`	Control radius.
`radii.pill`	Badge radius; `999` makes a pill.
`fonts.body`	Normal-text font stack.
`fonts.display`	Heading font stack.

Developer info

Client export	Purpose
`OpenMenu()`	Opens Aimlab.
`CloseMenu()`	Closes Aimlab.
`IsInAimlab()`	Returns local membership state.
`SetHud(payload)`	Sets HUD data.
`UpdateHud(payload)`	Updates HUD data.
`ReportStat(kind, amount)`	Reports one statistic.
`HandleDamageEvent(eventName, args)`	Passes a game damage event to Aimlab.
`HandleEntityDamaged(victim, hitting, weapon, baseDamage)`	Passes normalized entity damage.

Server exports

Export	Parameters	Returns / purpose
`GetLeaderboardPage`	`request`	Returns the Aimlab leaderboard page requested by the panel or another server resource.
`GetLeaderboardEntries`	`limit, sortMetric`	Returns Aimlab leaderboard entries, optionally limited and sorted by the requested metric.

Common issues

Targets do not appear

Check model, points, target mode, and timing. Keep every point inside the polygon.

The player is outside the area

Check spawn points, polygon order, and thickness; temporarily enable area.debug.

Loadouts fail

Verify inventory mode and every itemsData name.

Some configured weapons are not given

Each weapon is applied with its ammunition and components as one package. If a complete package does not fit, only that weapon is skipped. Other weapons are still given and the player receives one notification showing how many weapons were skipped.

Stats count twice

Use one report path per action; do not duplicate automatic damage handling.

Folder structure

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-aimlab/
|-- client/
|   |-- private/
|   |   \-- _main.lua
|   \-- public/
|       \-- main.lua
|-- locales/
|   \-- *.json
|-- server/
|   |-- private/
|   |   |-- _database.lua
|   |   |-- _events.lua
|   |   |-- _inventory.lua
|   |   |-- _main.lua
|   |   |-- _modes.lua
|   |   |-- _runtime.lua
|   |   \-- _state.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 and runtime

​Client hooks

​Server configuration

​Inventory, join, and routing

​Logs

​Mode schema

​Weapon schema

​Server hooks

​Shared files

​Theme system

​Developer info

​Server exports

​Common issues

​Targets do not appear

​The player is outside the area

​Loadouts fail

​Some configured weapons are not given

​Stats count twice

​Folder structure

​Common folders