Collect football clubs. Discover your favourites. Trade with friends. Build your collection.
FCDex is an open-source Discord bot project inspired by collectible dex bots, reimagined around football clubs.
Build your collection, discover clubs, and eventually compete and trade with other collectors — all through Discord.
Our goal is to create a flexible, modular, and community-driven football collecting experience.
FCDex is built by a team passionate about football, Discord bots, and open-source development.
| Member | Role |
|---|---|
| Astro | Project Lead & Lead Developer |
Ariel Aram |
Core Developer |
Alan |
Community and Bot Manager and Contributor |
Hiboman |
Developer |
Earthiopia |
Contributor |
Giga |
Contributor |
Bloxy |
Bot Hoster & Contributor |
Zion |
Contributor |
Want to join the team? Visit our Discord server and introduce yourself!
- ⚽ Club Collection — collect football clubs and build your personal collection.
- 🎯 Catch System — identify and catch clubs when they spawn, in home, away and third kits.
- 🏆 Tier-Based Rarity — discover clubs across weighted rarity tiers.
- 📦 Modular Packages — enable or disable features through configuration.
- 🛠️ Pitch Controls — spawn channel pinning, toggles, force spawns and bans.
- 🔄 Trading — escrowed transfer offers with fees and history.
- ⚔️ Matchdays & Duels — AI friendlies and PvP club duels with coin stakes.
- 🪙 Economy — daily wages, catch rewards and coin leaderboards.
- 🌐 Open Source — contribute, report bugs, and help shape FCDex.
🚧 FCDex is actively being developed. Some features are planned and are not yet available.
- Bun
- Node.js for the current production start script
- A Discord application
FCDex runs on no privileged intents. It enables only Guilds and GuildMessages; spawn detection never reads message content, so you can leave Message Content, Server Members, and Server Presence intents disabled in the Discord Developer Portal.
Bot invite permissions are minimal: View Channels and Send Messages. Slash commands deploy globally and require no additional permissions. The only gated surface is /pitch, whose controls are limited to members with Manage Server.
FCDex is fully compatible with the BallsDex PostgreSQL schema and runs on embedded PGlite. Import any pg_dump backup produced by BallsDex or FCDex v3:
bun run db:import path/to/ballsdex_backup.sqlThe importer sanitizes the dump, replays the DDL, converts every COPY block into batched inserts, applies foreign keys, adds FCDex additive columns (trade.status, trade.expires_at, trade.resolved_at) and syncs identity sequences. Clubs (ball), variants (special), collections (ballinstance), trades (trade + tradeobject), guild settings (guildconfig) and blacklists (blacklistedid) are read directly from the imported data.
For a fresh, empty database without a backup, create the schema from prisma/schema.sql:
bun run db:push1. Clone the repository
git clone https://github.com/saedevz/fcdex.git
cd fcdex2. Install dependencies
bun install3. Generate your local configuration
bun run setupOpen the generated src/config/config.ts and configure your Discord bot credentials and other settings.
4. Configure the database
Set up your PostgreSQL connection using the environment configuration expected by the Prisma client.
Consult the Database Setup Guide before proceeding.
5. Generate the Prisma client
bun run db:generate6. Start development
bun run dev
⚠️ Database migrations are intentionally not included in these quick-start commands. Review the Prisma schema and database setup documentation before applying migrations.
FCDex uses a central TypeScript configuration file.
You can configure settings such as:
- Discord bot credentials
- Enabled packages
- Club collection settings
- Catch messages and buttons
- Tier-based rarity settings
- Economy, matchday, and transfer settings
- Pitch (spawn channel) controls
- Logging and appearance
Keep credentials private. Never commit your real tokens, secrets, or database credentials to GitHub.
Your local configuration file should remain excluded from version control.
Everything you need to install, configure, run, and contribute to FCDex.
| Guide | Description |
|---|---|
| 🏠 Wiki Home | Overview of the documentation |
| 📦 Installation | Clone the repository and install dependencies |
| ⚙️ Configuration | Customize bot settings and enabled packages |
| 🗄️ Database Setup | Configure PostgreSQL and Prisma |
| Start the bot and understand startup logs | |
| 🧩 Package System | Understand the modular package architecture |
| 🛠️ Troubleshooting | Diagnose common errors and startup problems |
| 🤝 Contributing | Learn how to contribute to FCDex |
FCDex is designed around individual feature packages.
Each package can contain its own commands, event handlers, and functionality. The package loader discovers package folders and loads enabled packages according to the central configuration.
Planned packages include:
| Package | Purpose |
|---|---|
clubs |
Club collection and catching |
players |
Player-related features |
trade |
Club trading |
battle |
Club battles |
economy |
Currency and economy |
admin |
Administrative commands |
specials |
Special collection features |
guilds |
Server-specific settings |
groups |
Collection groups |
fcscript |
Custom scripting support |
Packages will become available as their implementations are completed.
Contributions, ideas, and bug reports are welcome!
- Read the Contributing Guide.
- Check existing issues.
- Create a branch for your changes.
- Submit a pull request with a clear description.
Please avoid committing secrets, generated files, or unrelated changes.
Need help, want to suggest a feature, or just want to follow development?
Discuss development, share ideas, and connect with other FCDex users.
FCDex is licensed under the MIT License.