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 codebase is organized around a clean separation of concerns: a single entry point in main.py, feature-grouped command extensions under cogs/, shared logic under utils/, and static assets for the 14 mood banners and 36 vibe creatures. Understanding this layout makes it easy to add new commands, adjust economy tuning, or swap out personality lines without touching unrelated modules.

​
Directory Tree

noxie/
├── main.py                  ← Bot entry point (NoxieBot class)
├── config.json              ← Configuration file
├── requirements.txt         ← Python dependencies
│
├── cogs/
│   ├── hunt.py              ← /hunt, /inventory, /vibe commands
│   ├── donate.py            ← /donate command + OxaPay flow
│   ├── profile.py           ← /profile command
│   ├── prefixes.py          ← prefix management + prefix_callable
│   └── help.py              ← noxie help command
│
├── utils/
│   ├── cv2_helpers.py       ← CV2 container builders + send_cv2()
│   ├── economy.py           ← SQLite economy system
│   ├── face_manager.py      ← Event → mood banner path mapping
│   ├── helpers.py           ← Config loader, DB conn, creature loader
│   └── logger.py            ← Colored console logging
│
├── mood_banners/            ← 14 JPEG mood banner images
├── vibe_creatures/
│   └── data.json            ← 36 creatures + rarity_weights
└── db/
    └── noxie.db             ← SQLite (auto-created on first run)

​
Module Descriptions

​
main.py — Bot Entry Point

main.py defines NoxieBot(commands.Bot), the single bot class that owns the application lifecycle. Its __init__ method configures discord.Intents (enabling message_content and members), sets prefix_callable from cogs.prefixes as the dynamic command prefix, disables the built-in help command, and enables case-insensitive prefix matching. The main() coroutine reads the bot token from the NOXIE_TOKEN environment variable or from config.json, then starts the bot inside an async with bot: context. Both on_command_error and on_app_command_error are implemented as global handlers that build CV2 face-reaction containers and send them back to the user rather than raising bare Python exceptions.

​
cogs/ — Command Extensions

The cogs/ directory contains all Discord command logic, split one feature per file. Each file defines a commands.Cog subclass and exposes a module-level async def setup(bot) coroutine so that load_extension() can load it dynamically. Commands are implemented in pairs: a slash command using @app_commands.command and a prefix command using @commands.command, sharing the same underlying logic through helper coroutines like do_hunt(). This dual-registration pattern means every user-facing action works with both /hunt and noxie hunt interchangeably.

​
utils/cv2_helpers.py — CV2 Primitives and Dispatch

cv2_helpers.py is the lowest layer of Noxie’s visual output system. It provides three low-level primitive builders (_make_file, _media, _sep), the RARITY_COLORS constant mapping rarity names to hex accent colors, the shared build_face_reaction_container() function used by error handlers and cooldown messages across the entire bot, and the send_cv2() dispatcher that accepts any valid send target (slash interaction, prefix context, or raw channel). Cog-specific container builders live in their respective cog files and import the primitives from here.

​
utils/economy.py — SQLite Economy System

economy.py owns all database interactions for Noxie’s economy layer. It defines init_db() to create the four core tables (economy, inventory, badges, donations) on first run, and exposes named functions for every CRUD operation the cogs need — balance reads, currency credits and debits, hunt recording, cooldown checks, inventory management, badge awarding, and donation logging. All functions accept a sqlite3.Connection as their first argument and use the sqlite3.Row row factory set up by helpers.get_db_conn(), so rows can be accessed by column name. The internal _ensure_row() helper silently inserts a default economy record for any user-guild pair that doesn’t yet exist, meaning callers never need to check for missing rows.

​
utils/face_manager.py — Event to Mood Banner Mapping

face_manager.py provides a declarative mapping from named events to Noxie’s 14 mood banner images. The module-level EVENT_MOOD dict maps string event keys (e.g. "hunt_mythic", "donate_fail", "cooldown") to mood keys (e.g. "evil", "dizzy", "sleepy"). Three public functions cover the three lookup patterns used across the codebase: get_face_for_event(event) for general event lookups, get_face_for_rarity(rarity) for hunt results, and get_face_for_creature_mood(creature_mood) for creature-native moods. All three return an absolute file path string or None if the image file doesn’t exist on disk. Unknown event keys fall back to the "neutral" mood automatically.

​
utils/helpers.py — Config, DB, and Creature Loaders

helpers.py provides the three bootstrapping utilities that the rest of the codebase depends on: load_config() reads config.json from the project root, get_db_conn() creates (or opens) db/noxie.db and sets row_factory = sqlite3.Row, and load_creatures() deserializes vibe_creatures/data.json into a Python dict. The module also exposes mood_banner_path(mood) as a convenience wrapper that resolves a mood key to a full file path, and two rarity/mood mapping constants — RARITY_MOOD and CREATURE_MOOD_BANNER — used by the hunt cog for banner selection logic.

​
Bot Lifecycle

Noxie’s startup sequence is entirely contained within NoxieBot.setup_hook(), which discord.py calls once before the bot connects to the Gateway. The order is fixed and intentional:
  1. Connect to SQLite — get_db_conn(CONFIG) opens (or creates) db/noxie.db and stores the connection on self.db.
  2. Initialize tables — init_prefix_table(self.db) and init_economy_db(self.db) run CREATE TABLE IF NOT EXISTS for all five tables, making the operation safe on every startup.
  3. Load cogs — Each module path in the cogs list is passed to await self.load_extension(). Failures are logged individually and do not abort the remaining cogs.
  4. Sync slash commands — await self.tree.sync() registers all application commands globally and stores the returned {name: id} mapping in self.slash_ids for use in help text.
async def setup_hook(self) -> None:
    self.db = get_db_conn(CONFIG)
    init_prefix_table(self.db)
    init_economy_db(self.db)

    cogs = ["cogs.prefixes", "cogs.hunt", "cogs.donate", "cogs.profile", "cogs.help"]
    for cog in cogs:
        await self.load_extension(cog)

    synced = await self.tree.sync()
    self.slash_ids = {cmd.name: cmd.id for cmd in synced}
Global slash command sync can take up to one hour to propagate to all Discord clients after a fresh bot registration. Guild-scoped syncs are instant but only appear within that server.

​
Error Handling

Noxie handles errors visually rather than with plain text fallbacks. Both global error handlers — on_command_error for prefix commands and on_app_command_error for slash commands — build a build_face_reaction_container() CV2 card and route it through send_cv2():
  • CommandOnCooldown triggers the "cooldown" event, which resolves to the sleepy mood banner, and displays the remaining seconds.
  • MissingPermissions sends a plain message with delete_after=5 since it does not warrant a mood reaction.
  • CommandNotFound is silently ignored to avoid noise from other bots’ prefixes.
  • MissingRequiredArgument sends a plain tip pointing the user toward noxie help.
  • All other errors trigger the "error" event (dizzy mood banner) and log the full traceback via utils.logger.
Slash command errors always send the CV2 error card as an ephemeral response, ensuring only the triggering user sees the message.
To add a new handled error type, extend the isinstance chain in on_command_error inside main.py and optionally call face_manager.get_face_for_event() with the appropriate event key for a matching mood banner.

Build docs developers (and LLMs) love

Get started for freeTalk to us