Exports & API

legends_safezones provides client and server exports for applying safe zone protections externally — useful for custom integrations like prison systems, event areas, or any scenario where players need safe zone effects outside of a configured zone.

Client Exports

ApplySafezoneEffects

Apply all safe zone protections to the local player from another resource.

exports['legends_safezones']:ApplySafezoneEffects(options)

Parameters:

Parameter	Type	Default	Description
`options`	`table` or `nil`	`nil`	Optional configuration table
`options.antiVDM`	`boolean`	`true`	Enable vehicle ghosting / anti-VDM protection
`options.disableControls`	`boolean`	`true`	Disable attack and melee controls
`options.showUI`	`boolean`	`false`	Show the "SAFE ZONE" UI indicator

Returns: boolean

true — Effects were applied successfully
false — Effects were already active (no action taken)

What it applies:

Damage immunity (entity proofs: fire, explosion, collision, steam, drown)
Health and armor clamping (restores health/armor if non-bypass damage is detected)
Ragdoll prevention
Attack and melee control disabling (configurable)
Vehicle ghosting and collision disabling for fast-moving vehicles (configurable)
Damage event cancellation

Example Usage:

-- Apply all protections with defaults
exports['legends_safezones']:ApplySafezoneEffects()
 
-- Apply with custom options
exports['legends_safezones']:ApplySafezoneEffects({
    antiVDM = true,
    disableControls = true,
    showUI = true
})
 
-- Apply damage immunity only (no VDM ghosting, allow attack controls)
exports['legends_safezones']:ApplySafezoneEffects({
    antiVDM = false,
    disableControls = false
})

RemoveSafezoneEffects

Remove externally-applied safe zone protections from the local player.

exports['legends_safezones']:RemoveSafezoneEffects()

Parameters: None

Returns: boolean

true — Effects were removed successfully
false — No external effects were active (no action taken)

If the player is currently inside an actual configured safe zone when you call this, zone-based protections will remain active. Only the externally-applied effects are removed.

Example Usage:

exports['legends_safezones']:RemoveSafezoneEffects()

IsInSafezone

Check if the local player currently has any safe zone protections active.

local isSafe, source = exports['legends_safezones']:IsInSafezone()

Parameters: None

Returns:

Return	Type	Description
`isSafe`	`boolean`	Whether the player has safe zone protections
`source`	`string`	Source of the protection

Source values:

Value	Description
`"zone"`	Player is inside a configured safe zone
`"external"`	Effects applied via `ApplySafezoneEffects` export
`"both"`	Player is in a zone AND has external effects active
`"none"`	No protections active

Example Usage:

local isSafe, source = exports['legends_safezones']:IsInSafezone()
 
if isSafe then
    print("Player is protected — source: " .. source)
end

Server Exports

ApplySafezoneEffects

Apply safe zone protections to a specific player from the server side.

exports['legends_safezones']:ApplySafezoneEffects(playerId)

Parameters:

Parameter	Type	Description
`playerId`	`number`	The server-side player ID (source)

Returns: boolean

true — Effects were applied successfully
false — Player not found

Example Usage:

-- Apply protections to a player
exports['legends_safezones']:ApplySafezoneEffects(source)

RemoveSafezoneEffects

Remove externally-applied safe zone protections from a specific player.

exports['legends_safezones']:RemoveSafezoneEffects(playerId)

Parameters:

Parameter	Type	Description
`playerId`	`number`	The server-side player ID (source)

Returns: boolean

true — Effects were removed successfully
false — Player had no external effects active

Example Usage:

-- Remove protections from a player
exports['legends_safezones']:RemoveSafezoneEffects(source)

Integration Examples

Prison System

-- server-side: when player is sent to prison
RegisterNetEvent('prison:sendToPrison')
AddEventHandler('prison:sendToPrison', function(playerId, duration)
    -- ... your prison logic ...
    exports['legends_safezones']:ApplySafezoneEffects(playerId)
end)
 
-- server-side: when player is released
RegisterNetEvent('prison:release')
AddEventHandler('prison:release', function(playerId)
    -- ... your release logic ...
    exports['legends_safezones']:RemoveSafezoneEffects(playerId)
end)

Spawn Protection

-- client-side: temporary protection after spawning
RegisterNetEvent('playerSpawned')
AddEventHandler('playerSpawned', function()
    exports['legends_safezones']:ApplySafezoneEffects({
        antiVDM = true,
        disableControls = false,
        showUI = true
    })
 
    -- Remove after 10 seconds
    Citizen.SetTimeout(10000, function()
        exports['legends_safezones']:RemoveSafezoneEffects()
    end)
end)

Conditional Logic Based on Safe Zone State

-- client-side: check before allowing an action
local isSafe, source = exports['legends_safezones']:IsInSafezone()
 
if isSafe then
    print("Cannot perform this action while protected (source: " .. source .. ")")
    return
end

⚠️

Important: If the resource that called ApplySafezoneEffects is stopped or restarted, make sure to call RemoveSafezoneEffects in your onResourceStop handler to prevent players from being permanently protected.

-- Clean up on resource stop
AddEventHandler('onResourceStop', function(resourceName)
    if resourceName == GetCurrentResourceName() then
        exports['legends_safezones']:RemoveSafezoneEffects()
    end
end)

Customization

Entity Proofs (client/editable.lua)

You can customize which damage protections are applied to players inside safe zones by editing client/editable.lua:

EntityProofs = {}
 
EntityProofs.BulletProof = true      -- Protects from bullet damage
EntityProofs.FireProof = true        -- Protects from fire damage
EntityProofs.ExplosionProof = true   -- Protects from explosion damage
EntityProofs.CollisionProof = true   -- Prevents collision interactions
EntityProofs.MeleeProof = true       -- Protects from melee damage
EntityProofs.SteamProof = true       -- Protects from steam damage
EntityProofs.P7 = true               -- Unknown parameter (keep true)
EntityProofs.DrownProof = true       -- Protects from drowning

⚠️

CollisionProof Note: If players experience issues entering vehicles or accessing trunks inside safe zones, set EntityProofs.CollisionProof = false. This allows normal vehicle interactions while still protecting from damage.

Zone Configuration

Zones are defined in config/config.lua. Each zone supports these options:

{
    name = "ZoneName",           -- Unique identifier
    debug = false,               -- Visualize zone boundaries
    points = { ... },            -- vector2 coordinates
    minZ = 0.0,                  -- Ground level
    maxZ = 100.0,                -- Ceiling level
    allWeapons = true,           -- Block all weapons
    weapons = {},                -- Specific weapons to block
    bypassJobs = { "police" },   -- Jobs that can use weapons
    antiVDM = true               -- Vehicle damage protection
}

Weapon Hash Reference

When blocking specific weapons, use GTA V weapon hashes:

-- Example: Block only heavy weapons
weapons = {
    `WEAPON_ASSAULTRIFLE`,
    `WEAPON_CARBINERIFLE`,
    `WEAPON_SNIPERRIFLE`,
    `WEAPON_RPG`,
    `WEAPON_GRENADELAUNCHER`,
}

Common weapon hashes:

Hash	Weapon
`WEAPON_PISTOL`	Pistol
`WEAPON_COMBATPISTOL`	Combat Pistol
`WEAPON_SMG`	SMG
`WEAPON_ASSAULTRIFLE`	Assault Rifle
`WEAPON_SNIPERRIFLE`	Sniper Rifle
`WEAPON_PUMPSHOTGUN`	Pump Shotgun
`WEAPON_RPG`	RPG
`WEAPON_KNIFE`	Knife
`WEAPON_BAT`	Baseball Bat

For a complete list of weapon hashes, see the FiveM Weapons Reference (opens in a new tab).

Localization

Language strings are stored in locales/en.json:

{
  "RestrictedArea": "You are not allowed to enter this area with that weapon",
  "SafeZoneTitle": "SAFE ZONE",
  "SafeZoneSubtitle": "Weapons & Violence Disabled"
}

To add a new language:

Create a new file (e.g., locales/es.json)
Translate all strings
Set Config.Lang = "es" in config

Custom UI

The safe zone UI can be customized by editing files in the ui/ folder:

ui/index.html - HTML structure
ui/style.css - Styling
ui/script.js - JavaScript logic

Integration Tips

Creating Zones for Custom MLOs

When adding zones for custom interiors:

Enable debug = true on your zone
Use PolyZone creator tools to get coordinates
Adjust minZ and maxZ to cover all floors
Test with different weapon types
Set debug = false for production

Job Bypass Recommendations

Common job bypass configurations:

-- Hospital: Allow medical and police
bypassJobs = { "police", "ambulance", "doctor" }
 
-- Government building: Only police
bypassJobs = { "police" }
 
-- Private security area
bypassJobs = { "police", "security" }

Need Help?

Join our Discord for support: discord.gg/lgnds (opens in a new tab)

Configuration 🪂 Airdrop System