Santafe Scripts
🎯 SF Crosshair
Configuration

Configuration Guide

Customize SF Crosshair to match your server's needs with these configuration options.

Configuration File

All settings are located in config.lua. Edit this file to customize the crosshair system.

Basic Settings

Command & Keybind

-- Command to open crosshair menu
Config.Command = 'crosshair'
 
-- Default keybind (players can change in FiveM settings)
Config.OpenKey = 'F5'

Options:

  • Command: Any valid command name (without /)
  • OpenKey: Any valid FiveM key code (F1-F12, etc.)

Display Settings

-- Show crosshair only when aiming
Config.ShowOnlyWhenAiming = true
 
-- Disable native GTA crosshair
Config.DisableNativeCrosshair = true

ShowOnlyWhenAiming Options:

  • true: Crosshair appears only when aiming (right-click)
  • false: Crosshair always visible when enabled

DisableNativeCrosshair Options:

  • true: Hides GTA's default crosshair completely
  • false: Keeps GTA crosshair (may overlap with custom)

Sharing System

Distance Configuration

-- Distance in meters to detect nearby players for sharing
Config.ShareDistance = 10.0

Recommended Values:

  • 5.0 - Close proximity only
  • 10.0 - Default, good balance
  • 20.0 - Larger area for busy servers
  • 50.0 - Very large detection range

Custom Images

Configure predefined crosshair images that players can easily select:

Config.CustomImages = {
    {
        name = "Dot",
        url = "https://i.imgur.com/example1.png",
        preview = "Simple dot crosshair"
    },
    {
        name = "Circle", 
        url = "https://i.imgur.com/example2.png",
        preview = "Circle crosshair"
    },
    {
        name = "Cross",
        url = "https://i.imgur.com/example3.png", 
        preview = "Traditional cross style"
    },
    -- Add more images here
}

Image Requirements

Format: PNG with transparent background Size: 64x64 to 128x128 pixels (square format) Hosting: Use reliable hosts like:

  • imgur.com
  • Discord CDN
  • Your own web server
  • GitHub raw files

Adding Custom Images

  1. Upload Image to a reliable host
  2. Get Direct URL (must end in .png)
  3. Add to Config:
{
    name = "Your Name",           -- Display name (short)
    url = "https://your-url.png", -- Direct image URL
    preview = "Description"       -- Brief description
}

Default Crosshair

Set the default crosshair configuration for new players:

Config.DefaultCrosshair = {
    enabled = true,      -- Crosshair enabled by default
    style = 0,          -- Default style (0-15)
    size = 20,          -- Size in pixels
    thickness = 2,      -- Line thickness
    color = "#B0F527",  -- Default color (hex)
    opacity = 100,      -- Opacity percentage
    gap = 4,            -- Gap from center
    outline = true,     -- Outline enabled
    dot = false,        -- Center dot disabled
    customImage = nil   -- No custom image
}

Style Options (0-15)

  • 0: Classic cross with gap
  • 1: Circle outline
  • 2: Solid dot
  • 3: Full cross (no gap)
  • 4: Square with cross
  • 5: Triangle
  • 6: Square outline
  • 7: Diagonal cross
  • 8: Circle with top line
  • 9: Horizontal line only
  • 10: Diamond shape
  • 11: T-shape
  • 12: Dashed circle
  • 13: X-shape
  • 14: Corner brackets
  • 15: Scope-style

Color Options

Use hex color codes:

  • #B0F527 - SantaFe Green (default)
  • #FFFFFF - White
  • #FF0000 - Red
  • #00FF00 - Green
  • #0000FF - Blue
  • #FFFF00 - Yellow
  • #FF00FF - Magenta
  • #00FFFF - Cyan

Advanced Configuration

Performance Settings

For high-population servers, consider these optimizations:

-- Reduce update frequency (in client.lua)
Citizen.Wait(100) -- Change to 200 for less frequent updates
 
-- Limit sharing distance for performance
Config.ShareDistance = 5.0 -- Smaller range = better performance

Database Optimization

For servers with many players, consider database indexing:

-- Add indexes for better performance (optional)
ALTER TABLE crosshair_configs ADD INDEX idx_identifier (identifier);
ALTER TABLE crosshair_favorites ADD INDEX idx_identifier (identifier);
ALTER TABLE crosshair_pins ADD INDEX idx_identifier (identifier);

Server-Specific Customization

Roleplay Servers

-- More realistic settings
Config.ShowOnlyWhenAiming = true
Config.DisableNativeCrosshair = true
Config.ShareDistance = 5.0  -- Closer interaction

PvP Servers

-- Competitive settings
Config.ShowOnlyWhenAiming = false  -- Always visible
Config.DisableNativeCrosshair = true
Config.ShareDistance = 20.0  -- Easier sharing

Casual Servers

-- Relaxed settings
Config.ShowOnlyWhenAiming = false
Config.DisableNativeCrosshair = true
Config.ShareDistance = 15.0

Configuration Validation

After making changes, validate your configuration:

1. Syntax Check

  • Ensure all strings are quoted
  • Check comma placement
  • Verify bracket matching

2. Test Values

  • Start server and check console for errors
  • Test crosshair functionality
  • Verify sharing system works

3. Player Testing

  • Have players test different scenarios
  • Check database saves correctly
  • Verify sharing between players

Configuration Examples

Minimal Setup

Config = {}
Config.Command = 'crosshair'
Config.OpenKey = 'F5'
Config.ShowOnlyWhenAiming = true
Config.DisableNativeCrosshair = true
Config.ShareDistance = 10.0
Config.CustomImages = {}
Config.DefaultCrosshair = {
    enabled = true,
    style = 0,
    size = 20,
    thickness = 2,
    color = "#FFFFFF",
    opacity = 100,
    gap = 4,
    outline = true,
    dot = false,
    customImage = nil
}

Full Featured Setup

Config = {}
Config.Command = 'crosshair'
Config.OpenKey = 'F5'
Config.ShowOnlyWhenAiming = true
Config.DisableNativeCrosshair = true
Config.ShareDistance = 15.0
 
Config.CustomImages = {
    {
        name = "Dot",
        url = "https://i.imgur.com/dot.png",
        preview = "Simple dot"
    },
    {
        name = "Circle",
        url = "https://i.imgur.com/circle.png", 
        preview = "Circle outline"
    },
    {
        name = "Cross",
        url = "https://i.imgur.com/cross.png",
        preview = "Traditional cross"
    }
}
 
Config.DefaultCrosshair = {
    enabled = true,
    style = 0,
    size = 25,
    thickness = 3,
    color = "#B0F527",
    opacity = 90,
    gap = 5,
    outline = true,
    dot = false,
    customImage = nil
}

Troubleshooting Configuration

Common Issues

Config not loading:

  • Check Lua syntax errors
  • Verify file encoding (UTF-8)
  • Ensure no special characters

Images not showing:

  • Test URLs in browser
  • Check image format (PNG required)
  • Verify transparent background

Sharing not working:

  • Check ShareDistance value
  • Verify both players online
  • Test with different distances

Next Steps

  • Usage Guide: Learn how players use the system
  • Sharing System: Understand the PIN-based sharing
  • Customization: Advanced customization options
  • Troubleshooting: Common issues and solutions

Configuration guide by SantaFe Team 🇲🇦

InstallationUsage Guide