Documentation
Install Crosshair Creator on your FiveM server: requirements, server.cfg load order, the automatic database setup, granting admin access and the config files.
Before installing Crosshair Creator, make sure your server meets the minimum requirements. Only two resources are mandatory, and no framework is needed at all.
Requirement | Status | Notes |
|---|---|---|
| Required | Saves each player's active crosshair, the share codes and the admin settings. The tables create themselves. |
| Required |
Callbacks, the rebindable keybind and the fallback notifications. |
Framework | Not needed | Works the same on QBCore, Qbox, ESX, ox_core, ND_Core or none. Players are identified by their |
Notifications | Optional | The script has its own. |
Discord webhook | Optional | Only for the admin audit log. |
After purchasing Crosshair Creator, the resource is automatically linked to your CFX Portal account.
Sign in to the CFX Portal using the same account used during checkout, open Granted Assets, and download Crosshair Creator.
After extracting the download, you should have the following:
[crosshair]/
├── qs-crosshair/
│ ├── config/ -- what you may edit: main, dynamics, webhooks
│ ├── client/custom/ -- client hooks: gate the panel, custom notifications
│ ├── server/custom/ -- server hooks: audit log, share events, commands
│ ├── locales/ -- 21 language files
│ ├── client/ server/ shared/ -- the script itself
│ └── html/ -- the interface
└── [sql]/
└── install.sql -- optional, the tables create themselvesThe folder must be named
qs-crosshair. The script calls its own exports asexports['qs-crosshair'], so a renamed copy cannot find itself and the reticle never applies.
Move the qs-crosshair folder into your server's resources directory. It can live anywhere inside it, including a category folder:
resources/
└── [qs]/
└── qs-crosshair/Once copied, open your server.cfg and start the two dependencies before the script:
ensure oxmysql
ensure ox_lib
# Optional notification resource, if you use one
# ensure qs-interface
ensure qs-crosshairThe loading order matters. The script waits up to 30 seconds for oxmysql to reach the started state; if it never does, nothing is saved and the console says so. ox_lib must be running first, or the resource does not load at all.
There is no SQL file to import. Crosshair Creator creates its own tables on every start if they are missing, all prefixed qs_crosshair_:
Table | Holds |
|---|---|
| Each player's active crosshair and whether it is switched on, keyed by licence. |
| Every |
| One row with everything set in the Admin tab: feature toggles, the official crosshair and the server identity. |
Each player's library of saved builds is not in MySQL. It is kept in the server's resource key-value store, also keyed by licence, so it follows the player across characters and reconnects.
Prefer to create the tables yourself?
[sql]/install.sqlholds the same three statements. Running it and letting the script start afterwards is safe — every statement isCREATE TABLE IF NOT EXISTS.
The Admin tab is where features are switched on and off for the whole server, so only admins see it. Everybody else does not even see the tab. A player counts as an admin if any of these aces is allowed for them:
The usual route, and the default. Most servers already give group.admin the command ace, which is accepted too. Add the player to the group in server.cfg:
add_ace group.admin command allow
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.adminLets somebody manage the crosshair without making them a full server admin:
add_ace identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx qs-crosshair.admin allowIf your staff live in a different group, point the script at it in config/main.lua. It must start with group. or principal. — anything else prints a warning on start.
Config.Admin = {
AceGroup = 'group.moderator',
-- ...
}Admin status is checked by the server every time the panel opens, so a newly added admin only needs to close and reopen it. Every admin save is checked again on the server before it is applied.
Most behaviour is set in game from the Admin tab and the player's own panel. The files only hold what has to be known before the first player joins:
File | Contents |
|---|---|
| Debug, language, the command and keybind, on by default, the admin group, sharing limits, notifications, library limits and the default visual tier. |
| The feel of each dynamic behaviour: how far fire feedback expands, when the low-ammo icon turns orange and red, how often targets are checked. |
| The Discord webhook for the admin audit log. |
| The translations. Edit a value to reword a message. |
The values worth reviewing first:
Config.Locale = 'en' -- one of the 21 languages in locales/
Config.OpenCommand = 'crosshair' -- /crosshair opens and closes the panel
Config.OpenKeybind = 'F4' -- default key; players can rebind it
Config.EnabledByDefault = true -- new players start with the crosshair on
Config.Admin = {
AceGroup = 'group.admin', -- who sees the Admin tab
DefaultThemeColor = '#48e0cb', -- panel colour for players who never picked one
EnableWebhookLog = false, -- post every admin change to Discord
}
Config.Library = {
MaxBuilds = 50, -- saved builds per player
MaxNameLength = 32, -- characters in a build name
}
Config.Performance = {
DefaultTier = 'medium', -- 'high' | 'medium' | 'low', players override it
}There is no default-crosshair table in the files, on purpose. The crosshair new players start with is chosen in game: build it, then press Apply as Official in the Admin tab. See The Admin Tab.
After completing the installation, restart your server and look for the banner in the server console:
┌───────────────────────────────────────────────┐
│ Quasar Crosshair • v1.0.0 • SQL: ready │
│ Quasar Store │
└───────────────────────────────────────────────┘
You are using the latest version of qs-crosshair!SQL: ready means the tables exist and saving works. SQL: n/a means oxmysql was not reachable: players still get a crosshair, but their active crosshair, share codes and admin settings are not saved. Then join your server and work through the first loop:
Take out a pistol and hold right-click. A white cross appears in the centre of the screen and disappears when you stop aiming. Fists, melee weapons and sniper rifles show nothing by default.
Press F4 or type /crosshair. Click any preset — it applies instantly. Aim again to see it.
As an admin, a fifth tab appears. Put your server name on the panel and choose the official crosshair for new players.
Nothing in the Admin tab needs a restart. Every toggle, the official crosshair and the server identity are saved to the database and pushed to every connected player the moment you change them. Only the files under
config/need a restart of the resource.