147 lines
5.9 KiB
Markdown
147 lines
5.9 KiB
Markdown
# AI Agent Guide: Pixelpöbel Discord Bot
|
|
|
|
This document is intended for AI agents to understand and recreate the `pixelpöbel` Discord bot.
|
|
|
|
## 🏗 Architecture Overview
|
|
|
|
The bot uses a **Modular Command & Event Loading** pattern with **ESM (ECMAScript Modules)** and **TypeScript**.
|
|
|
|
### Key Design Patterns:
|
|
1. **Extended Client Pattern:** Extend `discord.js` `Client` class to hold global state.
|
|
2. **Dynamic Discovery:** `index.ts` uses `readdirSync` and dynamic `import()` to register commands/events.
|
|
3. **Interface-Driven Commands:** All commands implement `Command` interface.
|
|
4. **Optimized SQLite Database:** Persistent storage with `better-sqlite3`, utilizing **WAL (Write-Ahead Logging)** and **In-Memory Caching** for frequently accessed data.
|
|
5. **Twitch Monitoring:** Periodic API polling using **Batch-Requests** (100 channels per request) with Stream ID tracking.
|
|
6. **TwitchMonitor IRC:** TMI.js-based IRC chat monitoring for mod events.
|
|
7. **Reminder System:** Periodic reminder checking with target_time tracking.
|
|
8. **Auto-Response System:** Trigger word detection for automatic replies (cached).
|
|
9. **Welcome/Goodbye System:** Guild member add/remove events with customizable messages.
|
|
10. **Logging System:** Configurable event logging (messages, roles, moderation, etc.).
|
|
11. **Role Selection System:** Self-service role assignment via select menus.
|
|
12. **Grouped Commands:** Admin/Owner/Trigger/Timer commands grouped under subcommands.
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
pixelpoebel/
|
|
├── src/
|
|
│ ├── index.ts # Entry point, loads commands/events
|
|
│ ├── deploy-commands.ts # Deploy script for Discord
|
|
│ ├── commands/
|
|
│ │ └── utility/ # All commands grouped here
|
|
│ ├── events/
|
|
│ │ ├── ... # All Discord event handlers
|
|
│ └── structures/
|
|
│ ├── ExtendedClient.ts
|
|
│ ├── Command.ts
|
|
│ ├── Database.ts # Database with Caching logic
|
|
│ ├── TwitchManager.ts # Batch Polling logic
|
|
│ ├── TwitchMonitor.ts # IRC Monitoring logic
|
|
│ ├── TwitchCache.ts # IRC Message FIFO Cache
|
|
│ ├── ReminderManager.ts
|
|
│ └── Deployer.ts
|
|
├── data/ # SQLite database (volume mounted)
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── Dockerfile
|
|
├── docker-compose.yml
|
|
├── .env.example
|
|
└── .gitattributes
|
|
```
|
|
|
|
## 📝 Implementation Steps
|
|
|
|
### 1. Database with Caching
|
|
|
|
The database uses WAL mode for performance and an in-memory Map for caching settings and triggers.
|
|
|
|
```typescript
|
|
// src/structures/Database.ts
|
|
export class DB {
|
|
private static settingsCache = new Map<string, any>();
|
|
private static triggersCache = new Map<string, any[]>();
|
|
|
|
static init() {
|
|
db.pragma('journal_mode = WAL');
|
|
// ... Table creation ...
|
|
}
|
|
|
|
static getSettings(guildId: string) {
|
|
if (this.settingsCache.has(guildId)) return this.settingsCache.get(guildId);
|
|
const settings = db.prepare('SELECT * FROM guild_settings WHERE guild_id = ?').get(guildId);
|
|
if (settings) this.settingsCache.set(guildId, settings);
|
|
return settings;
|
|
}
|
|
|
|
static run(query: string, ...params: any[]) {
|
|
const result = db.prepare(query).run(...params);
|
|
if (query.toLowerCase().includes('guild_settings') || query.toLowerCase().includes('auto_responses')) {
|
|
this.settingsCache.clear();
|
|
this.triggersCache.clear();
|
|
}
|
|
return result;
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Twitch Batch Polling
|
|
|
|
To stay within API limits and provide faster updates, the bot polls Twitch in batches of 100.
|
|
|
|
```typescript
|
|
// src/structures/TwitchManager.ts
|
|
static async checkStreams(client: any) {
|
|
const monitors = client.DB.all('SELECT * FROM twitch_monitors');
|
|
const uniqueChannels = [...new Set(monitors.map(m => m.channel_name.toLowerCase()))];
|
|
|
|
for (let i = 0; i < uniqueChannels.length; i += 100) {
|
|
const chunk = uniqueChannels.slice(i, i + 100);
|
|
const query = chunk.map(name => `user_login=${encodeURIComponent(name)}`).join('&');
|
|
// fetch https://api.twitch.tv/helix/streams?${query}
|
|
// ... process results ...
|
|
}
|
|
}
|
|
|
|
static startPolling(client: any) {
|
|
setInterval(() => this.checkStreams(client), 2 * 60 * 1000); // 2 minute interval
|
|
}
|
|
```
|
|
|
|
### 3. Event Logging Optimization
|
|
|
|
All logging events use a centralized `sendLog` pattern that utilizes the `DB.getSettings()` cache.
|
|
|
|
```typescript
|
|
async function sendLog(client: any, guildId: string, event: string, embed: EmbedBuilder) {
|
|
const settings = client.DB.getSettings(guildId);
|
|
if (!settings?.log_events || !settings?.log_channel) return;
|
|
|
|
const activeEvents = settings.log_events.split(',').filter(Boolean);
|
|
if (!activeEvents.includes(event)) return;
|
|
|
|
const channel = client.guilds.cache.get(guildId)?.channels.cache.get(settings.log_channel);
|
|
if (channel?.isTextBased()) await channel.send({ embeds: [embed] });
|
|
}
|
|
```
|
|
|
|
### 4. TwitchMonitor IRC Chat Logging
|
|
|
|
**Overview:** Uses TMI.js to connect to Twitch IRC and logs moderation events (bans, timeouts, deletes) via webhooks.
|
|
|
|
**Key Feature:** FIFO Message Cache (`TwitchCache.ts`) allows restoring the text of deleted messages in the logs.
|
|
|
|
## 🚀 Performance Benchmarks (approx.)
|
|
|
|
| Metric | Old (Individual) | New (Batch/Cached) |
|
|
|--------|------------------|-------------------|
|
|
| API Calls (500 channels) | 500 | 5 |
|
|
| DB Access (Triggers) | Disk I/O per msg | RAM access |
|
|
| Notification Delay | ~5-7 min | ~2 min |
|
|
|
|
## ⚠️ Critical Constraints
|
|
|
|
1. **Batching:** Never exceed 100 channels per Twitch API request.
|
|
2. **Caching:** Always invalidate cache (`clearCache`) when updating settings.
|
|
3. **WAL Mode:** Ensure the `data/` directory has proper permissions for `.shm` and `.wal` files.
|
|
4. **Webhook Safety:** Use `WebhookClient` for Twitch IRC logging to avoid Discord bot rate limits.
|