Configuration

All configuration is done in config.lua inside the f5_safezones resource folder.

General

config.lua

Config = Config or {}

Config.Locales = "en"          -- Language code (matches files in locales/)
Config.CheckInterval = 100     -- Zone check interval in milliseconds

Option	Type	Default	Description
Locales	string	"en"	Language file to use from locales/ folder
CheckInterval	number	100	How often (ms) the client checks if a player is inside a zone. Lower = more responsive, higher = better performance

Version Check

Automatically checks for updates via the GitHub Releases API on server start.

config.lua

Config.VersionCheck = true                          -- Enable/disable update check
Config.GitHubRepo = 'F5-Studio-FiveM/f5_safezones'   -- GitHub repository (owner/repo)

Option	Type	Default	Description
VersionCheck	boolean	true	Check for updates on server start. Set to false to disable
GitHubRepo	string	'F5-Studio-FiveM/f5_safezones'	GitHub repository in owner/repo format

The version checker compares your local version (from fxmanifest.lua) against the latest GitHub Release using semantic versioning. Console output:

Status	Message
Up to date	[f5_safezones] v2.1.0 — Up to date!
Update available	[f5_safezones] Update available! v2.1.0 -> v2.2.0 + download link
Dev build	[f5_safezones] v2.2.0 — Development build (latest release: v2.1.0)

Default Marker

Controls the default appearance for circle zone markers. Individual zones can override these values.

config.lua

Config.DefaultMarker = {
    type = 1,                                    -- Marker type (see table below)
    color = {r = 245, g = 166, b = 35, a = 100}, -- RGBA color
    scale = {x = 1.0, y = 1.0, z = 1.0},
    height = 30.0,                               -- Marker height
    bobbing = false,                             -- Floating up/down animation
    pulsing = false,                             -- Pulsating size effect
    rotating = false,                            -- Rotation animation
    colorShift = false,                          -- Rainbow color cycling
    autoLevel = true,                            -- Auto-adjust to ground level
    pulseSpeed = 2.0,                            -- Speed of pulse effect
    bobHeight = 0.5,                             -- Height of bobbing motion
    rotationSpeed = 1.0,                         -- Speed of rotation
    renderDistance = 150.0                        -- Distance to render marker
}

Marker Types

Type ID	Name	Description
1	Cylinder	Standard cylinder marker (GTA native ID 1)
2	Circle Fat	Thick circle on the ground (GTA native ID 23)
3	Circle Skinny	Thin circle on the ground (GTA native ID 25)
4	Circle Arrow	Circle with directional arrow (GTA native ID 26)
5	Split Arrow	Split directional arrow (GTA native ID 27)
6	Dome	Custom rendered dome using DrawPoly (not a native marker)

tip

Type 6 (Dome) is rendered using custom polygon drawing, giving a 3D dome effect over the zone. It is more resource-intensive than native markers.

Polygon Marker

Controls the default appearance for polygon zone walls and ground fill.

config.lua

Config.PolygonMarker = {
    wallColor = {r = 245, g = 166, b = 35, a = 50},     -- Wall color
    groundColor = {r = 245, g = 166, b = 35, a = 30},    -- Ground fill color
    wallHeight = 20.0,                                     -- Height of walls
    pulseEffect = false,                                   -- Pulsating walls
    gradientEffect = true,                                 -- Gradient on walls
    cornerBeams = true,                                    -- Vertical beams at corners
    insideOpacity = 0.8                                    -- Wall opacity from inside (0.1-1.0)
}

Collision System

Controls how the ghosting and protection systems work inside safezones.

config.lua

Config.CollisionSystem = {
    range = 100.0,           -- Range to detect vehicles/entities for collision
    explosionRange = 100.0,  -- Range to cancel explosions near safezone players
    vehicleAlpha = 200,      -- Vehicle transparency (0 = invisible, 255 = fully opaque)
    playerAlpha = 200,       -- Player transparency inside safezone
}

Option	Type	Default	Description
range	number	100.0	Maximum distance to detect and ghost vehicles/entities around the player
explosionRange	number	100.0	Distance within which explosions are cancelled near safezone players
vehicleAlpha	number	200	Transparency level for ghosted vehicles (0-255)
playerAlpha	number	200	Transparency level for the player while inside a safezone (0-255)

Performance

Fine-tune update intervals to balance responsiveness and server/client performance.

config.lua

Config.Performance = {
    lodDistances = {
        medium = 150.0               -- Distance threshold for reduced marker quality
    },
    updateIntervals = {
        playerCache = 600,           -- Player position cache refresh (ms)
        markerList = 1000,           -- Which markers to render (ms)
        collisionCheck = 450,        -- Collision entity scan (ms)
        weaponCheck = 250,           -- Weapon switch detection (ms)
        invincibility = 1000,        -- Invincibility state refresh (ms)
        vehicleProtection = 1000     -- Vehicle protection state refresh (ms)
    }
}

Option	Type	Default	Description
lodDistances.medium	number	150.0	Distance beyond which polygon markers render at reduced quality (fewer wall segments, simplified effects)

Performance Tuning

For servers with many players, consider increasing interval values. For competitive servers where responsiveness is key, decrease weaponCheck and collisionCheck.

Marker Presets

Pre-configured marker styles for quick zone setup. Reference these by name when creating zones.

config.lua

Config.MarkerPresets = {
    safe = {
        type = 1,
        color = {r = 245, g = 166, b = 35, a = 100},
        pulsing = true,
        pulseSpeed = 1.0,
        renderDistance = 150.0
    },
    danger = {
        type = 1,
        color = {r = 255, g = 0, b = 0, a = 100},
        pulsing = true,
        bobbing = true,
        pulseSpeed = 3.0,
        bobHeight = 0.5,
        renderDistance = 200.0
    },
    special = {
        type = 4, -- Circle Arrow
        color = {r = 255, g = 215, b = 0, a = 150},
        rotating = true,
        pulsing = true,
        colorShift = true,
        rotationSpeed = 1.5,
        pulseSpeed = 2.0,
        renderDistance = 250.0
    },
    vip = {
        type = 5, -- Split Arrow
        color = {r = 255, g = 215, b = 0, a = 200},
        bobbing = true,
        rotating = true,
        colorShift = true,
        bobHeight = 1.0,
        rotationSpeed = 2.0,
        renderDistance = 300.0
    }
}

Admin Permissions

Players with any of the following ACE permissions will have full admin access to safezone management (admin panel, debug, coordinates).

config.lua

Config.AdminPermissions = {
    'command', 'command.tx', 'txadmin', 'admin', 'moderator',
    'group.admin', 'group.moderator', 'safezones.admin', 'f5_safezones.admin'
}

Additionally, the bridge checks framework-specific permissions:

Framework	Recognized Permissions
QBCore	admin, god (via QBCore.Functions.HasPermission)
ESX	admin, superadmin (via xPlayer.getGroup())
QBox	ACE permissions only (no framework-specific fallback)

Custom Permission

Add 'safezones.admin' or 'f5_safezones.admin' to the list and grant it via ACE to specific staff members without giving them full admin access:

server.cfg

add_ace identifier.discord:123456789 safezones.admin allow

Commands

Enable or disable individual commands and customize their names.

config.lua

Config.Commands = {
    szcoords = {
        name = 'szcoords',
        active = true,
        description = 'Get current coordinates'
    },
    szdebug = {
        name = 'szdebug',
        active = true,
        description = 'Toggle debug mode'
    },
    szadmin = {
        name = 'szadmin',
        active = true,
        description = 'Open admin panel'
    },
    sztoggle = {
        name = 'sztoggle',
        active = true,
        description = 'Toggle zone marker'
    },
    debugrender = {
        name = 'debugrender',
        active = true,
        description = 'Toggle render distance debug'
    },
    setrenderdist = {
        name = 'setrenderdist',
        active = true,
        description = 'Set zone render distance'
    },
    listsafezones = {
        name = 'listsafezones',
        active = true,
        description = 'List all safezones'
    }
}

Command	Default Name	Usage	Description	Requires Admin
szcoords	/szcoords	/szcoords	Copy current coordinates to clipboard	Yes
szdebug	/szdebug	/szdebug [all|active|inactive|<zone_id>]	Toggle debug visualization mode	Yes
szadmin	/szadmin	/szadmin	Open the admin management panel	Yes
sztoggle	/sztoggle	/sztoggle <zone_id>	Toggle marker visibility for a zone	Yes
debugrender	/debugrender	/debugrender	Toggle render distance debug overlay	No
setrenderdist	/setrenderdist	/setrenderdist <zone_id> <distance>	Set render distance for a specific zone	No
listsafezones	/listsafezones	/listsafezones [all|config|custom]	List all zones in F8 console	Yes (except from server console)

To rename a command, change the name field. To disable a command, set active = false.

Audit Logging

Configure the server-side audit logging system. See Debug & Logging for full details.

config.lua

Config.Logging = {
    enabled = true,
    directory = '/data/logs',
    filePrefix = 'safezone-audit',
    retentionDays = 30,
    maxEntries = 500,
    categories = {
        ZONE = true,
        SECURITY = true
    },
    actions = {
        ['zone:create'] = true,
        ['zone:update'] = true,
        ['zone:delete'] = true,
        ['zone:toggle_marker'] = true,
        ['zone:toggle_activation'] = true,
        ['zone:toggle_activation_all'] = true,
        ['security:denied'] = true
    },
    includeIdentifiers = true,
    identifierTypes = { 'steam', 'discord', 'license' },
    ui = {
        showAdminName = true,
        showIdentifiers = true,
        dateFormat = 'DD/MM/YYYY HH:mm:ss'
    }
}

Debug Options

Visual debug marker appearance when debug mode is active:

config.lua

Config.DebugOptions = {
    enabled = false,                                    -- Default debug state
    markerColor = {r = 255, g = 0, b = 255, a = 150},  -- Debug marker color (magenta)
    showCoordinates = true,                             -- Show coordinate labels
    showZoneInfo = true                                 -- Show zone info labels
}

Bridge Logging

Controls logging output from the framework bridge (auto-detection, initialization, errors).

config.lua

Config.BridgeLog = true   -- Enable/disable bridge logs. Errors always show regardless.

Option	Type	Default	Description
BridgeLog	boolean	true	Show bridge initialization logs in console. Error-level logs (^1) always print even when disabled

Bridge logs are prefixed with [f5_safezones:bridge:SERVER] or [f5_safezones:bridge:CLIENT] and are color-coded by level:

Level	Color	Description
error	Red (^1)	Critical failures (always shown)
warn	Yellow (^3)	Non-critical warnings
info	Blue (^5)	Status messages
success	Green (^2)	Successful operations
debug	Blue (^4)	Detailed debug info

Debug

config.lua

Config.Debug = false            -- Master debug toggle (enables console logging)

Config.DebugCategories = {
    INIT = true,
    ZONE = true,
    COLLISION = true,
    NETWORK = true,
    ADMIN = true,
    UI = true,
    PLAYER = true,
    PERFORMANCE = true,
    COMMAND = true,
    ERROR = true,
    SUCCESS = true,
    DATA = true
}

Set Config.Debug = true to enable detailed console output. Disable individual categories to reduce noise.

See Also

• Zone Types — understand circle and polygon zone options
• Zone Creation — create zones using the in-game tools
• Debug & Logging — detailed logging configuration
• Troubleshooting — common configuration issues