sparkles-cat-bot/README.md

### Bot Setup in Discord Developer Portal

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
2. Create a new application or select your existing one
3. Go to the "Bot" tab
4. Enable the following Privileged Gateway Intents:
   - SERVER MEMBERS INTENT
   - MESSAGE CONTENT INTENT
5. Save changes
6. Create an invite link:
   - Go to OAuth2 > URL Generator
   - Under "SCOPES", select "bot" and "applications.commands"
   - Under "BOT PERMISSIONS", select:
     - Read Messages/View Channels
     - Send Messages
     - Connect
     - Speak
     - Change Nickname
   - Copy the generated URL and use it to invite your bot to servers

# Multi-Theme Discord Bot

A Discord bot that simulates various animal behaviors in your server! Choose from different themes like cats, dogs, foxes, or robots.

## Features

- Multiple themes to choose from (cat, dog, fox, robot)
- Randomly responds to messages with theme-specific vocalizations and actions
- Joins voice channels when people are active and plays themed sounds
- Fully configurable behavior (response chance, timing, pronoun preferences)
- Realistic animal-like unpredictable behavior
- Dynamic status messages that change regularly **and adapt based on voice channel presence**
- Per-server configuration (each server can have its own theme)
- Each theme has unique nicknames that the bot randomly assigns itself
- Bot automatically changes its Discord nickname to match the theme
- Support for multiple servers simultaneously with independent configurations
- Can join voice channels in multiple servers at the same time

## Setup

### Prerequisites

- Node.js 16.9.0 or higher
- npm or yarn
- A Discord bot token (create one at the [Discord Developer Portal](https://discord.com/developers/applications))

### Installation

1. Clone this repository
2. Install dependencies:
   ```
   npm install
   ```
   or
   ```
   yarn install
   ```
3. Copy the example environment file:
   ```
   cp .env.example .env
   ```
4. Edit the `.env` file and add your Discord bot token and configure other settings
5. Add cat sound files to the `src/audio` directory (MP3 format)
6. Build the project:
   ```
   npm run build
   ```
   or
   ```
   yarn build
   ```
7. Start the bot:
   ```
   npm start
   ```
   or
   ```
   yarn start
   ```

### Required Bot Permissions

When adding your bot to a Discord server, make sure it has the following permissions:
- Read Messages/View Channels
- Send Messages
- Connect to Voice Channels
- Speak in Voice Channels
- Change Nickname (for theme-based nicknames)

### Adding Audio Files

The bot expects audio files for each theme to be placed in the `src/audio` directory. The naming convention is:
`theme_sound.mp3` (e.g., cat_meow1.mp3, dog_bark1.mp3)

Recommended files for each theme:

**Cat Theme**:
- cat_meow1.mp3
- cat_meow2.mp3
- cat_meow3.mp3
- cat_purr.mp3
- cat_hiss.mp3
- cat_yowl.mp3

**Dog Theme**:
- dog_bark1.mp3
- dog_bark2.mp3
- dog_whine.mp3
- dog_pant.mp3
- dog_growl.mp3
- dog_howl.mp3

**Fox Theme**:
- fox_bark.mp3
- fox_scream.mp3
- fox_yip.mp3
- fox_howl.mp3
- fox_chirp.mp3

**Robot Theme**:
- robot_beep.mp3
- robot_whir.mp3
- robot_startup.mp3
- robot_shutdown.mp3
- robot_error.mp3
- robot_process.mp3

## Configuration

All bot settings can be adjusted in the `.env` file:

| Setting | Description | Default |
|---------|-------------|---------|  
| DISCORD_TOKEN | Your Discord bot token | (required) |
| APPLICATION_ID | Your application ID for slash commands | (required) |
| MESSAGE_RESPONSE_CHANCE | Percentage chance to respond to a message (0-100) | 10 |
| MIN_VOICE_JOIN_INTERVAL | Minimum time in seconds between voice channel joins | 300 |
| MAX_VOICE_JOIN_INTERVAL | Maximum time in seconds between voice channel joins | 1800 |
| MIN_VOICE_STAY_DURATION | Minimum time in seconds to stay in a voice channel | 60 |
| MAX_VOICE_STAY_DURATION | Maximum time in seconds to stay in a voice channel | 300 |
| MIN_VOICE_MEOW_INTERVAL | Minimum time in seconds between sounds in voice channel | 5 |
| MAX_VOICE_MEOW_INTERVAL | Maximum time in seconds between sounds in voice channel | 30 |
| STATUS_UPDATE_INTERVAL | How often (in seconds) the bot changes its status | 300 |
| DEFAULT_THEME | Default theme for new servers (cat, dog, fox, robot) | cat |
| CAT_PRONOUN | Default pronoun to use for actions (their, his, her, etc.) | their |

## Slash Commands

The bot provides slash commands for server administrators to customize its behavior:

- `/theme set <theme>` - Change the bot's theme (cat, dog, fox, robot)
- `/theme info` - View information about the current theme
- `/settings response <chance>` - Set how often the bot responds (0-100%)
- `/settings pronoun <pronoun>` - Set which pronoun the bot uses (their, his, her, etc.)
- `/settings view` - View current settings

## Theme Nicknames

Each time you change the theme, the bot randomly selects a nickname from the theme's list:

**Cat Theme**: Whiskers, Mittens, Shadow, Luna, Oliver, Simba, Bella, Mr. Purrington, Fluffy, Captain Fuzzyboots

**Dog Theme**: Buddy, Max, Bailey, Cooper, Daisy, Sir Barksalot, Fido, Rover, Scout, Captain Goodboy

**Fox Theme**: Sly, Rusty, Firefox, Swift, Amber, Vixen, Todd, Reynard, Professor Pounce

**Robot Theme**: B33P-B00P, CyberTron, Metal Friend, Unit-7, RoboCompanion, Circuit, T1000, BinaryBuddy, Mechanoid, SynthFriend

## Voice-Aware Status Messages

The bot changes its status messages depending on whether it's in a voice channel:

### Cat Theme Example:
- **Normal:** 🐱 hunting mice, 🐱 plotting world domination, 🐱 napping in a sunbeam
- **In Voice Channel:** 🐱 purring loudly, 🐱 meowing for attention, 🐱 batting at microphones

### Dog Theme Example:
- **Normal:** 🐶 chasing squirrels, 🐶 fetching balls, 🐶 guarding the house
- **In Voice Channel:** 🐶 barking excitedly, 🐶 panting into the mic, 🐶 howling along

## License

MIT