122 lines
3.3 KiB
Markdown
122 lines
3.3 KiB
Markdown
# twitter (v3)
|
|
|
|
a discord.js v14 moderation (+ more) bot
|
|
|
|
---
|
|
|
|
## 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 stuff) |
|
|
|
|
### 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**. you need this 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`).
|
|
|
|
|