⚽ Football Clubs Dex - FCDex

The Definitive Ballsdex TypeScript Alternative

Catch, collect, and exchange football clubs in FCDex! Built with TypeScript and the Discord.js framework!

---

👥 The Three Architects

Alex	Matt	fcdex

All united with empathy and dedication to make it happen.

🙏 Massive thanks to highschoolcrackhead for making this possible.

---

✨ Features

Feature	Description
🎣 Catch Clubs	Interactive Discord components for catching or trading football clubs.
🔄 Trading System	Trade football clubs with other users
📦 Inventory	View your club collection and completion percentage
📈 Leveling & XP	Progress through the game with experience
🧩 Modular Design	Commands, events, and components system
⚙️ Easy Config	Simple config.ts configuration

---

🚀 Getting Started

Prerequisites

• Node.js v24+
• pnpm package manager
• PostgreSQL database

📥 Clone the Repository

git clone https://github.com/TheFCProject/FCDex-DiscordBot.git
cd FCDex-DiscordBot

📦 Install Dependencies

pnpm install

⚙️ Configure the Bot

Copy the example config and edit it:

cp config/config.example.ts config.ts

Edit config.ts with your credentials:

export const config = {
    settings: {
        botToken: "your_bot_token", // Put your bot token there.
        botName: "FCDex",
        botDescription: "Catch, collect and exchange football clubs in your server!",
        prefix: "fc.",
        maxFavorites: 50,
        spawnAlert: true,
        minimalProfile: true,
        defaultEmbedColor: 0xFFFFFF, 
        exclusivityChance: 0.0005, 
    },

    spawnManager: {
        requiredMessageRange: [15, 30] as [number, number],
        cooldownTime: 180, // in seconds
        minimumMembersRequired: 20,
        spawnMessages: [
            { message: "A wild club has appeared!", rarity: 10 },
            { message: "A club just appeared out of nowhere on the field!", rarity: 9 },
            { message: "This club is rare! Go sign for it, now!", rarity: 4 },
            { message: "This club is rooting for you to catch the clubball! Come on man!", rarity: 0.5 },
        ],
        catchButtonMessages: [
            { message: "Catch me!", rarity: 10 },
            { message: "Sign me!", rarity: 7 },
            { message: "Make me proud by becoming the best manager!", rarity: 5 }
        ],
        wrongNameMessages: [
            { message: "We believe in you. Try again!", rarity: 10 },
            { message: "I'm afraid that's not the right club!", rarity: 9 },
            { message: "You got that club name wrong, sir.", rarity: 8 },
            { message: "You don't know this club? What a loser!", rarity: 4 }
        ],
        catchBonusRate: [-50, 50] as [number, number]
    },

    team: {
        teamMembersAreOwners: false, // Set this to true if you'd like.
        roots: ["id_1", "id_2"],
        superGuilds: ["id_1", "id_2"],
        superUsers: ["id_1", "id_2"],
        logChannel: "id_1"
    },

    appearance: {
        interface: {
            collectible: { singular: "club", plural: "clubs" },
            album: "League",
            country: "Club",
            exclusive: "Special Edition",
            stats: {
                atk: { name: "Attack", unit: "ATK" },
                def: { name: "Defense", unit: "DEF" }
            }
        },
        commands: {
            collection: "clubs",
            sudo: "sudo", // Set this to admin if you'd like. I prefer sudo.
            completion: { name: "completion", desc: "Show your club completion to others!" },
            trophies: { name: "trophies", desc: "Display your rarest achievements and clubs." },
            squad: { name: "squad", desc: "Display info from your FCDex squad." },
            inspect: { name: "inspect", desc: "Display detailed stats for a specific club." },
            gift: { name: "gift", desc: "Gift a club to another user." }
        }
    },

    information: {
        repositoryLink: "https://github.com/TheFCProject/FCDex-DiscordBot",
        serverInvite: "https://discord.gg/aP2EyFYxuR", // SET TO YOUR OWN INVITE LINK
        developers: ["mattd_ev", "alexxxdevelops", "highschoolcrackhead"], // DO NOT REMOVE mattd_ev or alexxxdevelops.
        contributors: ["fcdex", "mx7di_"]
    }
};

🗄️ Prepare the Database

# Generate Prisma Client
pnpm prisma:generate

Note: The database schema is defined in prisma/schema.prisma. Tables are created automatically with Prisma migrations.

▶️ Build and Run

Development:

pnpm dev

Production:

docker compose build
docker compose up

🔗 Invite the Bot

1. Go to the Discord Developer Portal
2. Select your application
3. Generate an OAuth2 invite link with:
   • bot scope
   • applications.commands scope
   • Required permissions
4. Enable the following intents in your application settings:
   • Message Content Intent
   • Server Members Intent
5. Invite the bot to your server

💡 Tip: Commands are registered automatically on startup. Restart the bot after adding new commands.

---

🎨 Customization

Want to customize the bot? You can! The codebase includes helpful comments and instructions throughout. Make sure to read them before making changes.

---

🔧 Troubleshooting

🤖 Bot not responding

• Ensure the bot is running
• Verify your TOML configuration
• Check that the database is started
• Review logs for errors

📝 Commands not registering

• Confirm command files are in src/commands/
• Check for syntax errors
• Verify bot has necessary permissions
• Ensure correct exports/imports
• Use camelCase file naming convention

🔐 Admin commands not working

• Verify bot has correct permissions
• Check guild_id in config.toml

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a new branch
3. Make your changes
4. Submit a pull request

---

📄 License

Football Clubs Dex © 2023 by FCDex Team