copilot-swe-agent[bot]andyhqe
e8049008eb
Co-authored-by: yhqe <139268606+yhqe@users.noreply.github.com>
121 lines
3.5 KiB
Markdown
121 lines
3.5 KiB
Markdown
# twitter_v3 — Discord Moderation Bot
|
|
|
|
A Discord.js **v14** bot base using traditional **prefix commands** (no slash commands) and structured **Winston logging**.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- 📨 **Prefix command system** — commands triggered by a configurable prefix (default `!`)
|
|
- 📁 **Auto-loading** — commands and events are loaded automatically from their folders
|
|
- 🔖 **Aliases** — each command can define one or more aliases
|
|
- 📝 **Winston logging** — coloured console output + rolling log files (`logs/combined.log`, `logs/error.log`)
|
|
- 🛡️ **Global error handling** — unhandled rejections and uncaught exceptions are caught and logged
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── index.js # Entry point — creates the client, loads handlers
|
|
├── commands/
|
|
│ ├── help.js # !help — lists commands or shows command detail
|
|
│ └── ping.js # !ping — latency check
|
|
├── events/
|
|
│ ├── ready.js # Fires once when the bot is online
|
|
│ └── messageCreate.js # Parses every message for prefix commands
|
|
├── handlers/
|
|
│ ├── commandHandler.js # Reads src/commands/ and registers commands
|
|
│ └── eventHandler.js # Reads src/events/ and registers Discord events
|
|
└── utils/
|
|
└── logger.js # Winston logger instance
|
|
logs/ # Created automatically at runtime (git-ignored)
|
|
```
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
### 1. Clone & install dependencies
|
|
|
|
```bash
|
|
git clone https://github.com/yhqe/twitter_v3.git
|
|
cd twitter_v3
|
|
npm install
|
|
```
|
|
|
|
### 2. Configure environment variables
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Open `.env` and fill in:
|
|
|
|
| Variable | Required | Description |
|
|
|-------------|----------|------------------------------------------------------|
|
|
| `BOT_TOKEN` | ✅ Yes | Your bot token from the Discord Developer Portal |
|
|
| `PREFIX` | ❌ No | Command prefix (default: `!`) |
|
|
| `GUILD_ID` | ❌ No | Test server ID (handy for dev utilities) |
|
|
|
|
### 3. Enable the Message Content intent
|
|
|
|
Go to your application in the [Discord Developer Portal](https://discord.com/developers/applications), open **Bot → Privileged Gateway Intents**, and enable **Message Content Intent**. This is required for prefix commands.
|
|
|
|
### 4. Start the bot
|
|
|
|
```bash
|
|
# Production
|
|
npm start
|
|
|
|
# Development (auto-restarts on file changes, Node.js 18+)
|
|
npm run dev
|
|
```
|
|
|
|
---
|
|
|
|
## Adding Commands
|
|
|
|
Create a file in `src/commands/`. The handler will load it automatically on next start.
|
|
|
|
```js
|
|
'use strict';
|
|
|
|
module.exports = {
|
|
name: 'example', // Primary command name (also used as the key)
|
|
description: 'An example command.',
|
|
aliases: ['ex'], // Optional aliases
|
|
usage: 'example <text>', // Shown in !help example
|
|
|
|
async execute(client, message, args) {
|
|
await message.reply(`You said: ${args.join(' ')}`);
|
|
},
|
|
};
|
|
```
|
|
|
|
## Adding Events
|
|
|
|
Create a file in `src/events/`. Set `once: true` if it should fire only once (e.g. `ready`).
|
|
|
|
```js
|
|
'use strict';
|
|
|
|
const { Events } = require('discord.js');
|
|
|
|
module.exports = {
|
|
name: Events.GuildMemberAdd,
|
|
|
|
async execute(client, member) {
|
|
console.log(`${member.user.tag} joined ${member.guild.name}`);
|
|
},
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Logging
|
|
|
|
Log files are written to the `logs/` directory (git-ignored). The log level defaults to `info` and can be overridden with the `LOG_LEVEL` environment variable (e.g. `LOG_LEVEL=debug npm start`).
|
|
|