Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/developer51709/Noxie/llms.txt

Use this file to discover all available pages before exploring further.

Noxie’s economy is the connective tissue between hunting, donating, and showing off. Every user has two currency balances — Glow Shards and Vibe Coins — that are fully scoped to the Discord server they’re earned in. Alongside the balances, the system tracks total hunt counts, the current hunt streak, and a set of achievement badges. All data persists in a local SQLite database at db/noxie.db, which is created automatically on first run.

​
Currencies

Glow Shards ✨

The primary currency of the economy. Earned on every successful hunt and from crypto donations. Used as the general measure of activity and generosity within a server.

Vibe Coins 🪙

The rarer of the two currencies. Earned in smaller quantities from hunts and from donations, at a more premium rate. Future shop and fusion features draw on Vibe Coins.
Both currencies are per-user per-guild. A user who hunts in two different servers accumulates separate balances in each one. There is no cross-server transfer.

​
Hunt Rewards

Each successful hunt credits both currencies immediately via economy.record_hunt(). The amounts are randomized within a range that scales with the rarity rolled. Base ranges are configured in config.json under economy.glow_shards_per_hunt and economy.vibe_coins_per_hunt; the table below reflects the default configuration.
RarityGlow ShardsVibe Coins
Common5–251–5
Uncommon10–502–8
Rare20–1004–15
Epic40–2008–30
Legendary100–50020–75
Mythic250–1,25050–200
The reward calculation in cogs/hunt.py: 
def roll_rewards(rarity: str) -> tuple[int, int]:
    multipliers = {
        "common":    (1.0, 1.0),
        "uncommon":  (2.0, 1.5),
        "rare":      (4.0, 3.0),
        "epic":      (8.0, 6.0),
        "legendary": (20.0, 15.0),
        "mythic":    (50.0, 40.0),
    }
    gs_range = CONFIG["economy"]["glow_shards_per_hunt"]
    vc_range = CONFIG["economy"]["vibe_coins_per_hunt"]
    mult = multipliers.get(rarity, (1.0, 1.0))
    glow  = int(random.randint(*gs_range) * mult[0])
    coins = int(random.randint(*vc_range) * mult[1])
    return glow, coins

​
Hunt Cooldown

By default there is a 30-second cooldown between hunts per user per guild. The cooldown duration is read from config.json: 
{
  "hunt_cooldown": 30
}
When a user hunts while on cooldown, the bot responds with the remaining seconds and a personality line, then exits without rolling or crediting any rewards. The cooldown is enforced by comparing the current Unix timestamp against last_hunt in the economy table. 
def check_hunt_cooldown(conn, user_id, guild_id) -> float:
    cooldown = CONFIG.get("hunt_cooldown", 30)
    elapsed = time.time() - (row["last_hunt"] or 0)
    remaining = cooldown - elapsed
    return max(0.0, remaining)

​
Hunt Streak

hunt_streak increments by 1 on every successful hunt and is stored in the economy table. Streaks are never automatically reset — they persist until a future mechanic (such as a failed hunt variant) resets them. The streak feeds directly into the personality engine to bias Noxie’s tone:
  • streak ≥ 15 → chaotic tone
  • high luck (derived from streak) → cozy tone
  • low luck / streak = 0 → sarcastic or deadpan tone
The /vibe command surfaces the streak to users alongside their current vibe status.

​
Donation Rewards

Donations go through the OxaPay crypto flow. Once a payment is confirmed, the economy module credits rewards at a flat rate:
RewardRate
Glow Shards ✨500 per $1 USD
Vibe Coins 🪙50 per $1 USD
Donor Badge 💎Awarded once on first successful donation

​
Badges

Badges are permanent achievements stored in the badges table. Each badge can only be awarded once per user — award_badge() uses an INSERT OR IGNORE pattern backed by a UNIQUE(user_id, badge_name) constraint.
Badge IDDisplay NameRequirement
donor💎 DonorFirst successful donation
hunter_10🏹 Hunter I10 total hunts
hunter_50🏹 Hunter II50 total hunts
hunter_100🏹 Hunter III100 total hunts
legendary🌟 Legendary FinderCatch a legendary creature
mythic🌌 Mythic WitnessCatch a mythic creature
streak_25🔥 Hot Streak25-hunt streak
Badge display strings are defined in utils/economy.py in the BADGE_DISPLAY dict and can be extended there without any schema changes.

​
SQLite Tables

All economy data lives in db/noxie.db. The schema is initialized on startup by economy.init_db().

​
economy

Stores balances, hunt counters, and the last-hunt timestamp. One row per (user_id, guild_id) pair. 
CREATE TABLE IF NOT EXISTS economy (
    user_id     TEXT    NOT NULL,
    guild_id    TEXT    NOT NULL,
    glow_shards INTEGER NOT NULL DEFAULT 0,
    vibe_coins  INTEGER NOT NULL DEFAULT 0,
    total_hunts INTEGER NOT NULL DEFAULT 0,
    hunt_streak INTEGER NOT NULL DEFAULT 0,
    last_hunt   REAL    NOT NULL DEFAULT 0,
    PRIMARY KEY (user_id, guild_id)
);

​
badges

One row per awarded badge. The UNIQUE(user_id, badge_name) constraint prevents duplicates. 
CREATE TABLE IF NOT EXISTS badges (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id    TEXT    NOT NULL,
    badge_name TEXT    NOT NULL,
    awarded_at REAL    NOT NULL DEFAULT 0,
    UNIQUE(user_id, badge_name)
);

​
donations

Log of every confirmed donation transaction. 
CREATE TABLE IF NOT EXISTS donations (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id    TEXT    NOT NULL,
    amount_usd REAL    NOT NULL,
    currency   TEXT    NOT NULL DEFAULT 'USDT',
    tx_id      TEXT    NOT NULL,
    awarded_at REAL    NOT NULL DEFAULT 0
);

​
inventory

One row per creature catch. The fused column is reserved for future fusion mechanics. 
CREATE TABLE IF NOT EXISTS inventory (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id     TEXT    NOT NULL,
    guild_id    TEXT    NOT NULL,
    creature_id TEXT    NOT NULL,
    caught_at   REAL    NOT NULL DEFAULT 0,
    fused       INTEGER NOT NULL DEFAULT 0
);
All timestamp columns (last_hunt, awarded_at, caught_at) store Unix epoch seconds as REAL values, compatible with Python’s time.time().

Build docs developers (and LLMs) love

Get started for freeTalk to us