Administrator Guide

ARS Gang System - Administrator Guide

This guide is for server administrators who manage the ARS Gang System. It covers admin tools, commands, and configuration options.

---

1. Accessing Admin Tools

Opening the Admin Menu

There are two ways to access the admin menu:

Method	Default Binding	Configurable
Keybind	F10	Config.AdminMenu.Keybind.DefaultMapping
Command	/admingangmenu	Config.AdminMenu.Command.String

Permission Requirements

Admin access is controlled through two mechanisms defined in shared/config.lua:

Method 1: ACE Permissions (Recommended)

Config.AdminMenu.Permissions = { 'admin', 'god' }

Players with any of these ACE permissions will have admin access. Add permissions via your server.cfg:

add_ace group.admin "admin" allow
add_principal identifier.steam:YOUR_STEAM_ID group.admin

Method 2: License Whitelist

Config.AdminMenu.License = {
    ['license:YOUR_LICENSE_HERE'] = true,
}

To find a player’s license:

1. Have them run /getlicense (if available)
2. Check your core framework’s database
3. Look in your server console when they connect
4. You can also find it in TXAdmin’s player list under “Identifiers”

Note: If both methods are configured, a player only needs to match one to gain access.

---

2. Gang Management

Creating New Gangs

1. Open the admin menu (F10 or /admingangmenu)
2. Click “Create Gang”
3. Fill in the required information:

Field	Description	Requirements
Gang Tag	Short identifier (max 4 characters)	Unique, alphanumeric
Gang Name	Display name	Any text
Leader Player ID	Server ID of the gang leader	Must be online
Color	Gang color for UI/blips	Hex color code (e.g., #eb4034)

4. Click confirm to create the gang

The leader will automatically be added as a member with the highest rank (Kingpin by default).

Viewing All Gangs

1. Open the admin menu
2. Click “View All Gangs”
3. A list displays all gangs with their:
   • Tag (ID)
   • Leader
   • XP
   • Cash

Click any gang to open its management menu.

Managing Existing Gangs

After selecting a gang from the list, you can:

Adjusting XP

1. Click “Adjust XP”
2. Choose Increase or Decrease
3. Enter the amount
4. Confirm the change

Note: XP cannot go below 0.

Adjusting Cash

1. Click “Adjust Cash”
2. Choose Increase or Decrease
3. Enter the amount
4. Confirm the change

Note: Cash cannot go below 0.

Changing Gang Leader

1. Click “Change Gang Leader”
2. Select a player from the online players list
3. Confirm the change

The new leader will receive the highest rank, and the previous leader will be demoted to the lowest rank.

Toggling Gang Status

1. Click “Toggle Gang Status”
2. Choose:
   • Disable Gang - Prevents members from accessing gang features
   • Enable Gang - Restores full access

When a gang is disabled:

• Members cannot access gang markers (garage, stash, locker)
• The gang won’t appear in turf war participation
• XP/cash systems are paused

Deleting Gangs

Warning: This action is permanent and cannot be undone!

1. Click “Delete Gang”
2. You will see a confirmation dialog
3. Click Confirm to delete or Decline to cancel

Deleting a gang:

• Removes all gang data from the database
• Removes all gang markers
• Kicks all members from the gang

---

3. Territory Administration

Creating Territories

Use the /createterritory command to create new gang territories.

/createterritory

Requires: group.admin ACE permission

Drawing Process

The territory creation uses an interactive PolyZone drawing mode:

1. Enter territory name in the dialog that appears
2. NoClip mode activates automatically for easy positioning
3. Left-click to add vertices to the polygon
4. Right-click to remove the last vertex
5. Mouse wheel up/down to adjust zone height (maxZ)
6. Press ENTER to finish the polygon (requires minimum 3 vertices)
7. Position the Airdrop NPC - Left-click to confirm location
8. Position the Airdrop crate - Left-click to confirm drop location

Controls During Creation

Control	Action
Left Mouse Click	Add vertex / Confirm position
Right Mouse Click	Remove last vertex
Mouse Wheel Up	Decrease zone height
Mouse Wheel Down	Increase zone height
ENTER	Finish polygon / Confirm
ESC	Cancel creation

Tip: The PolyZone preview shows the territory boundaries in real-time with a debug grid.

Removing Territories

/removeterritory [name]

Requires: group.admin ACE permission

Example:

/removeterritory downtown

This removes the territory from both the database and all clients. Any airdrop NPCs associated with the territory will be deleted.

Adding Control Points

Manually add territory control points for a gang:

/addterritorycontrol [territory] [gangtag] [points]

Requires: group.admin ACE permission

Parameter	Description	Default
territory	Territory name (required)	-
gangtag	Gang tag (required)	-
points	Points to add (optional)	50

Example:

/addterritorycontrol downtown VGS 75

Notes:

• Points are capped at 100 maximum
• Adding points to one gang reduces other gangs’ points by 1 per point added
• If a gang had 100 points, they lose control

---

4. Turf War Administration

Opening the Turf War Admin Menu

/turfwarmarker

Requires: group.admin ACE permission

This opens a menu showing all turf war zones with their status:

• Active/Inactive state
• Cooldown remaining
• Time since last war

Creating Turf War Zones

1. Open the turf war admin menu (/turfwarmarker)
2. Click “Create New Zone”
3. Fill in the zone details:

Field	Description	Default	Limits
Name	Internal identifier	-	Required
Label	Display name	-	Required
Radius	Zone radius in meters	100	50-500
Max Members per Gang	Limits how many players per gang can participate	10	1-50
Cash Reward	Winner cash prize	50000	Min 1000
XP Reward	Winner XP prize	500	Min 100
Cooldown	Minutes between wars	60	Min 10

4. Placement Mode:
   • NoClip activates automatically
   • Move to desired location
   • A preview sphere shows the zone
   • Left-click to place the zone
   • ESC to cancel

Warning: Avoid creating or editing zones while a turf war is active in that zone; the system blocks edits/deletions until the war concludes or the zone is manually disabled.

Editing Turf War Zones

1. Open the admin menu
2. Click on a zone to select it
3. Click “Edit”
4. Modify any of the following:
   • Label
   • Radius
   • Max Members per Gang
   • Cash Reward
   • XP Reward
   • Cooldown
   • Zone Enabled (checkbox)

Zone Enabled controls whether players can start a turf war in that zone. Turn it off to temporarily disable the zone without deleting it.

Warning: Changes to an active zone will be rejected until the current turf war finishes. Disable the zone or wait for the timer to end before updating.

Teleporting to Zones

1. Select a zone from the menu
2. Click “Teleport”
3. You will be teleported to the zone center

Deleting Zones

Warning: This action is permanent!

1. Select a zone from the menu
2. Click “Delete”
3. Confirm the deletion in the dialog

Previewing Zones

When the admin menu is open:

• All zones are displayed as sphere debug overlays
• Selected zones appear in orange/red
• Other zones appear in grey
• Previews clear when the menu closes

---

5. Configuration Overview

Key Configuration Options

All settings are in shared/config.lua:

Admin Settings

Config.AdminMenu = {
    Command = { Enable = true, String = 'admingangmenu' },
    Keybind = { Enable = true, DefaultMapping = 'F10' },
    Permissions = { 'admin', 'god' },
    License = {}
}

XP Settings

Config.AirdropXP = { Enable = true, Reward = 150 }
Config.TerritoryXP = {
    Enable = true,
    Passive = { Enable = true, IntervalMinutes = 30, PerTerritory = 10 },
    CaptureReward = 50
}
Config.PvPXP = { Enable = true, KillReward = 25, NotifyKiller = true }
Config.DailyXPBonus = { Enable = true, Hours = 24, MinMembers = 3, Amount = 100 }

Cooldown Settings

Config.GangMarkers.garage.cooldown = { enable = true, time = 60 }  -- seconds
Config.GangMarkers.stash.cooldown = { enable = true, time = 60 }
Config.GangMarkers.locker.cooldown = { enable = true, time = 60 }

Cost Settings

Config.GangMarkers.garage.cost = { xp = 100, cash = 5000 }
Config.GangMarkers.stash.cost = { xp = 100, cash = 5000 }
Config.GangMarkers.locker.cost = { xp = 100, cash = 5000 }

Turf War Settings

Config.TurfWars = {
    Enable = true,
    MinimumMembers = 3,      -- Min members online to start war
    MinimumGangs = 2,        -- Min gangs to proceed (including initiator)
    JoinCountdown = 2,       -- Minutes for registration phase
    WarDuration = 15,        -- Minutes for active war
    PointsPerSecond = 1,     -- Points per player per 10 seconds in zone
    PointsPerKill = 5,       -- Points per rival kill
    RespawnDelay = 3,        -- Seconds before respawning
    InvulnerabilityTime = 5, -- Seconds of invulnerability after respawn
    DefaultCooldown = 60,    -- Minutes between wars at same zone
    BuffDuration = 24        -- Hours victory buffs last
}

Debug Mode

Config.DebugMode = false  -- Set to true for verbose logging

---

6. Database Tables Reference

ars_gangsystem

Main gang data storage.

Column	Type	Description
tag	VARCHAR(100)	Primary key, gang identifier
name	VARCHAR(100)	Gang display name
color	VARCHAR(100)	Hex color code
xp	INT	Current XP
cash	INT	Current cash balance
leader	VARCHAR(100)	Leader’s identifier
ranks	LONGTEXT	JSON array of rank names
members	LONGTEXT	JSON array of member data
markers	LONGTEXT	JSON object of gang markers
rackets	LONGTEXT	JSON array of racket data
active_buffs	LONGTEXT	JSON: Active victory buffs (e.g., {turfwar: {expires_at: timestamp, buffs: {...}}})
disabled	TINYINT(1)	0 = active, 1 = disabled

ars_gangsystem_territories

Territory/zone data.

Column	Type	Description
name	VARCHAR	Territory identifier (primary key)
label	VARCHAR	Display name
zone	LONGTEXT	JSON: { poly, minZ, maxZ }
points	LONGTEXT	JSON: { [gangTag]: points }
airDropNpc	LONGTEXT	JSON: NPC position vector4
airDropLocation	LONGTEXT	JSON: Drop location vector3

ars_gangsystem_member_stats

Individual member statistics and contributions.

Column	Type	Description
identifier	VARCHAR(50)	Primary key, player identifier
kills	INT	PvP kill count
drugs_sold	INT	Drug sales count
rackets_completed	INT	Rackets completed
airdrops_looted	INT	Airdrops looted
last_updated	TIMESTAMP	Last update time

Note: The total_score field is calculated dynamically by CalculateTotalScore() export and is not stored in the database.

ars_gangsystem_turfwars

Turf war zone definitions.

Column	Type	Description
id	INT	Auto-increment primary key
name	VARCHAR(50)	Internal zone name
label	VARCHAR(100)	Display name
coords	LONGTEXT	JSON: { x, y, z }
radius	FLOAT	Zone radius in meters
rewards	LONGTEXT	JSON: { winner_cash, winner_xp }
cooldown_minutes	INT	Cooldown between wars
max_members_per_gang	INT	Maximum members per gang in war
active	TINYINT(1)	1 = active, 0 = inactive
created_at	TIMESTAMP	Creation timestamp

ars_gangsystem_turfwar_history

Historical war records.

Column	Type	Description
id	INT	Auto-increment primary key
zone_id	INT	Zone reference
zone_name	VARCHAR(50)	Zone name
start_time	TIMESTAMP	War start time
end_time	TIMESTAMP	War end time
winner_gang	VARCHAR(50)	Winner gang tag
scores	LONGTEXT	JSON: Final scores
participant_count	INT	Total participants
ended_early	TINYINT(1)	Whether war ended before timer (0 = false, 1 = true)

---

7. Troubleshooting

Common Issues

Admin Menu Not Opening

Possible causes:

1. Missing ACE permissions
2. License not in whitelist
3. Resource not started properly

Solutions:

# Check if player has permission
# In server console:
list_player_permissions [player_id]

# Verify resource is running
ensure ars_gangsystem

Gang Not Loading

Symptoms: Gang exists in database but doesn’t appear in-game

Solution:

1. Check server console for database errors
2. Verify the gang data is valid JSON in the database
3. Restart the resource: restart ars_gangsystem

Territory Not Working

Symptoms: Territory doesn’t trigger point accumulation

Check:

1. PolyZone must have at least 3 vertices
2. minZ and maxZ must encompass the play area
3. Player must have a gang tag
4. Check Config.TerritoryXP.Enable = true

Turf War Not Starting

Possible causes:

1. Not enough gang members online (< Config.TurfWars.MinimumMembers)
2. Another war already active
3. Zone on cooldown

Note: Active turf wars are stored in memory only and are not persisted to the database. Use the /turfwarmarker admin command to view current war status.

Debug Mode

Debug mode is enabled by default (Config.DebugMode = true). To disable it:

Config.DebugMode = false

Debug messages appear in the server console with prefixes like:

Debug messages appear in the server console with prefixes like:

• [INFO] - General information
• [ERROR] - Error conditions
• [TURFWARS] - Turf war system messages

Turf War Debug Command

When debug mode is enabled, you can use:

/turfwardebug

This toggles a mock turf war for testing purposes. Use this for development and testing only, not on production servers.

Manual Database Fixes

Reset a Gang’s Cash

UPDATE ars_gangsystem SET cash = 0 WHERE tag = 'GANGTAG';

Fix Corrupted Member Data

-- Backup first!
SELECT members FROM ars_gangsystem WHERE tag = 'GANGTAG';

-- Reset to empty
UPDATE ars_gangsystem SET members = '[]' WHERE tag = 'GANGTAG';

Reset Territory Points

UPDATE ars_gangsystem_territories SET points = '{}' WHERE name = 'territory_name';

Fix Member Stats for a Player

-- Reset stats
UPDATE ars_gangsystem_member_stats
SET kills = 0, drugs_sold = 0, rackets_completed = 0, airdrops_looted = 0
WHERE identifier = 'player_identifier';

---

8. Useful Commands Quick Reference

Admin Commands

Command	Parameters	Description
/admingangmenu	None	Open gang admin menu
/createterritory	None	Start territory creation mode
/removeterritory	[name]	Remove a territory
/addterritorycontrol	[territory] [gangtag] [points]	Add control points to territory
/turfwarmarker	None	Open turf war admin menu
/gangxp	<add|remove> <gangtag> <amount>	Add/remove gang XP
/setgangxp	<gangtag> <amount>	Set gang XP to exact amount
/balancexp	None	Balance all gangs to average XP

Player Commands (For Reference)

Command	Description
/gangmenu	Open player gang menu (F6)
/gangleaderboard	View gang leaderboard
/showpoints	Show points in current territory

XP Command Examples

# Add 500 XP to VGS gang
/gangxp add VGS 500

# Remove 200 XP from BLS gang
/gangxp remove BLS 200

# Set VGS gang XP to exactly 10000
/setgangxp VGS 10000

# Balance all gangs to average XP
/balancexp

---

Support

For additional support:

• Check the docs/ folder for other guides
• Review shared/config.lua for all configuration options
• Enable Config.DebugMode for detailed logging
• Check server console for error messages

---

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.