{"id":19940677,"url":"https://github.com/quantumbagel/playcord","last_synced_at":"2026-04-05T22:06:36.215Z","repository":{"id":260139233,"uuid":"878711212","full_name":"quantumbagel/PlayCord","owner":"quantumbagel","description":"PlayCord is a Discord minigame bot with an easily extensible API (mirrored to PlayCord/bot)","archived":false,"fork":false,"pushed_at":"2025-03-10T20:22:31.000Z","size":284,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-07T17:41:56.366Z","etag":null,"topics":["api","discord","discord-bot","discord-py","minigame","minigames","mysql","mysql-connector-python","python3","quantumbagel"],"latest_commit_sha":null,"homepage":"https://playcord.github.io/invite","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quantumbagel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-25T23:12:35.000Z","updated_at":"2025-03-10T20:22:34.000Z","dependencies_parsed_at":"2024-12-29T16:18:51.516Z","dependency_job_id":"6346276e-0781-4a49-99db-88afd9d4c2eb","html_url":"https://github.com/quantumbagel/PlayCord","commit_stats":null,"previous_names":["quantumbagel/playcord"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumbagel%2FPlayCord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumbagel%2FPlayCord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumbagel%2FPlayCord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantumbagel%2FPlayCord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quantumbagel","download_url":"https://codeload.github.com/quantumbagel/PlayCord/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252210791,"owners_count":21712276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","discord","discord-bot","discord-py","minigame","minigames","mysql","mysql-connector-python","python3","quantumbagel"],"created_at":"2024-11-13T00:06:24.257Z","updated_at":"2026-04-05T22:06:36.179Z","avatar_url":"https://github.com/quantumbagel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n  \u003ch1\u003e\n    \u003cimg src=\"docs/playcord_logo.jpg\" alt=\"PlayCord icon\" width=\"80\" align=\"center\" /\u003e PlayCord\n  \u003c/h1\u003e\n\n  \u003cp\u003e\u003cem\u003eA Discord bot for turn-based \u0026 paper/pencil games, written in Python\u003c/em\u003e\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.12-blue?logo=python\" alt=\"python\" /\u003e\u003c/a\u003e\n    \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-GPLv3-green?logo=opensourceinitiative\" alt=\"license\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/quantumbagel/playcord\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/quantumbagel/playcord?style=social\" alt=\"GitHub stars\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\n\u003c/div\u003e\n\n## About\n\nPlayCord aims to provide an easy-to-use framework and bot that can host classic paper-and-pencil games on Discord. The\nproject focuses on an extensible game API, server-side match state management, SVG rendering for game boards, and a\nPostgreSQL-backed leaderboard with TrueSkill-style ratings.\n\n### TLDR: Games, on Discord, without needing Activities.\n\n\u003e If you think this is cool, please (1) star the project and (2) follow me, it helps motivate me to keep improving the\n\u003e project :D\n\n## Features\n\n- Many games supported: Tic-Tac-Toe, Connect Four, Reversi, Battleship, Liar's Dice, and more\n- TrueSkill-based rankings (the same ELO used by Rocket League and Halo) with global and server leaderboards\n- Create new games with a simple Python API\n- Persistent leaderboards, match history, and analytics\n- Match with players across different Discord servers\n- Button-based gameplay with emoji support\n\n## Games\n\n### Implemented\n\n| Game            | Players | Description                |\n|-----------------|---------|----------------------------|\n| Tic-Tac-Toe     | 2       | Classic Xs and Os          |\n| Connect Four    | 2       | Drop discs to connect four |\n| Reversi         | 2       | Flip opponent's pieces     |\n| Battleship      | 2       | Sink the enemy fleet       |\n| Liar's Dice     | 2-6     | Bluffing dice game         |\n| Nim             | 2-4     | Take stones strategically  |\n| Mastermind Duel | 2       | Code-breaking game         |\n| No Thanks!      | 3-7     | Card avoidance game        |\n| Blackjack Table | 2-7     | Multiplayer blackjack      |\n\n### Planned\n\n| Game                  | Status         |\n|-----------------------|----------------|\n| Poker (Texas Hold'em) | In Development |\n| Chess                 | In Development |\n\n## Bot Usage\n\n### Starting a Game\n\n```\n/play \u003cgame\u003e              Start a new game\n/play tictactoe           Start Tic-Tac-Toe\n/play connectfour rated:false   Start an unrated game\n/play chess private:true   Start a private game\n```\n\n### During Games\n\n- Click buttons to make moves (game-specific)\n- Use `/move` commands for complex actions\n- Games run in private threads for clean organization\n\n### Profile \u0026 Stats\n\n```\n/playcord profile [@user]   View player profile and ratings\n/playcord history \u003cgame\u003e    View match history and rating trend\n/leaderboard \u003cgame\u003e         View server or global rankings\n/playcord catalog           Browse available games\n```\n\n### Settings\n\n```\n/playcord settings          Configure game preferences\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Docker \u0026 Docker Compose\n- Discord bot token\n\n\u003e **Note:** Docker Compose is the only officially supported setup method. Everything runs in containers - you do not\n\u003e need Python installed locally.\n\n### Installation\n\n1. **Clone the repository:**\n\n```bash\ngit clone https://github.com/quantumbagel/playcord.git\ncd playcord\n```\n\n2. **Configure the bot:**\n\n```bash\ncp configuration/config.yaml.example configuration/config.yaml\n# Edit config.yaml with your Discord bot token\n```\n\nOpen `configuration/config.yaml` and add your Discord bot token and any other settings you want to customize.\n\n3. **Start everything with Docker Compose:**\n\n```bash\ndocker compose up -d\n```\n\nThis will start both the PostgreSQL database and the bot in containers. The database will be automatically initialized\nwith the schema on first run.\n\nThat's it! Your bot is now running. Use `docker compose logs -f bot` to view the bot logs.\n\n## API Usage\n\nPlayCord provides a simple API for creating new games. See [docs/API.md](docs/API.md) for full documentation.\n\n### Quick Example\n\n```python\nfrom api.Game import Game\nfrom api.Command import Command\nfrom api.MessageComponents import Description, Button\n\n\nclass MyGame(Game):\n    name = \"My Game\"\n    player_count = 2\n    moves = [Command(name=\"move\", description=\"Make a move\", callback=\"do_move\")]\n\n    def __init__(self, players):\n        self.players = players\n        self.turn = 0\n\n    def state(self):\n        return [Description(f\"Turn: {self.current_turn().mention}\")]\n\n    def current_turn(self):\n        return self.players[self.turn]\n\n    def do_move(self, player):\n        self.turn = (self.turn + 1) % len(self.players)\n\n    def outcome(self):\n        return None  # Game ongoing\n```\n\n## Dependencies\n\n### Core\n\n- `discord.py` - Discord API wrapper\n- `psycopg` / `psycopg_pool` - PostgreSQL driver\n- `trueskill` - Rating system\n- `ruamel.yaml` - Configuration parsing\n\n### Optional\n\n- `cairosvg` - SVG rendering for game boards\n- `pillow` - Image manipulation\n\nPlayCord now uses SVG-based board renders (converted to PNG for Discord attachments) for visual-heavy games like Chess,\nConnect Four, and Battleship peek views when `cairosvg` is available.\n\n## Project Structure\n\n```\nplaycord/\n├── api/                 # Game API interfaces\n│   ├── Game.py         # Base game class\n│   ├── Player.py       # Player representation\n│   ├── Command.py      # Move/action definitions\n│   └── MessageComponents.py  # UI components\n├── games/              # Game implementations\n├── cogs/               # Discord bot commands\n├── utils/              # Utilities (database, views, etc.)\n├── configuration/      # Config files\n├── docs/               # Documentation\n└── tests/              # Test suite\n```\n\n## Planned features\n\nSee [BROKEN.md](BROKEN.md) for a running list of known issues and planned features.\n\n## License\n\nGPLv3 License - see LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantumbagel%2Fplaycord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquantumbagel%2Fplaycord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantumbagel%2Fplaycord/lists"}