⚙️Configuration

⚙️ Configuration Guide

0Bug_Atm is easy to configure through its main configuration file and localization files. This guide will walk you through every option.

---

📁 Configuration Files

File	Purpose
zr-config/zr-config.lua	Main configuration (interaction, security, framework, standalone overrides)
zr-locales/en.json	English translations
zr-locales/es.json	Spanish translations
zr-locales/fr.json	French translations

---

🎯 Basic Configuration (zr-config/zr-config.lua)

General Settings

Config.Debug = false                     -- Enable debug prints
Config.Language = 'en'                   -- Language: 'en', 'es', 'fr'

PIN & Security

Config.PinLength = 4                     -- PIN digit length
Config.MaxAttempts = 3                   -- Max failed PIN attempts before lockout
Config.LockDuration = 30                -- Lockout duration in seconds

Bank Card Item - Follow the BANK_CARD_SETUP.md

Config.UseCardItem = false              -- Enable bank card item requirement (true/false)
Config.CardItemName = 'bank_card'       -- The item name in your inventory system

External Banking (Optional)

If you want the ATM to open your existing banking UI (e.g., qb-banking) instead of the built-in system:

Config.UseBankingSystem = false          -- Set to true to use external banking

Config.OpenExternalBanking = function()
    -- Add your banking system logic here
    TriggerEvent('qb-banking:client:openBank')
end

---

🎮 Interaction System

0Bug_Atm supports two interaction modes. Choose the one that fits your server:

Mode	Description	Requires
'target'	Use a target system (ox_target, qb-target, or custom)	A target resource
'textui'	Use ox_lib TextUI (proximity-based, press E)	ox_lib

Setting the Interaction Type

Config.InteractionType = 'target'        -- 'target' or 'textui'
Config.InteractionDistance = 1.5          -- Distance in meters

ATM Prop Models

Config.ATMModels = {
    `prop_atm_01`,
    `prop_atm_02`,
    `prop_atm_03`,
    `prop_fleeca_atm`,
}

---

🎯 Target System Setup

Only used when Config.InteractionType = 'target'

By default, the script auto-detects ox_target and qb-target. You can also add any custom target system by editing the Config.SetupTargetSystem function:

Config.SetupTargetSystem = function(models, onSelect, canInteract, distance)

    -- ox_target (auto-detected)
    if GetResourceState('ox_target') == 'started' then
        exports.ox_target:addModel(models, {
            {
                name = '0bug_atm_use',
                label = 'Use ATM',
                icon = 'fas fa-credit-card',
                onSelect = onSelect,
                canInteract = canInteract,
                distance = distance,
            }
        })
        return true

    -- qb-target (auto-detected)
    elseif GetResourceState('qb-target') == 'started' then
        exports['qb-target']:AddTargetModel(models, {
            options = {
                {
                    type = 'client',
                    label = 'Use ATM',
                    icon = 'fas fa-credit-card',
                    action = onSelect,
                    canInteract = canInteract,
                }
            },
            distance = distance,
        })
        return true

    -- ─── ADD YOUR CUSTOM TARGET SYSTEM HERE ───
    -- Uncomment and modify:
    --[[
    elseif GetResourceState('your-target-resource') == 'started' then
        exports['your-target-resource']:AddTargetModel(models, {
            label = 'Use ATM',
            icon = 'fas fa-credit-card',
            action = onSelect,
            distance = distance,
        })
        return true
    ]]--
    end

    return false
end

Parameters available in your custom setup:

Parameter	Type	Description
models	table	ATM prop model hashes
onSelect	function	Call this to open the ATM
canInteract	function	Returns true if player can interact
distance	number	Interaction distance in meters

---

📱 TextUI Setup (ox_lib)

Only used when Config.InteractionType = 'textui' Requires ox_lib to be installed and started.

Players walk up to an ATM and press [E] to interact — no target system needed.

Config.TextUIOptions = {
    key = 'E',                           -- Display label for the key
    keyControl = 38,                     -- FiveM control ID (38 = E key)
    label = '[E] Use ATM',              -- Text shown on screen
    icon = 'fas fa-credit-card',        -- FontAwesome icon
    position = 'right-center',          -- Position: 'right-center', 'left-center', 'top-center'
    style = {},                          -- Optional: custom CSS style table
}

---

🖥️ Framework Auto-Detection

The script automatically detects your framework. No manual setup needed for:

• ✅ QBCore (qb-core)

• ✅ QBox (qbx_core)

• ✅ ESX (es_extended)

• ✅ Standalone (no framework — uses config overrides below)

---

💻 Standalone / Custom Framework Overrides

If you use QBCore, QBox, or ESX — these are IGNORED. Only edit these if your framework is detected as standalone.

These functions let you plug in any custom money system, identifier system, or character system for standalone setups.

💰 Get Player Bank Balance

Config.GetPlayerBalance = function(src)
    -- Must return a number (the player's bank balance)
    -- Examples:
    --   return exports['your-banking']:GetBalance(src)
    --   local result = MySQL.query.await('SELECT bank FROM users WHERE identifier = ?', { ... })
    --   return result[1].bank or 0
    return 0
end

💵 Get Player Cash

Config.GetPlayerCash = function(src)
    -- Must return a number (the player's cash on hand)
    -- Examples:
    --   return exports['your-money']:GetCash(src)
    return 0
end

➕ Add Money to Player

Config.AddMoney = function(src, account, amount)
    -- account: 'cash' or 'bank'
    -- amount: number
    -- Must return true on success, false on failure
    -- Examples:
    --   exports['your-money']:AddMoney(src, account, amount)
    --   return true
    --
    -- Example with direct SQL:
    --   if account == 'bank' then
    --       MySQL.update.await('UPDATE users SET bank = bank + ? WHERE identifier = ?', { amount, id })
    --   elseif account == 'cash' then
    --       MySQL.update.await('UPDATE users SET cash = cash + ? WHERE identifier = ?', { amount, id })
    --   end
    --   return true
    return false
end

➖ Remove Money from Player

Config.RemoveMoney = function(src, account, amount)
    -- account: 'cash' or 'bank'
    -- amount: number
    -- Must return true on success, false on failure
    -- Examples:
    --   exports['your-money']:RemoveMoney(src, account, amount)
    --   return true
    return false
end

🆔 Get Player Identifier

Config.GetPlayerIdentifier = function(src)
    -- Must return a unique string identifier for the player
    -- Default: uses FiveM license identifier
    -- Examples:
    --   return exports['your-framework']:GetIdentifier(src)
    --   return exports['your-characters']:GetCharacterId(src)
    for _, id in ipairs(GetPlayerIdentifiers(src)) do
        if string.find(id, 'license:') then
            return id
        end
    end
    return nil
end

👤 Get Player Display Name

Config.GetPlayerName = function(src)
    -- Must return a string (the player's display name)
    -- Examples:
    --   return exports['your-framework']:GetCharacterName(src)
    return GetPlayerName(src) or 'Unknown'
end

---

🌍 Localization (zr-locales/)

Change any text displayed in the ATM UI by editing the language JSON files:

{
  "welcome": "WELCOME",
  "insert_card": "Insert your card",
  "withdraw": "WITHDRAW",
  "deposit": "DEPOSIT",
  "exit": "EXIT"
}

Available languages:

File	Language
zr-locales/en.json	English
zr-locales/es.json	Spanish
zr-locales/fr.json	French

Set the language in the config:

Config.Language = 'en'    -- 'en', 'es', or 'fr'

---

✅ Testing Your Configuration

After making changes:

1. Save your config files

2. Restart the resource:

   restart 0Bug_Atm

3. Check console for any errors

4. Test in-game:

   • Walk up to an ATM

   • Verify interaction works (target eye or TextUI prompt)

   • Test PIN setup, withdraw, deposit

   • Check if balance updates correctly

---

🛠️ Common Issues

Issue	Cause	Solution
No interaction at ATM	Wrong InteractionType or missing target resource	Verify config matches your setup
TextUI not showing	ox_lib not installed	Install ox_lib and ensure it starts before 0Bug_Atm
Target eye not showing	Target resource not started	Ensure ox_target or qb-target starts before 0Bug_Atm
Balance always 0 (standalone)	Override functions not implemented	Edit Config.GetPlayerBalance and other overrides
Money not adding/removing	Override returns false	Ensure Config.AddMoney / Config.RemoveMoney return true
Framework not detected	0Bug_Atm loaded before framework	Fix load order in server.cfg

---

💾 Backup Reminder

Always backup your config files before making major changes:

• zr-config/zr-config.lua → zr-config/zr-config.lua.backup

• zr-locales/*.json → backup copies

---

Configuration complete! Your ATM system is ready to go. 🎉