disco-foxx
v0.1.30
Published
A sly discord bot framework
Downloads
116
Readme
Disco Foxx (A Discord Bot)
In active development, everything subject to change 😬
Requirements
- NodeJS 9.11 or higher
- Typescript 3.6 or higher
- A discord app token
- For voice channel usage an FFmpeg library must be installed
About
This library provides a user and developer friendly bot for discord.js. It can do:
- Message parsing (feature) with options:
- Per user
- Per channel
- On specified % chance
- Parsing functions (features)
- Call and Response -- Reply and React to arbitrary terms from user-defined list
- Multiple calls (terms to look for)
- Multiple responses, choose at random
- Multiple reacts, choose at random
- Granular trigger chance
- Independent chances for reply/react
- Independent chances based on bot mention
- Chance to react multiple times per trigger
- Require all, any, or only calls
- Require bot mention
- Restrict to channels
- Flags for content parsing (preserve whitespace, preserve case, preserve url)
- Call and Response -- Reply and React to arbitrary terms from user-defined list
- Commands using Discordjs-commando
- Sound playback in voice channel from user-defined list
- Post memes from szurubooru
- post random
- post random with specified tags
- PUBG API interaction
- Get last match stats
- Extend and Develop easily
- Public methods to access all discord client events and sequence actions with optional return early condition
- SQLite out of the box, available as Bot property, with default
memory
or easily configuredfile
options - Easily extend the base Bot class and directly access the discord client
- Hooks into Bot internals
- Prioritized event handle
- Events ordered by Bot (Pre), User, Bot (Post)
- Allows developers to write custom bots their users can continue to extend
- All feature functionality as modules/classes
Installation
npm install disco-foxx --save
Usage (User)
An env
object must be provided to the constructor of Bot
. env
must contain a discord token. The minimum valid structure for env
is:
{
"discord": {
"token": "yourToken"
}
}
To start the bot instantiate a new Bot class and pass it the env. Then invoke run()
import { Bot } from 'disco-foxx';
import env from './env.json';
const myBot = new Bot({env});
myBot.run(); // bot is now running
Events
All event listeners are inserted in the order they were created.
foxx-disco will pass through any discord client event using the same event api
myBot.on('message', (message) => {
console.log(`Message content: ${message.content}`);
});
myBot.once('ready', () => {
console.log('Bot is ready');
});
but extends event listener execution to allow an early exit if your listener returns true
. This is helpful if one listener meets a condition you want to act on but prevent any later listeners from acting as well.
// A user sends a message with 'say something important'
// this event is registered first
myBot.on('message', async (message) => {
if(message.content.includes('say something')) {
await message.channel.send('Something said.');
return true; // prevents the second listener from executing -- so the bot doesn't respond twice
}
});
// this event is registered second
myBot.on('message', async (message) => {
if(message.content.includes('something important')) {
await message.channel.send('yes, less important');
}
});
Usage (Developers/Extending The Bot)
Extra functionality, such as persistence (using db
), "immutable" events, and so on can be added by simply extending the Bot
class. Using ES6 syntax:
import { Bot } from 'disco-foxx';
import env from './env.json';
class MyCustomBot extends Bot {
constructor(props) {
super(props);
const {env} = props;
if(env.steam.token === undefined) {
throw new Error('Must define steam token!');
}
console.log('Starting my custom bot');
}
}
const bot = new MyCustomBot({env});
bot.run();
Events
When extending the Bot
class the addEvent
class method can be used to specify further listener types: user
, botPre
, botPost
Bot
listener types allow a developer to insert listeners at the beginning or end of any user-specified (using on
or once
) listeners. This is useful when the developer wants certain actions to only occur if no user listeners returned early, or if the developer wants to ensure their listeners are executed before any user listeners.
const newEvent = {
name: 'bot author response',
type: eventType.BOT_PRE, // will be executed before any user-defined listeners on the same event
func: async (message) => {
if(message.author.id === aBotSnowflake) {
await message.channel.send('I know you!');
return true;
}
}
}
this.addEvent('message', newEvent);
Features
disco-foxx/features
contains classes that can be used to add complex functionality to your bot. They are provided because the author uses them :)
Some feature methods features will return a function
if they are ready to execute a bot behavior, otherwise they return false. This is to help the user to determine if they should return early on the executing listener.
Call And Response (CAR)
CAR functionality is a common feature for most bots:
- A user sends a message to a channel/DM
- The bot detects a word or words in the message
- The bot responds with a message or reacts to the user's message
The CAR feature does this with minimal configuration while also allowing fine-tuning of every aspect of the bot's detection and response behavior.
Usage
import { Bot } from 'disco-foxx';
import { CallAndResponse } from "disco-foxx/features";
import env from './env.json';
const carObjects = {
data: [
{
call: ['major tom'],
response: ['ground control, anyone out there?']
}
]
}
const car = new CallAndResponse(carObjects);
const bot = new Bot({env});
bot.on('message', async (message) => {
const result = car.process(message);
if (typeof result === 'function') { // so we know callAndResponse matched the content and is ready to send a message
await result(message);
return true;
}
});
Refer to the CARData
interface for a full description of how to configure a CAR object
Other feature documentation coming soon
Commands
Most features have a corresponding commando command. To use these you must initialize a CommandBot
instead of Bot
from disco-foxx
. Then the commands may be used as normal with a CommandClient
.
import { CommandBot } from 'disco-foxx';
import { ClipPlayer } from 'disco-foxx/features';
import { SoundCommand } from 'disco-foxx/commands';
import env from './env.json';
const bot = new CommandBot({env})
bot.client.registry
.registerDefaults()
.registerGroups([
['fun', 'A fun Command Group']
]);
const player = new ClipPlayer(sounds, path.join(__dirname, 'sounds'));
const soundCmd = new SoundCommand(player, bot.client);
bot.client.registry.registerCommands([soundCmd]);
bot.run();
Example
See example folder for a kitchen sink reference of how to use this bot
3rd Party API Setup
Szurubooru
Follow the instructions for Authentication
- Include Basic Auth headers to retrieve a user token
- Create an auth token by base64 encoding this value:
userName:userToken
- Instantiate a
Szurubooru
object fromdisco-foxx/features
and provide with valid constructor arguments (endpoints and token). SeeszuruEndpoints
interface.
PUBG
- Register a new app on the pubg dev api site.
- Instantiate a new
Pubg
object fromdisco-foxx/features
. SeepubgEnv
interface.
Developing
From the project directory:
- After cloning run
npm install
- Run
tsc
to compile todist
dir