Santafe Scripts
🎯 SF Crosshair
Installation

Installation Guide

Follow these steps to install SF Crosshair on your FiveM server.

Prerequisites

Before installing, ensure you have:

  • FiveM Server with latest artifacts
  • mysql-async resource installed and running
  • ESX or QBCore framework (recommended)
  • Database access for SQL import

Step 1: Download & Extract

  1. Download the SF Crosshair resource from your purchase
  2. Extract the SF-Crosshair folder to your server's resources directory
  3. Ensure the folder structure looks like this:
resources/
└── SF-Crosshair/
    ├── client.lua
    ├── server.lua
    ├── config.lua
    ├── fxmanifest.lua
    ├── crosshair.sql
    ├── README.md
    └── web/
        └── out/
            └── (compiled web files)

Step 2: Database Setup

Import the database tables using the provided SQL file:

Method 1: phpMyAdmin

  1. Open phpMyAdmin in your browser
  2. Select your server's database
  3. Click "Import" tab
  4. Choose the crosshair.sql file
  5. Click "Go" to execute

Method 2: Command Line

mysql -u username -p database_name < crosshair.sql

Method 3: HeidiSQL

  1. Open HeidiSQL and connect to your database
  2. Select your database
  3. Go to File > Load SQL file
  4. Select crosshair.sql and execute

The following tables will be created:

  • crosshair_configs - Player crosshair configurations
  • crosshair_favorites - Saved favorite crosshairs
  • crosshair_pins - Unique PINs for sharing system

Step 3: Server Configuration

Add SF Crosshair to your server.cfg:

# Add this line to your server.cfg
ensure SF-Crosshair

# Make sure mysql-async starts before SF-Crosshair
ensure mysql-async
ensure SF-Crosshair

Important: Ensure mysql-async starts before SF-Crosshair to avoid database connection issues.

Step 4: Framework Detection

SF Crosshair automatically detects your framework:

ESX Servers

  • No additional configuration needed
  • Automatically detects es_extended export
  • Uses ESX character names in sharing system

QBCore Servers

  • No additional configuration needed
  • Automatically detects qb-core export
  • Uses QBCore character names in sharing system

Standalone Servers

  • Works without framework
  • Limited to Steam names for sharing
  • All other features fully functional

Step 5: Configuration (Optional)

Edit config.lua to customize the system:

-- Basic Settings
Config.Command = 'crosshair'        -- Command to open menu
Config.OpenKey = 'F5'               -- Default keybind
Config.ShowOnlyWhenAiming = true    -- Show only when aiming
Config.DisableNativeCrosshair = true -- Disable GTA crosshair
 
-- Sharing Settings
Config.ShareDistance = 10.0         -- Distance for nearby sharing
 
-- Custom Images (optional)
Config.CustomImages = {
    {
        name = "Dot",
        url = "https://example.com/dot.png",
        preview = "Simple dot crosshair"
    },
    -- Add more images here
}

Step 6: Start Server

  1. Save all configuration files
  2. Restart your FiveM server
  3. Check server console for any errors
  4. Look for success messages: 
    [SF Crosshair] Database tables checked/created successfully
[SF Crosshair] ESX Framework detected (or QBCore)
[SF Crosshair] v1.0 - Server loaded successfully

Step 7: Test Installation

  1. Join your server
  2. Use /crosshair command or press F5
  3. The crosshair menu should open
  4. Test basic functionality:
    • Change crosshair style
    • Adjust settings
    • Save a favorite
    • Check your PIN in Share tab

Verification Checklist

✅ Database Tables Created

  • Check that the three tables exist in your database

✅ Resource Started

  • Verify SF-Crosshair appears in server console startup

✅ Framework Detected

  • Look for framework detection message in console

✅ Menu Opens

  • Test /crosshair command works

✅ Settings Save

  • Make changes and rejoin to verify persistence

Common Installation Issues

Resource Not Starting

  • Check fxmanifest.lua exists and is valid
  • Ensure resource name matches folder name exactly
  • Verify ensure SF-Crosshair is in server.cfg

Database Errors

  • Confirm mysql-async is running before SF-Crosshair
  • Check database connection in server.cfg
  • Verify SQL file imported successfully
  • Check MySQL user permissions

Menu Not Opening

  • Test different keybinds in case F5 is conflicting
  • Check server console for Lua errors
  • Verify web files exist in web/out/ folder

Framework Not Detected

  • Ensure ESX/QBCore is running before SF-Crosshair
  • Check export names match your framework version
  • Verify framework is properly configured

Next Steps

Once installed successfully:

  1. Configure - Customize settings in Configuration
  2. Learn Usage - Read the Usage Guide
  3. Setup Sharing - Understand the Sharing System
  4. Customize - Explore Customization Options

Support

If you encounter issues during installation:

Installation guide by SantaFe Team 🇲🇦

OverviewConfiguration