126 lines
3.3 KiB
Markdown
126 lines
3.3 KiB
Markdown
# OC Bot - Original Character Management Discord Bot
|
|
|
|
A Discord bot for creating and managing original characters (OCs) with a user-friendly prefix-based command system.
|
|
|
|
## Quick Start
|
|
|
|
1. **Install dependencies**: `pip install -r requirements.txt`
|
|
2. **Setup MariaDB**: Create a database named `rp_bot`
|
|
3. **Configure**: Edit `.env` with your Discord token and database credentials
|
|
4. **Run**: `python bot.py`
|
|
|
|
## Features
|
|
|
|
✨ **Character Management**
|
|
- Create, edit, delete, and list original characters
|
|
- User-scoped triggers (multiple users can use same code)
|
|
- Avatar customization
|
|
- Character descriptions and metadata
|
|
- Last-used tracking
|
|
|
|
🎭 **Character Messaging**
|
|
- Send messages as your characters through webhooks
|
|
- Automatic message deletion of original command
|
|
- Character preview system
|
|
|
|
📚 **Help System**
|
|
- Comprehensive beginner-friendly guides
|
|
- Interactive command assistance
|
|
- FAQ and troubleshooting
|
|
|
|
⚡ **Performance**
|
|
- O(1) trigger lookup with caching
|
|
- Database indexes for fast queries
|
|
- Optimized for thousands of users
|
|
|
|
## Commands
|
|
|
|
### Basic
|
|
- `,help` - Show help menu
|
|
- `,ping` - Check bot status
|
|
- `,stats` - View statistics
|
|
|
|
### Character Management
|
|
- `,oc create` - Create new character (interactive)
|
|
- `,oc list` - List your characters
|
|
- `,oc info <name>` - View details
|
|
- `,oc edit <name>` - Edit character
|
|
- `,oc delete <name>` - Delete character
|
|
- `,oc preview <name>` - Preview message
|
|
|
|
### Character Messaging
|
|
```
|
|
,ba Hello everyone!
|
|
```
|
|
Send message as character with trigger 'ba'
|
|
|
|
## Requirements
|
|
|
|
- Python 3.8+
|
|
- MariaDB
|
|
- Discord.py 2.3.2+
|
|
- MySQL Connector
|
|
|
|
## Setup
|
|
|
|
See [SETUP.md](SETUP.md) for detailed installation and configuration guide.
|
|
|
|
### Quick Setup
|
|
1. Copy `.env.example` to `.env` and fill in your credentials
|
|
2. Install dependencies: `pip install -r requirements.txt`
|
|
3. Create MariaDB database: `CREATE DATABASE rp_bot;`
|
|
4. Run: `python bot.py`
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
rp-bot/
|
|
├── bot.py # Main bot application
|
|
├── database.py # Database management
|
|
├── requirements.txt # Dependencies
|
|
├── .env # Configuration (create this)
|
|
├── SETUP.md # Setup guide
|
|
└── cogs/
|
|
├── oc.py # Character commands
|
|
├── help.py # Help system
|
|
├── utils.py # Utility commands
|
|
└── config.py # Admin commands
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **User creates character** via `,oc create` with name, avatar, trigger
|
|
2. **Bot stores in database** with user ID and trigger
|
|
3. **User sends message** with trigger: `,ba Hello`
|
|
4. **Bot processes**:
|
|
- Checks if (user_id, trigger) exists
|
|
- Deletes original message
|
|
- Creates/reuses webhook
|
|
- Sends message as character
|
|
5. **Others see** message from character avatar/name
|
|
|
|
## Performance
|
|
|
|
- **Trigger Lookup**: < 1ms (in-memory cache + DB index)
|
|
- **Message Send**: ~100-500ms (Discord API)
|
|
- **Scale**: Supports 10,000+ users, 50,000+ characters
|
|
|
|
## Reserved Commands
|
|
|
|
These cannot be used as character triggers:
|
|
```
|
|
help, oc, ping, stats, invite, support, about, reload, debug, admin, config
|
|
```
|
|
|
|
## Security
|
|
|
|
- User-specific trigger scoping prevents conflicts
|
|
- Webhook management automatic and secure
|
|
- Original messages deleted to prevent confusion
|
|
- Database role-based access ready
|
|
|
|
## Support
|
|
|
|
Check [SETUP.md](SETUP.md) troubleshooting section for common issues.
|
|
|