EN | 中文

AniAvatar Discord Bot (Minori)

AniAvatar (appearing on Discord as Minori) is a feature-rich bot built with Python and discord.py. It automates a wide range of anime-related tasks, including searching for information, fetching profile pictures, hosting trivia games, and managing a server-wide leveling and economy system.

✨ Features

Progression & Economy

• EXP & Leveling: Gain EXP by chatting and playing games.
• Level Up Alerts: Receive public notifications on level-ups and rank changes.
• Automatic Role Assignment: The bot auto-creates and manages title roles (from Novice to Enlightened) based on user level.
• Customizable Profile Cards: Display your rank, title, and EXP with a personalized card featuring custom themes and backgrounds.
• Server Leaderboard: Compete for the top spot on a beautifully rendered leaderboard image.
• Shop, Inventory & Trading: Earn coins to spend in the item shop. Manage items in your inventory and donate them to other users.

View Progression Previews

Games & Fun

• Anime Quiz & Guessing Games: Test your knowledge with a multiple-choice quiz or a guess-the-character game to earn EXP and coins.
• Coin Gambling: Gamble your coins with a dynamic win chance.
• Waifu & Quotes: Get random waifu images or memorable quotes from various anime.
• Polling: Create custom polls with up to 5 options for the community to vote on.

View Games & Fun Previews

Anime & Utilities

• Anime & Character Search: Get detailed information about any anime or find the perfect profile picture for any character.
• Server Announcements: Admins can easily create and send formatted announcements.
• Dynamic Help Command: Get a clean, organized list of all available commands.
• Presence Rotation: The bot's status rotates every 20 minutes, "watching" a random anime.

View Utility Previews

🤖 Commands

Command	Category	Description
/profile [user]	Progression	Displays your or another user's profile card.
/leaderboard	Progression	Shows the server's top 10 users by EXP.
/profiletheme	Progression	Choose a custom background theme for your profile card.
/resetprofiletheme	Progression	Resets your profile card theme to the default.
/shop	Trading	Opens the item shop to buy consumables like EXP potions.
/inventory	Trading	Check your inventory and use your items.
/donate <member>	Trading	Give an item from your inventory to another user.
/anime <query>	Search	Fetches detailed information about an anime from AniList.
/animepfp <name>	Search	Finds a profile picture of an anime character.
/animequiz <questions>	Games	Starts a multiple-choice anime trivia quiz.
/guesscharacter	Games	Starts a guess-the-character from an image game.
/gamble	Fun	Gamble your coins with a dynamic win chance.
/waifu	Fun	Fetches a random waifu image.
/animequotes	Fun	Gives you a random quote from an anime.
/poll <duration>	Fun	Creates a poll with custom options via a pop-up modal.
/announce <mention> <channel>	Admin	(Admin Only) Creates and sends an announcement.
/help	General	Shows this list of all available commands.
/ping	General	Checks the bot's latency to Discord's servers.

🚀 Getting Started (Self-Hosting)

To run your own instance of Minori, follow these steps.

1. Prerequisites

• Python 3.11+
• Git
• A Discord Bot Token from the Discord Developer Portal.
• PostgreSQL (production) or local Postgres (for development). See notes below for Docker quick-start.

2. Installation

# Clone the repository
git clone https://github.com/Dendroculus/AniAvatar.git

# Navigate to the project directory
cd AniAvatar

# Create a virtual environment (recommended)
python -m venv .venv
.venv\Scripts\activate   # Windows
source .venv/bin/activate  # macOS / Linux

# Install the required dependencies
pip install -r requirements.txt

3. Configuration

This bot requires several API keys and custom emojis to function correctly.

A. Environment Setup

In your project directory, create a .env file and add the following keys. This file is included in .gitignore to prevent you from accidentally sharing your secrets.

DISCORD_TOKEN=your_discord_token
GOOGLE_API_KEY=your_google_api_key
GOOGLE_CSE_ID=your_google_cse_id

# Database (PostgreSQL)
DATABASE_URL=postgresql://<user>:<encoded_password>@<host>:5432/<database>

# REDIS (FOR CACHING)
REDIS_URL=YOUR_REDIS_URL

Notes on DATABASE_URL:

• Example: postgresql://postgres:secret%4023@localhost:5432/MinoriDB
• Percent-encode special characters in the password (use Python's urllib.parse.quote_plus or other URL-encoding tools).

B. Google Custom Search API

The /animepfp command requires a Google API Key and a Custom Search Engine ID.

Click here for instructions on how to get your Google API keys

1. Get an API Key

   • Go to the Google Cloud Console.
   • Create a new project (or use an existing one).
   • Navigate to APIs & Services → Credentials.
   • Click Create Credentials → API key and copy the key.

2. Create a Custom Search Engine (CSE)

   • Visit the Google Programmable Search Engine control panel.
   • Click Add to create a new search engine.
   • Under “Sites to search”, enter image-hosting sites like myanimelist.net, anilist.co, and zerochan.net.
   • Create the engine and copy the Search Engine ID (cx).

C. Custom Emojis

The bot uses custom emojis for its UI.

1. Upload all emojis from the /assets/other essentials emojis/ directory to a Discord server where your bot is present.
2. Enable Developer Mode in Discord, right-click each emoji, and copy its ID.
3. Update the emoji IDs in the code (primarily in games.py, progression.py, and cogs/utils/emojis.py) to match the uploaded emoji IDs.

4. Database (Postgres) & Migration from SQLite

This project originally used SQLite for local storage. The bot now uses PostgreSQL (asyncpg) in production/development. If you have an existing SQLite DB (data/minori.db) and want to migrate:

A. Quick local Postgres (Docker)

# Run a local Postgres container
docker run --name ani-pg -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres -e POSTGRES_DB=MinoriDB -p 5432:5432 -d postgres

# Example DATABASE_URL for local Docker:
# postgresql://postgres:postgres@127.0.0.1:5432/MinoriDB

B. Migration script (included) A migration helper script migrate_sqlite_to_postgres.py is included to convert your SQLite file to Postgres schema + rows.

Recommended flow:

1. Stop the bot (ensure no writes to the SQLite DB)
2. Backup your SQLite DB:

copy data\minori.db data\minori.db.bak

3. Checkpoint WAL (if present) to ensure consistency:

python -c "import sqlite3; c=sqlite3.connect('data\\minori.db'); c.execute('pragma wal_checkpoint(FULL)'); c.close(); print('checkpoint done')"

4. Dry-run to preview DDL (no data copied):

python migrate_sqlite_to_postgres.py --sqlite-file data\minori.db --database-url "%DATABASE_URL%" --dry-run

5. Run the real migration (copies data):

python migrate_sqlite_to_postgres.py --sqlite-file data\minori.db --database-url "%DATABASE_URL%"

6. Optional: convert columns to more specific types (BIGINT, INTEGER, JSONB) and add indexes — instructions and SQL are available in the docs or migration script comments.

C. If you don't need to migrate (fresh install)

• Create the Postgres database and user, set DATABASE_URL, and the bot's cog initialization will create required tables automatically (init code uses CREATE TABLE IF NOT EXISTS).

5. Run the Bot

Once configured, you can start the bot with:

python main.py

🛠 Built With

• Framework & Libraries: Python 3.11+, discord.py, aiohttp, Pillow (PIL)
• APIs: AniList API (GraphQL), Google Custom Search API
• Database: PostgreSQL (asyncpg). A lightweight migration helper is provided to import legacy SQLite data.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙌 Acknowledgements

• Thanks to Noto Fonts for providing CJK font support for the profile cards.
• This project is an independent creation and is not affiliated with, supported by, or endorsed by Discord Inc., AniList, or Google. All original assets are created by me.