Marcel the Bot
What is it?
Marcel is a plugin-based Discord bot. It uses discord.py to interact with Discord.
It comes with a good set a plugins for many uses, but you can add/remove any plugin if you want.
You can also make your own plugin, see Make your own plugin
Installation
This program requires Python 3.6+, discord.py with voice and youtube_dl for the media player.
Follow these instructions to install discord.py.
Voice functionnality requires ffmpeg
or avconv
to be installed.
You can install the bot through PyPI
python3 -m pip install --user --upgrade marcel-the-bot
or using the setup.py
python3 setup.py install
You can automatically install/uninstall the bot as a SystemD service on Linux using the given script
sudo ./install_linux_daemon.sh
#sudo ./uninstall_linux_daemon.sh
You can also run the bot manually with python3 -m marcel -c config_folder -p plugins_folder
.
Note: youtube_dl gets updated often, you will regularly need to update it in order for the related voice functionnalities to keep working: python3 -m pip install --user --upgrade youtube-dl
or su -c "python3 -m pip install --user --upgrade youtube-dl" marcel
if you installed the Linux service.
Configuration
Here's a configuration template (which you can find in the templates
folder):
{
"token": "your_bot_token_goes_here",
"owners": [],
"logging": {
"level": "warning"
},
"voice_client": {
"idle_limit": 1800,
"player_queue_limit": 20,
"duration_limit": 1800
},
"server_defaults": {
"prefix": "!!",
"clean_commands": false,
"delete_after": 10.0,
"volume": 1.0,
"volume_limit": 1.25
}
}
-
token
is your bot's token (https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token) -
owners
is a list of user IDs that are bot owners, these users will have all privileges over the bot -
logging
defines how the bot should log information-
level
is the logging level, by default it is set towarning
-
enabled
is optional, if set totrue
the bot will also log to a file (it defaults tocfg_folder/marcel-the-bot.log
) -
file
is optional, if set the bot will log to this file instead
-
-
voice_client
defines the voice client's behavior-
idle_limit
is the idle time (in seconds) before the voice client is automatically disconnected -
player_queue_limit
is the maximum amount of medias that the player queue will accept -
duration_limit
is the maximum duration of a media (in seconds)
-
-
server_defaults
are the default settings for the Discord servers (each plugin can store its own settings too)-
prefix
is the bot's prefix (by default!!
) -
clean_commands
will enable the command cleanup for commands that support it -
delete_after
is the time in seconds before temporary messages are deleted (must be handled by the plugin) -
volume
is the player's volume -
volume_limit
is the player's maximum volume
-
The server settings can be changed from Discord using the commands in the settings.py
plugin.
Make your own plugin
The bot will load all the files with a .py
extension in its plugins folder (can be set using -p
or --plugins
)
Here's a plugin template (which you can find in the templates
folder):
from marcel import Marcel
from marcel.util import embed_message
import discord
import logging
class MarcelPlugin:
plugin_name = "Template"
plugin_description = "Template plugin"
plugin_author = "https://github.com/hoot-w00t"
# The help message will be formatted to be displayed when running
# the "help" command
plugin_help = """`{prefix}ping` pongs! :clap:"""
# List of tuples in the form (command, target function, ...)
# There can be attributes after the target function:
# "clean_command" tells the bot to delete the command message
# Functions are given the following arguments:
# message: discord.Message()
# args: list() of the interpreted command arguments
# **kwargs: dict() containing additionnal information like
# the guild settings named "settings" (dict)
# the guild media player named "mediaplayer" (MarcelMediaPlayer)
bot_commands = [
("ping", "ping_cmd")
]
def __init__(self, marcel: Marcel):
# This is to give access to the bot at anytime, anywhere in the plugin
self.marcel = marcel
# You can log anything using the logging module
logging.debug("Hello world!")
def on_unload(self):
# This function will be called by the bot when unloading the plugin
# You can use it to stop background tasks for example
pass
async def ping_cmd(self, message: discord.Message, args: list, **kwargs):
"""Ping command"""
await message.channel.send(
message.author.mention,
embed=embed_message(
"Pong!",
discord.Color.orange(),
message="in {}ms".format(
int(self.marcel.bot.latency * 1000)
)
)
)
Plugin configuration
Rich Presence
The Rich Presence plugin reads its configuration from rich_presence.json
at the root of your bot's configuration folder:
[
{
"text": "Science is Fun",
"type": "listening",
"status": "dnd",
"duration": 15
},
{
"text": "version {version}",
"status": "idle",
"duration": 30
},
{
"text": "the sunrise.",
"type": "watching",
"duration": 15
}
]
-
text
is the text to be displayed -
type
is the activity type (playing
,watching
,listening
), it itplaying
by default -
status
is the bot's online status (online
,offline
,invisible
,do_not_disturb
,dnd
,idle
), it isonline
by default -
duration
is the duration of this status message (in seconds)
Some variables will be dynamically replaced by their corresponding value when displayed:
-
{version}
will be replaced with the bot's version number (e.g. 3.2.0) -
{plugin_count}
will be replaced with the number of loaded plugins -
{server_count}
will be replaced with the number of servers the bot is in
SoundBox
The SoundBox plugin will read media files from a soundbox
folder at the root of the configuration folder.
It currently accepts the following formats: mp3
, ogg
, webm
and wav
, any of those file types in the soundbox
folder can then be played.
Nicknames
The Nicknames plugin reads its configuration from nicknames.json
at the root of your bot's configuration folder:
{
"nicknames": [
"Marcel-o-tron",
"Herobrine"
],
"greets": [
"Fresh from the oven!",
"It's me, Mar!... nevermind."
]
}
-
nicknames
is a list of the different nickname the bot can choose from -
greets
is a list of phrases the bot will say when changing its nickname