mirror of
https://github.com/barelyprofessional/KfChatDotNet.git
synced 2026-05-02 12:32:03 -04:00
Nora (#87)
This commit is contained in:
xXCryingLaughingXx
committed by
GitHub
GitHub
parent
f701cae171
commit
30d9f48d2e
293
README.md
Normal file
293
README.md
Normal file
@@ -0,0 +1,293 @@
|
||||
# KfChatDotNet
|
||||
|
||||
> ## ⚠️ **IMPORTANT: Read This First** ⚠️
|
||||
>
|
||||
> **If you're contributing to this project, please read [PRIVACY.md](PRIVACY.md) to learn how to protect your identity.**
|
||||
|
||||
---
|
||||
A C# .NET chat bot for KiwiFarms (Sneedchat) with extensive third-party integrations for stream monitoring, gambling site tracking, and interactive commands.
|
||||
|
||||
## Features
|
||||
|
||||
- 🤖 **Interactive Chat Bot** - Command-based interactions with regex pattern matching
|
||||
- 🎰 **Kasino System** - Internal gambling games (mines, limbo, coinflip, blackjack, roulette, and more)
|
||||
- 📺 **Stream Monitoring** - Track streams across Twitch, Kick, DLive, PeerTube, Owncast, YouTube
|
||||
- 💬 **Multi-Platform Integration** - Discord relay, Twitch chat, Kick events
|
||||
- 🎲 **Gambling Tracking** - Monitor bets across Rainbet, Shuffle, Howlgg, Chips.gg, Clash.gg, and more
|
||||
- 🔄 **Auto-Reconnect** - Robust WebSocket connection with automatic cookie refresh
|
||||
- 🗃️ **Database-Backed Settings** - SQLite database with EF Core migrations
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or higher
|
||||
- A KiwiFarms account
|
||||
- (Optional) SQLite viewer for database inspection
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Clone and Build
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd KfChatDotNet
|
||||
dotnet build
|
||||
```
|
||||
|
||||
### 2. Configure Credentials
|
||||
|
||||
The bot uses a **database-backed settings system**. On first run, it will create `db.sqlite` with default settings.
|
||||
|
||||
#### Option A: Using config.json (Easiest for First Run)
|
||||
|
||||
Create `KfChatDotNetBot/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"KfUsername": "your_kiwifarms_username",
|
||||
"KfPassword": "your_kiwifarms_password",
|
||||
"KfChatRoomId": 15,
|
||||
"KfDomain": "kiwifarms.st",
|
||||
"KfWsEndpoint": "wss://kiwifarms.st:9443/chat.ws",
|
||||
"SuppressChatMessages": true
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** The bot will automatically migrate `config.json` to the database on first run and rename it to `config.json.migrated`.
|
||||
|
||||
#### Option B: Directly Edit Database (After First Run)
|
||||
|
||||
Build the project, then run the bot once. This generates tables which can be updated by running `sqlite`:
|
||||
|
||||
```bash
|
||||
# Build
|
||||
dotnet build
|
||||
|
||||
# Run
|
||||
dotnet run --project KfChatDotNetBot
|
||||
|
||||
# Ctr + C to stop the application, then run
|
||||
sqlite3 db.sqlite
|
||||
```
|
||||
|
||||
```sql
|
||||
-- Update your credentials
|
||||
UPDATE Settings SET Value = 'your_username' WHERE Key = 'KiwiFarms.Username';
|
||||
UPDATE Settings SET Value = 'your_password' WHERE Key = 'KiwiFarms.Password';
|
||||
|
||||
-- Enable read-only mode for testing
|
||||
UPDATE Settings SET Value = 'true' WHERE Key = 'KiwiFarms.SuppressChatMessages';
|
||||
```
|
||||
|
||||
### 3. Run the Bot
|
||||
|
||||
```bash
|
||||
cd KfChatDotNetBot
|
||||
dotnet run
|
||||
```
|
||||
|
||||
The bot will:
|
||||
1. ✅ Create/migrate the database
|
||||
2. ✅ Sync built-in settings
|
||||
3. ✅ Connect to KiwiFarms chat
|
||||
4. ✅ Start listening for commands
|
||||
|
||||
## Configuration Guide
|
||||
|
||||
### Essential Settings
|
||||
|
||||
| Setting | Description | Default | Required |
|
||||
|---------|-------------|---------|----------|
|
||||
| `KiwiFarms.Username` | Your KF username | - | ✅ Yes |
|
||||
| `KiwiFarms.Password` | Your KF password | - | ✅ Yes |
|
||||
| `KiwiFarms.RoomId` | Chat room ID to join | `15` | ✅ Yes |
|
||||
| `KiwiFarms.SuppressChatMessages` | Read-only mode (no messages sent) | `false` | Recommended for testing |
|
||||
|
||||
### Optional Integrations
|
||||
|
||||
All external services are **disabled by default** or optional:
|
||||
|
||||
| Service | Enable Setting | Auth Required |
|
||||
|---------|---------------|---------------|
|
||||
| Discord | `Discord.Token` | Bot token |
|
||||
| Kick | `Kick.Enabled` | None (public API) |
|
||||
| Twitch | Auto-enabled | None (public GraphQL) |
|
||||
| Jackpot | `Jackpot.Enabled` | None |
|
||||
| Rainbet | `Rainbet.Enabled` | None |
|
||||
| Shuffle | Auto-enabled | None |
|
||||
| YouTube | `YouTube.ApiKey` | API key |
|
||||
| FlareSolverr | `FlareSolverr.ApiUrl` | Service URL |
|
||||
|
||||
### Viewing All Settings
|
||||
|
||||
```bash
|
||||
# View non-secret settings
|
||||
sqlite3 db.sqlite "SELECT Key, Value, Description FROM Settings WHERE IsSecret = 0 LIMIT 20;"
|
||||
|
||||
# View secret settings (passwords, tokens)
|
||||
sqlite3 db.sqlite "SELECT Key, Value FROM Settings WHERE IsSecret = 1;"
|
||||
```
|
||||
|
||||
### Testing Mode
|
||||
|
||||
For safe testing without sending messages to chat:
|
||||
|
||||
```sql
|
||||
UPDATE Settings SET Value = 'true' WHERE Key = 'KiwiFarms.SuppressChatMessages';
|
||||
```
|
||||
|
||||
When enabled, the bot will connect, listen, and process commands but **won't actually send messages**.
|
||||
|
||||
## Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
KfChatDotNet/
|
||||
├── KfChatDotNetWsClient/ # WebSocket client library for KF chat
|
||||
├── KickWsClient/ # WebSocket client library for Kick
|
||||
└── KfChatDotNetBot/ # Main bot application
|
||||
├── Commands/ # Bot commands (implement ICommand)
|
||||
├── Services/ # External service integrations
|
||||
├── Models/ # Data models and DTOs
|
||||
├── Migrations/ # EF Core database migrations
|
||||
└── Settings/ # Settings system
|
||||
```
|
||||
|
||||
### Common Commands
|
||||
|
||||
```bash
|
||||
# Build the solution
|
||||
dotnet build
|
||||
|
||||
# Run in release mode
|
||||
dotnet run --project KfChatDotNetBot -c Release
|
||||
|
||||
# Clean build artifacts
|
||||
dotnet clean
|
||||
|
||||
# Add a database migration
|
||||
dotnet ef migrations add MigrationName --project KfChatDotNetBot
|
||||
|
||||
# Update database to latest migration
|
||||
dotnet ef database update --project KfChatDotNetBot
|
||||
|
||||
# View migration SQL
|
||||
dotnet ef migrations script --project KfChatDotNetBot
|
||||
```
|
||||
|
||||
### Adding a New Command
|
||||
|
||||
1. Create a class in `KfChatDotNetBot/Commands/` implementing `ICommand`
|
||||
2. Define regex patterns and command logic
|
||||
3. The bot auto-discovers commands via reflection on startup
|
||||
|
||||
Example:
|
||||
|
||||
```csharp
|
||||
public class HelloCommand : ICommand
|
||||
{
|
||||
public List<Regex> Patterns => [new Regex(@"^hello$", RegexOptions.IgnoreCase)];
|
||||
public string? HelpText => "Says hello!";
|
||||
public UserRight RequiredRight => UserRight.User;
|
||||
public TimeSpan Timeout => TimeSpan.FromSeconds(10);
|
||||
public RateLimitOptionsModel? RateLimitOptions => null;
|
||||
|
||||
public async Task RunCommand(ChatBot botInstance, MessageModel message,
|
||||
UserDbModel user, GroupCollection arguments, CancellationToken ctx)
|
||||
{
|
||||
botInstance.SendChatMessage($"Hello, @{message.Author.Username}!");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Database Migrations
|
||||
|
||||
Migrations run **automatically** on startup. The database schema is managed via Entity Framework Core.
|
||||
|
||||
```bash
|
||||
# Create a new migration
|
||||
dotnet ef migrations add AddNewFeature --project KfChatDotNetBot
|
||||
|
||||
# Migrations are applied automatically when the bot starts
|
||||
dotnet run --project KfChatDotNetBot
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Message Flow
|
||||
|
||||
```
|
||||
KiwiFarms Chat (WebSocket)
|
||||
↓
|
||||
ChatClient (WsClient library)
|
||||
↓
|
||||
ChatBot (Event handlers)
|
||||
↓
|
||||
BotCommands (Pattern matching)
|
||||
↓
|
||||
ICommand implementations (Your commands)
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
- **ChatClient** - WebSocket connection to KF, handles reconnection and cookie management
|
||||
- **ChatBot** - Main bot orchestration, message tracking, GambaSesh detection
|
||||
- **BotCommands** - Command routing with regex patterns, rate limiting, permissions
|
||||
- **BotServices** - Manages all external service connections (Discord, Twitch, gambling sites)
|
||||
- **Money** - Internal Kasino gambling system with balance tracking
|
||||
|
||||
### Settings System
|
||||
|
||||
Settings are **stored in the database**, not config files:
|
||||
|
||||
- All settings have defaults defined in `BuiltIn.cs`
|
||||
- Settings are cached to reduce database queries
|
||||
- Secrets are marked and hidden from logs
|
||||
- Settings sync automatically on startup
|
||||
|
||||
For more architectural details, see [CLAUDE.md](CLAUDE.md).
|
||||
|
||||
## Logging
|
||||
|
||||
Logging is configured via `NLog.config`. The bot logs extensively:
|
||||
|
||||
- **Debug**: Packet details, message processing, connection events
|
||||
- **Info**: User joins/parts, sent messages, state changes
|
||||
- **Error**: Exceptions, disconnections, failed operations
|
||||
|
||||
## Optional Services Setup
|
||||
|
||||
### FlareSolverr (for Cloudflare bypass)
|
||||
|
||||
```bash
|
||||
# Using Docker
|
||||
docker run -d \
|
||||
--name=flaresolverr \
|
||||
-p 8191:8191 \
|
||||
ghcr.io/flaresolverr/flaresolverr:latest
|
||||
|
||||
# Update setting
|
||||
UPDATE Settings SET Value = 'http://localhost:8191/' WHERE Key = 'FlareSolverr.ApiUrl';
|
||||
```
|
||||
|
||||
### Discord Bot
|
||||
|
||||
1. Create a bot at [Discord Developer Portal](https://discord.com/developers/applications)
|
||||
2. Get your bot token
|
||||
3. Update setting: `UPDATE Settings SET Value = 'your_bot_token' WHERE Key = 'Discord.Token';`
|
||||
|
||||
### Redis (for YouTube PubSub)
|
||||
|
||||
```bash
|
||||
# Using Docker
|
||||
docker run -d --name redis -p 6379:6379 redis:latest
|
||||
|
||||
# Update setting
|
||||
UPDATE Settings SET Value = 'localhost:6379' WHERE Key = 'YouTube.PubSub.RedisConnectionString';
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
|
||||
|
||||
See [LICENSE](LICENSE) for details.
|
||||
Reference in New Issue
Block a user