Documentation
Fix Crosshair Creator problems on your FiveM server: no crosshair when aiming, missing admin tab, SQL not ready, hitmarker and fire feedback issues, share code errors and debug output.
What goes wrong most often, what it actually means, and what to do about it. Most of these come down to load order, an ace, or a setting in the Admin tab.
The script waited 30 seconds for oxmysql and gave up. Make sure ensure oxmysql is in server.cfg, above ensure qs-crosshair, and that oxmysql itself connects to your database — its own error is a few lines higher in the console.
The tables could not be created or reached in time. Players still get a crosshair, but their active crosshair, share codes and admin settings are not saved. Look for a line starting [qs-crosshair] SQL bootstrap failed — it names the statement that failed, usually a database user without CREATE rights. Run [sql]/install.sql by hand in that case.
The server does not see the player as an admin. They need one of: the group in Config.Admin.AceGroup, the command ace, or qs-crosshair.admin. Check the identifier in add_principal is their license: one, then close and reopen the panel — admin status is checked on every open.
If the console prints Config.Admin.AceGroup = "…" — expected "group.*" or "principal.*", the value in config/main.lua is not a group name.
Check the folder is named exactly qs-crosshair. The script calls its own exports by that name; a renamed copy cannot reach itself, so the panel opens but the active crosshair is never applied.
Files under config/ are read when the resource starts. Restart it with ensure qs-crosshair. Settings in the Admin tab, on the other hand, apply instantly and override nothing in the files.
Work through these in order:
The master switch in the panel header says Crosshair Off. New players start with it off when Config.EnabledByDefault = false.
The player is holding fists, a melee weapon or a sniper rifle, which are hidden by default in the Admin tab.
The opacity in the Build tab is at or near 0.
Another crosshair or HUD resource is drawing over it or hiding the overlay.
Correct behaviour. The client waits until the player is fully in the session, then asks the server for their crosshair, retrying for up to about ten seconds while the database warms up. A slow database on a cold boot is the usual reason it takes longer than a second.
An admin switched it off in the Admin tab. Disabled features are removed from every player's panel on purpose, without a lock or a label.
Either the active shape is a dot — there is nothing to expand, so the switch is disabled — or the weapon is not losing ammo. Shots are detected by the magazine going down, so a weapon with infinite ammo from another script never triggers it.
It only marks damage the player aimed at. Bullets that auto-aim curves into somebody away from the centre of the reticle are ignored on purpose, and so are targets that were already dead. It also marks once per bullet, so a shotgun blast shows a single flash.
It counts the magazine, not the reserve, and only while aiming. Melee weapons, grenades and weapons without a magazine never show it. The thresholds are HalfMagRatio and CriticalRounds in config/dynamics.lua.
The official crosshair is handed to a player the first time they open the panel, and only once per licence. Players who used the panel before it was set keep their own. Check it is set — the Admin tab shows the current one — and ask the player to open the panel.
The player has Config.Library.MaxBuilds builds saved (50 by default). Delete one, or raise the limit and restart the resource.
Names must be between 1 and Config.Library.MaxNameLength characters (32 by default).
The other player is further than the radius (Config.Share.DefaultRadiusM, 30 m), or in a different routing bucket — another instance, an apartment, a minigame. Only the five closest are listed. If the list shows Cooling down…, wait two seconds between refreshes.
The recipient did not answer within Config.Share.TTLSeconds (60 seconds). If nothing reached them at all, the sender hit the limit of five sends a minute, or one of the two changed routing bucket in between.
A request to the server timed out — usually a slow or overloaded database. The panel keeps working with what it already has; reopen it in a moment.
What the Library says when a QSR-XXXX code cannot be imported:
Message | Means |
|---|---|
Invalid code format. Expected QSR-XXXX. | The text pasted is not a code — often a missing part or a stray space. Ask for it again. |
Code not found | It is older than 30 days, it came from another server, or the sender never pressed Copy — copying is what registers it. |
Unknown code | The server has no build for it. Ask the sender to copy it again in game. |
This code is already in your Library. | Nothing to import — it was added before. |
Server offline / Network error | The lookup did not get an answer. Try again in a moment. |
A code that collides with a different build already registered under the same code is refused rather than overwriting it; share that one by sending it to a nearby player instead.
For anything not covered here, turn on debug output in config/main.lua and restart the resource:
Config.Debug = trueBoth consoles then print a tagged line for every step — [qs-crosshair][SERVER][state] for saves and loads, [CLIENT][hydrate] for restoring the crosshair on join, [CLIENT][aim] for aim changes and [CLIENT][dyn] for the weapon class and the dynamic behaviours. Read the client side in F8. Turn it back off afterwards: it is meant for troubleshooting and fills the console.
Still stuck? Open a ticket and include the startup banner, the lines from the server console and the F8 console with
Config.Debugon, and the steps that reproduce the problem.