Troubleshooting

Common issues and solutions for SF-Crosshair.

Common Issues

Crosshair Not Showing

Problem: The crosshair doesn't appear when aiming.

Solutions:

1. Check if the script is enabled in config:

   Config.DefaultEnabled = true

2. Verify the crosshair is enabled in settings (F7 → Settings tab)

3. Make sure you're using a weapon (crosshair shows with all weapons including hands)

4. Check server console for any errors during resource start

UI Panel Not Opening

Problem: Pressing F7 doesn't open the crosshair panel.

Solutions:

1. Check if another resource is using the same keybind
2. Verify the keybind in config:

   Config.OpenKey = 'F7'
3. Try restarting the resource: restart sf-crosshair
4. Check F8 console for JavaScript errors

Database Issues

Problem: Favorites or sharing not working.

Solutions:

1. Ensure the database table was created:

   -- Run the crosshair.sql file

2. Check server console for database connection errors

3. Verify your framework (ESX/QBCore) is properly configured

Sharing Problems

Problem: Can't share crosshairs or receive shared crosshairs.

Solutions:

1. Make sure both players are online
2. Check if the crosshair is saved in favorites (only favorites can be shared)
3. Verify the PIN is correct (6 digits)
4. For nearby sharing, ensure players are within 10 meters

Performance Issues

Problem: FPS drops or lag when using crosshair.

Solutions:

1. Reduce crosshair update frequency in config:

   Config.UpdateInterval = 100 -- Increase value for better performance

2. Use simpler crosshair styles (styles 0-3 are most optimized)

3. Disable custom images if not needed

Custom Images Not Loading

Problem: Custom crosshair images don't appear.

Solutions:

1. Verify the image URL is accessible and returns a valid image
2. Check if the URL uses HTTPS (required for security)
3. Ensure the image format is supported (PNG, JPG, GIF, SVG)
4. Try using predefined images from config first

Framework Compatibility

ESX Issues

• Ensure ESX is fully loaded before starting sf-crosshair
• Check es_extended resource is running
• Verify player data is properly loaded

QBCore Issues

• Ensure QBCore is fully loaded before starting sf-crosshair
• Check qb-core resource is running
• Verify player data is properly loaded

Resource Conflicts

Common Conflicting Resources

• Other crosshair scripts
• UI frameworks that override NUI focus
• Resources that use the same keybinds

Resolution Steps

1. Stop conflicting resources temporarily
2. Test sf-crosshair functionality
3. Adjust keybinds if necessary
4. Contact support if conflicts persist

Getting Help

If you continue experiencing issues:

1. Check Logs: Always check both server console and F8 client console for errors
2. Restart Resource: Try restart sf-crosshair in server console
3. Update Script: Ensure you're using the latest version
4. Contact Support: Join our Discord for technical support

Support Channels

• Discord: discord.gg/gsUpFV3KgR (opens in a new tab)
• Store: santafedev.store (opens in a new tab)

Information to Provide

When seeking support, please provide:

• Server framework (ESX/QBCore) and version
• Error messages from console
• Steps to reproduce the issue
• Server artifacts version
• Other installed resources that might conflict

Version Information

You can check your current version in the About tab of the crosshair panel or in the server console when the resource starts.

The script includes automatic version checking that will notify you of available updates.