Skip to main content
Get your Project Stardust bot running in just a few steps. This guide will have you pulling characters and battling in no time.

​
Prerequisites

Project Stardust requires Python 3.8 or higher and a PostgreSQL database (we recommend Supabase).
Before you begin, make sure you have:
  • Python 3.8+ installed
  • A Discord bot token
  • A PostgreSQL database URL (Supabase recommended)
  • Git installed

​
Quick setup

1

Clone the repository

Clone the Project Stardust repository to your local machine:
git clone https://github.com/itstrudeauver/twt.git
cd twt
2

Install dependencies

Install all required Python packages:
pip install -r requirements.txt
This installs:
  • discord.py - Discord bot framework
  • asyncpg - PostgreSQL async driver
  • aiohttp - HTTP client for AniList API
  • Pillow - Image generation
  • python-dotenv - Environment variable management
3

Configure environment variables

Create a .env file in the root directory with your credentials:
DISCORD_TOKEN=your_discord_bot_token_here
DATABASE_URL=postgresql://user:password@host:port/database
COMMAND_PREFIX=!
PORT=8080
Never commit your .env file to version control. Add it to .gitignore to keep your credentials safe.
Getting a Discord bot token:
  1. Go to the Discord Developer Portal
  2. Create a new application
  3. Go to the “Bot” section and click “Add Bot”
  4. Copy the token and paste it into your .env file
Setting up Supabase (recommended):
  1. Create a free account at Supabase
  2. Create a new project
  3. Go to Settings → Database and copy the connection string
  4. Use the “Session” mode connection string for the free tier
4

Run the bot

Start Project Stardust:
python main.py
You should see output like this:
📡 Health check server live on port 8080
🗄️  Connecting to Supabase...
✅ Database initialized successfully.
⚙️  Loading Modules...
   ✅ Loaded: achievements.py
   ✅ Loaded: admin.py
   ✅ Loaded: battle.py
   ✅ Loaded: gacha.py
   ...
--------------------------------------------------
✨ Project Stardust is Online as: YourBotName
--------------------------------------------------
5

Test the bot

Invite your bot to a Discord server and try these commands:
!help           # View all available commands
!starter        # Claim your free starter pack
!team           # View your team
!pull 10        # Pull 10 characters (requires gems)
Your bot is now ready to use!

​
Troubleshooting

Make sure your DISCORD_TOKEN in the .env file is correct and has no extra spaces. The token should start with something like MTAx...
  • Verify your DATABASE_URL is correct
  • For Supabase free tier, use the “Session” mode connection string, not “Transaction” mode
  • Check that your database allows connections from your IP address
  • The connection pool is configured for max 3 connections to work with Supabase’s limits
  • Make sure you’re running Python 3.8 or higher
  • Verify all dependencies from requirements.txt are installed
  • Check the error message for specific missing modules
The bot uses the public AniList GraphQL API. If you see API errors:
  • Check your internet connection
  • The API might be temporarily down (rare)
  • Rate limits are handled automatically by the caching system

​
Next steps

Detailed setup

Learn about advanced configuration options and hosting

Core systems

Understand how the gacha, battles, and progression work

Command reference

Explore all available commands and their usage

Technical docs

Dive into the bot’s architecture and skills system

Build docs developers (and LLMs) love

Get started for freeTalk to us