From ceb168de55dca8673196ff5eb44735475711c8d2 Mon Sep 17 00:00:00 2001 From: rainer Date: Mon, 16 Jun 2025 01:18:23 +0200 Subject: [PATCH] Added API.md and fixed error in README.md --- API.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +- 2 files changed, 164 insertions(+), 2 deletions(-) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..08169bd --- /dev/null +++ b/API.md @@ -0,0 +1,162 @@ +# 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: + +```lua +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: + ```lua + { + 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:** +```lua +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:** +```lua +-- 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:** +```lua +-- 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. diff --git a/README.md b/README.md index 1e958a3..6230e16 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Bank Accounts (Redo & Extended) -A complete overhaul and extension of the original `bank_accounts` mod by Tmanyo and Trent Lasich. This project has been restructured from the ground up to ensure stability, security, and a significantly expanded feature set. +A complete overhaul and extension of the original `bank_accounts` mod by Tmanyo (Trent Lasich). This project has been restructured from the ground up to ensure stability, security, and a significantly expanded feature set. ## About This Version @@ -142,5 +142,5 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` ## Credits -* Original Mod: Tmanyo (Code) & Trent Lasich (Textures, Models) +* Original Mod: Tmanyo (Trent Lasich) * Complete Redo, Extension & Bugfixing: **Rage87**