Administrator Guide

This guide is for server administrators who manage safe zones using ARS SafeZone. It covers zone creation, configuration, permissions, and common admin tasks.

---

Table of Contents

1. Admin Commands Overview
2. Creating Safe Zones
3. Managing Zone Settings
4. Deleting Safe Zones
5. Admin Permissions
6. Troubleshooting
7. Best Practices

---

1. Admin Commands Overview

ARS SafeZone provides three main commands for managing safe zones:

Command	Description
/<createsafezone>	Opens the 3D zone editor to create a new safe zone
/<deletesafezone>	Deletes the safe zone you are currently standing in
/<zonesetting>	Opens the settings menu for the current zone

Note: These commands require admin permissions. See Admin Permissions for configuration details.

---

2. Creating Safe Zones

Step-by-Step Creation Process

1. Start the Creation Command

   • Type /<createsafezone> in chat
   • The script will automatically enable no-clip mode
   • On-screen instructions will appear

2. Place Zone Vertices

   • Left Click: Add a vertex at your crosshair position
   • Right Click: Remove the last vertex
   • Create at least 3 vertices to form a polygon

3. Adjust Zone Height

   • Hold Scroll Down to decrease zone thickness
   • Hold Scroll Up to increase zone thickness
   • The default thickness is 50.0 units

4. Complete the Zone

   • Press Enter to finish creating the polygon
   • The configuration dialog will appear

5. Configure Zone Settings Fill in the configuration form:

   • Zone Name: Unique identifier (spaces will be removed)
   • Zone Label: Display name for the zone
   • Bypass Admin: Allow admins to ignore zone restrictions
   • Disable Weapons: Prevent weapon usage in the zone
   • Disable Vehicle Damage: Protect vehicles from damage
   • Player Invisible: Make players invincible in the zone
   • Allow Whitelisted Weapons: Permit globally whitelisted weapons
   • Allow Whitelisted Job Weapons: Permit job-specific weapons
   • Enable Vehicle Speed Limit: Enforce maximum vehicle speed
   • Vehicle Speed Limit: Set the speed limit value
   • Entry Message: Custom message shown when entering
   • Exit Message: Custom message shown when exiting

No-Clip Controls During Creation

While creating a zone, you can use these controls:

Key	Action
W	Move forward
S	Move backward
A	Move left
D	Move right
Q	Move up
E	Move down
Left Control	Slow movement speed
Left Shift	Fast movement speed
Left Alt	Very fast movement speed
ESC	Cancel zone creation

Tip: The first vertex’s Z-coordinate determines the height for all vertices, creating a flat polygon zone.

---

3. Managing Zone Settings

Opening Zone Settings

1. Stand inside the safe zone you want to modify
2. Type /<zonesetting> in chat
3. The zone settings dialog will appear

Available Settings

Each setting can be toggled or modified:

Setting	Description	Default
Zone Label	Display name shown to players	Set during creation
Bypass Admin	Admins ignore all zone restrictions	false
Disable Weapons	Remove weapons and disable firing	true
Disable Vehicle Damage	Protect vehicles from damage	true
Player Invisible	Make players invincible	false
Allow Whitelisted Weapons	Allow globally whitelisted weapons	true
Allow Whitelisted Job Weapons	Allow job-specific weapons	true
Enable Vehicle Speed Limit	Enforce vehicle speed limit	false
Vehicle Speed Limit	Max speed in configured unit	30
Entry Message	Message when entering	Default locale text
Exit Message	Message when exiting	Default locale text

Real-time Updates

Changes made through the settings menu take effect immediately:

• All connected players receive updated zone data
• No server restart required
• Zone behavior changes instantly

Understanding Bypass Admin

The Bypass Admin setting allows administrators configured in Config.AdminWithGroup, Config.AdminWithLicense, or Config.AdminWithIdentifier to ignore all zone restrictions.

When enabled, admins can:

• Use weapons without them being removed
• Damage vehicles even if vehicle damage is disabled
• Exceed vehicle speed limits
• Take damage even if player invincibility is enabled

When disabled, admins are subject to:

• Weapon removal and firing restrictions
• Vehicle damage protection
• Speed limit enforcement
• Player invincibility effects

Tip: Use this setting for zones where admins need full control (e.g., administrative areas, spawn points). Disable it for zones where admins should follow the same rules as players (e.g., public meeting areas).

---

4. Deleting Safe Zones

Zone Deletion Process

1. Stand inside the safe zone you want to delete
2. Type /<deletesafezone> in chat
3. A confirmation dialog will appear
4. Click Confirm to delete or Cancel to abort

Warning: Zone deletion is permanent. The zone will be removed from the database immediately.

Verification

After deletion:

• The zone no longer affects players
• Database record is removed
• All clients receive zone removal notification

---

5. Admin Permissions

Configure admin access in shared/main.lua using one or more methods.

Group-Based Permissions

Best for QBCore servers with built-in permission groups:

Config.AdminWithGroup = {
    ['admin'] = true,
    ['god']   = true,
}

ESX: Checks the player’s group using xPlayer.getGroup() QBCore: Checks permissions using QBCore.Functions.HasPermission()

License-Based Permissions

Use player licenses for more granular control:

Config.AdminWithLicense = {
    ['license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'] = true,
}

Find player licenses in your server logs or use admin tools.

Identifier-Based Permissions

Grant access to specific characters:

Config.AdminWithIdentifier = {
    ['xxxxxxxx'] = true,
}

ESX: Uses character identifier from the users table QBCore: Uses citizen ID

Checking Permissions

The script checks permissions in this order:

1. Group-based permissions
2. License-based permissions
3. Identifier-based permissions

The first match grants admin access.

---

6. Troubleshooting

Zone Not Working

Symptoms: Players can use weapons or vehicles behave normally inside a zone.

Solutions:

• Verify zone options: Check that disableWeapons or disableVehicleDamage are enabled
• Check player whitelist: Verify the player’s weapon is not whitelisted
• Admin bypass: Ensure the player is not an admin with bypass enabled
• Debug mode: Enable Config.Debug = true and check console for errors

Cannot Create Zones

Symptoms: The /<createsafezone> command shows “no permission” error.

Solutions:

• Verify your admin configuration in Config.AdminWithGroup, Config.AdminWithLicense, or Config.AdminWithIdentifier
• Ensure you are using the correct identifier format
• Restart the script after making configuration changes
• Check server console for permission check errors

Zone Editor Not Responding

Symptoms: No-clip mode does not activate or vertices cannot be placed.

Solutions:

• Ensure ox_lib is working correctly
• Check for conflicting no-clip resources
• Disable debug mode: Config.Debug = false
• Restart the resource

Speed Limit Not Enforcing

Symptoms: Vehicles can exceed the configured speed limit.

Solutions:

• Verify enableVehicleSpeedLimit is enabled for the zone
• Check that vehicleSpeedLimit is greater than 0
• Ensure the player is in a vehicle (not on foot)
• Test with different vehicles to verify the feature

Zone Not Appearing After Creation

Symptoms: Zone is created but does not affect players.

Solutions:

• Verify the zone was saved to the database: SELECT * FROM ars_safezone;
• Check server console for errors during zone creation
• Restart the resource to reload zones from the database
• Enable debug mode: Config.Debug = true

---

7. Best Practices

Zone Design

• Overlap Prevention: Avoid overlapping zones to prevent conflicts
• Zone Size: Keep zones reasonably sized for better performance
• Zone Placement: Place zones away from critical game areas
• Height Consideration: Set appropriate thickness for 3D zones

Configuration

• Use Default Options: Configure Config.DefaultSafeZoneOptions for consistent zones
• Weapon Whitelists: Add only necessary weapons to reduce maintenance
• Speed Limits: Set reasonable speed limits for server performance
• Messages: Use clear, concise entry/exit messages

Admin Management

• Grant Minimum Access: Use the most restrictive permission method that works
• Document Permissions: Keep a record of admins and their access method
• Regular Reviews: Periodically review admin permissions
• Backup Zones: Regularly backup the ars_safezone database table

Performance

• Limit Zone Count: Avoid creating excessive numbers of zones
• Optimize Polygon Complexity: Use fewer vertices for simpler zones
• Monitor Resource Usage: Check resource performance on busy servers

---

Quick Reference

Common Tasks

Task	Command	Notes
Create zone	/<createsafezone>	Uses 3D editor
Edit zone	/<zonesetting>	Must be in zone
Delete zone	/<deletesafezone>	Must be in zone
Enable debug	Edit config	Set Config.Debug = true
Add admin	Edit config	Use license/identifier/group

Zone Options Reference

Option	Effect
disableWeapons	Players cannot fire weapons
disableVehicleDamage	Vehicles cannot take damage
disablePlayerInvisible	Players become invincible
allowWhitelistedWeapons	Whitelisted weapons allowed
allowWhitelistedJobWeapons	Job weapons allowed
enableVehicleSpeedLimit	Speed limit enforced
bypassAdmin	Admins ignore restrictions

---

Player Information

For information about what players experience when entering and leaving safe zones, see the Player Guide. This guide explains weapon removal, vehicle protection, speed limits, and notifications from a player’s perspective.

---

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.