Features
Ledger
The Ledger billing app: issuing and paying bills, installments, recurring bills, late fees, company billing rights, automatic collection, and Config.Billing.
Ledger (billing) holds the bills of a character and of their company. Settings are in apps/billing/config.lua (Config.Billing) and apps/billing/config_server.lua.
#What the player can do
- See the bills they received and sent, each with its state, and open a bill page with one Pay button. A bill with installments is paid one installment at a time, or in full.
- Issue a bill in three steps. It starts by picking a player in the world: players within
PickerDistanceget a name tag, and only those withinNearbyDistancecan be chosen. Then the amount, a description (at leastMinDescriptionletters), details, installments, the payment period, an optional recurring period and up to three picture links. - Cancel bills they sent, one at a time or in bulk (up to
MaxBulkCancel). - See the account page: the collection balance, an account picture (
AllowProfiles) and the last six months. Money paid on personal bills waits in the collection balance and is withdrawn to cash from this page. - For a company: issue bills in the company's name, pay bills addressed to the company from the till, and see the till ledger. Who may do this is set by the rank rules below.
The Official Ledger writes law fines as bills here, and the Business app shares the same bills.
#What it needs
| Need | Notes |
|---|---|
| Signal | Reading needs receive signal; issuing, paying and cancelling need send signal |
| Money | Personal payments come from the account in Config.MoneyAccount (cash by default). Company payments come from the company till |
| Jobs | Company billing works for jobs listed in Config.Company.Jobs |
#Settings
| Key | Default | What it does |
|---|---|---|
Enabled |
true |
Turns the app on |
AllowPersonalSend |
false |
Players may bill in their own name. Off: only companies issue bills |
AllowPersonalReceive |
true |
Players may receive bills |
AllowCreateUI |
true |
Issuing bills from the app. Off: only exports and other apps create bills |
MaxAmount |
100000 |
Largest bill in dollars |
MinDescription / MaxDescription / MaxDetails |
8 / 240 / 3000 |
Text lengths |
MaxInstallments |
24 |
Installments per bill |
MaxPeriodDays / MaxRecurringDays |
365 / 365 |
Longest payment period and recurring period |
PageSize |
12 |
Bills per page |
NearbyDistance |
5.0 |
Metres: the recipient must be this close |
EnforceNearby |
true |
The server checks the distance again when the bill is written |
PickerDistance |
15.0 |
Metres: players this close get a name tag in the picker |
DuplicateWindowSeconds |
120 |
The same bill sent twice inside this time is refused |
CompanySend |
'member' |
Who may bill in the company's name: 'member', 'boss' or a grade number |
CompanyManage |
'boss' |
Who may manage company bills |
JobPermissions |
{} |
Per job override, e.g. { sheriff = { send = 1, manage = 3 } } |
Blacklisted |
{} |
Per job block, e.g. { newspaper = { send = true } } |
Commission |
{} |
Issuer's share per job and grade, e.g. { sheriff = { [2] = 0.05, all = 0.02 } }. Frozen when the bill is written |
MaxAttachments / ImageHosts |
3 / {} |
Picture links per bill; empty hosts list allows public HTTPS hosts |
MaxBulkCancel |
50 |
Bills cancelled at once |
AllowProfiles |
true |
Account pictures |
Penalty |
{ Enabled = false, InitialPercent = 10, HourlyPercent = 0.5, MaxPercent = 100 } |
Late fee on overdue bills |
SweepInterval |
60000 |
Ms between checks for due and scheduled bills |
Enforcement |
{ Enabled = true, GraceMinutes = 30 } |
Unpaid bills older than this count as blocking for the CheckUnpaidInvoices export |
Collection |
Enabled = false, IntervalSeconds = 3600, GraceMinutes = 60, MaxPerRun = 1000, Reserve = 0, Companies = false |
Automatic collection of overdue bills |
Hooks |
Sent, Paid, Cancelled |
Functions called after a bill is sent, paid or cancelled |
When the boss has set a share in the Business app, or Config.Company.InvoiceShare.default is above 0, that share is used for company bills instead of Commission.
#Automatic collection
With Collection.Enabled = true the server takes overdue amounts GraceMinutes after the due time, from players who are in the game, up to MaxPerRun dollars per bill and run, and leaves Reserve dollars in their pocket. It never overdraws and never edits the rows of offline players. Companies = true collects from company tills too.
#Hooks
luaHooks = {
Sent = function(src, invoiceId) end,
Paid = function(src, invoiceId, amount) end,
Cancelled = function(src, invoiceId) end,
},
#Server-only settings
apps/billing/config_server.lua:
| Key | Default | What it does |
|---|---|---|
API.AllowedResources |
{} |
Resources allowed to call the billing exports |
API.AllowDistanceOverride |
false |
Bills created through the exports may skip the distance rule |
API.MaxRequests / API.WindowSeconds |
30 / 10 |
Rate limit for export calls |
API.MaxPayloadBytes |
16384 |
Largest export payload |
Logs |
enabled, core webhook fallback | This app's Discord log |