Installation and configuration

Guide on how to setup the script. Your Framework (esx/qb-core/qbox) is detected automatically.

1. Setup your Database

Don't worry about setting up the database yourself! If you have Tax.CreateTables = true in the config, they are created on script startup by theq script itself. You don't have to do anything.

2. Edit Config File

Now you have to edit the config.lua file to your liking. A full preview of the config file can be found here.

2.1 General

2.1.1 Language

Tax.Locale = 'en'

Here you can select your desired language. Currently available are en and de. You can also edit the existing translations in the locales folder or add your own. To do this, simply use the en.lua or de.lua file as a template and adapt it to your language.

2.1.2 Currency

Tax.Currency = '$'

Here you can change from € to $ or any other currency, depending on your server's setting. Only changes what is displayed in the notifications.

2.1.3 Auto Create Tables

Tax.CreateTables = true

If this is set to true, the script will automatically create needed tables and columns depending on your config on startup. Recommended to keep to true.

2.1.4 Tax Returns

Tax.TaxReturns = true
Tax.ReturnRate = 0.05
Tax.ReturnTime = 30
Tax.DeleteExpiredReturns = true
Tax.PedCoords = vector4(-547.1, -209.6, 37.6, 300.0)
Tax.PedModel = 's_f_y_airhostess_01'
Tax.Blip                    = 207
Tax.BlipColor               = 25
Tax.OxTarget                = false

With the first setting you can enable tax returns. If you turn them off, the setting below are irrelevant. With Tax Return on, players can go to the ped at the specified coords in Tax.PedCoords which has the model Tax.PedModel. There every Tax.ReturnTime days, players can file their tax report and receive back Tax.ReturnRate% of the amount of money they paid in taxes since their last tax report. Tax.DeleteExpiredReturns means, entries of paid taxes get deleted after Tax.ReturnTime days. For example a player who has paid 10.000$ taxes in the last month will receive back 500$ in with these settings. Everything paid before these 30 days got deleted. Tax.Blip is the blip used on the map, you can find every blip at the CFX Docs. Blip Color can be found in the Rage Docs. If Tax.OxTarget is set to true, the script will use ox_target instead of qb-target on QB-Core or the esx Pres E prompt.

2.2 Webhook / Logs

Tax.Webhook = false
Tax.WebhookLink = 'link'

It is highly recommended to turn this on. In Tax.WebhookLink you can insert your discord webhook link. Now logs of every action and paid tax will get sent to that channel.

2.3 Jobs and Permissions

Tax.AllowedJobsTitleVehicle = {
    any                     = false,
    owner                   = false,
    police                  = 3,
    mechanic                = 4,
}
Tax.AllowedJobsRegisterVehicle = {
    any                     = false,
    owner                   = false,
    mechanic                = 4,
}
Tax.AllowedJobsUnRegisterVehicle = {
    any                     = false,
    owner                   = false,
    mechanic                = 4,
}
Tax.AllowedJobsCheckVehicle = {
    any                     = false,
    owner                   = true,
    police                  = 3,
    mechanic                = 4,
}
Tax.AllowedJobsCheckPrice   = {
    any                     = true,
    owner                   = true,
}
Tax.AllowedJobsUpdateVehicleOwner = {
    any                     = false,
    owner                   = false,
    police                  = 3,
    mechanic                = 4
}

In this section, you can manage the permissions for the actions of the ingame menu. Each of the categories represents one action. If any = true, then anyone can do this action. if owner = true, the owner of the vehicle can perform this action. Underneath you can add as many jobs as you like, that should have permission for this action. Always follow the scheme job = minimum grade. So for example with police = 3, every player who has the job police and a minimum grade of 3 can do this.

2.4 Ingame Menu

Tax.MenuPosition            = 'top-left'
Tax.MaxDistance             = nil
Tax.MenuCommand             = 'vehiclemenu'
Tax.MenuDefaultKey          = 'f5'
Tax.OxLib                   = false

This section is used for the ingame menu for vehicle actions. Tax.MenuPosition defines the position of the menu (ESX only). Available options are: top-left, bottom-left, top-right, bottom-right, center. Tax.MaxDistance limits how far a player can be away to interact with a vehicle through this menu in GTA units. nil deactivates this. Tax.MenuCommand is a command to open the menu just like to keybind, just in case someone for some reason prefers this. Tax.DefaultKey is the default keybind for opening the menu, can be changed or removed in the settings by each player individually. Tax.OxLib set to true will use the ox_lib menu instead of the normal ESX / QB menus.

2.5 Fixed Taxes / Fees

Tax.EnableFixedTaxes        = true
Tax.FixedTaxes              = {
    phoneBill = {
        price = 150,
        interval = 7,
        jobs = {

        },
    },
    healthInsurance = {
        price = 300,
        interval = 7,
        jobs = {
            {job = 'police', price = 200},
            {job = 'off_police', price = 200},
            {job = 'ambulance', price = 150}
        },
    }
}

This are can be used to add your own custom fixed taxes/fees. Tax.EnableFixedTaxes enables/disables this feature completely, if disabled the settings underneath can be ignored.

We'll take the healthInsurance as an example. healthInsurace is the name of the tax, which will be used to locate the translation and also the name of the column in your player/users table. If you wan't to add a new one, you have to add a translation for it. To do so, go to your selected locale file and add a new line like this: taxName = "translation". This will be used as text for invoices and logs. price refers to the normal price players have to pay. Interval = 7 means the tax is paid every 7 days. in the jobs = {} part, you can configure exclusive amounts for players with a specific job. For example police officers in many countrys, pay less on some taxes. In there just create a new array with job = "job name", price = amount as data. Remember to also add the coresponding offDuty jobs if needed.

2.6 Capital Tax (player and company bank accounts)

2.6.1 Player Bank Accounts

Tax.EnablePercentualCapitalTax = true   
Tax.PercentualCapitalTax    = 0.005
Tax.EnableFixedCapitalTax   = true
Tax.FixedCapitalTax         = 500

Tax.EnablePercentualCapitalTax will take the money the player has in their bank account and multiply it by Tax.PercentualCapitalTax. 0.005 will result in 5% of the players money. Tax.EnableFixedCapitalTax will ignore how much money a player has in their bank account and always issue the amount specified in Tax.FixedCapitalTax. you can combine both together.

2.6.2 Company Bank Accounts

Tax.EnablePercentualCompanyTax = true
Tax.PercentualCompanyTax    = 0.005
Tax.EnableFixedCompanyTax   = true
Tax.FixedCompanyTax         = 5000
Tax.ExcludedCompanys        = {'society_police'}

Same as previous tax for player bank accounts, but for company accounts with esx_society or qb-management. In the array Tax.ExcludedCompanys you can add societys that should not receive tax. For ESX its usually society_jobname, on QB-core its just the job name

2.6.3 General Settings

Tax.CapitalInterval         = 7
Tax.CapitalRandomInterval   = 2

Tax.CapitalInterval means that players have to pay the tax every X days. Tax.CapitalRandomInterval will add a random factor to this, to make it unpredictable for players. In this case players will randomly have to pay every 5-9 days.

2.7 Vehicles

2.7.1 Delaership Script

Tax.Dealership = 'esx_vehicleshop'

This is the dealership script that is used to get the vehicles price. Available are: lc_dealership, okokVehicleShop, myCardealer, qb-vehicleshop, esx_vehicleshop and custom. For custom read below. esx_vehicleshop can be used for any script that uses the vehicles table and qb-vehicleshop can be used for any script that uses the qb-core/shared/vehicles.lua file.

2.7.2 Vehicle Tax

Tax.EnablePercentualVehicleTax = true
Tax.PercentualVehicleTax    = 0.0075

Tax.EnableFixedVehicleTax   = true
Tax.FixedVehicleTax         = 100

Tax.VehicleInterval         = 7

Just like the capital tax. Percentual Vehicle Tax will take the vehicle value multiplied by Tax.PercentualVehicleTax as the cost while Tax.FixedVehicleTax is a fixed amount. Can be combined. Tax.VehicleInterval means every X days the tax has to be paid.

2.7.3 Impound unpaid vehicles

Tax.ImpoundVehicleIfNotPaid = false
Tax.Impound                 = 'Police'

This setting is exlusive to owners of our script loki_impound. With this, whenever a player can not pay their vehicle taxes, the vehicle gets impounded to the specified impound from Tax.Impound.

2.7.4 Default Price

Tax.DefaultPrice            = 50000
Tax.NotifyOnDefualtPrice    = true

In the case that the script is unable to find the price for a vehicle with the provided dealership script, this price is used. Tax.NotifyOnDefaultPrice will print in the server console whenever this has to be used.

2.7.5 Sync Vehicles

Tax.SyncVehicles             = false

If this is set to true, on every restart the registered_vehicles table will be synced to the owned_vehicles/player_vehicles table. This means every vehicle is always known to the script and therefore has a title.

2.7.6 Always Register Synced Vehicles

Tax.AlwaysRegister            = false

This is only used, if 2.7.5 Sync Vehiclesis set to true. If this is set to true, on every restart, every vehicle inside the registered_vehicles table will be set to be registered. Useful for servers who do not have players to register vehicles.

2.7.7 Custom Dealership Function

function CustomDealership(hash, price)
    MySQL.Async.fetchAll('SELECT price from dealership_vehicles WHERE hash = @hash LIMIT 1', {
        ['@hash'] = hash
    }, function(result)
        price = result[1].price
        return price
    end)
end

This is an example of how a custom function could look like. You can use this to add support for your dealership function, in case it's not supported by us. The provided values are the vehicle hash and a price of 0. The vehicle price has to be returned. If you need any help with this, contact us on discord.

2.7.8 Vehicle Certificates

The Vehicle Certificates feature gives your players the option to create certification documents for players vehicles. Depending on the country and the chosen style, their purpose can vary a bit, but mostly its a document to certify you are the owner and it also contains some data about the vehicle. Currently only the german style (Zulassungsbescheinigung Teil 1) is available. A us version for a california certificate of title is coming soon. If you want to see more, let me know on discord.

Tax.RegistrationCertificates = true
Tax.CertificateStyle = 'de'
Tax.CertificateItem = "fahrzeugschein"
Tax.Inventory = "qs-inventory"

Insert the name for the item you want to use in Tax.CertificateItem. You can use the html/images/fahrzeugschein.png file as image. Insert your inventory name in Tax.Inventory. Currently qs-inventory, ox_inventory and qb-inventory are supported. If your inventory is not supported, you can ask us on discord to add support for it. For the german version there is also a green version of the certificate in the image files. It has a higher resolution, but is not the exact real design. If you wish to use that one, just rename to files to the names of the original.

2.8 Propertys

2.8.1 Housing Script

Tax.Housing = 'qs-housing'

This is the housing script used for getting the price of a property. Available systems are: qs-housing, loaf_housing and qb-houses.

2.8.2 Property Tax

Tax.EnablePercentualPropertyTax = true
Tax.PercentualPropertyTax   = 0.0075

Tax.EnableFixedPropertyTax  = true
Tax.FixedPropertyTax        = 100

Tax.PropertyInterval        = 7

The same as before. Percentual Property Tax will take the property value multiplied by Tax.PercentualPropertyTax as the cost while Tax.FixedPropertyTax is a fixed amount. Can be combined. Tax.PropertyInterval means every X days the tax has to be paid.

2.8.3 Custom Housing Function

function CustomHousing(license, tax)
    local houseID = nil
    MySQL.Async.fetchAll('SELECT * FROM housing WHERE owner = @owner AND lastPay < DATE_SUB(NOW(), INTERVAL @interval DAY)', {
        ['@interval'] = Tax.Interval,
        ['@owner'] = license
    }, function(resulthouses)
        for k, v in pairs(resulthouse) do
            houseID = v.houseId
            tax = tax + math.ceil(v.price * Tax.PropertyTax)
            MySQL.Async.execute('UPDATE housing SET lastPay = CURDATE() WHERE houseId = @id', {
                ['@id'] = houseID
            })
        end
    end)
    return tax
end

You can use this custom function, if you have a different housing script that is not supported by us. This is an example, of how this could look. Remember to add a column lastPay in your housing database table and also remember to reset this to CURRDATE() or CURRENT_TIMESTAMP() after the tax is paid. The provided values are license, which is the player identifier. On ESX this will either be just the license if you only have one char per player, or with multichar its usually char1:license or something similar. With QB-Core it's the citizenid. The amount that has to be paid needs to be returned. If you need help with this, contact us on our discord.

2.9 Shops

2.9.1 Shop Script

Tax.Shop = 'okokShop'

This is the script used for your player owned shops to get the shop price as well as the current balance. Currently only okokShop is supported, but you can add support for your own script with the custom function in 2.9.3

2.9.2 Shop Tax

Tax.EnablePercentualShopTax = false
Tax.PercentualShopTax       = 0.0075

Tax.EnableFixedShopTax      = false
Tax.FixedShopTax            = 500

Tax.EnableAccountShopTax    = false
Tax.AccountShopTax          = 0.0075

Tax.ShopInterval            = 7

Very similar to the previous taxes. Percentual Shop Tax is the shop value multiplied by Tax.PercentualShopTax. Fixed Shop Tax is the fixed amount from Tax.FixedShopTax. Whats new is Account Shop Tax. This will be a percentual Tax applied to the current account balance of the shop. So the balance multiplied by Tax.AccountShopTax. Can be combined. Tax.ShopInterval means every X days the tax has to be paid.

2.9.3 Custom Shop Function

function CustomShop(source)
    local identifier = '' -- you have to get the identifier
    MySQL.Async.fetchAll('SELECT * FROM shops WHERE owner = @owner AND lastPay < DATE_SUB(NOW(), INTERVAL @interval DAY)', {
        ['@owner'] = identifier,
        ['@interval'] = Tax.ShopInterval
    }, function(result)
        for k, v in pairs(result) do
            tax = tax + (v.price * Tax.PercentualShopTax) + Tax.FixedShopTax + (v.accountMoney * Tax.AccountShopTax)
            MySQL.Async.execute('UPDATE shops SET lastPay = CURRENT_TIMESTAMP() WHERE shopId = ?' {v.shopId})
        end
    end)
    return tax
end

If your shop script is not supported by us, you can use this custom function to add support for it. The provided value source is the player server id. This is an example of how this function could look like, but you have to change it to fit your script. If you need help with this, ask us on our discord.

2.10 Gas Stations

2.10.1 Gas Station Script

Tax.GasStation = 'okokGasStation'

This is the script used to get the gas stations value and account balance. Supported are okokGasStation and lc_gas_stations. If you have a different script, you can add support for it with the custom function in 2.10.3

2.10.2 Gas Station Tax

Tax.EnablePercentualGasTax  = false
Tax.PercentualGasTax        = 0.0075

Tax.EnableFixedGasTax       = false
Tax.FixedGasTax             = 500

Tax.EnableAccountGasTax     = false
Tax.AccountGasTax           = 0.0075

Tax.GasInterval             = 7

The same as shop tax. Percentual Gas Tax is the Gas Station Value multiplied by Tax.PercentualGasTax. Fixed Gas Tax is just a fixed amount to pay. Account Gas Tax is the current Gas Station Ballance multiplied by Tax.AccountGasTax. Can be combined. Tax.GasInterval means every X days the tax has to be paid.

2.10.3 Cutsom Gas Station Function

function CustomGasStation(source)
    local identifier = '' -- your logic to get the identifier here
    MySQL.Async.fetchAll('SELECT * FROM gasStations WHERE owner = @owner AND lastPay < DATE_SUB(NOW(), INTERVAL @interval DAY)', {
        ['@owner'] = identifier,
        ['@interval'] = Tax.ShopInterval
    }, function(result)
        for k, v in pairs(result) do
            tax = tax + (v.price * Tax.PercentualGasTax) + Tax.FixedGasTax + (v.accountMoney * Tax.AccountGasTax)
            MySQL.Async.execute('UPDATE gasStations SET lastPay = CURRENT_TIMESTAMP() WHERE id = ?' {v.id})
        end
    end)
    return tax
end

If your Gas Station script is not supported by us, you can use this custom function to add support for it. The provided value source is the player server id. This is an example of how this function could look like, but you have to change it to fit your script. If you need help with this, ask us on our discord.

2.11 Billing

2.11.1 Billing Script

Tax.Billing = 'esx_billing'

This is the script used, to issue invoices to the player. Supported scripts are: zapps_billing, esx_billing, okokBilling, qb (through the phone app) and none (just remove money from player account). Note that if you use qb-phone's app, itonly gets refreshed if the player rejoines. If your script is not supported by us, you can add it yourself with the custom function in 2.11.3

2.11.2 Billing Settings

Tax.TaxSociety              = 'society_police'
Tax.TaxSocietyName          = 'IRS'
Tax.TaxSenderName           = 'IRS'
Tax.TaxDaysToPay            = 7

Tax.TaxSociety is the society that will receive the money. For ESX it's usually society_jobname, for QB-Core it's just the job name. Tax.TaxSenderName is the name that will appear, depending on your billing script. Using your countrys Tax Agency is recommended. Tax.TaxSocietyName as well. Tax.TaxDaysToPay is the amount of days the player has time to pay the invoice (zapps_billing only)

2.11.3 Custom Billing Function

function CustomBilling(receiver, tax, plate, source, taxType)
    TriggerEvent()
end

If we do not support your billing script, you can add support for it yourself, using this function. receiver is the identifier/citizenid of the player. tax is the amount that has to be paid. source is the player server id. taxType is the type of tax, you can use this for texts or notifications. Possible taxTypes are property, vehicle, shop, gas, capital. Usually you just need to add your scripts export or TriggerEvent(), take a look at their documentation. If you need help with this, contact us on our discord.

2.12 Notifications

2.12.1 Notification Script

Tax.Notification = 'esx'

This is the notification script used. Supported scripts are: okokNotify, esx, lib (Ox_Lib), RiP-Notify, qb, wasabi_notify, mythic_notify and sy_notify. If yours is not supported, you can add your own script with the custom function in 2.12.2

2.12.2 Custom Notification Script

function CustomNotify(type, msg, heading, source) 
    TriggerClientEvent('customNotify')
end

If your notification script is not supported, you can use this to add support for your own. type is the type of notification. Possible types are info, success and error. msg is just the notification message. heading is the notification heading, if your script does not have notification headings, leave this out. source is the player server id. Usually you just need to add your scripts event or export. Read their docs. If you need help with this, contact us on our discord.

If you have any questions, open a ticket on our discord. If your script is not supported, you can ask us and we will try to add native support for it. https://discord.gg/CfnuaArDBk