@zerospacegg/vynthra/BOT_SETUP.md

Discord bot for ZeroSpace.gg data

# Vynthra Discord Bot Setup

Vynthra is a Discord bot that provides access to ZeroSpace.gg game data through slash commands.

## Prerequisites

- Node.js 16+ 
- A Discord application and bot token
- Guild (server) admin permissions to add the bot

## Getting a Discord Bot Token

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application" and give it a name (e.g., "Vynthra")
3. Go to the "Bot" section in the sidebar
4. Click "Add Bot" if not already created
5. Under "Token", click "Copy" to get your bot token
6. Under "OAuth2" → "General", copy your "Client ID"

## Configuration

You can configure the bot using either environment variables or a config file.

### Option 1: Environment Variables (Recommended for Production)

```bash
export DISCORD_TOKEN="your_bot_token_here"
export DISCORD_CLIENT_ID="your_client_id_here"
export DISCORD_GUILD_ID="your_guild_id_here"  # Optional, for development
```

### Option 2: Configuration File (Recommended for Development)

1. Copy the sample config:
   ```bash
   cp bot-config.sample.json bot-config.json
   ```

2. Edit `bot-config.json` with your credentials:
   ```json
   {
     "token": "your_bot_token_here",
     "clientId": "your_client_id_here", 
     "guildId": "your_guild_id_here"
   }
   ```

**Note:** The `guildId` is optional. If provided, commands will be deployed to that specific guild only (faster for development). If omitted, commands will be deployed globally (takes up to 1 hour to propagate).

## Installation & Setup

1. Build the project:
   ```bash
   npm run build
   ```

2. Deploy slash commands to Discord:
   ```bash
   npm run bot:deploy
   ```

3. Invite the bot to your server:
   - Go to OAuth2 → URL Generator in the Discord Developer Portal
   - Select scopes: `bot`, `applications.commands`
   - Select bot permissions: `Send Messages`, `Use Slash Commands`
   - Copy the generated URL and open it to invite the bot

## Running the Bot

Start the bot:
```bash
npm run bot:start
```

Or use the direct command:
```bash
node bin/bot.js start
```

## Available Commands

### `/zsgg stats <query>`

Search for game data and get detailed stats.

**Examples:**
- `/zsgg stats grell` - Get stats for the Grell unit
- `/zsgg stats terror tank` - Get stats for Terror Tank
- `/zsgg stats mera` - Get faction information for Mera
- `/zsgg stats foundry` - Get building information

**Query Types:**
- Unit names (e.g., "grell", "hunter")
- Building names (e.g., "foundry", "barracks") 
- Faction names (e.g., "mera", "zephyr")
- Map names (e.g., "dust bowl")
- Partial names and fuzzy matching supported

## CLI Commands

The bot includes several CLI commands:

```bash
node bin/bot.js <command>
```

**Available commands:**
- `start` - Start the Discord bot (default)
- `deploy` - Deploy slash commands to Discord
- `help` - Show help information

## Development

### Guild vs Global Commands

For development, use a specific `guildId` in your config:
- ✅ Commands appear instantly
- ✅ Easy to test changes
- ❌ Only available in that guild

For production, omit `guildId`:
- ✅ Available in all guilds
- ❌ Takes up to 1 hour to propagate

### Adding New Commands

1. Create a new command file in `src/bot/commands/`
2. Export a `BotCommand` object with `data` and `execute` properties
3. Import and add it to the commands array in `src/bot/client.ts`
4. Run `npm run bot:deploy` to register the new command

## Troubleshooting

### Bot doesn't respond to commands
- Ensure you've run `npm run bot:deploy` after making changes
- Check that the bot has the `Send Messages` and `Use Slash Commands` permissions
- If using global commands, wait up to 1 hour for propagation

### "Invalid token" error
- Double-check your bot token in the configuration
- Make sure the token is from the "Bot" section, not "OAuth2"

### Commands not appearing
- Verify the bot has `applications.commands` scope when invited
- Re-run `npm run bot:deploy` 
- For guild commands, ensure the `guildId` is correct

### Response too long errors
- The bot automatically splits long responses into multiple messages
- Discord has a 2000 character limit per message

## Security Notes

- Never commit `bot-config.json` to version control
- Keep your bot token secret - regenerate if compromised
- Use environment variables in production environments
- The bot only needs minimal permissions to function

## Data Source

The bot uses the `@zerospacegg/iolin` package for ZeroSpace.gg game data. This includes:
- Unit stats and abilities
- Building information
- Faction details and talents
- Map information
- Real-time game balance updates

Data is automatically updated when the iolin package is updated.