🐦 BirdBot Monorepo

BirdBot is an automated player for BombParty on jklm.fun, designed to help players improve their skills through practice and analysis.

✨ Features

• Practice: Train against a consistent, high-performance opponent
• Progress Tracking: Keep track of your records
• Research Tools: Access word research tools for specific categories
• Custom Game Modes: Experience unique game modes beyond classic BombParty

Quick Start

Production Setup

1. Clone the repository

   git clone <repository_url> birdbot
   cd birdbot

2. Configure Environment

   cp .env.example .env
   # Edit .env with your configuration

3. Launch with Docker

   ./prod.sh

Tech Stack

Component	Technology
Database	PostgreSQL
API	Fastify (TypeScript) + Prisma
Website	Next.js (TypeScript)
Bot	TypeScript + Socket.IO + Rust
Runtime	Docker + Node.js 23.7 (Alpine)

Development Guide

Prerequisites

For development:

• Docker
• Node.js v23.7+
• Rust 1.86+

For production:

• Docker

Development Setup

1. Start Development Database (Required)

./launch-open-db.sh

2. Run Individual Modules

To run the API module:

# Go to the API directory
cd api

# Create environment file (Configure as you wish)
cp .env.example .env

# Install dependencies locally
npm install

# Start the API with nodemon in watch mode
npm run dev

To run the Website module:

# Go to the website directory
cd website

# Create environment file (Configure as you wish)
cp .env.example .env

# Install dependencies locally
npm install

# Start the Next.js website in development mode
npm run dev

To run the Bot module:

# Go to the bot directory
cd bot

# Create environment file (Configure as you wish)
cp .env.example .env

# Build the BirdBot powerhouse for dictionary metadata generation
./build_birdbot_powerhouse.sh

# Create the bot starting script
# index.unstable.ts is gitignored to prevent versioning unstable bot starting scripts in development
cp src/index.ts src/index.unstable.ts

# Run the unstable bot starting script
npm run u

Note that, contrary to the API and website modules, you must fully restart the script everytime you make a change to the code.

Bot configuration

• admins.txt: one jklm auth.id per line for admin commands
• Optional JKLM_AUTH_TOKEN / JKLM_AUTH_USERNAME for a logged-in jklm account (guest hosting works without them)
• API_URL / API_KEY must match the API service used for profiles, credits, VIP, milestones, and moderation
• Optional moderation toggles and definitions socket overrides are documented in bot/.env.example
• Parity contract and intentional divergences: bot/BBV7_PARITY.md

The older Croco.games bot archive lives under archive/BBV7 for historical reference only.

Safe admin commands (admins.txt)

• /reconnect — reconnect the current room sockets
• /health — room + API status
• /givecredits, /givexp, /setxp, /suppress, /getid, /creatorid
• /broadcast, /rooms, /destroyallrooms, /diag

Destructive BBV7 reload/cache-wipe and profile-file delete flows are intentionally not ported.

---

Made with ❤️ for the BombParty community