ESX

Dependencies

• ox_lib

• ox_target or other target with identical format as ox_target (not guaranteed to work)

• ox_inventory

• esx_skin

• esx_addonaccount

• oxmysql

Installlation

1. Place the ylean_loans folder into your server's resources directory.

2. Import sql.sql into your MySQL database.

Config File

--Framework settings
ESX = exports["es_extended"]:getSharedObject()

Ylean = {}

Ylean.Debug = false

Ylean.Locales = "en"

Ylean.TargetResource = 'ox_target' -- 'ox_target' support available (you can try other if there is the same syntax as ox_target it should work)

-- Framework events
Ylean.NotifyEvent = 'esx:showNotification' --Client side only event

Ylean.JobUpdateEvent = 'esx:setJob' --Client side only event

Ylean.OnPlayerLoadedEvent = 'esx:playerLoaded' --Client side only event

Ylean.SocietyAccountEvent = 'esx_addonaccount:getSharedAccount' -- server side event

Ylean.OpenClothingMenu = 'esx_skin:openSaveableMenu' -- Boss menu clothing menu [client sided event]

Ylean.DefaultDuty = true -- if set to 'true', player will be on duty after loading in to server

-- GENERAL SETTINGS
Ylean.General = {
    blip = {
        active = true,
        coords = vector4(233.67, 221.3, 113.86, 338.37),
        type = 409, -- https://docs.fivem.net/docs/game-references/blips/
        text = "Viva Capital",
        color = 2 -- https://docs.fivem.net/docs/game-references/blips/#blip-colors
    },

    floatingEmblem = {
        active = true,
        coords = { vector3(233.67, 221.3, 113.00), vector3(246.81, 209.6, 113.00), vector3(241.21, 211.66, 113.00)},
        type = 29, -- Marker type: https://docs.fivem.net/docs/game-references/markers/
        color = {0, 255, 0, 255}, -- RGBA: green color
        waveEnabled = true, -- Enable or disable waving
        waveAmplitude = 0.2, -- Amplitude of the wave (height of the oscillation)
        waveSpeed = 2 -- Speed of the wave
    },

    ped = {
        active = true,
        coords = vector4(233.57, 220.39, 109.28, 352.01),
        model = "s_m_m_movprem_01", -- https://docs.fivem.net/docs/game-references/ped-models/
        animation = {
            dict = "amb@world_human_hang_out_street@female_arms_crossed@idle_a", -- Animation dictionary for an idle pose
            name = "idle_a", -- Animation name for a relaxed, crossed arms stance
            flag = 49 -- Loop the animation, prevent movement
        },

        waveToPlayer = {
            active = true,
            distance = 5.0,
            animation = {
                dict = "gestures@m@standing@casual", -- Animation dictionary 
                name = "gesture_hello", -- Animation name
                flag = 48 -- Prevents movement while waving
            }
        }
    },

    menu_open_points = {
        debug = false,
        coords = { vector3(233.67, 221.3, 111.5), vector3(246.81, 209.6, 111.5), vector3(241.21, 211.66, 111.5)},
        accessDistance = 5.0,
        icon = "fa-solid fa-right-to-bracket"
    }
}

-- JOB SETTINGS
Ylean.BrokerJob = {
    name = "financial",
    rejectionReasonLength = 200, -- Max. 500 chars
    grades = {
        ['0'] = {
            canGrantBusinessLoans = false, -- A variable defining whether an employee with a given rank is allowed to grant business loans
            canGrantLoansToPlayers = true, -- A variable defining whether an employee with a given rank is allowed to grant individual loans
            individualProfitFromInterest = 30, -- A variable defining the percentage of the interest rate that an employee receives for granting a indiviudal loan
            businessProfitFromInterest = 35 -- A variable defining the percentage of the interest rate that an employee receives for granting a business loan
        },
        ['1'] = {
            canGrantBusinessLoans = true,
            canGrantLoansToPlayers = true,
            individualProfitFromInterest = 45,
            businessProfitFromInterest = 50
        },
        ['2'] = {
            canGrantBusinessLoans = true,
            canGrantLoansToPlayers = true,
            individualProfitFromInterest = 70,
            businessProfitFromInterest = 80
        },
    },

    on_off_duty = {
        marker = {
            active = true,
            coords = vector3(262.98, 209.39, 112.00),
            type = 20,
            color = {
                r = 255,
                g = 215,
                b = 0,
                a = 100
            }
        },
        target = {
            active = true,
            coords = vector4(262.9, 209.4, 110.29, 346.69),
            icon = "fa-solid fa-sign-in-alt",
            debugPoly = false,
            distance = 2.0
        }
    },

    boss_menu = {
        coords = vector4(262.16, 205.88, 109.48, 320.02),
        hire_distance = 20.0,
        target = {
            debug = false,
            target_icon = "fas fa-sign-in-alt",
            distance = 2.0
        }
    }
}

-- INDIVIDUAL LOAN SETTINGS
Ylean.IndividualLoan = {
    approval = {
        active = true, -- If enabled, loans exceeding a certain amount will require mandatory approval from authorized employees
        from = 10000000 -- Loans exceeding this amount will require approval from an authorized employee (provided that active = true). If set to "0", every loan will require approval
    },

    minimumLoanAmount = 1200,
    maximumDeadline = 60,

    interestRate = {
        --[[
        If "constant" set to true, regardless of the repayment term chosen by the player, the interest rate will always remain the same (the "value" variable below). 
        If set to false, the minimum interest rate for a one-day repayment term will be the percentage set in the "min" variable, while the maximum rate 
        will be the percentage set in the "max" variable below.
        ]]--
        
        constant = false, 
        value = 12.5,

        min = 5,
        max = 15
    },
    
    creditScoreGrantedForRepayment = 1,
    
    loanPurposeLength = 150, -- in characters (max. 500)
    
    delay = 15, -- The time that must pass from the full repayment of the loan until the possibility of taking another one. (IN MINUTES)

    methodOfGrantingLoan = "bank" -- "bank" or "money"
}

-- INDIVIDUAL LOAN REPAYMENT SETTINGS
Ylean.IndividualLoanRepayment = {
    creditScoreLostInCaseOfDelay = 5,
    
    notifyAboutUpcomingRepayment = { 
        active = true, -- If set to true, the player will be notified about the upcoming installment payment
        hours = 30 -- How many hours before the payment due date should the player be notified
    },

    immediateDeduction = false,   -- If true, the loan amount will be immediately deducted from the account once the deadline is passed
    interestRate = 0.05,         -- Daily interest rate (e.g., 5%)
    daysBeforeDeduction = 3      -- Number of days after the deadline before funds are automatically deducted when interest accrues
}

-- BUSINESS LOAN SETTINGS
Ylean.BusinessLoan = {
    minimumLoanAmount = 50000,
    maximumLoanAmount = 100000,

    maximumDeadline = 120,
    interestRate = {
        --[[
        If "constant" set to true, regardless of the repayment term chosen by the player, the interest rate will always remain the same (the "value" variable below). 
        If set to false, the minimum interest rate for a one-day repayment term will be the percentage set in the "min" variable, while the maximum rate 
        will be the percentage set in the "max" variable below.
        ]]--
        
        constant = false, 
        value = 12.5,

        min = 5,
        max = 15.5
    },

    methodOfGrantingLoan = "bank" -- "bank" or "money"
}

-- BUSINESS LOAN REPAYMENT SETTINGS
Ylean.BusinessLoanRepayment = {
    notifyAboutUpcomingRepayment = { 
        active = true, -- If set to true, the player will be notified about the upcoming installment payment
        hours = 30 -- How many hours before the payment due date should the player be notified
    },
    
    immediateDeduction = true,   -- If true, the loan amount will be immediately deducted from the account once the deadline is passed
    interestRate = 0.05,         -- Daily interest rate (e.g., 5%)
    daysBeforeDeduction = 3      -- Number of days after the deadline before funds are automatically deducted when interest accrues
}

-- CREDIT SCORE SETTINGS
Ylean.CreditScore = {
    {from = 0, to = 5, max = 5000},  -- Players with a credit score between 0 and 5 can borrow up to 5000
    {from = 6, to = 9, max = 10000}, -- Players with a credit score between 6 and 9 can borrow up to 10000 ...
    {from = 10, to = 15, max = 15000},
    {from = 16, to = 20, max = 20000},
    {from = 21, to = 25, max = 35000},
    {from = 26, to = 30, max = 50000},
}

Ylean.BossStash = {
    id = 'financial_stash',
    label = 'Financial Stash',
    slots = 50,
    weight = 100000,
    owner = false,
    jobs = 'financial'
}

-- LOCALES INITIALIZE !!DON'T TOUCH!!
function Translate(key)
    local languageCode = Ylean.Locales or "en"
    local localesTable = _G["Locales_" .. languageCode]
    if not localesTable then
        localesTable = _G["Locales_en"]
    end
    return localesTable and localesTable[key] or key
end


function Debug(message)
    if Ylean.Debug then
        print("[Debug] " .. message)
    end
end

Job Settings

The Ylean.BrokerJob table defines the core settings for the “financial” job (the broker role). Any change in this section—both the name field and any modifications to the grades table—must be mirrored in your server’s main job configuration.

Ylean.BrokerJob = {
    -- Unique job identifier; must match your main job config
    name = "financial",

    -- Permissions and profit settings per grade
    grades = {
        ['0'] = {
            canGrantBusinessLoans        = false,  -- allows granting business loans
            canGrantLoansToPlayers       = true,   -- allows granting personal loans
            individualProfitFromInterest = 30,     -- % of interest the employee earns on personal loans
            businessProfitFromInterest   = 35      -- % of interest the employee earns on business loans
        },
        ['1'] = {
            canGrantBusinessLoans        = true,
            canGrantLoansToPlayers       = true,
            individualProfitFromInterest = 45,
            businessProfitFromInterest   = 50
        },
        ['2'] = {
            canGrantBusinessLoans        = true,
            canGrantLoansToPlayers       = true,
            individualProfitFromInterest = 70,
            businessProfitFromInterest   = 80
        },
    },
}

Configuration Requirements

• name Must exactly match the job name defined in your main configuration file.

• grades Each key ('0', '1', '2', etc.) must correspond to a grade defined in that same configuration. Any addition, removal, or renumbering of grades here must be applied to the main job config as well.

Boss Menu Access

Any player whose grade_name contains the substring "boss" is granted access to the Boss Menu for the “financial” job.

Interest Rate Settings

Both Business Loans and Individual Loans use the same interestRate configuration block. It controls how the loan’s interest rate is chosen based on whether you want a fixed rate or a rate that changes with the repayment period.

interestRate = {
    constant = <boolean>,
    value    = <number>,  -- only used if constant = true
    min      = <number>,  -- used when constant = false, for the shortest term (1 day)
    max      = <number>   -- used when constant = false, for the longest term
}

1. Fixed Rate Mode (constant = true)

• Behavior No matter what repayment term the player picks, the interest rate is always equal to value.

• Configuration

constant = true
value    = 12.5   -- example: always 12.5% interest
-- min and max are ignored

Fixed Rate Mode

2. Variable Rate Mode (constant = false)

• Behavior

  • For a 1-day loan, use the min rate.

  • For a loan at the maximum allowed deadline (defined by maximumDeadline), use the max rate.

  • For any term in between, interpolate linearly between min and max.

• Linear interpolation formula

• Configuration

  constant = false
  min      = 5     -- example: 5% for a 1-day loan
  max      = 15.5  -- example: 15.5% for the longest loan term
  -- value is ignored

Variable Rate Mode

Translation Guide

This section explains how to add or edit translations for ylean_loans, covering both the NUI (front-end) and server (back-end) locales, as well as the main NUI HTML file.

1. NUI (Front-End) Translations

• Directory: ylean_loans/nui/locales/ Contains pre-translated JSON files, e.g. en.json, pl.json, etc.

• Add or Edit a Language

  1. Create or modify your_lang.json in that folder.

     {
         "unkwnPlayer": "Unknown Player",
         "welcome": "Welcome",
         "yourcreditscore": "Your Credit Score",
         "hire_btn_txt": "HIRE",
         "employee_of_the_month": "Employee of the Month",
         "grant_business_loan": "GRANT BUSINESS LOAN",
         "no_data": "No Data",
       /* …other keys… */
     }

  2. Open ylean_loans/nui/index.js. Find the line:

     let selectedLanguage = "en";

     and add or change the code to your filename (without .json):

     let selectedLanguage = "your_lang";

2. Server (Back-End) Translations

• Directory: ylean_loans/locales/ Contains Lua locale files, e.g. en.lua, pl.lua, etc.

• Add or Edit a Language

  1. Create or modify yourLang.lua in that folder.

Locales_yourLang = {
    LOAN_GRANTED = "Loan Granted",
    LOAN_REPAID = "Loan Repaid",
    LOAN_DEFAULTED_COLLECTED = "Loan Defaulted - Collected",
    LOAN_REJECTED = "Loan Rejected",    
    LOAN_PENDING = "Pending acceptance",
    
    -- …other keys…
}

1. Open config.lua. Find the Ylean.Locales table and add your filename (without .lua):

Ylean.Locales = "en"

3. Main NUI HTML

• File: ylean_loans/nui/index.html Contains static text (headings, placeholders) that may need translation beyond what your JSON files cover.

• Edit for Your Language

  1. Open index.html.

  2. Translate any hard-coded strings

  3. Restart script

---

With these steps, you can fully localize ylean_loans in both the UI and server logic. Remember to keep your filenames (without extensions) consistent when referencing them in index.js and config.lua.

Changing the Displayed Currency

To switch the currency symbol shown throughout ylean_loans, update three places: the back-end Lua locales, the NUI JSON locales, and the NUI script.

1. Back-End (Lua Locales)

   • Open the appropriate file in ylean_loans/locales/ (e.g. en.lua, pl.lua).

   • Locate any entries containing the currency symbol (for example a key like insufficientCreditScore = "Insufficient credit score for a $%d loan! Max allowed: $%d" or inline strings).

   • Replace "$" with your desired symbol (e.g. "€").

   • Save and restart the resource to apply changes.

2. Front-End NUI (JSON Locales)

   • Open the corresponding JSON file in ylean_loans/nui/locales/ (e.g. en.json, pl.json).

   • Find any keys or values that include the currency symbol (for example "validate_repayment_range": "Repayment Amount must be between $").

   • Replace "$" with your desired symbol.

   • Save the file and reload the NUI to see the updated labels.

3. Front-End NUI Script

   • Open ylean_loans/nui/index.js.

   • Find the line:

     const currency = "$";

   • Change it to your new symbol, for example:

     const currency = "€";

   • Save the file and reload the script (e.g., via ensure ylean_loans ).

After completing these three steps, all monetary values and labels in both the UI and server logic will use your new currency symbol.

Changing the Date Format

To adjust how dates are displayed in the NUI:

1. Open ylean_loans/nui/index.js.

2. Locate the line:

   const date_format = "en-US";

3. Replace "en-US" with any valid ECMAScript Intl locale string—for example:

   const date_format = "en-GB";  // DD/MM/YYYY
   const date_format = "pl-PL";  // DD.MM.YYYY
   const date_format = "de-DE";  // DD.MM.YYYY with German month names

4. Save the file and reload the script (e.g., via ensure ylean_loans ).

The UI will now format all dates according to your chosen locale.

Upcoming Repayment Notification Mechanism

The reminder system alerts borrowers as their payment deadline approaches:

• Activation: Controlled by notifyAboutUpcomingRepayment.active in each loan’s configuration namespace (IndividualLoanRepayment or BusinessLoanRepayment).

• Threshold: Defined by notifyAboutUpcomingRepayment.hours—reminders start when the time until the deadline is less than or equal to this value.

• Frequency: Once the threshold is reached, borrowers receive a notification every hour until they either repay the loan or the deadline passes and the deduction or interest-accrual procedure is triggered.

To configure:

1. Enable or disable reminders with the active flag.

2. Set the hours value to determine how far in advance hourly reminders begin.

Immediate Deduction Mode

In this mode, once the repayment deadline passes, the system automatically deducts the full outstanding balance from the borrower’s bank account. This applies to both individual and business loans, subject to the following configuration:

• Enable/Disable: Controlled by the immediateDeduction flag in each loan’s settings.

• Credit Score Penalty (individual loans only): If enabled, a fixed number of credit score points (creditScoreLostInCaseOfDelay) is deducted when the funds are collected.

• Notification: Upon deduction, a log entry and optional webhook notification (e.g., Discord) inform administrators and the borrower of the action.

All related configuration options are defined within the Ylean.IndividualLoanRepayment and Ylean.BusinessLoanRepayment namespaces.

Configuration Steps:

1. Set immediateDeduction = true to activate this mode.

2. (Individual loans) Define creditScoreLostInCaseOfDelay to apply penalties for delayed repayment.

Interest Accrual Mode

This mode gradually increases the loan amount by a daily interest rate, providing a grace period before enforcing a full deduction:

• Interest Accrual: The outstanding principal is multiplied by (1 + interestRate) once per day, compounding until collection.

• Grace Period: A configurable number of days (daysBeforeDeduction) gives borrowers time to repay without immediate loss of funds.

• Final Collection: After the grace period, the total accumulated balance (principal plus accrued interest) is deducted in full. Individual loans may also incur a credit score penalty at this point.

All related configuration options are defined within the Ylean.IndividualLoanRepayment and Ylean.BusinessLoanRepayment namespaces.

Configuration Steps:

1. Set immediateDeduction = false to use interest accrual.

2. Define interestRate (daily rate) and daysBeforeDeduction (grace period).

3. (Individual loans) Optionally configure creditScoreLostInCaseOfDelay for score penalties upon final collection.

Comparison of Modes

Feature	Immediate Deduction	Interest Accrual
Activation	immediateDeduction = true	immediateDeduction = false
Interest before deduction	None	Accrued daily until the threshold
Status change	Immediately upon delay	After daysBeforeDeduction days overdue
Funds deducted	Full principal	Accumulated principal + interest
Credit score impact	Individual loans only	Individual loans only

Discord Webhook Logging

Key loan events can be logged to Discord via webhooks, with each action configurable individually under the YleanDC.Logs namespace in discord_logs_cfg.lua file.

Global Settings (YleanDC):

• ServerName (string): Name of the server displayed in the embed footer.

• DefaultEmbedColor (integer): Default color code used for embeds when an event-specific color is not provided.

Per-Event Configuration: Each event under YleanDC.Logs supports:

• Enabled (boolean): Turn logging on or off.

• WebhookURL (string): Discord webhook endpoint for that event.

• BotName (string) and BotAvatar (string URL): Identity of the webhook bot.

• Embed (object): Customization of the embed’s Title, Color, and Thumbnail.

Configured Events:

Event	Description
LoanIndividualNoApproval	Player applied for an individual loan that does not require approval
LoanIndividualApproval	Player applied for an individual loan that requires approval
PartialLoanRepayment	Player made a partial repayment on a loan
FullLoanRepayment	Player fully repaid a loan
SubmitBusinessLoan	Employee submitted a business loan
AcceptBusinessLoan	Player accepted a business loan
RejectBusinessLoan	Player rejected a business loan
OverdueLoanIndividual	Player failed to repay an individual loan on time
OverdueLoanBusiness	Player failed to repay a business loan on time
EmployeeLoanIndividual	Employee granted an individual loan
EmployeeRejectLoanIndividual	Employee rejected an individual loan
EmployeeClockOut	Employee clocked out (ended duty)
EmployeeClockIn	Employee clocked in (started duty)
BossFireEmployee	Boss fired an employee
BossChangeJobGrade	Boss changed an employee's job grade
BossHireEmployee	Boss hired a new employee
CompanyBankDeposit	Deposit made into the company bank account
CompanyBankWithdrawal	Withdrawal made from the company bank account