# 🦖 ARK: Survival Evolved Cluster Discord Bot Suite

A comprehensive suite of interconnected Discord bots designed for large ARK:

Survival Evolved cluster servers. Built in Python with discord.py, featuring modern
UI components, persistent storage, and seamless integration.

## 🌟 Features

- **Modular Architecture**: 13 specialized bots working together as a unified

ecosystem
- **Modern UI**: Rich embeds, buttons, dropdowns, and interactive components
- **Persistent Storage**: SQLite database with shared user/tribe/points system
- **Auto-Setup**: Bots automatically create required channels, roles, and
configurations
- **Permission System**: Role-based access control with admin safeguards
- **RCON Integration**: Server-side command execution for in-game actions
- **Comprehensive Logging**: Audit trails and activity tracking across all bots

## 🤖 Bot Overview

### 1. **Alpha Bot** 🏆

- Track and assign "Alpha Tribe" status per map
- Commands: `/alpha set`, `/alpha reset`, `/alpha leaderboard`, `/alpha history`
- Button UI for alpha challenges
- Auto-updates pinned leaderboards

### 2. **Beef Bot** ⚔️

- Track PvP beefs between players and tribes
- Commands: `/beef log`, `/beef resolve`, `/beef list`
- Dropdown selection for beef resolution
- Comprehensive beef tracking system

### 3. **Kit Bot** 🎒

- Slash command kit claiming with cooldowns
- Button-based kit selection (Beginner, Raider, Builder)
- RCON integration for in-game item delivery
- Admin override capabilities

### 4. **Shop Bot** 💰

- In-game item shop with point currency
- Button-based purchasing system
- Transaction logging and confirmation
- Admin point management

### 5. **Admin Console Bot** 🔧

- GUI-style admin controls
- Server management (wipe, restart, ban)
- System status monitoring
- Maintenance mode controls

### 6. **Event Bot** 🎯

- Automated and manual PvP events
- Sign-up system with button interactions
- Event leaderboards and rewards
- Multiple event types (PvP, Tame, Build)

### 7. **Ticket Bot** 🎫

- Support ticket system with categories
- Ticket creation, management, and resolution
- Admin controls for ticket handling
- Commands: `/ticket create`, `/ticket close`, `/ticket list`, `/ticket add`

### 8. **Log Bot** 📊

- Monitor ARK server logs for suspicious activity
- Customizable watch lists and alert patterns
- Real-time alerts for admin actions and potential exploits
- Commands: `/log watch`, `/log mute`, `/log alerts`, `/log stats`

### 9. **Backup Bot** 💾

- Server backup management and scheduling
- Save file backup and restoration
- Automated backup schedules
- Commands: `/backup create`, `/backup restore`, `/backup schedule`, `/backup
status`

### 10. **Whitelist Bot** ✅

- Player whitelist and blacklist management
- Whitelist request system with approval workflow
- Player access control and permissions
- Commands: `/whitelist add`, `/whitelist remove`, `/whitelist request`,
`/blacklist`

### 11. **Announcement Bot** 📢

- Server announcements and scheduled messages
- Broadcast system for multiple channels
- Announcement templates and automation
- Commands: `/announce send`, `/announce schedule`, `/broadcast`, `/announce
template`

### 12. **Statistics Bot** 📈

- Server statistics and player metrics tracking
- Leaderboards and performance analytics
- Statistical reports and data visualization
- Commands: `/stats server`, `/stats player`, `/leaderboard`, `/report`

### 13. **Automation Bot** 🤖

- Automated task scheduling and execution
- Server maintenance automation
- Rule-based automation and triggers
- Commands: `/automation schedule`, `/automation rules`, `/automation maintenance`,
`/automationstatus`

## 🚀 Quick Start

### Prerequisites
- Python 3.8 or higher
- Discord Bot Token
- Windows 10 (or compatible system)

### Installation

1. **Clone the repository**

```bash
git clone <repository-url>
cd ark-discord-bots
```

2. **Install dependencies**
 ```bash
pip install -r requirements.txt
```

3. **Configure the bot**

- Edit `config.json` with your Discord bot token and server settings
- Update guild_id, owner_id, and other configuration values

4. **Run the bots**

```bash
# Run all bots
python main.py --all

# Run specific bot

python main.py --bot alpha

# Check setup
python main.py --check
```

## ⚙️ Configuration

### config.json Structure

```json
{
"discord": {
"token": "YOUR_BOT_TOKEN_HERE",
"guild_id": 1234567890123456789,
"owner_id": 1234567890123456789
},
"channels": {
"alpha_logs": "alpha-logs",
"beef_logs": "beef-logs",
"mod_alerts": "mod-alerts",
"bot_logs": "bot-logs"
},
"roles": {
"admin": "Admin",
"moderator": "Moderator",
"alpha_tribe": "Alpha Tribe"
},
"maps": [
"The Island",
"Scorched Earth",
"Aberration"
],
"kits": {
"beginner": {
"name": "Beginner Kit",
"cooldown_hours": 24,
"items": ["Stone Pick", "Stone Hatchet"]
}
}
}
```

## 📋 Commands Reference

### Alpha Bot Commands

- `/alpha set <tribe> <map>` - Set alpha tribe for a map
- `/alpha reset <map>` - Reset alpha tribe for a map
- `/alpha leaderboard` - Show current alpha tribes
- `/alpha history` - View alpha tribe history

### Beef Bot Commands

- `/beef log <attacker> <victim> <reason>` - Log a new beef
- `/beef resolve` - Resolve active beefs
- `/beef list` - List all active beefs

### Kit Bot Commands

- `/kit` - Open kit selection menu
- `/kitstatus` - Check kit cooldowns
- `/kitadmin give <user> <kit>` - Admin give kit
- `/kitadmin reset <user> <kit>` - Reset kit cooldown

### Shop Bot Commands

- `/shop` - Open shop menu
- `/balance` - Check point balance
- `/givepoints <user> <amount>` - Admin give points
- `/shopadmin list` - List shop items

### Admin Bot Commands

- `/admin` - Open admin console
- `/status` - Check system status
- `/wipe <map>` - Wipe a map
- `/restart <map>` - Restart a server
- `/ban <user> <reason>` - Ban a player
- `/maintenance` - Toggle maintenance mode

### Event Bot Commands

- `/event start <type> <name>` - Start an event
- `/event join` - Join active event
- `/event leave` - Leave current event
- `/event list` - List active events
- `/event leaderboard` - Show event leaderboard
- `/reward <user> <points> <reason>` - Give event rewards

### Ticket Bot Commands

- `/ticket create <category>` - Create support ticket
- `/ticket close` - Close your ticket
- `/ticket list` - List active tickets (Admin)
- `/ticket add <user>` - Add user to ticket
- `/ticketsetup` - Setup ticket system (Admin)

### Log Bot Commands

- `/log watch <username>` - Add user to watch list
- `/log mute <pattern>` - Mute alert pattern
- `/log alerts` - View recent alerts
- `/log stats` - View monitoring statistics
- `/logtest` - Test log monitoring (Admin)

### Backup Bot Commands

- `/backup create <map>` - Create server backup
- `/backup list [map]` - List available backups
- `/backup restore <backup_id>` - Restore a backup
- `/backup schedule` - Manage backup schedules
- `/backup status` - Show backup system status
- `/backupcleanup <days>` - Clean up old backups
### Whitelist Bot Commands
- `/whitelist add <player> [reason]` - Add player to whitelist
- `/whitelist remove <player> [reason]` - Remove player from whitelist
- `/whitelist list` - List whitelisted players
- `/whitelist request [reason]` - Request whitelist access
- `/whitelist approve <player>` - Approve whitelist request
- `/whitelist deny <player> [reason]` - Deny whitelist request
- `/blacklist add <player> [reason]` - Add player to blacklist
- `/blacklist remove <player>` - Remove player from blacklist
- `/blacklist list` - List blacklisted players
- `/whitelistrequests` - View pending requests

### Announcement Bot Commands

- `/announce send <message> [channel]` - Send immediate announcement
- `/announce schedule <message> [channel] [delay]` - Schedule announcement
- `/announce list` - List scheduled announcements
- `/announce cancel` - Cancel scheduled announcement
- `/announce template` - Show announcement templates
- `/broadcast <message> <channels>` - Send to multiple channels

### Statistics Bot Commands

- `/stats server` - View server statistics
- `/stats player <player>` - View player statistics
- `/stats daily` - View daily statistics
- `/stats weekly` - View weekly statistics
- `/stats monthly` - View monthly statistics
- `/leaderboard players` - Player leaderboard
- `/leaderboard tribes` - Tribe leaderboard
- `/leaderboard events` - Event leaderboard
- `/leaderboard points` - Points leaderboard
- `/report <type> [format]` - Generate statistical report

### Automation Bot Commands

- `/automation schedule <task> [interval]` - Schedule automated task
- `/automation list` - List scheduled tasks
- `/automation cancel <task>` - Cancel scheduled task
- `/automation rules` - Manage automation rules
- `/automation maintenance` - Manage maintenance schedule
- `/automationstatus` - Check automation system status

## Database Schema

The bots use a shared SQLite database (`ark_bots.db`) with the following tables:

- **users**: User profiles and point balances

- **tribes**: Tribe information and leadership
- **alpha_tribes**: Alpha tribe assignments per map
- **beefs**: PvP beef tracking
- **kit_usage**: Kit claim history and cooldowns
- **shop_transactions**: Shop purchase history
- **events**: Event information and status
- **event_participants**: Event participation tracking
- **bot_logs**: Comprehensive audit trail

## 🔧 Advanced Features

### RCON Integration

The bots support RCON integration for in-game actions:
- Kit delivery
- Shop item delivery
- Server management commands

### Auto-Setup System

Bots automatically create:
- Required Discord channels
- Role hierarchy
- Database tables
- Configuration files

### Permission System

- Role-based access control
- Admin command protection
- Audit logging for all actions

### Logging System

- Comprehensive activity logging
- Error tracking and reporting
- Performance monitoring
- System status tracking

## Development

### Project Structure

```
ark-discord-bots/
├── shared/ # Shared modules
│ ├── database.py # Database operations
│ ├── utils.py # Utility functions
│ ├── base_bot.py # Base bot class
│ └── __init__.py
├── bots/ # Individual bots
│ ├── alpha_bot.py # Alpha tribe management
│ ├── beef_bot.py # PvP beef tracking
│ ├── kit_bot.py # Kit system
│ ├── shop_bot.py # Shop system
│ ├── admin_bot.py # Admin console
│ ├── event_bot.py # Event management
│ ├── ticket_bot.py # Support ticket system
│ ├── log_bot.py # Log monitoring and alerts
│ ├── backup_bot.py # Backup management
│ ├── whitelist_bot.py # Whitelist management
│ ├── announcement_bot.py # Announcement system
│ ├── statistics_bot.py # Statistics and analytics
│ └── automation_bot.py # Automation and scheduling
├── config.json # Configuration file
├── requirements.txt # Python dependencies
├── main.py # Main launcher
└── README.md # This file
```

### Adding New Bots

1. Create a new bot file in the `bots/` directory
2. Inherit from `BaseBot` class
3. Implement required methods
4. Add to the bot mapping in `main.py`

### Customization
- Modify `config.json` for server-specific settings
- Add new kits in the kits section
- Configure custom roles and channels
- Extend database schema as needed

## 🚨 Troubleshooting

### Common Issues

**Bot won't start**

- Check bot token in config.json
- Ensure all dependencies are installed
- Verify Discord permissions

**Commands not working**

- Check bot permissions in Discord
- Verify role assignments
- Check database connectivity

**RCON not working**

- Verify RCON settings in config.json
- Check server RCON configuration
- Ensure network connectivity

### Debug Mode

Enable debug logging by setting log level in config.json:
```json
{
"logging": {
"level": "DEBUG"
}
}
```

## 📝 License

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

## 🤝 Contributing

1. Fork the repository

2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📞 Support

For support and questions:

- Create an issue on GitHub
- Check the troubleshooting section
- Review the configuration examples

## 🎯 Roadmap

- [x] Ticket system integration

- [x] Log monitoring system
- [x] Backup management system
- [x] Whitelist management system
- [x] Announcement system
- [x] Statistics and analytics
- [x] Automation system
- [ ] Advanced RCON features
- [ ] Web dashboard
- [ ] Mobile app support
- [ ] Additional event types
- [ ] Advanced analytics
- [ ] Log monitoring dashboard
- [ ] Automated moderation features
- [ ] Real-time server monitoring
- [ ] Advanced backup scheduling
- [ ] Player behavior analytics
- [ ] Integration with external APIs

---

**Built with ❤️ for the ARK: Survival Evolved community**