Skip to content

Home

Jump to bottom
FoxWorn3365 edited this page Sep 7, 2024 · 4 revisions

Welcome to the SimpleDiscord official wiki!

Caution

This wiki is updated for the version v0.9.0 of SimpleDiscord!

Getting started with the lib

SimpleDiscord.Client is the Discord Client to interact with the Discord Gateway and the Discord APIs.
It can be created without any arguments or with an argument - the config: if you don't give the config a default one will be used.

Note

Check the config part of the wiki to learn more about SimpleDiscord configuration!

Here an example on initializing a new client:

Client client = new Client(new ClientConfig()
{
    Debug = true,
});

Next: logging in

Config

The config allows you to decide what the lib should - or should'd - do.
The default one is the following:

# Enable the debug mode for debugging purpouse
debug: false
# Enable the system logs: very few and simple logs that register the main actions (HTTP requests, Heartbeat and Heartbeat ACK)
system_logs: true
# If true the bot will require - through the gateway - a list of every member inside every guild you have. It requires GUILD_MEMBERS intent
load_members: false
# If true every received message will be saved (and updated) inside the specific GuildTextChannel object
save_messages: true
# If true when a thread is loaded inside a guild object every member of the thread are loaded inside it's object
fetch_thread_members: true
# Decide the behavior of the command registering system. None does not register anything, CreateAndEdit will edit already-existing roles, CreateAndSkip instead only creates new roles and doesn't touch already-existing ones.
register_commands: None
# If true every registered command (also new ones) will be saved inside the Client object
save_global_registered_commands: true
# If true every registered commands (also new ones) will be saved inside the given Guild object
save_guild_registered_commands: true
# If true as soon as the bot gets ready an HTTP request to retrive every app information about the current app (Bot)
load_app_info: false

The config tho it's not a YAML but it's a class that you can initialize while editing data.
The values here given are the default ones

Tip

The default configuration it's not the more Ram optimized one!
If you want to save resources just disable LoadMembers, SaveMessages, FetchThreadMembers, SaveGlobalRegisteredCommands and SaveGuildRegisteredCommands!

Logging in

You obv need to authenticate yourself to the Discord Gateway.\

Warning

This function won't only log-in you but it would also start the main event loop! So, if you are using a CLI app you should have to freeze the app (await Task.Delay(-1)) or by awaiting the function!

Tip

In the SimpleDiscord.Gateway.Gateway class you can find some pre-registered intents: defaultIntents, privilegedIntents and allIntents: you can use them inside the LoginAsync method!

<awaitable> client.LoginAsync(<token>, <intents>);

Example:

client.LoginAsync("mytoken", Gateway.allIntents);

Next: handling events

Handling events

As SimpleDiscord is an event-driven lib events are one of the most important things here.
For this reason we have made registering -and handling- events really easy.\

Important

Handling events is available only with a class!
So yeah, you'll have to create a class (or just put them inside the bot class if you've created one) in order to be able to register them!

To register every events (inside a class, both static or not) you can use the Client::EventHandler.RegisterEvents() method.
By default the method can accept multiple inputs:

// If you have multiple classes with multiple event methods (STATIC) you can just give the method an `Assembly` class (get it from `Assembly.GetExecutingAssembly()`)
client.EventHandler.RegisterEvents(Assembly.GetExecutingAssembly());

// If you want to register a class with event methods (STATIC) you can just give the function the `Type`
client.EventHandler.RegisterEvents(null, typeof(MyEventClass));

// If you want to register a class with both static and not event methods you can give just the instance of it
MyEventClassButWithAlsoNotStaticMethods cl = new();
caller.EventHandler.RegisterEvents(cl);

To handle events you need both a method and the attribute SocketEvent.
The method must have a void as a return type and an object as first argument.
The method can have zero arguments and can be async!

Tip

Every event has it's own class that will be shared with you.
Every event class it's an extension of BaseGatewayEvent so you can put also this but no one will stop you from putting the expected class for the event like MessageCreate if SocketEvent is MESSAGE_CREATE!

Example:

class MyBeautifulClass
{
    [SocketEvent("MESSAGE_CREATE")]
    public static void OnMessageCreate(MessageCreate ev)
    {
        // This function is STATIC so it will be always registered if you give the MyBeautifulClass to the EventHandler
        // code...
    }

    [SocketEvent("MESSAGE_UPDATE")]
    public static void OnMessageUpdate(MessageUpdate ev)
    {
        // This function is NOT STATIC so it won't be always registered if you give the MyBeautifulClass to the EventHandler
        // code...
    }
}

Next: Using components

Using components

SimpleDiscord handles every discord object as a "component".
So there will be a component for the Guilds, Channels, Threads, Roles, etc.
The hierarchy of the components it's the following

|
+- Guild
|   |
|   +- Channel (GuildChannel, GuildTextChannel, GuildVoiceChannel)
|   |   |
|   |   +- Message**
|   |   |
|   |   +- Thread (GuildThreadChannel)**
|   |
|   +- Thread (GuildThreadChannel)
|   |   |
|   |   +- Thread Member
|   |
|   +- Role [1]
|   |
|   +- Member* 
|   |
|   +- Member Presence
|   |
|   +- Command*
|   |
|   +- Emoji [1]
|
+- User

So, if an element is under another one that means that IT HAS THE RELATED INSTANCE INSIDE OF IT!
Let's take Message as an example: you can do Message::Channel::Guild to get the guild - the same from Member::Guild!

* - Can be nullable by settings
** - Only if Channel is GuildTextChannel
[1] - Don't have a Guild reference inside of them as they are not a standalone feature and every event that handle them has the Guild in the args!

Component-specific features

Every feature is handled with a function from the more-related component.
For example, to react to a message with the emoji 👍 you have to do that from the Message component (Message::React(<Emoji>))
Do you want to edit a channel? Channel::Edit(<SocketSendChannel)
Needs to delete a message? Message::Delete()

Tip

Most of the features that modify a Channel, a Message or a Member can be "motivated" with a string reason that will appear in the audit log by just inserting a string like Message::Delete("it was horrible!")!
Just remember to check if the function that you want to use supports that!

Get a child

To get a child you can both use the Get<Component name>() function like GetChannel(<long>) from the Guild component or you can just iterate the list (Guild::Channels::FirstOrDefault(ch => ch.Id == myBeautifulId))

Builders

SimpleDiscord also offer some helper class -also called "builders"- to help you create some specific components to send.
At the moment these builders are available:

  • AcionRowBuilder
  • ApplicationCommandBuilder
  • CommandOptionBuilder
  • EmbedBuilder
  • MessageBuilder
  • HttpMessageBuilder
  • ModalBuilder

Name explaination

<component> - base component
Socket<component> - socket component: it represents what do we expect to receive from Discord
SocketSend<component> - socket send component: it represents what does discord expect from us

Note

To send data you'll always need a SocketSend<component> class

Clone this wiki locally