Oxide.Ext.Discord is an extension made for the OxideMod project which can run the modding community for many games, one of them including a popular survial game rust. This is made to be as easy to use as possible
By default, a discord bot is rated to handle up to 120 events in 60 seconds. Roughly 2 events a second we are allowed to work with. So the library/extension has a built in rate limiter which will handle any issues. There are exceptions to this rate limiting process. For example, if the bot has created requests outside of the libraries control then the library will not know about this and then it will not be able to respond accordingly. This goes the same with restarting the library. Your bots will be able to send 2 requests every 1 second by default. This is editable in the config, but I do not suggest editing it.
By default the library supports both default console and oxide logging. But besides that there are three (four) types of logging.
- Normal : Basic messages a server owner needs to see. Config loading, the bot saying its ready, all that jazz.
- Debug : These are a little more advanced messages, such as specific events starting up, some more debugging, etc.
- Developer : This contains every single log shown, the bot starting, raw events, specific http and websocket events, etc. You should only ever need this if you are submitting a bug report and I request more data.
- Global : You wont see these often. These are simply called outside of a discord clients control. Meaning registering a client, and other things.
- Every single event discord has to offer is fully covered and available. Reconnecting to discord is a big part of this, as the internet is not perfect. I have implemented discords fully functional reconnection and revent system. Where you can reconnect and re-do the events seen over the last x amount of time. This is useful if you want to watch every event, such as message creation, user joining, etc.
- The library also does not follow along with oxide hooks. Instead, we use C#'s built in event system, allowing for complete control of method naming, and everything else you could wish for. We also use EventArguments. Basically, we supply what we want for you to see in your events.
Discord has a way of handling bots with 1000's of servers using a system called sharding. Basically in a nut shell it can split resources between different bot applications, allowing one to handle messages, one to handle channel creation, voice, etc. This library can automatically ish shard. It will use the correct amount of shards if needed, however as of now, it does not have the ability to handle the full capability of sharding. If anyone runs into an issue with sharding please contact me or create an issue
Config and Multi-Bot Support
Instead of using a general one bot on config system. Instead when you create a bot you supply a configuration created via the DiscordConfiguration class. Which allows for custom sharding, token, thresholds, etc. This allows for nearly complete control as a plugin or user of this extension/library. Each plugin is also limited to 5 discord clients, this can be increased via the extension config, but there should not be a reason to increase it.
The library covers nearly every possible error discord can throw at us. From WebSocket errors to HTTP errors. We cover every single one nearly allowing for a completely smooth experience connecting to discord.
Getting your API Key
An API key is used to authenticate requests made to and from Discord.
NOTE: DO NOT SHARE YOUR API KEY/TOKEN. Sharing your token may result in punishments from Discord if the token is used to abuse the API.
Steps to obtain an API Key.
- Visit the official Discord Developers page here. Discord Developer Documenation
- Click "New App".
- Name your app and click create! NOTE: A description isn't required.
- You will now be redirected to your created app, at the point you will need to click "Create a Bot User".
- Under the newly created bot section you will see "Token" below "Username", reveal the token and copy it into your plugin.
- Now it's time to add your new bot to your guild! To add your bot to your guild you must visit this link and replace "botUserID" with the client ID found at the top of your discord app. https://discordapp.com/oauth2/authorize?client_id=botUserID&scope=bot&permissions=8 NOTE: "permissions=8" in the link will provide the bot with administrative permissions so you won't have to give it some.