Configuration

legends_tax uses two configuration files:

config.json - Main tax settings (can be edited in-game via admin panel)
permissions.lua - Admin access configuration

Non-technical users: Use the in-game admin panel (/taxadmin) to configure most settings without editing files!

General Settings

useCustomNotifications

"general": {
    "useCustomNotifications": true
}

Description: Use ox_lib notifications instead of framework-specific ones.

Type: boolean | Default: true

notificationDuration

"notificationDuration": 20000

Description: How long notifications display (milliseconds).

Type: number | Default: 20000 (20 seconds)

enableDebug

"enableDebug": false

Description: Enable debug prints in server console.

Type: boolean | Default: false

allowNegativeBank

"allowNegativeBank": true

Description: Allow players to go into negative bank balance when auto-pay triggers.

Type: boolean | Default: true

Tax Type Toggles

"enableVehicleTax": true,
"enableBankTax": true,
"enableHouseTax": false

Setting	Description
`enableVehicleTax`	Enable/disable vehicle taxation
`enableBankTax`	Enable/disable bank balance taxation
`enableHouseTax`	Enable/disable property taxation

playerInteractionMode

"playerInteractionMode": "npc"

Description: How players access the tax UI to view and pay their invoices.

Type: string | Default: "npc"

Value	Behavior
`"npc"`	Players interact with a Tax Office NPC placed in the world
`"command"`	Players use the `/taxui` chat command instead

When set to "command", the Tax Office NPC will not spawn. Players will use /taxui to open their invoice viewer.

Inactive Player Bypass

"enableInactivePlayerBypass": false,
"inactivePlayerDays": 30

Setting	Type	Default	Description
`enableInactivePlayerBypass`	boolean	`false`	Skip taxation for players who haven't logged in recently
`inactivePlayerDays`	number	`30`	Number of days of inactivity before a player is excluded from tax collection

When enabled, players who haven't joined the server within the specified number of days will be automatically skipped during tax collection cycles. This prevents accumulating taxes on players who may have left the server permanently.

Bank Tax Settings

"bankTax": {
    "bankTaxRate": 0.05,
    "minBankBalanceForTax": 10000,
    "maxBankBalanceForTax": 1000000
}

Property	Type	Description
`bankTaxRate`	number	Percentage of bank balance to tax (0.05 = 5%)
`minBankBalanceForTax`	number	Minimum balance before bank tax applies
`maxBankBalanceForTax`	number	Maximum balance to consider for taxation

Example: With 5% rate and $50,000 bank balance:

Tax = $50,000 × 0.05 = $2,500

Vehicle Tax Settings

"vehicleTax": {
    "baseVehicleTaxRate": 0.02,
    "extraVehicleTaxRate": 0.02,
    "maxVehicleTaxRate": 0.10,
    "useGlobalVehicleTaxRates": false,
    "categoryRates": {}
}

Property	Type	Description
`baseVehicleTaxRate`	number	Base rate for first vehicle (0.02 = 2%)
`extraVehicleTaxRate`	number	Additional rate per extra vehicle
`maxVehicleTaxRate`	number	Maximum rate cap (0.10 = 10%)
`useGlobalVehicleTaxRates`	boolean	Use flat rate vs category-based rates
`categoryRates`	object	Per-category tax rates

Category-Based Rates

When useGlobalVehicleTaxRates is false, you can set rates per vehicle class:

"categoryRates": {
    "Super": 0.08,
    "Sports": 0.06,
    "Muscle": 0.04,
    "Sedans": 0.02,
    "Compacts": 0.01
}

Property Tax Settings

"propertyTax": {
    "taxPerHouse": false,
    "pricePerHouse": 100000,
    "percentagePerHouse": 0.05
}

Property	Type	Description
`taxPerHouse`	boolean	Flat amount per house vs percentage
`pricePerHouse`	number	Flat amount if `taxPerHouse` is true
`percentagePerHouse`	number	Percentage of house value if false

Supported Housing Scripts

The resource automatically detects which housing script is installed. No manual configuration is required.

Housing Script	Detection Method
NoLag Properties	`properties` + `properties_owners` tables
PS-Housing	`properties` table with `property_id` column
QB-Houses	`player_houses` + `houselocations` tables
QS-Housing Advanced	`player_houses` + `houselocations` + `house_rents` tables

Housing system detection happens automatically on resource start. Use the /taxhousing admin command to check which housing system was detected.

Tax Intervals

Global vs Separate Intervals

"taxIntervals": {
    "useGlobalInterval": false,
    "globalTaxIntervalDays": 7,
    "vehicleTaxIntervalDays": 7,
    "propertyTaxIntervalDays": 14,
    "bankTaxIntervalDays": 3,
    "showCollectionTimer": true
}

Property	Type	Description
`useGlobalInterval`	boolean	Use single interval for all taxes
`globalTaxIntervalDays`	number	Days between tax collections (global mode)
`vehicleTaxIntervalDays`	number	Days between vehicle tax
`propertyTaxIntervalDays`	number	Days between property tax
`bankTaxIntervalDays`	number	Days between bank tax
`showCollectionTimer`	boolean	Show countdown in player UI

When useGlobalInterval is true, all taxes are collected together using globalTaxIntervalDays.

Unpaid Tax Settings

"unpaidTax": {
    "taxInterestRate": 0.05,
    "taxInterestIntervalDays": 3,
    "autoPayUnpaidTaxDays": 7,
    "maxTaxInterestRate": 0.5
}

Property	Type	Description
`taxInterestRate`	number	Interest added per interval (0.05 = 5%)
`taxInterestIntervalDays`	number	Days between interest applications
`autoPayUnpaidTaxDays`	number	Days before auto-pay triggers
`maxTaxInterestRate`	number	Maximum total interest cap (0.5 = 50%)

Example flow:

Invoice created: $1,000
After 3 days (unpaid): $1,000 + 5% = $1,050
After 6 days: $1,050 + 5% = $1,102.50
After 7 days: Auto-pay from bank

Job Discounts

"jobDiscounts": {
    "police": 15,
    "ambulance": 10,
    "mechanic": 5
}

Format: "jobName": discountPercentage

Players with these jobs receive the specified percentage discount on all taxes.

NPC Settings

"npc": {
    "model": "a_m_y_business_01",
    "coords": { "x": 216.19, "y": -808.77, "z": 30.74 },
    "heading": 90.0,
    "label": "Tax Office",
    "icon": "fa-solid fa-money-bill-wave",
    "useOxTarget": true
}

Property	Type	Description
`model`	string	NPC ped model name
`coords`	object	NPC spawn location
`heading`	number	NPC facing direction
`label`	string	Target/interaction label
`icon`	string	FontAwesome icon class
`useOxTarget`	boolean	Use ox_target for interaction

Testing Mode

"testing": {
    "testingMode": false,
    "testingGlobalIntervalSeconds": 10,
    "testingVehicleTaxIntervalSeconds": 10,
    "testingPropertyTaxIntervalSeconds": 15,
    "testingBankTaxIntervalSeconds": 5,
    "testingInterestIntervalSeconds": 20,
    "testingAutoPaySeconds": 145
}

⚠️

Testing Mode: When enabled, all intervals use seconds instead of days. Never enable in production!

Performance Settings

"performance": {
    "taxCycleYieldInterval": 10,
    "adminBulkBatchSize": 10,
    "adminBatchDelayMs": 100,
    "adminQueryTimeoutMs": 10000
}

Property	Description
`taxCycleYieldInterval`	Yield every N players during tax cycles
`adminBulkBatchSize`	Batch size for bulk admin operations
`adminBatchDelayMs`	Delay between batches
`adminQueryTimeoutMs`	Timeout for admin queries

Maintenance Settings

"maintenance": {
    "auditLogRetentionDays": 90,
    "invoiceArchiveAfterDays": 365,
    "maintenanceScheduleHour": 4,
    "maintenanceBatchSize": 1000
}

Property	Description
`auditLogRetentionDays`	Days to keep audit logs
`invoiceArchiveAfterDays`	Days before archiving paid invoices
`maintenanceScheduleHour`	Hour to run maintenance (0-23)
`maintenanceBatchSize`	Records per maintenance batch

Permissions Configuration

Location: permissions.lua

Permission Modes

Permissions.UseAcePermissions = true   -- Use ACE permissions
Permissions.UseWhitelist = true        -- Use identifier whitelist
Permissions.RequireBoth = false        -- Require both or just one

ACE Permission

Permissions.AcePermission = "tax.admin"

Add to server.cfg:

add_ace group.admin tax.admin allow

Whitelist

Permissions.Whitelist = {
    "steam:11000010000000",
    "discord:123456789012345678",
    "license:1234567890abcdef1234567890abcdef12345678",
    "fivem:123456",
}

CitizenID Whitelist (Legacy)

Permissions.CitizenIds = {
    "ABC12345",
    "XYZ98765",
}

Discord Webhook

Permissions.UseDiscordLogging = true
Permissions.DiscordWebhook = "https://discord.com/api/webhooks/..."

Example Configurations

Low Tax Server

{
    "bankTax": {
        "bankTaxRate": 0.02,
        "minBankBalanceForTax": 50000
    },
    "vehicleTax": {
        "baseVehicleTaxRate": 0.01
    },
    "unpaidTax": {
        "taxInterestRate": 0.02,
        "autoPayUnpaidTaxDays": 14
    }
}

High Tax Economy Server

{
    "bankTax": {
        "bankTaxRate": 0.10,
        "minBankBalanceForTax": 5000
    },
    "vehicleTax": {
        "baseVehicleTaxRate": 0.05,
        "extraVehicleTaxRate": 0.03
    },
    "unpaidTax": {
        "taxInterestRate": 0.10,
        "autoPayUnpaidTaxDays": 3
    }
}

Need Help?

Join our Discord for support: discord.gg/lgnds (opens in a new tab)

Installation Exports & API