Features
Company (fx-companyapp)
The bundled company management app, how it installs into the phone, its main settings and its full developer API.
#What it is
fx-companyapp is a company management app: employee roster, hiring and firing, ranks, company funds (deposit and withdraw), announcements, company invoices with commission, statistics, a business directory and an audit log.
#Requirements
| Resource | Required |
|---|---|
fx-phone |
Yes (the app also installs into lb-phone or cylex_phone) |
qb-core, or qbx_core with the qb-core bridge |
Yes |
oxmysql |
Yes |
A banking resource: tgiann-bank, okokBanking, qb-banking, qb-management or qb-bossmenu |
Yes, pick one in config.lua |
#Installation
cfgensure oxmysql
ensure qb-core
ensure fx-phone
ensure fx-companyapp
- Keep the folder name. Other scripts call this resource as
exports['fx-companyapp']. - The database tables are created on first start. Import
setup/sql/install.sqlonly if the console reports that the tables could not be created. - Choose the jobs that can use the app with
Config.UseWhitelist,Config.JobWhitelistandConfig.JobBlacklist. A job that is not allowed sees a "no company" screen. - Set
Config.Banking.Providerand do one test deposit and one test withdrawal on a test character.
#How it registers into the phone
The resource has one adapter per phone in client/phone/. With Config.Phone.Resource = "auto" the first running phone wins, in the order fx-phone, lb-phone, cylex_phone.
- The FX Phone adapter calls
exports['fx-phone']:AddCustomAppwithidentifier = Config.AppIdentifier(defaultfx_company),name = Config.AppName, the description, developer,defaultApp = Config.DefaultApp,price = Config.AppPrice, a screenshot,uiandicon. - Notifications go through
exports['fx-phone']:SendNotification. - With
Config.Phone.WalletTransactions = true, deposits and withdrawals are also written to the phone's bank history withAddTransaction.
To keep the app from starting at all, set ['fx-companyapp'] = false in Config.BundledApps. See Apps.
#Config highlights
config.lua:
| Setting | Meaning |
|---|---|
Config.AppName, Config.AppIdentifier, Config.AppPrice, Config.DefaultApp, Config.Developer |
How the app appears on the phone. Never set the identifier to company |
Config.Phone |
Phone choice, per-phone scale, WalletTransactions |
Config.Locale, Config.Theme, Config.Currency |
Language, first-open theme (system, corporate, midnight), currency symbol |
Config.Account |
Player's personal account: bank or cash |
Config.Banking.Provider |
tgiann-bank, okokBanking, qb-banking, qb-management, qbcore-society or custom (bank_adapter.lua) |
Config.UseWhitelist, Config.JobWhitelist, Config.JobBlacklist |
Which jobs can open the app |
Config.UnemployedJob |
Job given when someone is fired |
Config.Permissions |
Who may do what, see below |
Config.JobPermissionOverrides |
Per-job overrides of Config.Permissions |
Config.ProtectHigherRanks |
Nobody can fire or re-rank someone at or above their own rank |
Config.HireMode, Config.HireNearbyDistance, Config.DefaultHireGrade |
How hiring works |
Config.MinKasaAmount, Config.MaxKasaAmount |
Limits for one in-app deposit or withdrawal |
Config.HistoryLimit, Config.LogLimit, Config.PruneAfterDays |
How much history is shown and kept |
Config.Invoices |
Company invoices: CompanyOnly, BlockSelf, BlockSameCompany, PayAccount, commission limits, TaxPercent, MaxAmount, MaxDistance, ExpireDays and more |
Config.InvoicePresets, Config.JobTypes |
Ready invoice lists per business type |
Config.Directory (config_directory.lua) |
Business directory defaults: categories, accent colours, allowed image hosts, text limits |
Config.Permissions maps each action to "boss" (ranks flagged isboss), "member" (anyone in the company) or a grade level number (that grade and above). The actions are hire, fire, setGrade, withdraw, deposit, announce, viewLogs, viewKasa, invoice, viewInvoices, cancelInvoice, manageInvoices, viewStats, editProfile, viewMessages, takeLine.
config_server.lua is server only. It holds the log settings: Discord webhooks (a default, one per group and per company), which events are sent, and console output.
#API rules
- Exports are server side unless listed under Client exports.
- Actions return
ok, value. Whenokistruethe second value is the result. Whenokisfalseit is an error reason, listed at the end of this page. - Exports do not check player permissions. They act as the system. If you act on behalf of a player, ask first with
HasPermission. - Hooks still run. A
beforeFirehook blocks a fire whether it came from the app or from an export. - Changes are visible live. Open apps of the affected company refresh by themselves.
- A job does not have to be in
Config.JobWhitelistfor the exports to work. The whitelist only controls who can open the app. - A job name is a non-empty string of at most 60 characters.
Many actions accept an opts table:
| Field | Type | Meaning |
|---|---|---|
actor |
string | Name shown in the audit log and history. Default: the name of source, or "System" |
source |
number | Server id of the player who caused it, passed to hooks and events |
notify |
boolean | false sends the affected player no phone notification |
title |
string | Transaction title (funds only) |
category |
string | Transaction category (funds only) |
log |
boolean | false writes no history or audit row |
#Server exports: company and employees
#GetPlayerCompany
Returns the player's company as the app sees it.
lua---@param src number
---@return table|nil company { job, label, isboss, grade = { level, name } }
exports['fx-companyapp']:GetPlayerCompany(src)
lualocal company = exports['fx-companyapp']:GetPlayerCompany(source)
Returns nil when the player's job cannot use the app.
#IsJobAllowed
Tells whether a job can use the app.
lua---@param job string
---@return boolean
exports['fx-companyapp']:IsJobAllowed(job)
lualocal allowed = exports['fx-companyapp']:IsJobAllowed('mechanic')
#HasPermission
Tells whether a player may do an action in their company.
lua---@param src number
---@param action string A key of Config.Permissions, e.g. 'withdraw'
---@return boolean
exports['fx-companyapp']:HasPermission(src, action)
luaif not exports['fx-companyapp']:HasPermission(source, 'withdraw') then return end
Always false when the player has no company.
#GetPermissions
Returns every permission of a player in one call.
lua---@param src number
---@return table<string, boolean> permissions
exports['fx-companyapp']:GetPermissions(src)
lualocal perms = exports['fx-companyapp']:GetPermissions(source)
#GetCompanyGrades
Returns a job's ranks, sorted by level.
lua---@param job string
---@return table[] grades { level, name, isboss, payment }
exports['fx-companyapp']:GetCompanyGrades(job)
lualocal grades = exports['fx-companyapp']:GetCompanyGrades('mechanic')
#GetCompanyMembers
Returns every employee, online and offline, highest rank first.
lua---@param job string
---@return table[] members { citizenid, name, grade, gradeName, isboss, online, onduty }
exports['fx-companyapp']:GetCompanyMembers(job)
lualocal members = exports['fx-companyapp']:GetCompanyMembers('mechanic')
The roster is cached per job and dropped on every hire, fire, rank change and job update.
#GetEmployee
Returns one employee of a job.
lua---@param job string
---@param who string|number Citizen id or server id
---@return table|nil employee { citizenid, source?, online, level, isboss, name }
exports['fx-companyapp']:GetEmployee(job, who)
lualocal emp = exports['fx-companyapp']:GetEmployee('mechanic', source)
Returns nil when they are not in that job. source is nil when the employee is offline.
#GetOnlineEmployees
Returns the online employees of a job.
lua---@param job string
---@param onDutyOnly? boolean
---@return table[] employees { source, citizenid, onduty }
exports['fx-companyapp']:GetOnlineEmployees(job, onDutyOnly)
lualocal staff = exports['fx-companyapp']:GetOnlineEmployees('police', true)
#GetCompanySummary
Returns head counts, payroll and balance of a company.
lua---@param job string
---@return table|nil summary { job, label, memberCount, onlineCount, onDutyCount, payroll, balance }
exports['fx-companyapp']:GetCompanySummary(job)
lualocal summary = exports['fx-companyapp']:GetCompanySummary('mechanic')
payroll is the sum of every employee's rank payment.
#Server exports: company funds
The funds live in the banking resource chosen in Config.Banking.Provider. These exports go through the same provider and write the in-app transaction history.
#GetCompanyBalance
Returns the company's funds.
lua---@param job string
---@return number balance
exports['fx-companyapp']:GetCompanyBalance(job)
lualocal balance = exports['fx-companyapp']:GetCompanyBalance('mechanic')
#CompanyAccountExists
Tells whether the banking resource has an account for the job.
lua---@param job string
---@return boolean
exports['fx-companyapp']:CompanyAccountExists(job)
lualocal exists = exports['fx-companyapp']:CompanyAccountExists('mechanic')
Providers that cannot tell (qb-banking, qb-management, qb-bossmenu) always return true.
#AddCompanyMoney
Adds money to the company funds and writes a history row.
lua---@param job string
---@param amount number Positive; decimals are floored
---@param opts? table { title?, category?, actor?, source?, log? }
---@return boolean ok
---@return number|string newBalanceOrReason
exports['fx-companyapp']:AddCompanyMoney(job, amount, opts)
lualocal ok, balance = exports['fx-companyapp']:AddCompanyMoney('mechanic', 2500, { title = 'Invoice #1042', category = 'invoice' })
Config.MaxKasaAmountdoes not apply here. It only limits a single in-app deposit or withdrawal.- Defaults: title "Income", category
income, actor "System". - Failure reasons:
invalidJob,invalidAmount,kasaUnavailable,generic, or the reason abeforeMoneyChangehook returned.
#RemoveCompanyMoney
Removes money from the company funds and writes a history row.
lua---@param job string
---@param amount number Positive; decimals are floored
---@param opts? table { title?, category?, actor?, source?, log? }
---@return boolean ok
---@return number|string newBalanceOrReason
exports['fx-companyapp']:RemoveCompanyMoney(job, amount, opts)
lualocal ok, balance = exports['fx-companyapp']:RemoveCompanyMoney('burger', 800, { title = 'Stock order', category = 'stock' })
Fails with insufficientKasa instead of going negative. Defaults: title "Expense", category expense.
#LogTransaction
Writes a history row without moving money.
lua---@param job string
---@param amount number Positive = in, negative = out
---@param title string
---@param category? string
---@param actor? string
exports['fx-companyapp']:LogTransaction(job, amount, title, category, actor)
luaexports['fx-companyapp']:LogTransaction('mechanic', 500, 'Tow fee', 'service', 'John Doe')
Use it when your script already moved the money through the banking resource itself. Call it right after the money moved, so the account ledger does not record the movement a second time.
#GetCompanyTransactions
Returns the newest transactions of a company.
lua---@param job string
---@param limit? number Default Config.HistoryLimit
---@return table[] transactions { amount, title, category, actor, ts }
exports['fx-companyapp']:GetCompanyTransactions(job, limit)
lualocal rows = exports['fx-companyapp']:GetCompanyTransactions('mechanic', 20)
ts is a Unix timestamp.
#Server exports: employee management
These do what the app does, without the permission and rank-protection checks. The target gets a phone notification and their open app reloads.
#HireEmployee
Hires an online player.
lua---@param job string
---@param targetSrc number
---@param grade? number Default Config.DefaultHireGrade
---@param opts? table { actor?, source?, notify? }
---@return boolean ok
---@return string gradeNameOrReason
exports['fx-companyapp']:HireEmployee(job, targetSrc, grade, opts)
lualocal ok, res = exports['fx-companyapp']:HireEmployee('mechanic', targetId, 0, { actor = 'Job Center' })
Failure reasons: invalidJob, playerNotOnline, alreadyInCompany, invalidGrade.
#FireEmployee
Fires an employee, online or offline.
lua---@param job string
---@param citizenid string
---@param opts? table { actor?, source?, notify? }
---@return boolean ok
---@return string nameOrReason
exports['fx-companyapp']:FireEmployee(job, citizenid, opts)
lualocal ok, name = exports['fx-companyapp']:FireEmployee('mechanic', 'ABC12345')
The employee is moved to Config.UnemployedJob. Fails with playerNotFound when the citizen id is not an employee of that job.
#SetEmployeeGrade
Changes an employee's rank, online or offline.
lua---@param job string
---@param citizenid string
---@param grade number
---@param opts? table { actor?, source?, notify? }
---@return boolean ok
---@return string nameOrReason
exports['fx-companyapp']:SetEmployeeGrade(job, citizenid, grade, opts)
luaexports['fx-companyapp']:SetEmployeeGrade('police', 'ABC12345', 3, { actor = 'Command' })
The audit log records it as promoted or demoted.
#Server exports: audit log
#LogAction
Adds a row to the company's audit log.
lua---@param job string
---@param action string Short key, at most 32 characters
---@param actor? string
---@param target? string
---@param detail? string Line text shown in the app
exports['fx-companyapp']:LogAction(job, action, actor, target, detail)
luaexports['fx-companyapp']:LogAction('mechanic', 'craft', 'John Doe', nil, 'John Doe crafted 5x Repair Kit')
Known actions get their own icon: hired, fired, graded, deposit, withdraw, announce.
#GetCompanyLogs
Returns the newest audit rows of a company.
lua---@param job string
---@param limit? number 1 to 200, default Config.LogLimit
---@return table[] logs { action, actor, target, detail, ts }
exports['fx-companyapp']:GetCompanyLogs(job, limit)
lualocal logs = exports['fx-companyapp']:GetCompanyLogs('mechanic', 50)
#Server exports: notifications
#NotifyPlayer
Sends a phone notification to an online player.
lua---@param src number
---@param title string
---@param message string
---@return boolean sent
exports['fx-companyapp']:NotifyPlayer(src, title, message)
luaexports['fx-companyapp']:NotifyPlayer(source, 'Shift', 'Your shift starts in 5 minutes')
#NotifyEmployee
Sends a phone notification by citizen id.
lua---@param citizenid string
---@param title string
---@param message string
---@return boolean sent
exports['fx-companyapp']:NotifyEmployee(citizenid, title, message)
luaexports['fx-companyapp']:NotifyEmployee('ABC12345', 'Payroll', 'Your bonus was paid')
Returns false when the player is offline. Nothing is queued.
#SendAnnouncement
Sends a notification to every online employee of a job.
lua---@param job string
---@param message string
---@param opts? table { title?, onDutyOnly?, exclude?, actor?, log? }
---@return number sent How many employees received it
exports['fx-companyapp']:SendAnnouncement(job, message, opts)
lualocal sent = exports['fx-companyapp']:SendAnnouncement('police', 'Code 3 at Legion Square', { onDutyOnly = true, title = 'Dispatch' })
excludeis a server id to skip.log = falsewrites no audit row.- Returns
0for an invalid job or an empty message.
#Server exports: phone and app
#GetPhoneResource
Returns the phone resource in use on the server.
lua---@return string|nil phone 'fx-phone', 'lb-phone', 'cylex_phone' or nil
exports['fx-companyapp']:GetPhoneResource()
lualocal phone = exports['fx-companyapp']:GetPhoneResource()
#RefreshApp
Forces open apps to reload their data.
lua---@param target number|string Server id or job name
---@param scope? string 'all' (default), 'members', 'kasa', 'logs' or 'invoices'
exports['fx-companyapp']:RefreshApp(target, scope)
luaexports['fx-companyapp']:RefreshApp('mechanic', 'kasa')
You only need this when your script changed something the app reads without going through these exports.
#GetVersionStatus
Returns the result of the update check.
lua---@return table status { state, current, latest, behind }
exports['fx-companyapp']:GetVersionStatus()
lualocal status = exports['fx-companyapp']:GetVersionStatus()
#Server exports: invoices
Invoices are always issued in a company's name. When one is paid, the commission goes to the employee who issued it, the optional tax is removed and the rest goes to the company funds.
#CreateInvoice
Issues an invoice in a company's name.
lua---@param job string
---@param target number|string Server id or citizen id
---@param amount number
---@param label string
---@param opts? table { issuerSrc?, issuerCid?, issuerName?, note?, notify? }
---@return boolean ok
---@return table|string invoiceOrReason
exports['fx-companyapp']:CreateInvoice(job, target, amount, label, opts)
lualocal ok, inv = exports['fx-companyapp']:CreateInvoice('mechanic', customerSrc, 1500, 'Engine repair', { issuerSrc = source })
- No permission check. Your resource decides who may bill.
- Offline players can be invoiced by citizen id.
issuerSrcis the online employee who gets the commission. Without it the issuer isissuerCid/issuerName, or the company itself.labelis cut toConfig.Invoices.LabelMaxLength.- Failure reasons:
invalidJob,invalidAmount,invalidLabel,playerNotFound, or a hook's reason.
#PayInvoice
Pays an invoice from the payer's money.
lua---@param id number
---@param payerSrc number
---@param opts? table { anyPayer? }
---@return boolean ok
---@return table|string invoiceOrReason
exports['fx-companyapp']:PayInvoice(id, payerSrc, opts)
lualocal ok, inv = exports['fx-companyapp']:PayInvoice(42, source)
Pays from Config.Invoices.PayAccount, with a cash fallback when PayFallbackToCash is on. Only the invoice's customer can pay unless opts.anyPayer = true.
#CancelInvoice
Cancels an unpaid invoice.
lua---@param id number
---@param opts? table { actor?, source? }
---@return boolean ok
---@return number|string idOrReason
exports['fx-companyapp']:CancelInvoice(id, opts)
luaexports['fx-companyapp']:CancelInvoice(42, { actor = 'Dispatch' })
#GetInvoice
Returns one invoice.
lua---@param id number
---@return table|nil invoice
exports['fx-companyapp']:GetInvoice(id)
lualocal inv = exports['fx-companyapp']:GetInvoice(42)
Fields: id, job, companyLabel, label, note, amount, status, issuerCid, issuerName, targetCid, targetName, commissionPct, commission, tax, companyShare, closedBy, createdAt, closedAt. status is unpaid, paid, cancelled or expired.
#GetCompanyInvoices
Returns a company's invoices, newest first.
lua---@param job string
---@param filter? table { status?, issuerCid?, targetCid?, limit?, offset? }
---@return table[] invoices
exports['fx-companyapp']:GetCompanyInvoices(job, filter)
lualocal unpaid = exports['fx-companyapp']:GetCompanyInvoices('mechanic', { status = 'unpaid', limit = 20 })
limit is at most 100.
#GetPlayerInvoices
Returns the invoices addressed to a player, from any company.
lua---@param who number|string Server id or citizen id
---@param status? string
---@param limit? number
---@return table[] invoices
exports['fx-companyapp']:GetPlayerInvoices(who, status, limit)
lualocal invoices = exports['fx-companyapp']:GetPlayerInvoices(source, 'unpaid')
#GetUnpaidInvoiceCount
Returns how many unpaid invoices a player has.
lua---@param who number|string Server id or citizen id
---@param job? string Count only this company's invoices
---@return number count
exports['fx-companyapp']:GetUnpaidInvoiceCount(who, job)
lualocal count = exports['fx-companyapp']:GetUnpaidInvoiceCount(source)
#GetUnpaidInvoiceTotal
Returns the total unpaid amount a player owes.
lua---@param who number|string Server id or citizen id
---@param job? string Sum only this company's invoices
---@return number total
exports['fx-companyapp']:GetUnpaidInvoiceTotal(who, job)
lualocal total = exports['fx-companyapp']:GetUnpaidInvoiceTotal(source, 'mechanic')
#HasUnpaidInvoices
Tells whether a player has at least one unpaid company invoice.
lua---@param who number|string Server id or citizen id
---@param notify? boolean Send the "unpaid invoices" phone notification when it blocks
---@return boolean blocked
exports['fx-companyapp']:HasUnpaidInvoices(who, notify)
luaif exports['fx-companyapp']:HasUnpaidInvoices(citizenid, true) then return end
A database error returns false, so a failure never locks a garage.
#GetPendingCommission
Returns the commission waiting for an employee who was offline when an invoice was paid.
lua---@param who number|string Server id or citizen id
---@return number amount
exports['fx-companyapp']:GetPendingCommission(who)
lualocal pending = exports['fx-companyapp']:GetPendingCommission('ABC12345')
#CanIssuePersonalInvoice
Tells whether a player may send an invoice in their own name.
lua---@param src number
---@return boolean allowed
---@return string|nil reason 'companyOnly'
exports['fx-companyapp']:CanIssuePersonalInvoice(src)
lualocal allowed = exports['fx-companyapp']:CanIssuePersonalInvoice(source)
Returns false, 'companyOnly' when the player belongs to a company and Config.Invoices.CompanyOnly is on. Meant for other billing scripts.
#GetInvoiceIssuer
Returns who an invoice from this player should be issued as.
lua---@param src number
---@return table issuer { type = 'company', job, label } or { type = 'personal' }
exports['fx-companyapp']:GetInvoiceIssuer(src)
lualocal issuer = exports['fx-companyapp']:GetInvoiceIssuer(source)
#Server exports: invoice settings
#GetInvoiceSettings
Returns a company's invoice settings.
lua---@param job string
---@return table|nil settings { commission, commissionMin, commissionMax, presets, presetType, allowCustom, maxAmount }
exports['fx-companyapp']:GetInvoiceSettings(job)
lualocal settings = exports['fx-companyapp']:GetInvoiceSettings('mechanic')
presets is a list of { label, price }.
#SetInvoiceSettings
Saves part of a company's invoice settings.
lua---@param job string
---@param patch table
---@return boolean ok
---@return table|string settingsOrReason
exports['fx-companyapp']:SetInvoiceSettings(job, patch)
lualocal ok, settings = exports['fx-companyapp']:SetInvoiceSettings('mechanic', { allowCustom = false })
Values are clamped to the config limits and the change is logged. Returns false, 'invalidJob' for a bad job or a patch that is not a table.
#GetCommission
Returns a company's commission percentage.
lua---@param job string
---@return number percent
exports['fx-companyapp']:GetCommission(job)
lualocal pct = exports['fx-companyapp']:GetCommission('mechanic')
#SetCommission
Sets a company's commission percentage.
lua---@param job string
---@param percent number
---@return boolean ok
---@return number|string percentOrReason
exports['fx-companyapp']:SetCommission(job, percent)
lualocal ok, pct = exports['fx-companyapp']:SetCommission('mechanic', 15)
The value is clamped to the commission limits; the second return value is what was stored.
#GetInvoicePresets
Returns a company's ready invoice list.
lua---@param job string
---@return table[] presets { label, price }
exports['fx-companyapp']:GetInvoicePresets(job)
lualocal presets = exports['fx-companyapp']:GetInvoicePresets('mechanic')
#GetInvoiceTemplates
Returns the built-in invoice templates.
lua---@return table[] templates { key, label, count }
exports['fx-companyapp']:GetInvoiceTemplates()
lualocal templates = exports['fx-companyapp']:GetInvoiceTemplates()
#Server exports: statistics
days is 1, 7, 30 or 90.
#GetCompanyStats
Returns income, expense and invoice statistics of a company.
lua---@param job string
---@param days number
---@return table|nil stats { days, series, income, expense, net, categories, invoices, top }
exports['fx-companyapp']:GetCompanyStats(job, days)
lualocal stats = exports['fx-companyapp']:GetCompanyStats('mechanic', 30)
seriesis a list of{ day, income, expense }.categorieshasincomeandexpenselists of{ category, amount }.invoiceshascount,gross,paidCount,paid,unpaidCount,unpaid,commission,tax,company.topis the first five rows ofGetEmployeeRanking.
#GetEmployeeRanking
Returns employees ranked by what they earned for the company.
lua---@param job string
---@param days number
---@return table[] ranking { citizenid, name, issued, gross, paidCount, paid, commission, company }
exports['fx-companyapp']:GetEmployeeRanking(job, days)
lualocal ranking = exports['fx-companyapp']:GetEmployeeRanking('mechanic', 7)
#GetEmployeeStats
Returns one employee's statistics.
lua---@param job string
---@param citizenid string
---@param days number
---@return table|nil stats
exports['fx-companyapp']:GetEmployeeStats(job, citizenid, days)
lualocal stats = exports['fx-companyapp']:GetEmployeeStats('mechanic', 'ABC12345', 30)
The ranking fields plus pendingCommission, deposited, withdrawn, allTime = { issued, paid, commission } and recent (the last 30 invoices).
#Server exports: business directory
A directory key is the job name, or the group key when several jobs share one directory card.
#GetDirectoryKey
Returns the directory key a job belongs to.
lua---@param job string
---@return string|nil key
exports['fx-companyapp']:GetDirectoryKey(job)
lualocal key = exports['fx-companyapp']:GetDirectoryKey('mechanic')
#GetDirectoryProfile
Returns a business's directory profile.
lua---@param key string
---@return table|nil profile
exports['fx-companyapp']:GetDirectoryProfile(key)
lualocal profile = exports['fx-companyapp']:GetDirectoryProfile('mechanic')
Fields: name, slogan, description, hours, logo, banner, category, accent, location, listed, callable, messaging, callMode, callGrades. Saved values are laid over the defaults.
#SetDirectoryProfile
Changes a business's directory profile from code.
lua---@param key string
---@param patch table
---@return boolean ok
---@return table|string profileOrReason
exports['fx-companyapp']:SetDirectoryProfile(key, patch)
lualocal ok, profile = exports['fx-companyapp']:SetDirectoryProfile('mechanic', { slogan = 'Open every day' })
The patch goes through the same validation as an edit in the app (text limits, allowed image hosts). The stored location is kept. Returns false, 'invalidJob' for a bad key.
#Hooks
Hooks let you block an action before it happens, whether it came from the app or from an export.
#AddHook
Registers a function that runs before an action.
lua---@param name string Hook name, see the table below
---@param fn fun(payload: table): boolean|nil, string|nil
---@return number|nil hookId
exports['fx-companyapp']:AddHook(name, fn)
lualocal id = exports['fx-companyapp']:AddHook('beforeFire', function(p)
if p.job == 'police' and GlobalState.raidActive then return false, 'blocked' end
end)
- Return
false, 'reason'to cancel. Any other return value lets the action through. - The reason is shown to the player as
error.<reason>from the locale file. Unknown reasons show the generic error. - Returns
nilfor an unknown hook name. - Hooks are removed when the resource that added them stops.
- Keep hooks fast. They run inside the player's request.
#RemoveHook
Removes a hook.
lua---@param hookId number
---@return boolean removed
exports['fx-companyapp']:RemoveHook(hookId)
luaexports['fx-companyapp']:RemoveHook(id)
| Hook | Runs before | Payload |
|---|---|---|
beforeHire |
a hire | job, grade, source, actor, targetSource, targetCitizenid, targetName, previousJob |
beforeFire |
a fire | job, grade, source, actor, targetSource, targetCitizenid, targetName |
beforeSetGrade |
a rank change | job, oldGrade, grade, source, actor, targetSource, targetCitizenid, targetName |
beforeDeposit |
an in-app deposit | job, source, actor, amount |
beforeWithdraw |
an in-app withdrawal | job, source, actor, amount |
beforeAnnounce |
an in-app announcement | job, source, actor, message |
beforeMoneyChange |
AddCompanyMoney / RemoveCompanyMoney |
job, amount (negative = remove), source, actor, title, category, resource |
beforeInvoiceCreate |
an app invoice / CreateInvoice |
job, label, amount, note, source, issuerCid, actor, targetSource, targetCid, targetName, resource |
beforeInvoicePay |
an app payment / PayInvoice |
id, job, amount, label, source, payerCid, issuerCid |
beforeInvoiceCancel |
an app cancel / CancelInvoice |
id, job, source, actor |
beforeSettingsChange |
a boss saving invoice settings | job, source, actor, settings |
source is the player who did it, or nil for a system or export action. targetSource is nil when the target is offline.
#Server events
Fired after an action succeeded, with the same payload as the matching hook plus the result fields. They are local server events (TriggerEvent), so clients cannot fire them. Do not register them as net events.
| Event | Extra fields |
|---|---|
fx-companyapp:server:hired |
gradeName |
fx-companyapp:server:fired |
|
fx-companyapp:server:gradeChanged |
gradeName |
fx-companyapp:server:deposit |
balance (after) |
fx-companyapp:server:withdraw |
balance (after) |
fx-companyapp:server:moneyChanged |
balance (after), from AddCompanyMoney / RemoveCompanyMoney |
fx-companyapp:server:announce |
sent |
fx-companyapp:server:invoiceCreated |
id |
fx-companyapp:server:invoicePaid |
commission, tax, companyShare, account, commissionState (paid, pending or company) |
fx-companyapp:server:invoiceCancelled |
status |
fx-companyapp:server:invoiceExpired |
status |
fx-companyapp:server:settingsChanged |
settings (after) |
The directory also fires fx-companyapp:server:profileChanged, fx-companyapp:server:directoryMessage and fx-companyapp:server:ticketReply.
luaAddEventHandler('fx-companyapp:server:withdraw', function(p)
print(('%s withdrew %d from %s, %d left'):format(p.actor, p.amount, p.job, p.balance))
end)
#Client exports
#GetPhoneResource
Returns the phone in use on this client.
lua---@return string|nil phone 'fx-phone', 'lb-phone', 'cylex_phone' or nil
exports['fx-companyapp']:GetPhoneResource()
lualocal phone = exports['fx-companyapp']:GetPhoneResource()
#IsAppInstalled
Tells whether the app is registered on that phone.
lua---@return boolean
exports['fx-companyapp']:IsAppInstalled()
lualocal installed = exports['fx-companyapp']:IsAppInstalled()
#RefreshApp
Reloads this player's open app.
lua---@param scope? string 'all' (default), 'members', 'kasa', 'logs' or 'invoices'
---@return boolean sent
exports['fx-companyapp']:RefreshApp(scope)
luaexports['fx-companyapp']:RefreshApp('members')
#ReinstallApp
Registers the app into the phone again.
lua---@return boolean ok
exports['fx-companyapp']:ReinstallApp()
luaexports['fx-companyapp']:ReinstallApp()
#Notify
Shows a phone notification from the app on this client.
lua---@param title string
---@param message string
---@return boolean sent
exports['fx-companyapp']:Notify(title, message)
luaexports['fx-companyapp']:Notify('Shift', 'Your shift starts in 5 minutes')
#Error reasons
Returned as the second value when ok is false. Each has a text in locales/*.json under error..
| Reason | When |
|---|---|
invalidJob |
Job name empty or too long; for hire and rank changes also when the job is not in your job list |
invalidAmount |
Not a positive whole number, or too large |
invalidLabel |
Invoice label empty or not a string |
kasaUnavailable |
The banking resource has no account for this job |
insufficientKasa |
Not enough company funds |
insufficientPersonal |
(app only) The player lacks the money to deposit |
playerNotFound |
The citizen id is not an employee of that job, or the invoice target cannot be found |
playerNotOnline |
The hire target is not online |
alreadyInCompany |
The hire target already has this job |
invalidGrade |
The grade does not exist for the job |
companyOnly |
The player must bill in the company's name |
cannotTargetSelf |
(app only) Acting on yourself |
protectedRank |
(app only) The target is at or above your rank |
noPermission |
(app only) Missing permission |
noCompany |
(app only) The player has no usable company |
cooldown |
(app only) Too fast |
blocked |
A hook cancelled it without giving a reason |
generic |
The framework or bank refused it |
#Troubleshooting
| Symptom | Cause |
|---|---|
| App does not appear in the phone | The phone is not started, or started after this resource |
| "No company" screen for everyone | The job is not in Config.JobWhitelist |
Funds always show 0 |
Wrong Config.Banking.Provider, or that resource is not started |
| Deposit fails with "funds not ready" | The job has no account in your banking resource |
| Rank names are empty, hiring fails | qb-core starts after this resource, or job definitions are missing |