bird-rpg

Imported from oddgoo/bird-rpg (AGENTS.md). Install upstream with npx skills add oddgoo/bird-rpg. Copyright stays with the author.

AGENTS.md

This file provides guidance to coding agents when working with code in this repository.

Quick Playbook

• Mission: keep the bird-themed Discord RPG running smoothly and in-theme.
• Before changing gameplay logic or user-facing copy, read README.md for setup/run basics and skim templates/help.html for command behavior and tone.
• Stack: Discord bot (discord.py slash commands in commands/) plus Flask web server (web/server.py) with templates in templates/ and assets in static/.
• Data: game state is persisted in Supabase via helpers in data/storage.py; local reference/config data and backups still use files under config.config.DATA_PATH.
• Runtime: create a venv, pip install -r requirements.txt, set required env vars, and run python bot.py (starts bot + web server).
• Testing: run pytest ./tests; prefer targeted tests near changed logic.
• Web/UI: keep styles aligned with the established mystical/papyrus vibe in templates/base.html.
• Bot commands: add cogs in commands/, register via the existing startup/sync pattern, and respect limits in config/config.py.
• Data safety: when stored shapes change, add safe migrations and avoid breaking existing data.
• Library docs: use Context7 MCP docs for library-specific details.

Project Overview

Bird RPG is a bird-themed Discord bot game with an accompanying Flask web server. Players collect birds, tend gardens, and engage in community activities.

Commands

# Setup
python3 -m venv venv
source ./venv/bin/activate  # Mac/Linux
pip install -r requirements.txt

# Run the bot (starts both Discord bot and Flask server on port 10000)
python bot.py

# Run tests (use venv python)
venv/bin/pytest ./tests

# Run a single test file
venv/bin/pytest ./tests/test_manifest.py

# Run a specific test
venv/bin/pytest ./tests/test_manifest.py::test_function_name

# Migrate JSON data to Supabase (one-time)
python scripts/migrate_to_supabase.py

Set DEBUG=true in .env to enable debug commands and template auto-reload.

Environment Variables

Required in .env:

• DISCORD_TOKEN - Discord bot token
• SUPABASE_URL - Supabase project URL (e.g. https://your-project.supabase.co)
• SUPABASE_KEY - Supabase anon/public key
• ADMIN_PASSWORD - Password for web admin panel
• DEBUG - Set to true for debug mode (optional)
• XENO_CANTO_API_KEY - Xeno-canto API key for bird song audio in /sing commands (optional, falls back to bundled MP3s)
• WEB_BASE_URL - Base URL for the web server (optional, defaults to http://localhost:10000). Used for generating decorator links.

Architecture

Dual-server design: bot.py starts both the Discord bot (discord.py with slash commands) and Flask web server in a separate thread.

Commands: Discord slash commands live in commands/ as cogs. Each cog class inherits from commands.Cog and registers via async def setup(bot). Add new commands by creating a cog file and adding it to the COGS list in bot.py.

Web: Flask routes in web/server.py, templates in templates/ (Jinja2), static assets in static/. templates/base.html provides the layout with a mystical/papyrus aesthetic. Route handlers are split into web/home.py, web/research.py, web/birdwatch.py, web/awards.py, web/admin.py, and web/decorator.py. Navigation menu is in templates/components/navbar.html.

Data storage: Supabase (PostgreSQL) via the supabase-py library. All game state is stored in ~20 normalized tables (players, player_birds, eggs, daily_actions, etc.).

• data/db.py - Supabase client singleton (get_sync_client() for Flask, get_async_client() for Discord commands)
• data/storage.py - All database operations as async functions (with _sync suffixed variants for Flask routes)
• data/models.py - Game logic functions (async) that call storage.py

Reference data files (read-only, bundled with code):

• data/bird_species.json - Base bird species catalog
• data/plant_species.json - Base plant species catalog
• data/treasures.json - Treasure/sticker items
• data/human_entities.json - Human spawner data
• data/research_entities.json - Research system config (default event)
• data/research_entities_digraa2026.json - Research entities for digraa2026 event
• data/realm_lore.json - Realm narrative messages

Birdwatch: /birdwatch command accepts image attachments via discord.Attachment. Images are resized (max 1920px) and compressed to JPEG with Pillow before uploading to a Supabase Storage public bucket (birdwatch-images). Requires the bucket to be created manually in the Supabase dashboard.

Visual Decorator: /decorator command generates a temporary URL (1-hour expiry) that opens a web-based drag-and-drop sticker decorator. Players can visually place, rotate, resize, reorder, and remove stickers on birds, plants, or their nest. Token management is in web/decorator_tokens.py (in-memory, thread-safe). Routes are in web/decorator.py. The decorator template (templates/decorator.html) uses vanilla JS with Pointer Events for unified mouse/touch handling. Treasure tables (bird_treasures, plant_treasures, nest_treasures) include rotation (degrees), z_index (layering), and size (percentage, default 25%) columns.

Birdsong audio: /sing and /sing_repeat commands attach a short MP3 of a bird song from a random bird in the singer's collection. utils/birdsong_audio.py fetches audio from xeno-canto API v3 (requires XENO_CANTO_API_KEY), with an in-memory LRU cache (50 entries). Falls back to bundled MP3s in static/audio/birdsongs/ when the API is unavailable. Audio failure never blocks the text response.

Configuration: config/config.py holds limits (MAX_BIRDS_PER_NEST, MAX_GARDEN_SIZE), birdwatch image settings, Supabase connection config, and environment variables. Game constants in constants.py and data/constants.py.

Database Schema

Schema SQL is at scripts/schema.sql. Incremental SQL migrations for existing DBs live in scripts/migrations/. Key tables:

• players - Player data (twigs, seeds, inspiration, etc.)
• player_birds / player_plants - Birds and plants owned by players (nullable group_name column for user-defined grouping)
• common_nest - Shared community nest (singleton)
• eggs / egg_multipliers / egg_brooders - Egg incubation system
• daily_actions / daily_songs / daily_brooding - Daily activity tracking
• manifested_birds / manifested_plants - Community-created species
• research_progress / exploration - Progression systems
• birdwatch_sightings - User-uploaded bird photos (stored in Supabase Storage birdwatch-images bucket)
• game_settings - Key-value config (e.g. active_event for the event system, weather_location for configurable weather coordinates)

RPC functions provide atomic operations:

• increment_common_nest / increment_player_field - Atomic field increments
• increment_research_progress - Atomic research progress upsert
• increment_exploration_points - Atomic exploration upsert (returns new total)
• upsert_released_bird_atomic - Atomic released bird count increment

Key Patterns

• Async/sync split: Discord commands use async DB functions; Flask routes use _sync suffixed variants
• Atomic operations: Use db.increment_player_field() / db.increment_common_nest() (RPC calls) instead of read-modify-write for numeric fields. db.increment_research(), db.increment_exploration(), and db.upsert_released_bird() also use atomic RPCs.
• Read-only player lookup: Use db.get_player_sync(user_id) for web routes that should NOT auto-create players (returns None if not found). Use db.load_player_sync() only when auto-creation is intended.
• First-action-of-day checks: is_first_action_of_type(user_id, type) checks a single action type. is_first_action_of_any_type(user_id, types) checks multiple related types (e.g. ["build", "build_common"]) to prevent bonuses firing twice for personal vs common nest actions.
• Gardening pure helpers: can_afford_plant(), has_garden_space(), calc_compost_refund() in data/models.py are pure functions used by both commands/gardening.py and tests.
• Admin routes require POST: Destructive admin routes (purge_old_actions, download_species_images) use methods=['POST'] to prevent CSRF via GET requests.
• No load-everything pattern: Each command makes targeted DB calls (SELECT/INSERT/UPDATE) instead of loading all data
• Cached reference data: Read-only JSON files (treasures.json, research_entities.json) are cached at module level. Use data.models.load_treasures() and data.storage.load_research_entities(event) instead of reading files directly. commands/foraging.py:load_treasures() delegates to the cached version. load_bird_species() / load_bird_species_sync() are also cached; call clear_bird_species_cache() after manifesting a new bird.
• Group/ungroup commands: /group and /ungroup in commands/customisation.py let players organize birds and plants into named groups. Groups display as subheadings on the user profile page (templates/user.html). The template uses Jinja2 macros (bird_card, plant_card) and data-attribute-based JS for image loading.
• Batch singing operations: _process_singing() in commands/singing.py uses batch DB operations (db.get_sung_to_targets_today(), db.record_songs_batch()) and asyncio.gather() for concurrent bonus actions to minimize DB round-trips. Bird bonuses and inspiration are pre-computed once before the loop.
• Batch brooding target discovery: /brood_all and /brood_random in commands/incubation.py now prefilter with batch DB helpers (db.get_eggs_for_users(), db.get_bird_counts_for_users(), db.get_brooded_targets_today()) to avoid per-player query loops. The command resolves guild members from cache first (guild.get_member) and only falls back to bounded concurrent fetch_member calls.
• Event system: The game_settings table stores active_event (default: "default"). Toggle events directly in Supabase. load_research_entities(event) loads event-specific JSON files (research_entities_{event}.json). load_all_research_entities() combines entities from all events for milestone bonus calculations. The /study dropdown shows 8 shuffled authors from the active event.
• Weather location: The game_settings table stores weather_location as a JSON string with latitude, longitude, timezone, and name fields. Defaults to Melbourne/Naarm if not set. Change it in Supabase when switching events to update /weather and daily weather updates.
• Research entity format: All research entity JSON files use {"milestone": "+1 Bird Limit"} (single string). The milestone repeats for every threshold. Use _get_milestone_type(entity) helper in data/models.py to read the milestone type.
• Bulk-fetch helpers: Use db.get_bird_treasures_for_birds_sync(bird_ids) for batch bird treasure lookups instead of per-bird queries
• Slash commands auto-sync on bot startup
• Use utils.logging.log_debug for debug output
• Time functions in utils/time_utils.py use Australian timezone
• templates/help.html is the authoritative user-facing command guide - update when gameplay changes

Testing

Tests in tests/ use pytest with pytest-asyncio for async tests. Tests mock the Supabase client via unittest.mock.AsyncMock on data.storage functions. Prefer targeted tests near changed logic.

# Run all tests
venv/bin/pytest ./tests

# Run a single test file
venv/bin/pytest ./tests/test_birdsong_audio.py

# Run a specific test by name
venv/bin/pytest ./tests/test_manifest.py::test_function_name

# Verbose output
venv/bin/pytest ./tests -v

Workflow Rules

• Read this file before every task: Before starting any change, read AGENTS.md to align with current commands, patterns, and architecture notes.
• Update this file after every task: After completing any task, review AGENTS.md and update it with any new relevant information (new commands, patterns, architecture changes, etc.) so it stays accurate.
• Use MCP Context7 for documentation lookups: When you need documentation for any library or framework, always use the Context7 MCP tools (resolve-library-id then query-docs) to get up-to-date docs instead of relying on training data.