Compatibility

Bank adapters

How the Bank app connects to vorp_banking, rsg-banking or its own internal bank, how the adapter is chosen and how to write one for another bank script.

The Bank app (and Katalog, for payments) does not keep the character's main balance itself. It asks an adapter in framework/frameworks.lua (FXBank). The file is open: you may change it.

#Supported banks

Mode Bank script How it is reached
vorp vorp_banking 1.9 Table bank_users, one row per branch. vorp_banking has no server exports, so the adapter reads and changes the row directly.
rsg rsg-banking 3.x rsg-banking's server exports GetHomeBranch, HasAccount, GetBranchBalance, AddBranchMoney, RemoveBranchMoney. An older rsg-banking without these exports falls back to the RSG bank money of the player (online players only).
internal none The notebook's own table fx_pocketbook_bank
custom yours The empty adapter you fill in (below)

#How the mode is chosen

apps/bank/config.lua:

luaMode = 'auto', -- auto | vorp | rsg | internal | custom

'auto' picks:

  1. vorp when the framework is VORP and vorp_banking is started,
  2. rsg when the framework is RSG and rsg-banking is started,
  3. internal otherwise.

Any other value uses that adapter directly. When the adapter says it is not available, the Bank app shows the reason and moves no money.

#Settings

Key Default What it does
Mode 'auto' See above
Internal.Name 'Defter Bankasi' Bank name shown with the internal bank
Vorp.Branch 'Valentine' The vorp_banking branch the notebook uses (the key in vorp_banking's Config.banks, the name column of bank_users)
Vorp.Label nil Bank name shown; empty: '<Branch> Bankasi'
Vorp.CreateAccount true Open an account at that branch on the first deposit, with vorp_banking's defaults. false: the player must open one at the bank.
Rsg.Branch 'home' 'home' is the home branch the player chose in rsg-banking, or a fixed branch name such as 'valentine'
Rsg.Labels branch names Bank name shown per branch

With rsg-banking, accounts are opened at the counter. The notebook does not open one.

#The adapter contract

Every adapter is a table in FXBank.Adapters with these functions:

Function Returns When it is called
Available() true, or false, reason Before every bank action
Label(src, char) bank name To show the bank's name
HasAccount(src, char) true or false To show whether the player has an account
OpenAccount(src, char) true, or false, reason Before a deposit
Balance(src, char) cents, or nil, reason To show the balance
Credit(ctx, cents) true, false or nil Money into this character's bank
Debit(ctx, cents) true, false or nil Money out of it; must refuse when there is not enough
TargetAccount(targetCharacterId) true, or false, reason Check the receiver of a transfer
CreditCharacter(targetId, cents, ctx) true, false or nil Pay the receiver of a transfer, who may be offline
  • char is { id, framework, name, job, grade }. char.id is 'vorp:...' or 'rsg:...'. FXFramework.CharacterKey(char, 'vorp') returns the part after the colon.
  • ctx is { src, char, queries }. queries are the notebook's own ledger statements. A SQL adapter should run them in the same MySQL.transaction as its balance change. An export adapter can ignore them; the notebook writes them afterwards.
  • Amounts are whole cents. FXFramework.ToCents(dollars) converts.

The result of a money function means:

Result Meaning
true Done and checked
false Certainly not done; nothing changed
nil Unknown: it may or may not have happened. The notebook holds the operation for an administrator and does not try it again.

#Writing a custom adapter

Set Mode = 'custom' in apps/bank/config.lua and fill in the custom adapter in framework/frameworks.lua. The file ships with this template; the comments show where an export based bank is called:

lualocal custom = {}
FXBank.Adapters.custom = custom
function custom.Available()
    -- return GetResourceState('my_bank') == 'started'
    return false, 'Ozel banka baglantisi yapilmamis.'
end
function custom.Label() return 'Banka' end
function custom.HasAccount(src, char) return false end
function custom.OpenAccount(src, char) return false, 'Ozel banka baglantisi yapilmamis.' end
function custom.Balance(src, char)
    -- local dollars = exports.my_bank:GetBalance(char.id); return FXFramework.ToCents(dollars)
    return nil, 'Ozel banka baglantisi yapilmamis.'
end
function custom.Credit(ctx, cents)
    -- return exports.my_bank:AddMoney(ctx.char.id, cents / 100) == true
    return false
end
function custom.Debit(ctx, cents)
    -- return exports.my_bank:RemoveMoney(ctx.char.id, cents / 100) == true   -- must refuse if not enough
    return false
end
function custom.TargetAccount(targetId) return false, 'Ozel banka baglantisi yapilmamis.' end
function custom.CreditCharacter(targetId, cents, ctx) return false end

A filled-in version for a bank script with exports could look like this (my_bank and its exports stand for your script):

luafunction custom.Available()
    if GetResourceState('my_bank') ~= 'started' then return false, 'my_bank is not running.' end
    return true
end
function custom.Label() return 'Frontier Bank' end
function custom.HasAccount(src, char) return true end
function custom.OpenAccount(src, char) return true end
function custom.Balance(src, char)
    local ok, dollars = pcall(function() return exports.my_bank:GetBalance(char.id) end)
    if not ok then return nil, 'Balance could not be read.' end
    return FXFramework.ToCents(dollars) or 0
end
function custom.Credit(ctx, cents)
    local ok, done = pcall(function() return exports.my_bank:AddMoney(ctx.char.id, cents / 100) end)
    if not ok then return nil end -- failed half way: unknown
    return done == true
end
function custom.Debit(ctx, cents)
    local ok, done = pcall(function() return exports.my_bank:RemoveMoney(ctx.char.id, cents / 100) end)
    if not ok then return nil end
    return done == true
end

Return nil only when you really cannot tell whether the money moved. Return false when you know nothing changed.