mirror of
https://github.com/VCMP-SqMod/SqMod.git
synced 2026-05-10 04:37:18 +02:00
Add D++ library.
This commit is contained in:
Sandu Liviu Catalin
@@ -0,0 +1,112 @@
|
||||
\page attach-file Attaching a file to a message
|
||||
|
||||
Attached files must be locally stored.
|
||||
|
||||
To attach a file to a message, you can upload a local image.
|
||||
|
||||
D++ has this helper function to read a file: `dpp::utility::read_file`.
|
||||
|
||||
An example program:
|
||||
|
||||
@note Because these examples utilizes message content, they require the message content privileged intent.
|
||||
|
||||
~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
int main() {
|
||||
dpp::cluster bot("token", dpp::i_default_intents | dpp::i_message_content);
|
||||
|
||||
bot.on_log(dpp::utility::cout_logger());
|
||||
|
||||
/* Message handler to look for a command called !file */
|
||||
bot.on_message_create([&bot](const dpp::message_create_t &event) {
|
||||
if (event.msg.content == "!file") {
|
||||
// create a message
|
||||
dpp::message msg(event.msg.channel_id, "Hey there, i've got a new file!");
|
||||
|
||||
// attach the file to the message
|
||||
msg.add_file("foobar.txt", dpp::utility::read_file("path_to_your_file.txt"));
|
||||
|
||||
// send the message
|
||||
bot.message_create(msg);
|
||||
}
|
||||
});
|
||||
|
||||
bot.start(dpp::st_wait);
|
||||
return 0;
|
||||
}
|
||||
~~~~~~~~~~
|
||||
|
||||
Attachments via an url aren't possible. But there's a workaround for. You can download the file and then attach it to the message.
|
||||
|
||||
To make requests, D++ also has a helper function: `dpp::cluster::request`.
|
||||
|
||||
The following example program shows how to request a file and attach it to a message.
|
||||
|
||||
~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
int main() {
|
||||
dpp::cluster bot("token", dpp::i_default_intents | dpp::i_message_content);
|
||||
|
||||
bot.on_log(dpp::utility::cout_logger());
|
||||
|
||||
/* Message handler to look for a command called !file */
|
||||
bot.on_message_create([&bot](const dpp::message_create_t &event) {
|
||||
if (event.msg.content == "!file") {
|
||||
// request an image
|
||||
bot.request("https://dpp.dev/DPP-Logo.png", dpp::m_get, [&bot, channel_id = event.msg.channel_id](const dpp::http_request_completion_t & httpRequestCompletion) {
|
||||
|
||||
// create a message
|
||||
dpp::message msg(channel_id, "This is my new attachment:");
|
||||
|
||||
// attach the image on success
|
||||
if (httpRequestCompletion.status == 200) {
|
||||
msg.add_file("logo.png", httpRequestCompletion.body);
|
||||
}
|
||||
|
||||
// send the message
|
||||
bot.message_create(msg);
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
bot.start(dpp::st_wait);
|
||||
return 0;
|
||||
}
|
||||
~~~~~~~~~~
|
||||
|
||||
Here's another example of how to add a local image to an embed.
|
||||
|
||||
Upload the image in the same message as the embed and then reference it in the embed.
|
||||
|
||||
~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
int main() {
|
||||
dpp::cluster bot("token", dpp::i_default_intents | dpp::i_message_content);
|
||||
|
||||
bot.on_log(dpp::utility::cout_logger());
|
||||
|
||||
/* Message handler to look for a command called !file */
|
||||
bot.on_message_create([&bot](const dpp::message_create_t &event) {
|
||||
if (event.msg.content == "!file") {
|
||||
// create a message
|
||||
dpp::message msg(event.msg.channel_id, "");
|
||||
|
||||
// attach the image to the message
|
||||
msg.add_file("image.jpg", dpp::utility::read_file("path_to_your_image.jpg"));
|
||||
|
||||
dpp::embed embed;
|
||||
embed.set_image("attachment://image.jpg"); // reference to the attached file
|
||||
msg.add_embed(embed);
|
||||
|
||||
// send the message
|
||||
bot.message_create(msg);
|
||||
}
|
||||
});
|
||||
|
||||
bot.start(dpp::st_wait);
|
||||
return 0;
|
||||
}
|
||||
~~~~~~~~~~
|
||||
@@ -0,0 +1,56 @@
|
||||
\page embed-message Sending Embeds
|
||||
|
||||
You might have seen these special messages, often sent by bots. In this section, we will show how to create an embed.
|
||||
|
||||
@note Because this example utilizes message content, it requires the message content privileged intent.
|
||||
|
||||
~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
int main() {
|
||||
/* Setup the bot */
|
||||
dpp::cluster bot("token", dpp::i_default_intents | dpp::i_message_content);
|
||||
|
||||
/* Message handler to look for a command called !embed */
|
||||
bot.on_message_create([&bot](const dpp::message_create_t & event) {
|
||||
if (event.msg.content == "!embed") {
|
||||
|
||||
/* create the embed */
|
||||
dpp::embed embed = dpp::embed().
|
||||
set_color(dpp::colors::sti_blue).
|
||||
set_title("Some name").
|
||||
set_url("https://dpp.dev/").
|
||||
set_author("Some name", "https://dpp.dev/", "https://dpp.dev/DPP-Logo.png").
|
||||
set_description("Some description here").
|
||||
set_thumbnail("https://dpp.dev/DPP-Logo.png").
|
||||
add_field(
|
||||
"Regular field title",
|
||||
"Some value here"
|
||||
).
|
||||
add_field(
|
||||
"Inline field title",
|
||||
"Some value here",
|
||||
true
|
||||
).
|
||||
add_field(
|
||||
"Inline field title",
|
||||
"Some value here",
|
||||
true
|
||||
).
|
||||
set_image("https://dpp.dev/DPP-Logo.png").
|
||||
set_footer(dpp::embed_footer().set_text("Some footer text here").set_icon("https://dpp.dev/DPP-Logo.png")).
|
||||
set_timestamp(time(0));
|
||||
|
||||
/* reply with the created embed */
|
||||
bot.message_create(dpp::message(event.msg.channel_id, embed).set_reference(event.msg.id));
|
||||
}
|
||||
});
|
||||
|
||||
bot.start(dpp::st_wait);
|
||||
return 0;
|
||||
}
|
||||
~~~~~~~~~~
|
||||
|
||||
The code will send the following message.
|
||||
|
||||
\image html embed.png
|
||||
@@ -0,0 +1,244 @@
|
||||
\page firstbot Creating Your First Bot
|
||||
|
||||
In this example we will create a C++ version of the [discord.js](https://discord.js.org/#/) example program.
|
||||
|
||||
The two programs can be seen side by side below:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>D++</th>
|
||||
<th>Discord.js</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
|
||||
~~~~~~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
const std::string BOT_TOKEN = "add your token here";
|
||||
|
||||
int main() {
|
||||
dpp::cluster bot(BOT_TOKEN);
|
||||
|
||||
bot.on_log(dpp::utility::cout_logger());
|
||||
|
||||
bot.on_slashcommand([](const dpp::slashcommand_t& event) {
|
||||
if (event.command.get_command_name() == "ping") {
|
||||
event.reply("Pong!");
|
||||
}
|
||||
});
|
||||
|
||||
bot.on_ready([&bot](const dpp::ready_t& event) {
|
||||
if (dpp::run_once<struct register_bot_commands>()) {
|
||||
bot.global_command_create(
|
||||
dpp::slashcommand("ping", "Ping pong!", bot.me.id)
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
bot.start(dpp::st_wait);
|
||||
}
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
|
||||
~~~~~~~~~~~~~~~{.cpp}
|
||||
let Discord = require('discord.js');
|
||||
|
||||
|
||||
let BOT_TOKEN = 'add your token here';
|
||||
|
||||
|
||||
let bot = new Discord.Client({ intents: [] });
|
||||
|
||||
|
||||
bot.on('interactionCreate', (interaction) => {
|
||||
if (interaction.isCommand() && interaction.commandName === 'ping') {
|
||||
interaction.reply({content: 'Pong!'});
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
bot.once('ready', async () => {
|
||||
await client.commands.create({
|
||||
name: 'ping',
|
||||
description: "Ping pong!"
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
bot.login(BOT_TOKEN);
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
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>`!
|
||||
|
||||
~~~~~~~~~~~~~~{.cpp}
|
||||
#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!
|
||||
|
||||
~~~~~~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
const std::string BOT_TOKEN = "add your token here";
|
||||
|
||||
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).
|
||||
|
||||
~~~~~~~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
const std::string BOT_TOKEN = "add your token here";
|
||||
|
||||
int main() {
|
||||
dpp::cluster bot(BOT_TOKEN);
|
||||
|
||||
bot.on_ready([&bot](const dpp::ready_t& event) {
|
||||
if (dpp::run_once<struct register_bot_commands>()) {
|
||||
bot.global_command_create(dpp::slashcommand("ping", "Ping pong!", bot.me.id));
|
||||
}
|
||||
});
|
||||
}
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
### 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.js `interactionCreate` event. Lets add this to the program before the `on_ready` event:
|
||||
|
||||
~~~~~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
const std::string BOT_TOKEN = "add your token here";
|
||||
|
||||
int main() {
|
||||
dpp::cluster bot(BOT_TOKEN);
|
||||
|
||||
bot.on_slashcommand([](const dpp::slashcommand_t& event) {
|
||||
});
|
||||
|
||||
bot.on_ready([&bot](const dpp::ready_t& event) {
|
||||
if (dpp::run_once<struct register_bot_commands>()) {
|
||||
bot.global_command_create(dpp::slashcommand("ping", "Ping pong!", bot.me.id));
|
||||
}
|
||||
});
|
||||
}
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
### 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 with `Pong!`:
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
const std::string BOT_TOKEN = "add your token here";
|
||||
|
||||
int main() {
|
||||
dpp::cluster bot(BOT_TOKEN);
|
||||
|
||||
bot.on_slashcommand([](const dpp::slashcommand_t& event) {
|
||||
if (event.command.get_command_name() == "ping") {
|
||||
event.reply("Pong!");
|
||||
}
|
||||
});
|
||||
|
||||
bot.on_ready([&bot](const dpp::ready_t& event) {
|
||||
if (dpp::run_once<struct register_bot_commands>()) {
|
||||
bot.global_command_create(dpp::slashcommand("ping", "Ping pong!", bot.me.id));
|
||||
}
|
||||
});
|
||||
|
||||
}
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Let's break down the code in the `on_slashcommand` event so that we can discuss what it is doing:
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
|
||||
bot.on_slashcommand([](const dpp::slashcommand_t& event) {
|
||||
if (event.command.get_command_name() == "ping") {
|
||||
event.reply("Pong!");
|
||||
}
|
||||
});
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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 the `event.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 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, `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.
|
||||
|
||||
The parameter which we set to false indicates if the function should return once all shards are created. Passing `false` here tells the program you do not need to do anything once `bot.start` is called.
|
||||
|
||||
~~~~~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
const std::string BOT_TOKEN = "add your token here";
|
||||
|
||||
int main() {
|
||||
dpp::cluster bot(BOT_TOKEN);
|
||||
|
||||
bot.on_log(dpp::utility::cout_logger());
|
||||
|
||||
bot.on_slashcommand([](const dpp::slashcommand_t& event) {
|
||||
if (event.command.get_command_name() == "ping") {
|
||||
event.reply("Pong!");
|
||||
}
|
||||
});
|
||||
|
||||
bot.on_ready([&bot](const dpp::ready_t& event) {
|
||||
if (dpp::run_once<struct register_bot_commands>()) {
|
||||
bot.global_command_create(dpp::slashcommand("ping", "Ping pong!", bot.me.id));
|
||||
}
|
||||
});
|
||||
|
||||
bot.start(dpp::st_wait);
|
||||
}
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
### 7. Compile and run your bot
|
||||
|
||||
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`.
|
||||
|
||||
### 8. Inviting your bot to your server
|
||||
|
||||
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:
|
||||
|
||||
`https://discord.com/oauth2/authorize?client_id=YOUR-BOTS-ID-HERE&scope=bot+applications.commands&permissions=BOT-PERMISSIONS-HERE`
|
||||
|
||||
Replace `YOUR-BOTS-ID-HERE` with your bot's user ID, and `BOT-PERMISSIONS-HERE` with the permissions your bot requires.
|
||||
|
||||
**Congratulations** - you now have a working bot written using the D++ library!
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
\page webhooks Webhooks
|
||||
|
||||
Webhooks are a simple way to post messages from other apps and websites into Discord. They allow getting automated messages and data updates sent to a text channel in your server. [Read more](https://support.discord.com/hc/en-us/articles/228383668) in this article about Webhooks.
|
||||
|
||||
The following code shows how to send messages in a channel using a webhook.
|
||||
|
||||
~~~~~~~~~~{.cpp}
|
||||
#include <dpp/dpp.h>
|
||||
|
||||
int main()
|
||||
{
|
||||
dpp::cluster bot(""); // normally, you put your bot token in here. But to just run a webhook its not required
|
||||
|
||||
bot.on_log(dpp::utility::cout_logger());
|
||||
|
||||
/* construct a webhook object using the URL you got from Discord */
|
||||
dpp::webhook wh("https://discord.com/api/webhooks/833047646548133537/ntCHEYYIoHSLy_GOxPx6pmM0sUoLbP101ct-WI6F-S4beAV2vaIcl_Id5loAMyQwxqhE");
|
||||
|
||||
/* send a message with this webhook */
|
||||
bot.execute_webhook_sync(wh, dpp::message("Have a great time here :smile:"));
|
||||
|
||||
return 0;
|
||||
}
|
||||
~~~~~~~~~~
|
||||
|
||||
The above is just a very simple example. You can also send embed messages. All you have to do is to add an embed to the message you want to send. If you want to, you can also send it into a thread.
|
||||
Reference in New Issue
Block a user