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 PickerDistance get a name tag, and only those within NearbyDistance can be chosen. Then the amount, a description (at least MinDescription letters), 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