📂Configuration

Complete guide to configuring your economy system

Introduction

The Economy addon configuration file (economy.json) controls every aspect of your server's virtual currency system. This guide will walk you through each section to help you create a balanced and engaging economy.

Part 1: Coin Rewards

Understanding Coin Rewards

The coins section defines how many coins users earn for different activities. Setting a value to 0 disables coin rewards for that activity.

coins: {
    message_sent: 1,
    invite: 150,
    game_played: 5,
    game_won: 15,
    counting_game: 3,
    level_up: 100,
    daily: 125,
    weekly: 1000,
    calltime_minute: 15,
    approved_suggestion: 200,
    suggestion_vote: 25,
    poll_vote: 25,
    birthday: 5000,
    starboard_message: 200,
    punishment: -5000,
}

Activity Breakdown

message_sent

Coins earned per message sent in chat
Recommended: 1-5 coins
Too high = spam encouragement | Too low = no incentive

invite

Coins earned when a user's invite brings a new member
Recommended: 100-500 coins
High value encourages organic growth

calltime_minute

Coins earned per minute in voice channels
Recommended: 10-30 coins
Encourages voice activity and community engagement

suggestion_vote & poll_vote

Coins earned for voting on suggestions or polls
Recommended: 10-50 coins each
Encourages community participation in decisions

approved_suggestion

Bonus coins when your suggestion is approved
Recommended: 100-500 coins
Rewards quality suggestions

starboard_message

Coins earned when your message gets starred
Recommended: 100-300 coins
Rewards popular/quality content

Game Activities

game_played

Coins earned just for playing a game
Recommended: 1-10 coins
Participation reward

game_won

Coins earned for winning a game
Recommended: 10-50 coins
Should be higher than game_played

counting_game

Coins earned per successful count in counting channel
Recommended: 1-5 coins
Small but consistent reward

Progression Activities

level_up

Bonus coins when reaching a new level
Recommended: 50-200 coins
Scales with your leveling system difficulty

daily

Base reward for daily claims
Recommended: 100-500 coins
Influenced by streak bonuses (see Streaks section)

weekly

Base reward for weekly claims
Recommended: 500-2000 coins
Should be significantly higher than daily

birthday

Special reward on user's birthday
Recommended: 1000-10000 coins
Once-per-year celebration bonus

Punishment

punishment

Coins deducted when a user is punished (warned, muted, etc.)
Recommended: -1000 to -10000 coins
Use negative values to deduct coins
Serves as an economic deterrent for rule-breaking

Part 2: Shop Items

Understanding Shop Structure

Shop items appear in the /shop command and can be purchased with earned coins. Each item has rewards that are automatically delivered upon purchase.

shop_items: [
    {
        id: 0,
        emoji: '👑',
        name: 'VIP',
        description: 'Enter to purchase the VIP role',
        cost: 50000,
        requirement: {
            rankId: 5,
            oneTimePurchase: true,
        },
        reward: [
            {
                type: "ROLE",
                target: "804354029076348959",
            }
        ],
    }
]

Item Configuration Options

Basic Properties

id (Number)

Unique identifier for the item
CRITICAL: Never reuse IDs, even after deleting items
Used to track who purchased what
Start at 0 and increment for each new item

emoji (String)

Emoji displayed next to the item in the shop
Use any Discord emoji or Unicode emoji
Example: '👑', '🎁', '💎'

name (String)

Display name of the item
Keep it short and descriptive
Shown in shop list and purchase confirmations

description (String)

Longer explanation of what the item does
Tell users exactly what they're buying
Example: "Permanent VIP role with exclusive perks"

cost (Number)

Price in coins
Must be greater than 0
Consider your coin earning rates when pricing

Requirements

rankId (Number)

Minimum economy rank required to purchase
Set to 0 for no requirement
Higher ranks = more exclusive items
Use for progression-locked rewards

oneTimePurchase (Boolean)

true = Can only buy once per user
false = Can buy unlimited times
Use true for roles and permanent items
Use false for consumables (boosters, lootboxes)

Reward Types

Each item can have multiple rewards. When purchased, all rewards are given simultaneously.

ROLE Reward

Grants a Discord role to the purchaser:

reward: [
    {
        type: "ROLE",
        target: "804354029076348959",
    }
]

target = Role ID (right-click role with Developer Mode enabled)
Bot must have permission to assign roles
Bot's role must be higher than the target role

BOOSTER Reward

Gives a coin multiplier booster:

reward: [
    {
        type: "BOOSTER",
        target: "booster_coin_1h_2",
    }
]

target = Booster ID from your booster configuration
Format usually: booster_coin_<duration>_<multiplier>
Examples: booster_coin_1h_2 = 2x coins for 1 hour
Users activate boosters with /booster activate

LOOTBOX Reward

Adds lootboxes to the user's inventory:

reward: [
    {
        type: "LOOTBOX",
        target: null,
        amount: 1,
    }
]

target = Always null for lootboxes
amount = Number of lootboxes to give
Lootboxes contain random rewards when opened

CHANNEL_MESSAGE Reward

Sends a predefined message to a specific channel:

reward: [
    {
        type: "CHANNEL_MESSAGE",
        target: "1274005906610454619",
        predefined_id: "vip_announcement",
    }
]

target = Channel ID where the message will be sent
predefined_id = ID of your saved message template
Create templates using /sendmsg and /editmsg commands
Useful for announcing purchases or sending instructions

COUPON Reward

Generates a Tebex store coupon code:

reward: [
    {
        type: "COUPON",
        target: "10",
    }
]

target = Coupon value (percentage or fixed amount)
Requires Tebex plugin integration
Automatically generates and DMs the code to the user
Perfect for bridging virtual and real economy

Warning: Coupon rewards can be exploited if coin earning rates are too high or if jobs generate too much passive income. Use with caution and balance your economy carefully!

Shop Item Examples

Example 1: VIP Role

Permanent role requiring rank 5:

{
    id: 0,
    emoji: '👑',
    name: 'VIP',
    description: 'Permanent VIP role with exclusive perks and channels',
    cost: 50000,
    requirement: {
        rankId: 5,
        oneTimePurchase: true,
    },
    reward: [
        {
            type: "ROLE",
            target: "804354029076348959",
        }
    ],
}

Example 2: Coin Booster

Consumable 2x booster for 1 hour:

{
    id: 1,
    emoji: '🪄',
    name: 'Gilded Elixir',
    description: 'Double your coin earnings for 1 hour',
    cost: 750,
    requirement: {
        rankId: 0,
        oneTimePurchase: false,
    },
    reward: [
        {
            type: "BOOSTER",
            target: "booster_coin_1h_2",
        },
    ],
}

Example 3: Lootbox

Random reward box:

{
    id: 2,
    emoji: '🎁',
    name: 'Mystery Lootbox',
    description: 'Open for random coins, boosters, or rare items!',
    cost: 500,
    requirement: {
        rankId: 0,
        oneTimePurchase: false,
    },
    reward: [
        {
            type: "LOOTBOX",
            target: null,
            amount: 1,
        }
    ],
}

Example 4: Announcement Purchase

Send a message to a public channel:

{
    id: 3,
    emoji: '💬',
    name: 'Server Announcement',
    description: 'Post your custom message in the announcements channel',
    cost: 2000,
    requirement: {
        rankId: 3,
        oneTimePurchase: false,
    },
    reward: [
        {
            type: "CHANNEL_MESSAGE",
            target: "1274005906610454619",
            predefined_id: "user_announcement",
        }
    ],
}

Example 5: Store Coupon

Real-money store discount:

{
    id: 4,
    emoji: '🎟️',
    name: 'Store Coupon',
    description: '10% discount code for our Tebex store',
    cost: 100000,
    requirement: {
        rankId: 10,
        oneTimePurchase: false,
    },
    reward: [
        {
            type: "COUPON",
            target: "10",
        }
    ],
}

Example 6: Multiple Rewards

Item granting multiple rewards at once:

{
    id: 5,
    emoji: '🎉',
    name: 'Ultimate Package',
    description: 'VIP role + 3 lootboxes + announcement',
    cost: 75000,
    requirement: {
        rankId: 8,
        oneTimePurchase: true,
    },
    reward: [
        {
            type: "ROLE",
            target: "804354029076348959",
        },
        {
            type: "LOOTBOX",
            target: null,
            amount: 3,
        },
        {
            type: "CHANNEL_MESSAGE",
            target: "1274005906610454619",
            predefined_id: "vip_welcome",
        }
    ],
}

Part 3: Streak Bonuses

Understanding Streaks

Streaks encourage users to claim their daily/weekly rewards consistently. Each consecutive claim increases their streak counter, which adds bonus coins on top of the base reward.

streaks: {
    daily: {
        enabled: true,
        bonus: "%streak% * 25 + 25",
    },
    weekly: {
        enabled: true,
        bonus: "%streak% * 250 + 250",
    }
}

Streak Configuration

enabled (Boolean)

true = Streak bonuses are active
false = Only base reward is given (no streak tracking)

bonus (String - Formula)

Mathematical formula to calculate bonus coins
%streak% placeholder = Current streak count (0, 1, 2, 3...)
Can use operators: +, -, *, /, ( )

Streak Formula Examples

Linear Growth

bonus: "%streak% * 25 + 25"

Streak 0: 0 * 25 + 25 = 25 coins
Streak 1: 1 * 25 + 25 = 50 coins
Streak 5: 5 * 25 + 25 = 150 coins
Streak 10: 10 * 25 + 25 = 275 coins

Exponential Growth

bonus: "%streak% * %streak% * 10"

Streak 0: 0 * 0 * 10 = 0 coins
Streak 1: 1 * 1 * 10 = 10 coins
Streak 5: 5 * 5 * 10 = 250 coins
Streak 10: 10 * 10 * 10 = 1000 coins

Capped Growth

For formulas, you'll need to handle caps in your economy system logic, but you can design slower growth:

bonus: "%streak% * 10"

Streak 0: 0 * 10 = 0 coins
Streak 10: 10 * 10 = 100 coins
Streak 30: 30 * 10 = 300 coins

How Streaks Work

User claims their daily/weekly reward
Base reward is given (from coins section)
Streak counter increases by 1
Bonus is calculated using the formula
Bonus is added to the base reward
If user misses the claim window, streak resets to 0

Example with Daily:

Base daily reward: 125 coins
User on 5-day streak
Bonus formula: %streak% * 25 + 25 = 5 * 25 + 25 = 150 coins
Total reward: 125 + 150 = 275 coins

Part 4: Game Wagers

Understanding Wagers

The wager system lets users bet coins on games. If they win, they get their wager back plus additional coins based on the multiplier.

game_wagers: {
    enabled: true,
    max: 1000,
    cooldown: "5m",
    multipliers: {
        gtn: 1.5,
        hangman: 1.5,
        rps: 2,
        trivia: 2.5,
    }
}

Wager Configuration

enabled (Boolean)

true = Wager system is active for games
false = Wagers are disabled (only base game rewards apply)

max (Number)

Maximum coins that can be wagered on a single game
Prevents large losses/gains that imbalance economy
Recommended: 500-2000 coins

cooldown (String)

Time users must wait between placing wagers
Prevents rapid betting/grinding
Format: "5m", "1h", "30s"
Recommended: "5m" to "30m"

multipliers (Object)

Defines payout multiplier for each game type
Higher multiplier = Higher difficulty/risk
Format: game_name: multiplier

Game Multipliers

gtn (Guess The Number)

Recommended: 1.5 - 2.0
Easy game, lower multiplier

hangman

Recommended: 1.5 - 2.0
Medium difficulty

rps (Rock Paper Scissors)

Recommended: 1.5 - 2.5
Pure luck, moderate multiplier

trivia

Recommended: 2.0 - 3.0
Knowledge-based, higher multiplier

Wager Calculation Example

User wagers 500 coins on Trivia (2.5x multiplier):

If they win:

Wager returned: 500 coins
Winnings: 500 * 2.5 = 1,250 coins
Total gained: 1,750 coins (net +1,250)

If they lose:

Total lost: 500 coins (wager is taken)

Part 5: Cooldowns

Understanding Cooldowns

Cooldowns prevent spam and balance the economy by limiting how often certain actions can be performed.

cooldowns: {
    spy: "30m",
    rob: "3h",
    beg: "2h",
}

Cooldown Configuration

spy (String)

Cooldown for /bank spy command
Prevents constant wealth checking
Recommended: "15m" to "1h"

rob (String)

Cooldown for /rob command
Prevents repeated robbery attempts
Recommended: "1h" to "6h"
Should be longer due to potential for large gains/losses

beg (String)

Cooldown for /beg command
Limits passive income from begging
Recommended: "30m" to "3h"

Time Format

Use these formats for cooldown values:

"30s" = 30 seconds
"5m" = 5 minutes
"2h" = 2 hours
"1d" = 1 day
"1w" = 1 week

Complete Configuration Example

Here's a balanced economy configuration for a medium-sized server:

config: {
    coins: {
        message_sent: 2,
        invite: 200,
        game_played: 5,
        game_won: 20,
        counting_game: 3,
        level_up: 150,
        daily: 200,
        weekly: 1500,
        calltime_minute: 20,
        approved_suggestion: 300,
        suggestion_vote: 30,
        poll_vote: 30,
        birthday: 5000,
        starboard_message: 250,
        punishment: -3000,
    },

    shop_items: [
        {
            id: 0,
            emoji: '👑',
            name: 'VIP',
            description: 'Permanent VIP role',
            cost: 50000,
            requirement: {
                rankId: 5,
                oneTimePurchase: true,
            },
            reward: [
                { type: "ROLE", target: "YOUR_ROLE_ID" }
            ],
        },
        {
            id: 1,
            emoji: '🪄',
            name: '2x Coin Booster',
            description: 'Double coins for 1 hour',
            cost: 1000,
            requirement: {
                rankId: 0,
                oneTimePurchase: false,
            },
            reward: [
                { type: "BOOSTER", target: "booster_coin_1h_2" }
            ],
        },
        {
            id: 2,
            emoji: '🎁',
            name: 'Lootbox',
            description: 'Random reward box',
            cost: 750,
            requirement: {
                rankId: 0,
                oneTimePurchase: false,
            },
            reward: [
                { type: "LOOTBOX", target: null, amount: 1 }
            ],
        },
    ],

    streaks: {
        daily: {
            enabled: true,
            bonus: "%streak% * 30 + 30",
        },
        weekly: {
            enabled: true,
            bonus: "%streak% * 300 + 300",
        }
    },

    game_wagers: {
        enabled: true,
        max: 1500,
        cooldown: "10m",
        multipliers: {
            gtn: 1.5,
            hangman: 1.75,
            rps: 2,
            trivia: 2.5,
        }
    },

    cooldowns: {
        spy: "30m",
        rob: "4h",
        beg: "2h",
    }
}

Last updated 5 months ago

Introduction

Part 1: Coin Rewards

Understanding Coin Rewards

Activity Breakdown

Social Activities

Game Activities

Progression Activities

Punishment

Part 2: Shop Items

Understanding Shop Structure

Item Configuration Options

Basic Properties

Requirements

Reward Types

ROLE Reward

BOOSTER Reward

LOOTBOX Reward

CHANNEL_MESSAGE Reward

COUPON Reward

Shop Item Examples

Example 1: VIP Role

Example 2: Coin Booster

Example 3: Lootbox

Example 4: Announcement Purchase

Example 5: Store Coupon

Example 6: Multiple Rewards

Part 3: Streak Bonuses

Understanding Streaks

Streak Configuration

Streak Formula Examples

Linear Growth

Exponential Growth

Capped Growth

How Streaks Work

Part 4: Game Wagers

Understanding Wagers

Wager Configuration

Game Multipliers

Wager Calculation Example

Part 5: Cooldowns

Understanding Cooldowns

Cooldown Configuration

Time Format

Complete Configuration Example