McNiibot: Clicker Heroes Discord Bot

A Discord.js bot designed for the Clicker Heroes Discord server. It provides a wide array of game-specific information, moderation assistance, and automated role assignments based on player progress.

👾 Features

• Extensive Game Information: Over 80 slash commands providing detailed information about Clicker Heroes 1 mechanics, ancients, outsiders, strategies, and more (e.g., /active, /ancients, /as, /firsttrans, /hybrid, /idle, /merc, /outsiders, /rubies, /skills, /timelapse, /trans).
• Utility Commands: Includes /calclist for links to useful calculators, /faq, /glossary, and an /image command with autocomplete for posting catered images.
• Moderation & Auto-Moderation: Features basic moderation tools and robust auto-moderation capabilities, including anti-spam, detection of scam links (e.g., fake Nitro), filtering of racist comments, and restrictions on posting external Discord links by new members.
• Automated Role Assignment: Assigns Discord roles to users based on their in-game progress. Players can DM the bot their .txt save file, which the bot processes to determine the highest hero unlocked and assign a corresponding role.
• Automated Responses: Provides quick answers to common questions and phrases within the community.

⚙️ Setup

1. Install Dependencies

npm install

2. Configure the Bot

Create your environment configuration file:

cp .env.example .env

Then edit the .env file and replace the placeholder values with your actual:

• DISCORD_TOKEN: Your Discord bot token.
• DISCORD_CLIENT_ID: Your bot's client ID.
• DISCORD_GUILD_ID: The ID of the Discord server (guild) where the bot will operate.
• SENTRY_DSN (optional): Your Sentry DSN for error tracking.

If you are developing locally, you may want to use a dedicated test server and its ID for DISCORD_GUILD_ID.

3. Feature Flags

Each moderation feature can be switched off without a code change. Set the flag to false to disable it, true or omit it to leave it on. Any other value stops the bot at startup rather than guessing.

Flag	Feature	Reads message text
RECRUITMENT_FORMAT_ENABLED	Deletes recruitment posts missing the Recruiting: prefix	yes
NITRO_SCAM_MOD_ENABLED	Bans nitro scam posts	yes
INVITE_LINK_MOD_ENABLED	Removes discord.gg links from new members	yes
GOOGLE_PLAY_SPAM_MOD_ENABLED	Removes the Google Play spam message	yes
SLUR_BAN_MOD_ENABLED	Bans new members posting slurs	yes
RAPID_MESSAGE_SPAM_MOD_ENABLED	Bans 6 messages in 8 seconds from new members	no
CROSS_CHANNEL_SPAM_MOD_ENABLED	Bans posting to 4+ channels in 10 seconds	no

The Message Content privileged intent is requested only while at least one text-reading feature is on. Turn all five off and the bot connects without it. The startup log reports which features are disabled and whether the intent was requested.

Activity Audit

User-visible bot actions are appended to daily logs/audit-YYYY-MM-DD.jsonl files. Each line contains a timestamp, a stable event name, and relevant IDs or outcome metadata.

4. Start the Bot

npm start

If the configuration is correct, the bot should appear online in Discord, and its slash commands will be registered/updated for the specified guild.

To type-check without running:

npm run typecheck

🧹 Code Quality

This project uses Biome for consistent code style and quality:

npm run biome

🚢 Deployment

Simply create a new release in GitHub and the bot will be automatically deployed to the server.

Note

How it works: When you create a new Github release, a GitHub Action will merge the main branch into the production branch and Forge will deploy the changes. The deployment is handled by Laravel Forge using the production branch.

Note

Always create releases from the main branch to ensure all tested changes are included in the deployment.

Deploy script used in Forge:

cd /home/forge/mc-niibot

git pull --tags origin $FORGE_SITE_BRANCH

# Ensure logs directory exists
mkdir -p logs

npm install

# Restart the application using PM2 ecosystem config
pm2 reload ecosystem.config.cjs --env production || pm2 start ecosystem.config.cjs --env production

pm2 save

📂 Uploads folder

The uploads folder is used to store the attachments sent by users, such as .txt save files. Make sure this folder is writable by the bot process.

📜 License

This project is licensed under the MIT License.