Kentroid Twitch Bot

kotlin twitch ai game development chatbot on August 20, 2025

A Twitch bot built with Kotlin and Ktor that provides chat bot functionality, games, AI integration, and a local API for controlling the bot.

Note: The GitHub repository for this project is private due to containing sensitive configuration data. This project was entirely written with Cursor/AI as another demonstration of what can be built with AI tools.

Features

Twitch Chat Bot: Connects to Twitch chat and responds to commands
Local API: Control the bot via a REST API
Multiple Games: Blackjack, Slots, Tic Tac Toe, Metroid RPG
AI Integration: LM Studio integration with multiple AI personalities
Combat System: PvP combat with missiles, beams, and power bombs
Boss Battles: Epic boss fights with team rewards
Economy System: Corn currency with store and item purchases
XP & Leveling: Progressive leveling system with E-Tank rewards
Extensible: Easy to add new commands and functionality

Bot Commands

Basic Commands

Command	Description
`!ping`	Responds with "Pong!"
`!hello`	Multi-language greetings
`!help`	Show organized command list with categories

Player Status & Economy

Command	Description
`!me`	View your complete stats (energy, missiles, super missiles, corn, power bombs, level, XP)
`!view @username`	View another player's stats
`!givecorn <amount> @username`	Transfer corn to another user

Games

Blackjack

Command	Description
`!blackjack new [bet]`	Start a new blackjack game (bet: 1-50 corn, default 5)
`!blackjack hit`	Take another card
`!blackjack stay`	Keep current hand
`!blackjack double`	Double your bet, get one card, then stay
`!blackjack split`	Split pairs into two hands (doubles bet)
`!blackjack status`	View current game state
`!blackjack help`	Show blackjack commands

Blackjack Betting & Payouts:

Betting: Bet 1-50 corn per game (default: 5)
Blackjack: Pays 3:2 (bet × 1.5)
Win: Pays 1:1 (double your bet)
Push: Refunds your bet
Loss/Bust: Lose your bet
Double Down: Available on first two cards only
Split: Available when you have a pair

Slots

Command	Description
`!slots [bet]`	Spin slots (bet 1-50 corn, default 1)
`!slots daily`	Claim 50 corn once per day
`!slots leaderboard`	Show top corn earners
`!slots help`	Show slots commands and symbols

Slot Symbols & Multipliers:

kentro7NinjaNES (1 point), kentro7Ninja (2), kentro7ColonelKernel (3), kentro7Steve (5)
kentro7SteveRIP (-5), kentro7MotherWorm (-2) (penalty symbols)
Multipliers: 2 of a kind = 1×, 3 of a kind = 4×, 4 of a kind = 8×, 5 of a kind = 16×, Full House = 10×

Tic Tac Toe

Command	Description
`!ttt new @username`	Start new game with opponent
`!ttt get`	Show your current game
`!ttt get @username`	Show game with specific player
`!ttt <position>`	Make a move (1-9: top-left to bottom-right)
`!ttt help`	Show tic tac toe commands

Metroid RPG (Single Player Adventure)

Command	Description
`!mrpg new`	Start new adventure
`!mrpg status`	Check status and location
`!mrpg look`	Examine surroundings
`!mrpg go <direction>`	Move (up, down, left, right)
`!mrpg shoot door`	Blast open locked doors
`!mrpg attack`	Attack enemies with beam
`!mrpg missile`	Attack with missiles (25 damage)
`!mrpg collect <item>`	Collect items
`!mrpg help`	Show RPG commands

RPG Rewards:

Regular enemies: 10-30 corn + XP per defeat
Boss enemies: 300 corn + major XP per defeat
53 rooms across 3 areas: Brinstar, Maridia, Norfair

AI Integration

LLM Assistant

Command	Description
`!llm <prompt>`	Ask the AI assistant (30s cooldown)
`!llm model <name>`	Change AI model (kentroid only)

LLM Features:

AI Models: Connects to LM Studio (default: gemma-3-27b-it@q8_0)
Available Models: gemma-3-27b-it@q8_0, deepseek-r1-distill-qwen-32b, deepseek-r1-distill-qwen-7b
Request Queue: Only 1 request processed at a time (prevents overload)
Cooldown: 30 seconds between requests per user
Smart Responses: Context-aware, Twitch-optimized responses
Auto-truncation: Long responses are automatically shortened for chat

AI Character Personalities

Command	Description
`!samus <message>`	Talk to Samus Aran (Metroid bounty hunter)
`!kraid <message>`	Chat with Kraid (grumpy space dragon)
`!ninja <message>`	Talk to Ninja (mysterious warrior)

Combat System (PvP)

Command	Description
`!missile @username`	Attack user with missile (25 damage, costs 1 missile, 5s cooldown)
`!supermissile @username`	Attack with super missile (100 damage, costs 1 super missile, 5s cooldown)
`!beam @username`	Attack user with beam (10 damage, unlimited use, 5s cooldown)
`!powerbomb` (`!pb`)	Area attack - damages ALL users in chat (50 damage, costs 1 power bomb)
`!revive @username`	Kentroid: Free revival to 99 energy Others: Sacrifice 99 of your energy

Combat Features:

Death Messages: Missile/Super Missile kills show "@username FK'N EXPLODED!!"
Death System: Dead players (0 energy) cannot attack until revived
XP Rewards: Earn XP for successful combat actions

Boss Battles

Command	Description
`!missile {boss}`	Attack with missile (25 damage, costs 1 missile, 5s cooldown)
`!supermissile {boss}`	Attack with super missile (100 damage, costs 1 super missile, 5s cooldown)
`!beam {boss}`	Attack with beam (10 damage, unlimited use, 5s cooldown)

Available Bosses: | Boss | Health | Aliases | |------|--------|---------| | Kraid | 200 HP | kraid | | Ridley | 250 HP | ridley | | Zebesian | 50 HP | zebesian | | Mother Brain | 300 HP | motherbrain, mother_brain, mother, brain |

Boss Attack Patterns: | Boss | Attacks | Damage | |------|---------|--------| | Kraid | Claw Swipe, Stomach Spikes, Roar | 15, 30, 10 | | Ridley | Wing Slash, Plasma Beam, Tail Swipe | 20, 35, 15 | | Zebesian | Laser Blast, Jump Attack, Claw Strike | 8, 12, 10 | | Mother Brain | Brain Beam, Laser Ring, Psychic Wave | 40, 25, 30 |

Boss Combat System:

Bosses attack random LIVING users every 15-30 seconds
Each boss has unique attacks with different damage values
When defeated, ALL attackers receive: +3 missiles, +50 energy, +300 corn, +major XP
If everyone dies, the boss wins with victory celebration
"Cowards not rewarded!" - only fighters get rewards

Store & Economy

Command	Description
`!store`	Browse Ken's Pawn Shop
`!store buy <item>`	Purchase items from store

Store Items:

mx1/mx3/mx5 - Missiles (1/3/5 count)
smx1/smx3/smx5 - Super missiles (1/3/5 count)
pbx1/pbx3/pbx5 - Power bombs (1/3/5 count)
ex50/ex100 - Energy refills (+50/+100 energy)
etank1/etank2/etank3/etank4/etank5 - Energy capacity upgrades

E-TANK SYSTEM:

Visual Display: ⬜️⬜️⬜️🔳🔳29 - Filled tanks (⬜️), empty tanks (🔳), plus remaining energy!
Base Capacity: 99 energy (almost 1 E-Tank worth)
Each E-Tank: +100 max energy capacity (permanent upgrade!)
Level Rewards: +1 E-Tank per level (automatic!)
Store Purchases: Buy 1-5 E-Tanks at bulk pricing

Bulk discounts available for multi-item purchases

XP & Leveling System

Earn XP from: Games, combat, bosses, daily activities
Level Rewards: +1 E-Tank per level (automatic capacity increase!)
Progressive XP requirements for each level

Daily Bonuses & Defaults

!slots daily - Claim 50 corn once per day
New users start: 99 energy, 0 missiles, 0 super missiles, 100 corn, 0 power bombs, 0 XP
Individual user data saved to ~/.kentroid_bot/username.json

API Endpoints

The bot exposes the following API endpoints:

Bot Control

Endpoint	Method	Description	Request Body	Response
`/bot/status`	GET	Check if the bot is running	None	`{"running": true/false}`
`/bot/start`	POST	Start the bot	None	`{"message": "Bot started successfully"}`
`/bot/stop`	POST	Stop the bot	None	`{"message": "Bot stopped"}`
`/bot/message`	POST	Send a message to the channel	`{"message": "Hello, world!"}`	`{"message": "Message sent successfully"}`
`/bot/chat`	POST	Send a message to Twitch chat (requires OAuth token)	`{"message": "Hello, Twitch!"}`	`{"message": "Chat message sent successfully"}` or error

Boss Battle API

Endpoint	Method	Description
`/bot/bosses/{boss}/start`	POST	Start a boss battle
`/bot/bosses/{boss}/end`	POST	End boss battle (retreat, no rewards)
`/bot/bosses/{boss}/kill`	POST	Instantly kill boss (admin, with rewards)
`/bot/bosses/{boss}/status`	GET	Get boss status
`/bot/bosses/status`	GET	Get all bosses status

Building & Running

To build or run the project, use one of the following tasks:

Task	Description
`./gradlew run`	Run the server
`bash stop-server.sh`	Stop the running server
`bash restart-server.sh`	Stop and restart the server
`bash restart-server.sh --rebuild`	Stop, rebuild, and restart the server
`./gradlew build`	Build everything
`./gradlew buildFatJar`	Build an executable JAR with all dependencies

Extending the Bot

To add new commands, modify the handleChatMessage method in TwitchBot.kt. The bot uses a modular architecture with separate classes for different game types:

BlackjackBot.kt - Blackjack game logic
SlotsBot.kt - Slot machine game logic
TicTacToeBot.kt - Tic Tac Toe game logic
MetroidRpgBot.kt - Metroid RPG adventure logic
LLMBot.kt - AI integration logic
NpcBot.kt - AI character personalities
StoreBot.kt - Economy and store logic
GameStateManager.kt - Player data and combat system

Token Management

The bot includes an automatic token refresh system that handles OAuth token expiration:

Automatic Refresh: When an access token expires, the bot automatically uses the refresh token to get a new one
Error Handling: Comprehensive logging and error handling for token refresh failures
Sleep Recovery: Robust handling of computer sleep/wake cycles that can cause network state issues
Manual Refresh: Admin can manually refresh tokens via the configuration file if needed