bank_accounts/API.md

Bank Accounts - API Documentation

This document describes the public API for the bank_accounts mod, allowing other mods to safely interact with player account data.

Introduction

The entire API is accessible through the global table bank_accounts. It is highly recommended to check for its existence before using it to ensure the mod is enabled:

if not bank_accounts then
    -- bank_accounts mod is not enabled or not loaded yet
    return
end

All functions that modify a player's balance or credit will automatically create a corresponding entry in the player's transaction history (account statement).

Data Types

• player_name: A string representing the player's name (e.g., "Rage87").
• amount: A number. The API supports floating-point numbers for digital transactions. Note that the ATM and Teller Computer nodes enforce integer-only values for physical cash withdrawals and deposits.
• trans_type: A short, non-translatable string used as a key to identify the transaction method (e.g., "API Purchase", "Quest Reward"). This string should be added to a .tr file for localization.
• purpose: A short, user-facing string that describes the transaction. This will be displayed directly in the account statement.
• other_party: A string representing the name of the other player or entity involved in the transaction.

---

API Functions

Data Retrieval

---

bank_accounts.get_account_data(player_name)

Returns a table containing all key data for a single player. This is the most efficient way to get multiple pieces of information at once.

• player_name (string): The name of the player.
• Returns: A table with the following structure:

  {
    balance = 1234.56, -- (number) The player's current balance.
    credit = 500.00,   -- (number) The player's current credit debt.
    pin = "1234",      -- (string) The player's PIN.
    history = { ... }  -- (table) A list of transaction tables for the player.
  }
  

Example:

local data = bank_accounts.get_account_data("Rage87")
if data then
    print("Balance for Rage87: " .. data.balance)
end

---

bank_accounts.get_balance(player_name)

Returns only the balance of a player.

• player_name (string): The name of the player.
• Returns: A number representing the player's balance, or 0 if the player has no account.

---

bank_accounts.get_credit(player_name)

Returns only the credit debt of a player.

• player_name (string): The name of the player.
• Returns: A number representing the player's credit debt, or 0.

---

bank_accounts.player_has_account(player_name)

Checks if a player has an account in the database.

• player_name (string): The name of the player.
• Returns: true if the account exists, false otherwise.

---

Data Modification

All modification functions will create an entry in the transaction history.

---

bank_accounts.add_balance(player_name, amount, trans_type, purpose, other_party)

Adds a value to a player's balance. Use a negative amount to subtract.

• player_name (string): The name of the player whose balance will be changed.
• amount (number): The amount to add (can be negative).
• trans_type (string): The internal type for this transaction (e.g., "Quest Reward").
• purpose (string): (optional) A user-facing description (e.g., "For completing the 'Dragon Slayer' quest.").
• other_party (string): (optional) The name of the entity giving the money (e.g., "King's Treasury").
• Returns: true on success.

Example:

-- Give player 'Rage87' a quest reward of 150.75 MG.
bank_accounts.add_balance("Rage87", 150.75, "Quest Reward", "Dragon Slaying", "King Arthur")

---

bank_accounts.set_balance(player_name, amount, trans_type, purpose, other_party)

Sets a player's balance to an absolute value. The transaction log will record the difference between the old and new balance.

• player_name (string): The name of the player.
• amount (number): The new absolute balance.
• trans_type, purpose, other_party: Same as above.
• Returns: true on success.

---

bank_accounts.add_credit(player_name, amount, trans_type, purpose, other_party)

Adds a value to a player's credit debt. Use a negative amount to pay off debt.

• Parameters: Same as add_balance.
• Returns: true on success.

Example:

-- A shop mod charges an item to the player's credit card.
bank_accounts.add_credit("Rage87", 99.95, "Credit Purchase", "Diamond Pickaxe", "Tool Shop")

---

bank_accounts.set_credit(player_name, amount, trans_type, purpose, other_party)

Sets a player's credit debt to an absolute value.

• Parameters: Same as set_balance.
• Returns: true on success.

---

bank_accounts.set_pin(player_name, pin)

Sets a player's PIN. This should rarely be used by external mods.

• player_name (string): The name of the player.
• pin (string): The new 4-digit PIN.
• Returns: true on success.

---

Background Scripting Functions

These functions are intended for scripts that need to process all accounts at once, like the interest.lua script. Use with caution.

---

bank_accounts.get_all_data()

Reads and returns the entire accounts database.

• Returns: The complete data table.

---

bank_accounts.save_all(data)

Saves the entire provided data table, overwriting the existing file. Includes a lock to wait for the interest calculation to finish.

• data (table): The complete and modified data table to be saved.
• Returns: true on success.