esx_society

esx_society turns an ESX job into a company. It links a job to a shared bank account, adds a boss menu for hiring, firing, promotions, salaries, grade labels and uniforms, and lets bosses launder black money into the company account. Job resources such as esx_policejob, esx_taxijob and esx_mechanicjob register their society with it and open its boss menu.

OverviewCopy Anchor Link

A society is a plain record kept in memory:

Societies are not saved in the database. Every job resource must register its society again on every start.

InstallationCopy Anchor Link

CREATE TABLE `society_moneywash` (
	`id` int NOT NULL AUTO_INCREMENT,
	`identifier` varchar(60) NOT NULL,
	`society` varchar(60) NOT NULL,
	`amount` int NOT NULL,
	PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

ensure cron
ensure esx_addonaccount
ensure esx_datastore
ensure esx_addoninventory
ensure esx_society
# job resources after this line
ensure esx_policejob
ensure esx_taxijob

ConfigurationCopy Anchor Link

All keys live in config.lua.

Config.BossGrades = {
    ['boss'] = true,
    ['chef'] = true,   -- give a second grade access to the boss menu
}

How it worksCopy Anchor Link

• Boss check: a player has boss access to a society when xPlayer.getJob().name == society.name and the grade name is in Config.BossGrades. Every server event and callback repeats this check. The client menu is only a view.
• Account: balance, deposits and withdrawals go through the shared esx_addonaccount account named in society.account.
• Salaries and labels are written to job_grades and then reloaded with ESX.RefreshJob(job) (or ESX.RefreshJobs() as fallback), so changes apply without a restart.
• Employees are listed in pages of 50: online players first, then offline players from the users table.
• Money washing is queued in society_moneywash_operations and paid by a cron task every day at 03:00 (TriggerEvent('cron:runAt', 3, 0, WashMoneyCRON)).
• Society payouts: when es_extended's Config.EnableSocietyPayouts is true, the paycheck module calls esx_society:getSociety and pays salaries from the society account. See Money and accounts.

Server APICopy Anchor Link

registerSociety (export and event)Copy Anchor Link

Registers a job as a society. Call it once when your job resource starts.

exports.esx_society:registerSociety(name, label, account, datastore, inventory, data)
TriggerEvent('esx_society:registerSociety', name, label, account, datastore, inventory, data)

Returns nothing. Registering the same name twice prints a warning and keeps the first entry.

exports.esx_society:registerSociety('taxi', 'Taxi', 'society_taxi', 'society_taxi', 'society_taxi', { type = 'public' })

The event is a local server event (AddEventHandler). Clients cannot trigger it.

GetSociety (export)Copy Anchor Link

local society = exports.esx_society:GetSociety(name)

Returns the society table or nil.

local society = exports.esx_society:GetSociety('police')

if society then
    TriggerEvent('esx_addonaccount:getSharedAccount', society.account, function(account)
        print(('%s has $%s'):format(society.label, account.money))
    end)
end

esx_society:getSociety (event)Copy Anchor Link

Callback style lookup, used by es_extended's paycheck module.

TriggerEvent('esx_society:getSociety', name, cb)

esx_society:getSocieties (event)Copy Anchor Link

TriggerEvent('esx_society:getSocieties', function(societies)
    for _, society in ipairs(societies) do
        print(society.name, society.account)
    end
end)

Returns the array of all registered societies.

Client APICopy Anchor Link

esx_society:openBossMenuCopy Anchor Link

Opens the boss menu (ESX context menu). Use it from a marker or target zone in your job resource.

TriggerEvent('esx_society:openBossMenu', society, close, options)

TriggerEvent('esx_society:openBossMenu', 'taxi', function()
    ESX.CloseContext()
end, { wash = false, uniforms = true })

The menu first asks the server through the esx_society:isBoss callback. Non-bosses see nothing.

Network events (client to server)Copy Anchor Link

These are RegisterServerEvent handlers, so any client can send them. All of them validate on the server.

TriggerServerEvent('esx_society:depositMoney', 'taxi', 500)

Server callbacksCopy Anchor Link

Registered with xLib.callback.registerCompat. Call them with ESX.TriggerServerCallback, ESX.AwaitServerCallback or xLib.callback. See Callbacks.

esx_society:setJob rulesCopy Anchor Link

actionType must be 'hire', 'promote' or 'fire'.

• hire / promote: job must be the boss's own job and grade must exist and be lower than or equal to the boss's grade. Hiring needs the target online.
• fire: job must be 'unemployed' and grade must be 0.
• Offline targets (promote or fire) are updated in the users table only if they currently work for the boss's job.

local ok = ESX.AwaitServerCallback('esx_society:setJob', targetIdentifier, 'taxi', 2, 'promote')

if ok then
    ESX.ShowNotification('Promoted')
end

Reading the balance in a HUDCopy Anchor Link

local job = ESX.PlayerData.job

ESX.TriggerServerCallback('esx_society:getSocietyMoney', function(money)
    print(('Company balance: $%s'):format(money))
end, job.name)

Money washing in detailCopy Anchor Link

1. The boss enters an amount. The server checks boss access and the player's black_money.
2. Inside WithPlayerPersistence, the amount is removed from black_money and a row is written to society_moneywash_operations with state queued in one transaction. If that fails, the money is refunded.
3. Every day at 03:00 the cron task adds each queued amount to the society account and marks it paid.

There is no washing fee: 1,000 black money becomes 1,000 in the society account. Old rows in society_moneywash are migrated into the new table on start.

Integration tipsCopy Anchor Link

• Create the SQL rows first. A society needs society_<job> in addon_account (shared = 1). The official job SQL files also add the same name to datastore and addon_inventory.
• Register the society at the top of your server file, after esx_society started. With ensure order this is guaranteed.
• To give a second grade boss rights, add its job_grades.name to Config.BossGrades. The check uses the name, not the grade number.
• Uniforms are stored in job_grades.skin_male and skin_female and are read by job scripts that dress players from the grade skin.

Common issuesCopy Anchor Link

• Menu shows nothing: the grade name is not in Config.BossGrades, or the job name passed to openBossMenu differs from the player's job. The server log shows esx_society: <identifier> attempted open a society boss menu!.
• "Society has no shared account" in the console: the addon_account row for society_<job> is missing or not marked shared = 1.
• Salary change does nothing: the value is above Config.MaxSalary, not a whole number, equal to the current value, or sent within Config.JobGradeUpdateCooldown.
• Washed money never arrives: the cron resource is not running, the server was offline at 03:00, or the wash module was disabled because a table is not InnoDB. Queued entries stay queued and are paid on the next run.
• Employee list empty for offline players: with Config.EnableESXIdentity = true the query selects firstname and lastname. Without esx_identity those columns may not exist; set the option to false.

RelatedCopy Anchor Link

• esx_addonaccount
• esx_datastore
• Create a job
• Money and accounts
• Addons overview

Frequently asked questions