Economy System
Relevant source files
The following files were used as context for generating this wiki page:
The Economy System in Amina provides a server-wide virtual currency feature to enhance user engagement. It allows users to earn, manage, and spend coins through various commands. The entire system can be enabled or disabled globally via the main configuration. When enabled, it introduces commands for banking, gambling, and daily rewards, all tied to a user's persistent wallet and bank balance stored in the database.
The system is designed to be interactive, with clear and consistent user feedback provided through styled embeds. It relies on the IUser database schema to track each user's financial data and a central configuration file for defining core economic parameters.
Sources: src/config/config.ts:81-87, types/schemas.d.ts:79-93, src/commands/economy/bank.ts, src/commands/economy/gamble.ts
Configuration
The economy system's behavior is controlled by the ECONOMY object within the main bot configuration. These settings define the currency symbol, reward amounts, and whether the feature is active.
Sources: src/config/config.ts:81-87, types/modules.d.ts:68-74
| Parameter | Type | Default Value | Description |
|---|---|---|---|
ENABLED | boolean | true | Toggles the entire economy system on or off. |
CURRENCY | string | ₪ | The currency symbol used in all economy-related messages. |
DAILY_COINS | number | 100 | The number of coins a user receives from the daily command. |
MIN_BEG_AMOUNT | number | 100 | The minimum coins a user can receive from the beg command. |
MAX_BEG_AMOUNT | number | 2500 | The maximum coins a user can receive from the beg command. |
Sources: src/config/config.ts:81-87, types/modules.d.ts:68-74
Data Model
User-specific economy data is stored within the User document in the database, as defined by the IUser interface. This includes the user's wallet (coins), bank balance (bank), and daily reward tracking.
The diagram below illustrates the economy-related fields within the IUser schema.
Sources: types/schemas.d.ts:79-93
IUser Economy Fields
| Field | Type | Description |
|---|---|---|
coins | number | The amount of currency in the user's active wallet. |
bank | number | The amount of currency stored in the user's bank account. |
daily | object | An object containing data for tracking daily reward streaks. |
daily.streak | number | The user's current daily reward streak. |
daily.timestamp | Date | The timestamp of the user's last daily reward claim. |
Sources: types/schemas.d.ts:79-93
Core Commands
The economy system is exposed to users through a set of slash commands.
/bank
The /bank command is the central hub for managing a user's finances. It includes subcommands for checking balances, depositing, withdrawing, and transferring coins.
Sources: src/commands/economy/bank.ts
Subcommands
| Subcommand | Description | Options |
|---|---|---|
balance | View your or another user's wallet and bank balance. | user (Optional): The user to check. |
deposit | Move coins from your wallet to your bank. | coins (Required): The amount to deposit. |
withdraw | Move coins from your bank to your wallet. | coins (Required): The amount to withdraw. |
transfer | Send coins from your wallet to another user. | user (Required): The recipient. coins (Required): The amount to transfer. |
Sources: src/commands/economy/bank.ts:14-72
Flow: Bank Transfer
The following diagram shows the sequence of events when a user executes the /bank transfer command.
Sources: src/commands/economy/bank.ts
/gamble
The /gamble command allows users to bet their coins on a slot machine for a chance to win more. The reward is determined by the number of matching emojis.
Sources: src/commands/economy/gamble.ts
Options
| Option | Type | Description | Constraints |
|---|---|---|---|
coins | Integer | The number of coins to bet. | Required, must be >= 10. |
Sources: src/commands/economy/gamble.ts:13-20, src/commands/economy/gamble.ts:60
Logic Flow
The gamble command follows a clear process from input validation to reward calculation and user notification.
The reward is calculated by the calculateReward function, which returns 3x the bet for a three-of-a-kind, 2x for a pair, and 0 otherwise.
Sources: src/commands/economy/gamble.ts:46-52
User Interface and Responses
The economy system leverages the MinaEmbed factory to provide consistent and visually distinct feedback for command outcomes.
- Success actions, like a winning gamble, use
MinaEmbed.success(). - Jackpots in the gamble command use the special
MinaEmbed.gold(). - Errors, such as insufficient funds or losing a gamble, use
MinaEmbed.error(). - The
withEconomymethod onMinaEmbedcan be used to format embeds with standardized fields for amount and balance.
This ensures that users can quickly understand the result of an economy-related action based on the color and content of the response embed.
Sources: src/commands/economy/gamble.ts:90-102, src/structures/embeds/MinaEmbed.ts:251-267