diff --git a/advanced-reference.js b/advanced-reference.js index 1bba746da9f..49598a23c94 100644 --- a/advanced-reference.js +++ b/advanced-reference.js @@ -3,8 +3,8 @@ var advanced_reference = [ "Clusters, Shards, and Guilds", "clusters-shards-guilds.html", null ], [ "Thread Model", "thread-model.html", null ], [ "Voice Model", "voice-model.html", [ - [ "High Level Summary", "voice-model.html#autotoc_md84", null ], - [ "Flow Diagram", "voice-model.html#autotoc_md85", null ] + [ "High Level Summary", "voice-model.html#autotoc_md87", null ], + [ "Flow Diagram", "voice-model.html#autotoc_md88", null ] ] ], [ "Coding Style Standards", "coding-standards.html", null ], [ "Documentation Style Standards", "docs-standards.html", null ], diff --git a/build-a-bot-xcode.html b/build-a-bot-xcode.html index e08e029145d..8a7456e8b4d 100644 --- a/build-a-bot-xcode.html +++ b/build-a-bot-xcode.html @@ -120,7 +120,7 @@ -
Open up CLion and open the folder for your bot. You may notice that CLion will start doing the whole CMake process and it will create a folder called cmake-build-debug
, this is normal so don't be alarmed! It is just CLion registering all the CMake stuff so it can build and give you auto-suggestions.
Now, you can open your main.cpp
file. If you have code there, then you're one step ahead! If not, copy and paste the following example program in the main.cpp
and set your bot token (see Creating a Bot Token). Here's how your main.cpp
file should look:
To create a basic bot using Visual Studio 2019 or Visual Studio 2022, follow the steps below to create a working skeleton project you can build upon.
If you prefer a video tutorial, you can watch the video below! Otherwise, scroll past and keep reading!
--
Before continuing, you will need to install cmake
on your system. To be sure that cmake
is installed, you can type the following command:
If your CMake version is not as shown above then don't worry! You can still follow along, even if you're ahead or behind!
-In an empty directory, create the following files and directories:
You'll need to modify the CMakeLists.txt
to tell CMake what it's looking for, and other information.
Here is an example CMake configuration, you can adapt it according to your needs:
@@ -156,7 +156,7 @@Now that we have our all our cmake stuff setup and we've got our code in place, we can initalise CMake. You'll want to go inside the build/
directory and do cmake ..
.
Once that's completed, you'll want to head back to your up-most folder (where all the folders are for your bot) and run cmake --build build/ -j4
(replace -j4 with however many threads you want to use). This will start compiling your bot and creating the executable.
sudo
, along with make install
. You will need sudo
installed if you are not the root user.Since the project uses CMake
, you'll need to install it! If you don't have it, you can do the following:
If you wish to use voice support, you'll need to install opus:
Replace the number after -j
with a number suitable for your setup, usually the same as the number of cores on your machine. cmake
will fetch any dependencies that are required for you and ensure they are compiled alongside the library.
If you want to install the library, its dependencies and header files to a different directory, specify this directory when running cmake
:
Then once the build is complete, run sudo make install
to install to the location you specified.
Once installed, you can make use of the library in standalone programs simply by including it and linking to it:
kill 1
in the shell. This is not guaranteed to work, and you might need to try it a few times. If it still does not work, then we recommend you obtain some affordable non-free hosting instead.Replace the number after -j
with a number suitable for your setup, usually the same as the number of cores on your machine. cmake
will fetch any dependencies that are required for you and ensure they are compiled alongside the library.
If you want to install the library, its dependencies, and header files to a different directory, specify this directory when running cmake
:
Then once the build is complete, run make install
to install to the location you specified.
Once installed to the /usr/local
directory, you can make use of the library in standalone programs simply by including it and linking to it:
Before compiling, you will need to install meson
on your system. To be sure that meson
is installed, you can type the following command:
First, you'll need to go ahead and create an empty directory, we'll call it meson-project
.
Then, run this command:
Add the following line after the project()
line in your meson.build
file.
Meson automatically generates a cpp for your project. And a test suite.
-To build a Meson project, run the following:
doas
, along with make install
.Since the project uses CMake
, you'll need to install it! If you don't have it, you can do the following:
If you wish to use voice support, you'll need to do the following:
Replace the number after -j
with a number suitable for your setup, usually the same as the number of cores on your machine. cmake
will fetch any dependencies that are required for you and ensure they are compiled alongside the library.
If you want to install the library, its dependencies and header files to a different directory, specify this directory when running cmake
:
Then once the build is complete, run make install
to install to the location you specified.
Once installed to the /usr/local
directory, you can make use of the library in CMake, without linking to a folder! You can't use this with clang++
, nor g++
, as OpenBSD seems to be broken on this end, so your only option from here is to use CMake. This isn't a bad thing, as we recommend people to use CMake anyways!
Have fun!
diff --git a/buildosx.html b/buildosx.html index 35421075e14..88184242fab 100644 --- a/buildosx.html +++ b/buildosx.html @@ -101,34 +101,34 @@Before compiling make sure you have all the tools installed.
brew install cmake
.For voice support, additional dependency is required:
Replace the number after -j
with a number suitable for your setup, usually the same as the number of cores on your machine. cmake
will fetch any dependencies that are required for you and ensure they are compiled alongside the library.
If you want to install the library, its dependencies, and header files to a different directory, specify this directory when running cmake
:
Then once the build is complete, run sudo make install
to install to the location you specified.
Once installed, you can make use of the library in standalone programs simply by including it and linking to it:
To build on Windows follow these steps exactly. The build process depends on specific libraries being installed on your system in specific locations.
-CMakeLists.txt
, ensure that you have installed the C++ development portions of Visual Studio (not just web development portions) with at least the default options.After compilation you can directly reference the compiled project in your own CMakeLists.txt
as a library or use the lib/dll/headers
as you wish. Note that openssl
and zlib
will also be an indirect dependency of your program (as DLL
files) and should be copied alongside dpp.dll
.
Have fun!
diff --git a/checking-member-permissions.html b/checking-member-permissions.html index cfd6de0b3b6..c84e55f7bab 100644 --- a/checking-member-permissions.html +++ b/checking-member-permissions.html @@ -114,9 +114,9 @@Discord's intended way to manage permissions for commands is through default member permissions. You set them using dpp::slashcommand::set_default_permissions when creating or updating a command to set the default permissions a user must have to use it. However, server administrators can then overwrite these permissions by their own restrictions.
The corresponding code to create a command with default permissions would look something like this:
@@ -133,7 +133,7 @@If you want to check permissions on your own, the easiest way to check if a member has certain permissions in interaction events is by using the dpp::interaction::get_resolved_permission function. The resolved list contains associated structures for the command and does not use the cache or require any extra API calls. Note that the permissions in the resolved set are pre-calculated by Discord and taking into account channel overwrites, roles and admin privileges. So no need to loop through roles or stuff like that.
Let's imagine the following scenario:
@@ -151,7 +151,7 @@The resolved set also contains the permissions of members from command parameters.
For example, let's say you want to prohibit people from banning server admins with your ban command.
@@ -168,7 +168,7 @@You also might want to check if the bot itself has the ban permission before processing the command further. You can access the bot's permissions in the dpp::interaction::app_permissions field.
bool dpp::discord_voice_client::execute_pending_upgrade_downgrade | +( | +) | ++ |
Execute pending protocol upgrade/downgrade to/from dave.
+void dpp::discord_voice_client::process_mls_group_rosters | +( | +const std::map< uint64_t, std::vector< uint8_t > > & | +rmap | ) | ++ |
Process roster map from commit/welcome.
+rmap | Roster map |
void dpp::discord_voice_client::ready_for_transition | +( | +const std::string & | +data | ) | ++ |
Notify gateway ready for a DAVE transition.
+Fires Voice Ready event when appropriate.
+https://daveprotocol.com/#commit-handling
+data | Websocket frame data |
void dpp::discord_voice_client::recover_from_invalid_commit_welcome | +( | +) | ++ |
Reset dave session, send voice_client_dave_mls_invalid_commit_welcome payload with current transition Id and our new key package to gateway.
+https://daveprotocol.com/#recovery-from-invalid-commit-or-welcome
+ +void dpp::discord_voice_client::reinit_dave_mls_group | +( | +) | ++ |
Reset dave session and prepare initial session group.
+With coroutines, it becomes a lot easier to do several asynchronous requests for one task. As an example an "addemoji" command taking a file and a name as a parameter. This means downloading the emoji, submitting it to Discord, and finally replying, with some error handling along the way. Normally we would have to use callbacks and some sort of object keeping track of our state, but with coroutines, the function can simply pause and be resumed when we receive the response to our request :
@@ -189,7 +189,7 @@Earlier we mentioned two other types of coroutines provided by dpp: dpp::coroutine and dpp::task. They both take their return type as a template parameter, which may be void. Both dpp::job and dpp::task start on the constructor for asynchronous execution, however only the latter can be co_await
-ed, this allows you to retrieve its return value. If a dpp::task is destroyed before it ends, it is cancelled and will stop when it is resumed from the next co_await
. dpp::coroutine also has a return value and can be co_await
-ed, however it only starts when co_await
-ing, meaning it is executed synchronously.
Many times people will ask: "How do I make a command like 'eval' in C++?". For the uninitiated, an eval
command is a command often found in interpreted languages such as JavaScript and Python, which allows the developer to pass in raw interpreter statements which are then executed within the context of the running program, without any sandboxing. Eval commands are plain evil, if not properly coded in.
Needless to say, this is very dangerous. If you are asking how to do this, and want to put this into your bot, we trust that you have a very good reason to do so and have considered alternatives before resorting to this. The code below is for educational purposes only and makes several assumptions:
@@ -114,13 +114,13 @@To create this program you must create two files, eval.h
and eval.cpp
. The header file lists forward declarations of functions that you will be able to use directly within your eval
code. As well as this the entirety of D++ will be available to the eval command via the local variable bot
, and the entire on_message_create
event variable via a local variable called event
.
The evaluated code will run within its own thread, so can execute for as long as it needs (but use common sense, don't go spawning a tight while
loop that runs forever, you'll lock a thread at 100% CPU that won't ever end!).
This code operates by outputting your provided code to be evaluated into a simple boilerplate program which can be compiled to a shared object library (.so
) file. This .so
file is then compiled with g++
, using the -shared
and -fPIC
flags. If the program can be successfully compiled, it is then loaded using dlopen()
, and the symbol so_exec()
searched for within it, and called. This so_exec()
function will contain the body of the code given to the eval command. Once this has been called and it has returned, the dlclose()
function is called to unload the library, and finally any temporary files (such as the .so
file and its corresponding .cpp
file) are cleaned up. Docker is definitely recommended if you code on Windows/macOS, because Docker desktop still uses a Linux VM, so your code can easily use the .so
file and your code runs the same on your VPS (if it also uses Linux distro).
Remember that eval.h
contains forward-declarations of any functions you want to expose to the eval command. It is included both by the bot itself, and by any shared object files compiled for evaluation.
This is the main body of the example program.
To compile this program you must link against libdl
. It is also critically important to include the -rdynamic
flag. For example:
Before you start coding, you need to create and register your bot in the Discord developer portal. You can then add this bot to your Discord server.
-To create a new application, take the steps as follows:
Once you've created your bot in the discord developer portal, you may wonder:
@@ -142,7 +142,7 @@
- Copy and paste the resulting URL in your browser. Choose a server to invite the bot to, and click "Authorize".
-
- Note
- For bots with elevated permissions, Discord enforces two-factor authentication on the bot owner's account when added to servers that have server-wide 2FA enabled.
+
Troubleshooting
- Stuck? You can find us on the official discord server - ask away! We don't bite!
diff --git a/editing-channels-and-messages.html b/editing-channels-and-messages.html index d0a0d57acef..76be2e68f62 100644 --- a/editing-channels-and-messages.html +++ b/editing-channels-and-messages.html @@ -103,7 +103,7 @@Sometimes we need to update an object, such as a message (whether it's plain text or an embed) or a channel. At first, it might seem confusing, but it's actually really simple! You need an object with all the properties being identical to the existing one. Say you're editing a message. You need to have an object with its ID the same as the one in Discord. Then you replace what you need, such as its content.
-
- Note
- This example uses callback functions and embeds. To see more information about them, visit Using Callback Functions and Sending Embeds.
+
Editing messages
Here we send a message and edit it after. To do so, we first reply to the command
msg-send
with some text, "This is a message" in our case. As described above, on the next step the message object is taken and the text is replaced with whatever the user desires.#include <dpp/dpp.h>@@ -176,7 +176,7 @@
-![]()
+
Editing channels
Now we'll want to edit an existing channel - its name in this case. This works similarly to how messages are edited.
#include <dpp/dpp.h>@@ -233,7 +233,7 @@
-![]()
+
Editing embeds
Now let's send an embed and edit it. If a message has one
content
field, it can have a fewembed
fields, up to 10 to be precise. So we first get the embed we want and edit and change its description.#include <dpp/dpp.h>diff --git a/firstbot.html b/firstbot.html index 0f00e50fd8f..c9b8c19a8db 100644 --- a/firstbot.html +++ b/firstbot.html @@ -169,14 +169,14 @@Let's break this program down step by step:
-+
1. Start with an empty C++ program
Make sure to include the header file for the D++ library with the instruction
#include <dpp/dpp.h>
!#include <dpp/dpp.h>int main() {}-+
2. Create an instance of dpp::cluster
To make use of the library you must create a dpp::cluster object. This object is the main object in your program like the
Discord.Client
object in Discord.js.You can instantiate this class as shown below. Remember to put your bot token in the constant!
@@ -187,7 +187,7 @@
int main() {dpp::cluster bot(BOT_TOKEN);}-+
3. Attach to an event
To have a bot that does something, you should attach to some events. Let's start by attaching to the
on_ready
event (dpp::cluster::on_ready) which will notify your program when the bot is connected. In this event, we will register a slash command called 'ping'. Note that we must wrap our registration of the command in a template called dpp::run_once which prevents it from being re-run every time your bot does a full reconnection (e.g. if the connection fails).+
4. Attach to another event to receive slash commands
If you want to handle a slash command, you should also attach your program to the
on_slashcommand
event (dpp::cluster::on_slashcommand) which is basically the same as the Discord.jsinteractionCreate
event. Lets add this to the program before theon_ready
event:+
5. Add some content to the events
Attaching to an event is a good start, but to make a bot you should actually put some program code into the interaction event. We will add some code to the
on_slashcommand
to look for our slash command '/ping' and reply withPong!
:This code is simply comparing the command name
event.command.get_command_name()
(dpp::interaction::get_command_name) against the value in a constant string value"ping"
. If they match, then theevent.reply
method is called.The
-event.reply
function (dpp::slashcommand_t::reply) replies to a slash command with a message. There are many ways to call this function to send embed messages, upload files, and more, but for this simple demonstration we will just send some message text.+
6. Add code to start the bot!
To make the bot start, we must call the dpp::cluster::start method, e.g. in our program by using
bot.start(dpp::st_wait)
.We also add a line to tell the library to output all its log information to the console,
@@ -280,10 +280,10 @@bot.on_log(dpp::utility::cout_logger());
- if you wanted to do something more advanced, you can replace this parameter with a lambda just like all other events.
bot.start(dpp::st_wait);}-
Compile your bot using g++ -std=c++17 -o bot bot.cpp -ldpp
(if your .cpp file is called bot.cpp
) and run it with ./bot
.
When you invite your bot, you must use the applications.commands
and bots
scopes to ensure your bot can create guild slash commands. For example:
D++ is a lightweight and simple library for Discord written in modern C++. It is designed to cover as much of the API specification as possible and to have a incredibly small memory footprint, even when caching large amounts of data.
It is created by the developer of TriviaBot and contributed to by a dedicated team of developers.
This project is in stable development and accepting PRs and feature requests — Don't be a stranger! If you want to contribute, just get in touch via GitHub or our official Discord server!
The following downloads are for the most recent version:
You can find further releases in other architectures and formats or the source code on the GitHub Repository. For a realtime JSON format list of all download links, click here
-The library runs ideally on Linux.
-The library is well-functional and stable on Mac OS X, FreeBSD, and OpenBSD too!
-For running your bot on a Raspberry Pi, we offer a prebuilt .deb package for ARM64, ARM6, and ARM7 so that you do not have to wait for it to compile.
-Windows is well-supported with ready-made compiled DLL and LIB files, please check out our Windows Bot Template repository. The Windows Bot repository can be cloned and integrated immediately into any Visual Studio 2019 and 2022 project in a matter of minutes.
-The library should work fine on other operating systems as well, and if you run a D++ bot on something not listed here, please let us know!
-g++
command is not advised in any real project, and the example above should be used only as a test. From here, you should learn to create a bot in D++ by moving on to Building a Discord Bot Using CMake (UNIX) or if you have not yet created a token for your bot, Creating a Bot Token - If you are having trouble setting up CMake, you can try our template cmake bot project.To unlink and uninstall dpp, run
Head on over to File > Settings
(Ctrl+Alt+S), then navigate to Build, Execution, Deployment > Toolchains
.
From there, you need to drag it to the top (if it didn't already add at the top) to ensure it's the default toolchain.
-To use vcpkg in CLion, add the following line to your CMake options in the settings (Located under Settings > Build, Execution, Deployment > CMake
)
For example, if your root folder is C:/vcpkg/
then the CMake option will be:
Open your main.cpp
file and then copy and paste the following example program in. Then, set your bot token (see Creating a Bot Token). Here's how your main.cpp
file should look:
If everything went well, you should now have a functioning bot! If not, feel free to ask us on the D++ discord server.
-If you see a message like Detecting C compiler ABI info - failed
or something along the lines of "cl.exe" is not able to compile a simple test program
, then try to reinstall Windows Build Tools
along with the Windows SDK
from the Visual Studio Installer.
You can compile this example using the following command
You can use liboggz
to stream an Ogg Opus file to discord voice channel. liboggz
provides higher level abstraction and useful APIs. Some features liboggz
provides include: seeking and timestamp interpretation. Read more on the documentation.
At present our roadmap is:
-Short term (6 months):: Stabilise coroutine support and release it as stable a feature
-Long term: Continue development of the library to implement Discord new features as they add them. Discord does not share their internal roadmap with library developers, so we are informed of these new features shortly before they become public given enough time to implement them. This is our permanent ongoing goal.
+Get transition ID for process_welcome
+Get transition ID for process_commit and process_welcome
If you are adding functionality to D++, make sure to run unit tests. This makes sure that the changes do not break anything. All pull requests must pass all unit tests before merging.
Before running test cases, create a test server for your test bot. You should:
diff --git a/voice-model.html b/voice-model.html index 9d41e197c8d..41e03da827c 100644 --- a/voice-model.html +++ b/voice-model.html @@ -101,7 +101,7 @@Discord's audio system consists of several layers and inter-related systems as shown in the flow chart below.
At the top level, connecting to a voice server requires the library to request the details of a voice server from Discord via the websocket for the shard where the server is located. Performing this request will make Discord reply with a websocket URI and an ephemeral token (not the bot token) which are used to establish an initial connection to this secondary websocket. Every connection to a voice channel creates a separate secondary websocket.
@@ -116,7 +116,7 @@After reading all this, go get a coffee or something, you deserve it! ☕
-Where is my bot now, I can't see him on my server?! @@ -48,7 +48,7 @@