Configuration Guide

Configuration Guide: ATM Owner System

This guide covers all configuration options available in the ATM Owner System.

---

Configuration File

All configuration is done in config.lua. The file is not encrypted and can be freely edited.

---

Core Configuration

Locale Settings

Config.Locale = "en"  -- Set your default language

Available Languages:

• "en" - English (default)

• "pt" - Portuguese

• Add more by creating locale files in locales/ folder

How to Add Languages:

1. Copy locales/en.lua to locales/your_language.lua

2. Translate all strings in the file

3. Set Config.Locale = "your_language"

---

Debug Mode

Config.Debug = true  -- Enable debug prints

When to Enable:

• During setup and testing

• When troubleshooting issues

• When reporting bugs

When to Disable:

• In production servers

• For better performance

• To reduce console spam

Debug Output:

• ATM loading messages

• Transaction processing logs

• Permission checks

• Network statistics

---

Proximity Detection

Config.ProximityRadius = 1.0  -- Detection radius in meters

What It Does:

• Determines how close a player must be to an ATM for automatic tax detection

• Used for transaction detection when Config.AutoDetectBankDelta = true

Recommended Values:

• 1.0 - Default, balanced detection

• 0.5 - More precise, less CPU usage

• 1.5-2.0 - Easier detection, more CPU usage

Performance Impact:

• Lower values = less CPU usage

• Higher values = easier detection but more processing

---

Automatic Tax Detection

Config.AutoDetectBankDelta = true  -- Auto-detect and tax transactions

What It Does:

• Automatically detects when players deposit/withdraw money near ATMs

• Calculates tax based on ATM's tax rate

• Deducts tax from appropriate source (cash for withdraw, bank for deposit)

How It Works:

1. Player approaches ATM (within Config.ProximityRadius)

2. System monitors bank and cash balance changes

3. Detects transaction type (deposit/withdraw)

4. Calculates tax amount

5. Deducts tax and adds to ATM revenue

When to Disable:

• If you have custom banking scripts that conflict

• If you want manual transaction processing only

• If experiencing performance issues

---

Ownership Limits

Config.MaxATMsPerPlayer = 2  -- Maximum ATMs per player (0 = unlimited)

Options:

• 0 - Unlimited ATMs per player

• 1+ - Maximum number of ATMs a player can own

Use Cases:

• 1-2: Small servers, balanced economy

• 3-5: Medium servers, more business opportunities

• 0: Large servers, unlimited ownership

Enforcement:

• Checked when purchasing ATMs

• Prevents exceeding limit

• Error message shown if limit reached

---

ATM Blip Configuration

Blip Settings

Config.ATMBlip = {
    Enabled = true,      -- Master toggle for ATM blips
    Sprite = 277,        -- Blip sprite ID (bank/ATM icon)
    Scale = 0.6,         -- Blip size (0.1 - 2.0)
    Color = 2,           -- Blip color (green)
    ShortRange = true    -- Only visible when near
}

Blip Options

Enabled:

• true - Show ATM blips on map

• false - Hide all ATM blips

Sprite:

• 277 - Bank/ATM icon (default)

• See FiveM blip sprite reference for other options

Scale:

• 0.1 - Very small

• 0.6 - Default size

• 1.0 - Large

• 2.0 - Very large

Color:

• 0 - White

• 1 - Red

• 2 - Green (default)

• 3 - Blue

• See FiveM blip color reference for full list

ShortRange:

• true - Only visible when player is nearby

• false - Always visible on map

Blip Labels:

• Blips show as "ATM [ID]" (e.g., "ATM 1", "ATM 2")

• ID corresponds to ATM database ID

---

ATM Manager NPC Configuration

NPC Settings

Config.ATMNpc = {
    Enabled = true,                          -- Enable/disable NPC
    Model = "cs_bankman",                     -- Ped model name
    Coords = vector3(-1381.12, -499.61, 32.16), -- Spawn coordinates
    Heading = 193.62,                          -- NPC facing direction (0-360)
    InteractionDistance = 2.0,                -- Interaction range in meters
    TextUI = "[E] Manage ATMs",               -- Text shown in ox_lib text UI
    Blip = {
        Enabled = true,                       -- Show blip for NPC
        Sprite = 480,                         -- Blip icon
        Scale = 0.7,                          -- Blip size
        Color = 2,                            -- Blip color (green)
        Label = "ATM Manager"                 -- Blip label
    }
}

NPC Options

Enabled:

• true - Spawn NPC at configured location

• false - No NPC (players must use /addatm command)

Model:

• "cs_bankman" - Bank manager (default)

• "s_m_m_bankman" - Alternative bank manager

• Any valid FiveM ped model name

Coords:

• vector3(x, y, z) - Spawn location

• Use /getcoords in-game to find coordinates

Heading:

• 0-360 - Direction NPC faces (degrees)

• 0 = North, 90 = East, 180 = South, 270 = West

InteractionDistance:

• Distance in meters player must be to see interaction prompt

• 2.0 - Default, comfortable range

• 1.5 - Closer range

• 3.0 - Wider range

TextUI:

• Text shown when player is near NPC

• Uses ox_lib text UI system

• Customize message as needed

Blip Settings:

• Same options as ATM blips

• Shows NPC location on map

• Helps players find the NPC

---

Tax Permission Configuration

Tax Change Permissions

Config.RequireOwnerForTax = false  -- Only owner can change tax
Config.AllowTaxChangeByManagers = true  -- Managers can change tax

Permission Logic

Scenario 1: Owner-Only Tax Changes

Config.RequireOwnerForTax = true
Config.AllowTaxChangeByManagers = false  -- Ignored when RequireOwnerForTax = true

• Result: Only the ATM owner can change tax rate

• Employees: Cannot change tax, even with manage_tax permission

Scenario 2: Owner + Managers

Config.RequireOwnerForTax = false
Config.AllowTaxChangeByManagers = true

• Result: Owner OR employees with manage permission can change tax

• Employees with manage_tax: Can also change tax

Scenario 3: Owner + Tax Permission

Config.RequireOwnerForTax = false
Config.AllowTaxChangeByManagers = false

• Result: Owner OR employees with manage_tax permission can change tax

• Employees with manage only: Cannot change tax

Level-Based Tax Limits

Tax rates are automatically limited based on owner's level:

• Level 1: 0-10% tax

• Level 2: 0-20% tax

• Level 3: 0-30% tax

• Level 4: 0-35% tax

• Level 5+: 0-39% tax

Note: These limits are enforced automatically and cannot be configured.

---

Advanced Configuration

Framework Integration

The script uses ic3d_lib for framework abstraction. No framework-specific configuration needed - it auto-detects:

• QBCore - Automatically detected

• ESX - Automatically detected

• Qbox - Automatically detected

Database Configuration

Database connection is handled by oxmysql. Configure in your oxmysql resource:

-- oxmysql configuration
mysql_connection_string = "mysql://user:password@localhost:3306/database"

Network Configuration

Chunked Streaming:

• Automatically enabled

• Prevents network overflow

• Configurable in server/main.lua (advanced)

Throttling:

• 5-second minimum between coordinate pushes

• Prevents spam

• Configurable in server/main.lua (advanced)

---

Configuration Examples

Example 1: Small Server Setup

Config.Locale = "en"
Config.Debug = false
Config.ProximityRadius = 1.0
Config.AutoDetectBankDelta = true
Config.MaxATMsPerPlayer = 1

Config.ATMBlip = {
    Enabled = true,
    Sprite = 277,
    Scale = 0.6,
    Color = 2,
    ShortRange = true
}

Config.RequireOwnerForTax = true
Config.AllowTaxChangeByManagers = false

Example 2: Large Server Setup

Config.Locale = "en"
Config.Debug = false
Config.ProximityRadius = 0.8
Config.AutoDetectBankDelta = true
Config.MaxATMsPerPlayer = 0  -- Unlimited

Config.ATMBlip = {
    Enabled = true,
    Sprite = 277,
    Scale = 0.5,
    Color = 2,
    ShortRange = false  -- Always visible
}

Config.RequireOwnerForTax = false
Config.AllowTaxChangeByManagers = true

Example 3: Performance-Optimized Setup

Config.Locale = "en"
Config.Debug = false
Config.ProximityRadius = 0.5  -- Smaller radius
Config.AutoDetectBankDelta = false  -- Disabled for performance
Config.MaxATMsPerPlayer = 2

Config.ATMBlip = {
    Enabled = false  -- Disabled to reduce overhead
}

Config.RequireOwnerForTax = true
Config.AllowTaxChangeByManagers = false

---

Configuration Validation

Common Mistakes

❌ Wrong:

Config.ProximityRadius = "1.0"  -- String instead of number
Config.MaxATMsPerPlayer = -1    -- Negative number
Config.ATMBlip.Enabled = "true" -- String instead of boolean

✅ Correct:

Config.ProximityRadius = 1.0     -- Number
Config.MaxATMsPerPlayer = 2      -- Positive number or 0
Config.ATMBlip.Enabled = true    -- Boolean

Validation Tips

• Numbers: Use actual numbers, not strings

• Booleans: Use true/false, not "true"/"false"

• Vectors: Use vector3(x, y, z) format

• Strings: Use quotes for text values

---

Reloading Configuration

How to Apply Changes

1. Edit config.lua with your changes

2. Restart the resource:

   restart godv_buyatm

3. Or restart server for full reload

What Requires Restart

Requires Restart:

• All Config.* changes

• Locale changes

• NPC configuration changes

Doesn't Require Restart:

• Database changes (ATMs, employees, etc.)

• UI modifications (if using external files)

---

Configuration Best Practices

Production Server

Config.Debug = false  -- Always disable in production
Config.ProximityRadius = 1.0  -- Balanced value
Config.AutoDetectBankDelta = true  -- Enable for automatic tax

Development Server

Config.Debug = true  -- Enable for troubleshooting
Config.ProximityRadius = 1.5  -- Easier testing
Config.AutoDetectBankDelta = true

Testing Configuration

Config.Debug = true
Config.MaxATMsPerPlayer = 0  -- Unlimited for testing
Config.ATMBlip.Enabled = true  -- See all ATMs

---

For installation instructions, see Installation Guide.

For troubleshooting, see Troubleshooting Guide.