diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 000000000..fbae6d524 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,50 @@ +# Frequently Asked Questions + +#### Whats the difference between DNet and DNet Labs? +DNet Labs is mostly the same as DNet as it just adds additional features. Discord.NET-labs adds several features Discord.NET does not. Examples of this are: Threads, application commands, message components, stage channels, role icons & more small functionality changes. More details [here](https://github.com/discord-net/Discord.Net/pull/1923). + +#### Should I use DNet Labs instead of DNet? or can I use both at the same time? +DNet Labs implements new experimental/unstable features and generally shouldn't be used in production environments. You should only use it if you want to test out new Discord features. As DNet Labs builds on top of DNet, you can not use both at the same time, however DNet Labs should be a pretty straight forward drop-in replacement for DNet. + +#### Why is x not doing y when it should? +Double check you are on the most recent version of Discord .Net labs, if you are and it looks like an issue, report it on [Discord](https://discord.com/invite/dnet-labs) or create an issue on [GitHub](https://github.com/Discord-Net-Labs/Discord.Net-Labs) + +#### When is feature x going to be added? +When someone adds it. If a new Discord feature is currently untouched, submit an issue on [GitHub](https://github.com/Discord-Net-Labs/Discord.Net-Labs) regarding the request. + +#### What's the difference between RespondAsync, DeferAsync and FollowupAsync? +The difference between these 3 functions is in how you handle the command response. [RespondAsync](https://discord-net-labs.com/api/Discord.WebSocket.SocketCommandBase.html#Discord_WebSocket_SocketCommandBase_DeferAsync_System_Boolean_Discord_RequestOptions_) and [DeferAsync](https://discord-net-labs.com/api/Discord.WebSocket.SocketCommandBase.html#Discord_WebSocket_SocketCommandBase_DeferAsync_System_Boolean_Discord_RequestOptions_) let the API know you have succesfully received the command. This is also called 'acknowledging' a command. DeferAsync will not send out a response, RespondAsync will not. [FollowupAsync](https://discord-net-labs.com/api/Discord.WebSocket.SocketCommandBase.html#Discord_WebSocket_SocketCommandBase_DeferAsync_System_Boolean_Discord_RequestOptions_) follows up on succesful acknowledgement. + +> [!WARNING] +> If you have not acknowledged the command FollowupAsync will not work. + +#### What's the difference between global commands and guild commands? (Why isn't my command show up in discord?) +Global commands can be used in every guild your bot is in. However, it can take up to an hour for every guild to have access to the commands. +Guild commands can only be used in specific guilds. They are available within a few minutes. (This is great for testing purposes). + +#### I'm getting a 50001: Missing access error while trying to create a guild command! +Guild commands require you give grant the bot the applications.commands OAuth2 scope in order to register guild commands in that guild. You can register global commands without this OAuth2 scope but will need it to use global commands in that guild. + +#### I'm getting errors when trying to create a slash command (The application command failed to be created, 400 bad request, 50035: Invalid Form Body, etc) +This could be caused by several things but the most common one is an invalid "Name" for the command or any of the options/arguments for the command. Make sure your "Name" is all lowercase and only contains letters or dashes. It should also be less than 32 characters. If you are still having issues after checking this, read up on the other slash commands limits [here](https://discord.com/developers/docs/interactions/slash-commands#a-quick-note-on-limits). + +> [!NOTE] +> In most cases, you can catch an [ApplicationCommandException](https://discord-net-labs.com/api/Discord.Net.ApplicationCommandException.html?q=applicationcommandexception) error from creation. +> This exception will tell you what part of your command is invalid as well as why. + +#### How can I use Victoria with Labs? +You can add a special build of victoria that supports labs by adding the below to your references: +```xml + + https://www.myget.org/F/yucked/api/v3/index.json + +``` + +#### I'm getting a 10062 exception: Unknown Interaction. What can I do? +This exception happens when an app tries to send an initial response to an interaction twice. This can be caused by: +- 2 instances of your app running at once. +- Responding 3+ seconds after the interaction was received. +If you're positive that your app doesn't do this and you are still receiving the exception, please submit an issue. + +#### Why is BannerId/AccentColour always null? +Currently SocketUser/SocketGuildUser does not expose the [BannerId](https://discord-net-labs.com/api/Discord.IUser.html#Discord_IUser_BannerId) nor [AccentColor](https://discord-net-labs.com/api/Discord.IUser.html#Discord_IUser_AccentColor). To get this info, a [RestUser](https://discord-net-labs.com/api/Discord.Rest.RestUser.html?q=RestUser) must be requested. diff --git a/README.md b/README.md index c3343cd38..789119574 100644 --- a/README.md +++ b/README.md @@ -20,17 +20,60 @@ This repo is a custom fork of Discord.Net that introduces the newest features of discord for testing and experimenting. Nothing here is guaranteed to work but you are more than welcome to submit bugs in the issues tabs -### ♥ Sponsor us! +---- + +- 📄 [Documentation](https://discord-net-labs.com) +- 🔗 [Support](https://discord.com/invite/dnet-labs) +- 📚 [Guides](https://discord-net-labs.com/guides/introduction/intro.html) + +## Sponsor us! ❤ - If this library benefits you consider [sponsoring](https://github.com/sponsors/quinchs) the project as it really helps out. *Only sponsor if you're financially stable!* -## Known issues -Labs will not work with normal package of Playwo's [InteractivityAddon](https://www.nuget.org/packages/Discord.InteractivityAddon). The reason is that his package depends on the base discord.net lib. You can instead use the [InteractivityAddon.Labs](https://www.nuget.org/packages/Discord.InteractivityAddon.Labs) package which implements some of the features added in Discord.Net-Labs. +## Known compatibility issues + +- Playwo's [InteractivityAddon](https://www.nuget.org/packages/Discord.InteractivityAddon) + * ❌ Reason: The default package depends on Discord.NET instead of labs. + * ✔ Fix: [InteractivityAddon.Labs](https://www.nuget.org/packages/Discord.InteractivityAddon.Labs), which implements some of the features added in Discord.Net-Labs. + +- [Victoria](https://github.com/Yucked/Victoria) + * ❌ Reason: Victoria is built around Discord.NET and is not supported by labs. + * ✔ Fix: A custom build based on Discord.NET-labs: +```xml + + https://www.myget.org/F/yucked/api/v3/index.json + +``` ## How to use Setting up labs in your project is really simple, here's how to do it: 1) Remove Discord.Net from your project 2) Add Discord.Net Labs nuget to your project -3) Enjoy! +3) That's all! + +## Implementations +What Discord.NET-labs has that Discord.NET does not: + +- Major changes + * Added Interaction Support. + * Added Application commands (slash, user, message). + * Added Message Components (buttons, select menus). + * Added Thread Channels. + * Added Stage Channels. + * Revamped Stickers. + +- Minor changes + * Added `TimestampTag`. + * Made `Hierarchy` a `IGuildUser` property. + * Changes embed discription length to 4096. + * Added `Name` property to teams. + * Added url validation to embeds. + * Added `NsfwLevel` to Guilds. + * Added helpers to `Emoji` for parsing. + * Fixed gateway serialization to include nulls. + * Added banner and accent color to guild users. + * Fixed `CurrentUserId` in sharded clients being null. + * Fixed Guild owner and Admin `GuildPermissions.All`. + * Added `RatelimitCallback` to `RequestOptions`. ## Branches @@ -45,110 +88,3 @@ This branch is on pause and does not work currently, There is a pull request ope ### feature/xyz These branches are features for new things, you are more than welcome to clone them and give feedback in the discord server or issues tab. - -## Listening for Interactions - -Interaction docs can be found [here](https://github.com/Discord-Net-Labs/Discord.Net-Labs/tree/release/3.x/docs/guides/interactions). They are much more in depth than this readme. - -```cs -// Subscribe to the InteractionCreated event -client.InteractionCreated += Client_InteractionCreated; - -... -private async Task Client_InteractionCreated(SocketInteraction interaction) -{ - // Checking the type of this interaction - switch (interaction) - { - // Slash commands - case SocketSlashCommand commandInteraction: - await MySlashCommandHandler(commandInteraction); - break; - - // Button clicks/selection dropdowns - case SocketMessageComponent componentInteraction: - await MyMessageComponentHandler(componentInteraction); - break; - - // Unused or Unknown/Unsupported - default: - break; - } -} -``` - -### Simple handling slash commands -```cs -private async Task MySlashCommandHandler(SocketSlashCommand interaction) -{ - // Checking command name - if (interaction.Data.Name == "ping") - { - // Respond to interaction with message. - // You can also use "ephemeral" so that only the original user of the interaction sees the message - await interaction.RespondAsync($"Pong!", ephemeral: true); - - // Also you can followup with a additional messages, which also can be "ephemeral" - await interaction.FollowupAsync($"PongPong!", ephemeral: true); - } -} -``` - -### Simple handling button clicks and selection dropdowns -```cs -private async Task MyMessageComponentHandler(SocketMessageComponent interaction) -{ - // Get the custom ID - var customId = interaction.Data.CustomId; - // Get the user - var user = (SocketGuildUser) interaction.User; - // Get the guild - var guild = user.Guild; - - // Respond with the update message. This edits the message which this component resides. - await interaction.UpdateAsync(msgProps => msgProps.Content = $"Clicked {interaction.Data.CustomId}!"); - - // Also you can followup with a additional messages - await interaction.FollowupAsync($"Clicked {interaction.Data.CustomId}!", ephemeral: true); - - // If you are using selection dropdowns, you can get the selected label and values using these - var selectedLabel = ((SelectMenu) interaction.Message.Components.First().Components.First()).Options.FirstOrDefault(x => x.Value == interaction.Data.Values.FirstOrDefault())?.Label; - var selectedValue = interaction.Data.Values.First(); -} -``` - -> Note: The example above assumes that the selection dropdown is expecting only 1 returned value, if you configured your dropdown for multiple values, you'll need to modify the code slightly. - -### Sending messages with buttons -Theres a new field in all `SendMessageAsync` functions that takes in a `MessageComponent`, you can use it like so: -```cs -var builder = new ComponentBuilder().WithButton("Hello!", customId: "id_1", ButtonStyle.Primary, row: 0); -await Context.Channel.SendMessageAsync("Test buttons!", component: builder.Build()); -``` - -### Sending messages with selection dropdowns -Theres a new field in all `SendMessageAsync` functions that takes in a `MessageComponent`, you can use it like so: -```cs -var builder = new ComponentBuilder() - .WithSelectMenu(new SelectMenuBuilder() - .WithCustomId("id_2") - .WithPlaceholder("This is a placeholder") - .AddOption( - label: "Option", - value: "value1", - description: "Evan pog champ", - emote: Emote.Parse("<:evanpog:810017136814194698>") - ) - .AddOption("Option B", "value2", "Option B is poggers") - ); - -await Context.Channel.SendMessageAsync("Test selection!", component: builder.Build()); -``` - -> Note: You can only have 5 buttons per row and 5 rows per message. If a row contains a selection dropdown it cannot contain any buttons. - -## Slash Commands & Context Menu Commands -Slash command & Context command examples and how to's can be found [here](https://github.com/Discord-Net-Labs/Discord.Net-Labs/tree/release/3.x/docs/guides/interactions/application-commands). - -## Message Components -Message components (buttons, menus, etc) examples and how to's can be found [here](https://github.com/Discord-Net-Labs/Discord.Net-Labs/tree/release/3.x/docs/guides/interactions/message-components) diff --git a/docs/docfx.json b/docs/docfx.json index 424b951bc..9179035fd 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -23,7 +23,8 @@ "files": ["toc.yml", "index.md"] }, { - "files": ["faq/**.md", "faq/**/toc.yml"] + "src": "../", + "files": ["FAQ.md"] }, { "files": ["guides/**.md", "guides/**/toc.yml"] @@ -59,8 +60,8 @@ ], "overwrite": "_overwrites/**/**.md", "globalMetadata": { - "_appTitle": "Discord.Net Documentation", - "_appFooter": "Discord.Net (c) 2015-2020 2.2.0", + "_appTitle": "Discord.Net-Labs Documentation", + "_appFooter": "Discord.Net-Labs (c) 2020-2021 3.1.6", "_enableSearch": true, "_appLogoPath": "marketing/logo/SVG/Logomark Purple.svg", "_appFaviconPath": "favicon.ico" diff --git a/docs/faq/basics/basic-operations.md b/docs/faq/basics/basic-operations.md deleted file mode 100644 index 35c71709f..000000000 --- a/docs/faq/basics/basic-operations.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -uid: FAQ.Basics.BasicOp -title: Questions about Basic Operations ---- - -# Basic Operations Questions - -In the following section, you will find commonly asked questions and -answers regarding basic usage of the library, as well as -language-specific tips when using this library. - -## How should I safely check a type? - -> [!WARNING] -> Direct casting (e.g., `(Type)type`) is **the least recommended** -> way of casting, as it *can* throw an [InvalidCastException] -> when the object isn't the desired type. -> -> Please refer to [this post] for more details. - -In Discord.Net, the idea of polymorphism is used throughout. You may -need to cast the object as a certain type before you can perform any -action. - -A good and safe casting example: - -[!code-csharp[Casting](samples/cast.cs)] - -[InvalidCastException]: https://docs.microsoft.com/en-us/dotnet/api/system.invalidcastexception -[this post]: https://docs.microsoft.com/en-us/dotnet/csharp/how-to/safely-cast-using-pattern-matching-is-and-as-operators - -## How do I send a message? - -> [!TIP] -> The [GetChannel] method by default returns an [IChannel], allowing -> channel types such as [IVoiceChannel], [ICategoryChannel] -> to be returned; consequently, you cannot send a message -> to channels like those. - -Any implementation of [IMessageChannel] has a [SendMessageAsync] -method. You can get the channel via [GetChannel] under the client. -Remember, when using Discord.Net, polymorphism is a common recurring -theme. This means an object may take in many shapes or form, which -means casting is your friend. You should attempt to cast the channel -as an [IMessageChannel] or any other entity that implements it to be -able to message. - -[SendMessageAsync]: xref:Discord.IMessageChannel.SendMessageAsync* -[GetChannel]: xref:Discord.WebSocket.DiscordSocketClient.GetChannel* - -## How can I tell if a message is from X, Y, Z channel? - -You may check the message channel type. Visit [Glossary] to see the -various types of channels. - -[Glossary]: xref:FAQ.Glossary#message-channels - -## How can I get the guild from a message? - -There are 2 ways to do this. You can do either of the following, - -1. Cast the user as an [IGuildUser] and use its [IGuild] property. -2. Cast the channel as an [IGuildChannel] and use its [IGuild] property. - -## How do I add hyperlink text to an embed? - -Embeds can use standard [markdown] in the description field as well -as in field values. With that in mind, links can be added with -`[text](link)`. - -[markdown]: https://support.discordapp.com/hc/en-us/articles/210298617-Markdown-Text-101-Chat-Formatting-Bold-Italic-Underline- - -## How do I add reactions to a message? - -Any entity that implements [IUserMessage] has an [AddReactionAsync] -method. This method expects an [IEmote] as a parameter. -In Discord.Net, an Emote represents a custom-image emote, while an -Emoji is a Unicode emoji (standard emoji). Both [Emoji] and [Emote] -implement [IEmote] and are valid options. - -# [Adding a reaction to another message](#tab/emoji-others) - -[!code-csharp[Emoji](samples/emoji-others.cs)] - -# [Adding a reaction to a sent message](#tab/emoji-self) - -[!code-csharp[Emoji](samples/emoji-self.cs)] - -*** - -[AddReactionAsync]: xref:Discord.IMessage.AddReactionAsync* - -## What is a "preemptive rate limit?" - -A preemptive rate limit is Discord.Net's way of telling you to slow -down before you get hit by the real rate limit. Hitting a real rate -limit might prevent your entire client from sending any requests for -a period of time. This is calculated based on the HTTP header -returned by a Discord response. - -## Why am I getting so many preemptive rate limits when I try to add more than one reactions? - -This is due to how HTML header works, mistreating -0.25sec/action to 1sec. This causes the lib to throw preemptive rate -limit more frequently than it should for methods such as adding -reactions. - -## Can I opt-out of preemptive rate limits? - -Unfortunately, not at the moment. See [#401](https://github.com/RogueException/Discord.Net/issues/401). - -[IChannel]: xref:Discord.IChannel -[ICategoryChannel]: xref:Discord.ICategoryChannel -[IGuildChannel]: xref:Discord.IGuildChannel -[ITextChannel]: xref:Discord.ITextChannel -[IGuild]: xref:Discord.IGuild -[IVoiceChannel]: xref:Discord.IVoiceChannel -[IGuildUser]: xref:Discord.IGuildUser -[IMessageChannel]: xref:Discord.IMessageChannel -[IUserMessage]: xref:Discord.IUserMessage -[IEmote]: xref:Discord.IEmote -[Emote]: xref:Discord.Emote -[Emoji]: xref:Discord.Emoji \ No newline at end of file diff --git a/docs/faq/basics/client-basics.md b/docs/faq/basics/client-basics.md deleted file mode 100644 index 1176ee3fd..000000000 --- a/docs/faq/basics/client-basics.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -uid: FAQ.Basics.ClientBasics -title: Basic Questions about Client ---- - -# Client Basics Questions - -In the following section, you will find commonly asked questions and -answers about common issues that you may face when utilizing the -various clients offered by the library. - -## My client keeps returning 401 upon logging in! - -> [!WARNING] -> Userbot/selfbot (logging in with a user token) is no -> longer supported with this library starting from 2.0, as -> logging in under a user account may result in account termination. -> -> For more information, see issue [827] & [958], as well as the official -> [Discord API Terms of Service]. - -There are few possible reasons why this may occur. - -1. You are not using the appropriate [TokenType]. If you are using a - bot account created from the Discord Developer portal, you should - be using `TokenType.Bot`. -2. You are not using the correct login credentials. Please keep in - mind that a token is **different** from a *client secret*. - -[TokenType]: xref:Discord.TokenType -[827]: https://github.com/RogueException/Discord.Net/issues/827 -[958]: https://github.com/RogueException/Discord.Net/issues/958 -[Discord API Terms of Service]: https://discord.com/developers/docs/legal - -## How do I do X, Y, Z when my bot connects/logs on? Why do I get a `NullReferenceException` upon calling any client methods after connect? - -Your bot should **not** attempt to interact in any way with -guilds/servers until the [Ready] event fires. When the bot -connects, it first has to download guild information from -Discord for you to get access to any server -information; the client is not ready at this point. - -Technically, the [GuildAvailable] event fires once the data for a -particular guild has downloaded; however, it is best to wait for all -guilds to be downloaded. Once all downloads are complete, the [Ready] -event is triggered, then you can proceed to do whatever you like. - -[Ready]: xref:Discord.WebSocket.DiscordSocketClient.Ready -[GuildAvailable]: xref:Discord.WebSocket.BaseSocketClient.GuildAvailable - -## How do I get a message's previous content when that message is edited? - -If you need to do anything with messages (e.g., checking Reactions, -checking the content of edited/deleted messages), you must set the -[MessageCacheSize] in your [DiscordSocketConfig] settings in order to -use the cached message entity. Read more about it [here](xref:Guides.Concepts.Events#cacheable). - -1. Message Cache must be enabled. -2. Hook the MessageUpdated event. This event provides a *before* and - *after* object. -3. Only messages received *after* the bot comes online will be - available in the cache. - -[MessageCacheSize]: xref:Discord.WebSocket.DiscordSocketConfig.MessageCacheSize -[DiscordSocketConfig]: xref:Discord.WebSocket.DiscordSocketConfig -[MessageUpdated]: xref:Discord.WebSocket.BaseSocketClient.MessageUpdated - -## What is a shard/sharded client, and how is it different from the `DiscordSocketClient`? -As your bot grows in popularity, it is recommended that you should section your bot off into separate processes. -The [DiscordShardedClient] is essentially a class that allows you to easily create and manage multiple [DiscordSocketClient] -instances, with each one serving a different amount of guilds. - -There are very few differences from the [DiscordSocketClient] class, and it is very straightforward -to modify your existing code to use a [DiscordShardedClient] when necessary. - -1. You need to specify the total amount of shards, or shard ids, via [DiscordShardedClient]'s constructors. -2. The [Connected], [Disconnected], [Ready], and [LatencyUpdated] events - are replaced with [ShardConnected], [ShardDisconnected], [ShardReady], and [ShardLatencyUpdated]. -3. Every event handler you apply/remove to the [DiscordShardedClient] is applied/removed to each shard. - If you wish to control a specific shard's events, you can access an individual shard through the `Shards` property. - -If you do not wish to use the [DiscordShardedClient] and instead reuse the same [DiscordSocketClient] code and manually shard them, -you can do so by specifying the [ShardId] for the [DiscordSocketConfig] and pass that to the [DiscordSocketClient]'s constructor. - -[DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient -[DiscordShardedClient]: xref:Discord.WebSocket.DiscordShardedClient -[Connected]: xref:Discord.WebSocket.DiscordSocketClient.Connected -[Disconnected]: xref:Discord.WebSocket.DiscordSocketClient.Disconnected -[LatencyUpdated]: xref:Discord.WebSocket.DiscordSocketClient.LatencyUpdated -[ShardConnected]: xref:Discord.WebSocket.DiscordShardedClient.ShardConnected -[ShardDisconnected]: xref:Discord.WebSocket.DiscordShardedClient.ShardDisconnected -[ShardReady]: xref:Discord.WebSocket.DiscordShardedClient.ShardReady -[ShardLatencyUpdated]: xref:Discord.WebSocket.DiscordShardedClient.ShardLatencyUpdated -[ShardId]: xref:Discord.WebSocket.DiscordSocketConfig.ShardId diff --git a/docs/faq/basics/getting-started.md b/docs/faq/basics/getting-started.md deleted file mode 100644 index e254226d0..000000000 --- a/docs/faq/basics/getting-started.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -uid: FAQ.Basics.GetStarted -title: Beginner Questions / How to Get Started ---- - -# Basic Concepts / Getting Started - -In this following section, you will find commonly asked questions and -answers about how to get started with Discord.Net, as well as basic -introduction to the Discord API ecosystem. - -## How do I add my bot to my server/guild? - -You can do so by using the [permission calculator] provided -by [FiniteReality]. -This tool allows you to set permissions that the bot will be assigned -with, and invite the bot into your guild. With this method, bots will -also be assigned a unique role that a regular user cannot use; this -is what we call a `Managed` role. Because you cannot assign this -role to any other users, it is much safer than creating a single -role which, intentionally or not, can be applied to other users -to escalate their privilege. - -[FiniteReality]: https://github.com/FiniteReality/permissions-calculator -[permission calculator]: https://finitereality.github.io/permissions-calculator - -## What is a token? - -A token is a credential used to log into an account. This information -should be kept **private** and for your eyes only. Anyone with your -token can log into your account. This risk applies to both user -and bot accounts. That also means that you should **never** hardcode -your token or add it into source control, as your identity may be -stolen by scrape bots on the internet that scours through -constantly to obtain a token. - -## What is a client/user/object ID? - -Each user and object on Discord has its own snowflake ID generated -based on various conditions. - -![Snowflake Generation](images/snowflake.png) - -Anyone can see the ID; it is public. It is merely used to -identify an object in the Discord ecosystem. Many things in the -Discord ecosystem require an ID to retrieve or identify the said -object. - -There are 2 common ways to obtain the said ID. - -### [Discord Developer Mode](#tab/dev-mode) - -By enabling the developer mode you can right click on most objects -to obtain their snowflake IDs (please note that this may not apply to -all objects, such as role IDs, or DM channel IDs). - -![Developer Mode](images/dev-mode.png) - -### [Escape Character](#tab/escape-char) - -You can escape an object by using `\` in front the object in the -Discord client. For example, when you do `\@Example#1234` in chat, -it will return the user ID of the aforementioned user. - -![Escaping mentions](images/mention-escape.png) - -*** - -## How do I get the role ID? - -> [!WARNING] -> Right-clicking on the role and copying the ID will **not** work. -> This will only copy the message ID. - -Several common ways to do this: - -1. (Easiest) Right click on the role either in the Server Settings - or in the user's role list. - ![Roles](images/role-copy.png) -2. Make the role mentionable and mention the role, and escape it - using the `\` character in front. -3. Inspect the roles collection within the guild via your debugger. \ No newline at end of file diff --git a/docs/faq/basics/images/dev-mode.png b/docs/faq/basics/images/dev-mode.png deleted file mode 100644 index fd20b95d1..000000000 Binary files a/docs/faq/basics/images/dev-mode.png and /dev/null differ diff --git a/docs/faq/basics/images/mention-escape.png b/docs/faq/basics/images/mention-escape.png deleted file mode 100644 index 927978061..000000000 Binary files a/docs/faq/basics/images/mention-escape.png and /dev/null differ diff --git a/docs/faq/basics/images/role-copy.png b/docs/faq/basics/images/role-copy.png deleted file mode 100644 index 1dbc2982f..000000000 Binary files a/docs/faq/basics/images/role-copy.png and /dev/null differ diff --git a/docs/faq/basics/images/snowflake.png b/docs/faq/basics/images/snowflake.png deleted file mode 100644 index 816a10eee..000000000 Binary files a/docs/faq/basics/images/snowflake.png and /dev/null differ diff --git a/docs/faq/basics/samples/cast.cs b/docs/faq/basics/samples/cast.cs deleted file mode 100644 index 73ef5237f..000000000 --- a/docs/faq/basics/samples/cast.cs +++ /dev/null @@ -1,15 +0,0 @@ -public async Task MessageReceivedHandler(SocketMessage msg) -{ - // Option 1: - // Using the `as` keyword, which will return `null` if the object isn't the desired type. - var usermsg = msg as SocketUserMessage; - // We bail when the message isn't the desired type. - if (msg == null) return; - - // Option 2: - // Using the `is` keyword to cast (C#7 or above only) - if (msg is SocketUserMessage usermsg) - { - // Do things - } -} \ No newline at end of file diff --git a/docs/faq/basics/samples/emoji-others.cs b/docs/faq/basics/samples/emoji-others.cs deleted file mode 100644 index dd3e6317f..000000000 --- a/docs/faq/basics/samples/emoji-others.cs +++ /dev/null @@ -1,18 +0,0 @@ -// bail if the message is not a user one (system messages cannot have reactions) -var usermsg = msg as IUserMessage; -if (usermsg == null) return; - -// standard Unicode emojis -Emoji emoji = new Emoji("👍"); -// or -// Emoji emoji = new Emoji("\uD83D\uDC4D"); - -// custom guild emotes -Emote emote = Emote.Parse("<:dotnet:232902710280716288>"); -// using Emote.TryParse may be safer in regards to errors being thrown; -// please note that the method does not verify if the emote exists, -// it simply creates the Emote object for you. - -// add the reaction to the message -await usermsg.AddReactionAsync(emoji); -await usermsg.AddReactionAsync(emote); \ No newline at end of file diff --git a/docs/faq/basics/samples/emoji-self.cs b/docs/faq/basics/samples/emoji-self.cs deleted file mode 100644 index cd4cff171..000000000 --- a/docs/faq/basics/samples/emoji-self.cs +++ /dev/null @@ -1,17 +0,0 @@ -// capture the message you're sending in a variable -var msg = await channel.SendMessageAsync("This will have reactions added."); - -// standard Unicode emojis -Emoji emoji = new Emoji("👍"); -// or -// Emoji emoji = new Emoji("\uD83D\uDC4D"); - -// custom guild emotes -Emote emote = Emote.Parse("<:dotnet:232902710280716288>"); -// using Emote.TryParse may be safer in regards to errors being thrown; -// please note that the method does not verify if the emote exists, -// it simply creates the Emote object for you. - -// add the reaction to the message -await msg.AddReactionAsync(emoji); -await msg.AddReactionAsync(emote); \ No newline at end of file diff --git a/docs/faq/commands/dependency-injection.md b/docs/faq/commands/dependency-injection.md deleted file mode 100644 index 0a5de3e32..000000000 --- a/docs/faq/commands/dependency-injection.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -uid: FAQ.Commands.DI -title: Questions about Dependency Injection with Commands ---- - -# Dependency-injection-related Questions - -In the following section, you will find common questions and answers -to utilizing dependency injection with @Discord.Commands, as well as -common troubleshooting steps regarding DI. - -## What is a service? Why does my module not hold any data after execution? - -In Discord.Net, modules are created similarly to ASP.NET, meaning -that they have a transient nature; modules are spawned whenever a -request is received, and are killed from memory when the execution -finishes. In other words, you cannot store persistent -data inside a module. Consider using a service if you wish to -workaround this. - -Service is often used to hold data externally so that they persist -throughout execution. Think of it like a chest that holds -whatever you throw at it that won't be affected by anything unless -you want it to. Note that you should also learn Microsoft's -implementation of [Dependency Injection] \([video]) before proceeding, -as well as how it works in [Discord.Net](xref:Guides.Commands.DI#usage-in-modules). - -A brief example of service and dependency injection can be seen below. - -[!code-csharp[DI](samples/DI.cs)] - -[Dependency Injection]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection -[video]: https://www.youtube.com/watch?v=QtDTfn8YxXg - -## Why is my `CommandService` complaining about a missing dependency? - -If you encounter an error similar to `Failed to create MyModule, -dependency MyExternalDependency was not found.`, you may have -forgotten to add the external dependency to the dependency container. - -Starting from Discord.Net 2.0, all dependencies required by each -module must be present when the module is loaded into the -[CommandService]. This means when loading the module, you must pass a -valid [IServiceProvider] with the dependency loaded before the module -can be successfully registered. - -For example, if your module, `MyModule`, requests a `DatabaseService` -in its constructor, the `DatabaseService` must be present in the -[IServiceProvider] when registering `MyModule`. - -[!code-csharp[Missing Dependencies](samples/missing-dep.cs)] - -[IServiceProvider]: xref:System.IServiceProvider -[CommandService]: xref:Discord.Commands.CommandService diff --git a/docs/faq/commands/general.md b/docs/faq/commands/general.md deleted file mode 100644 index de6d48dc1..000000000 --- a/docs/faq/commands/general.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -uid: FAQ.Commands.General -title: General Questions about Commands ---- - -# Command-related Questions - -In the following section, you will find commonly asked questions and -answered regarding general command usage when using @Discord.Commands. - -## How can I restrict some of my commands so only specific users can execute them? - -Based on how you want to implement the restrictions, you can use the -built-in [RequireUserPermission] precondition, which allows you to -restrict the command based on the user's current permissions in the -guild or channel (*e.g., `GuildPermission.Administrator`, -`ChannelPermission.ManageMessages`*). - -If, however, you wish to restrict the commands based on the user's -role, you can either create your custom precondition or use -Joe4evr's [Preconditions Addons] that provides a few custom -preconditions that aren't provided in the stock library. -Its source can also be used as an example for creating your -custom preconditions. - -[RequireUserPermission]: xref:Discord.Commands.RequireUserPermissionAttribute -[Preconditions Addons]: https://github.com/Joe4evr/Discord.Addons/tree/master/src/Discord.Addons.Preconditions - -## Why am I getting an error about `Assembly.GetEntryAssembly`? - -You may be confusing @Discord.Commands.CommandService.AddModulesAsync* -with @Discord.Commands.CommandService.AddModuleAsync*. The former -is used to add modules via the assembly, while the latter is used to -add a single module. - -## What does [Remainder] do in the command signature? - -The [RemainderAttribute] leaves the string unparsed, meaning you -do not have to add quotes around the text for the text to be -recognized as a single object. Please note that if your method has -multiple parameters, the remainder attribute can only be applied to -the last parameter. - -[!code-csharp[Remainder](samples/Remainder.cs)] - -[RemainderAttribute]: xref:Discord.Commands.RemainderAttribute - -## Discord.Net keeps saying that a `MessageReceived` handler is blocking the gateway, what should I do? - -By default, the library warns the user about any long-running event -handler that persists for **more than 3 seconds**. Any event -handlers that are run on the same thread as the gateway task, the task -in charge of keeping the connection alive, may block the processing of -heartbeat, and thus terminating the connection. - -In this case, the library detects that a `MessageReceived` -event handler is blocking the gateway thread. This warning is -typically associated with the command handler as it listens for that -particular event. If the command handler is blocking the thread, then -this **might** mean that you have a long-running command. - -> [!NOTE] -> In rare cases, runtime errors can also cause blockage, usually -> associated with Mono, which is not supported by this library. - -To prevent a long-running command from blocking the gateway -thread, a flag called [RunMode] is explicitly designed to resolve -this issue. - -There are 2 main `RunMode`s. - -1. `RunMode.Sync` -2. `RunMode.Async` - -`Sync` is the default behavior and makes the command to be run on the -same thread as the gateway one. `Async` will spin the task off to a -different thread from the gateway one. - -> [!IMPORTANT] -> While specifying `RunMode.Async` allows the command to be spun off -> to a different thread, keep in mind that by doing so, there will be -> **potentially unwanted consequences**. Before applying this flag, -> please consider whether it is necessary to do so. -> -> Further details regarding `RunMode.Async` can be found below. - -You can set the `RunMode` either by specifying it individually via -the `CommandAttribute` or by setting the global default with -the [DefaultRunMode] flag under `CommandServiceConfig`. - -# [CommandAttribute](#tab/cmdattrib) - -[!code-csharp[Command Attribute](samples/runmode-cmdattrib.cs)] - -# [CommandServiceConfig](#tab/cmdconfig) - -[!code-csharp[Command Service Config](samples/runmode-cmdconfig.cs)] - -*** - -*** - -[RunMode]: xref:Discord.Commands.RunMode -[CommandAttribute]: xref:Discord.Commands.CommandAttribute -[DefaultRunMode]: xref:Discord.Commands.CommandServiceConfig.DefaultRunMode - -## How does `RunMode.Async` work, and why is Discord.Net *not* using it by default? - -`RunMode.Async` works by spawning a new `Task` with an unawaited -[Task.Run], essentially making the task that is used to invoke the -command task to be finished on a different thread. This design means -that [ExecuteAsync] will be forced to return a successful -[ExecuteResult] regardless of the actual execution result. - -The following are the known caveats with `RunMode.Async`, - -1. You can potentially introduce a race condition. -2. Unnecessary overhead caused by the [async state machine]. -3. [ExecuteAsync] will immediately return [ExecuteResult] instead of - other result types (this is particularly important for those who wish - to utilize [RuntimeResult] in 2.0). -4. Exceptions are swallowed in the `ExecuteAsync` result. - -However, there are ways to remedy some of these. - -For #3, in Discord.Net 2.0, the library introduces a new event called -[CommandService.CommandExecuted], which is raised whenever the command is executed. -This event will be raised regardless of -the `RunMode` type and will return the appropriate execution result -and the associated @Discord.Commands.CommandInfo if applicable. - -For #4, exceptions are caught in [CommandService.Log] event under -[LogMessage.Exception] as [CommandException] and in the -[CommandService.CommandExecuted] event under the [IResult] as -[ExecuteResult.Exception]. - -[Task.Run]: https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.run -[async state machine]: https://www.red-gate.com/simple-talk/dotnet/net-tools/c-async-what-is-it-and-how-does-it-work/ -[ExecuteAsync]: xref:Discord.Commands.CommandService.ExecuteAsync* -[ExecuteResult]: xref:Discord.Commands.ExecuteResult -[RuntimeResult]: xref:Discord.Commands.RuntimeResult -[CommandService.CommandExecuted]: xref:Discord.Commands.CommandService.CommandExecuted -[CommandService.Log]: xref:Discord.Commands.CommandService.Log -[LogMessage.Exception]: xref:Discord.LogMessage.Exception* -[ExecuteResult.Exception]: xref:Discord.Commands.ExecuteResult.Exception* -[CommandException]: xref:Discord.Commands.CommandException -[IResult]: xref:Discord.Commands.IResult \ No newline at end of file diff --git a/docs/faq/commands/samples/DI.cs b/docs/faq/commands/samples/DI.cs deleted file mode 100644 index ce4454bc2..000000000 --- a/docs/faq/commands/samples/DI.cs +++ /dev/null @@ -1,28 +0,0 @@ -public class MyService -{ - public string MyCoolString { get; set; } -} -public class Setup -{ - public IServiceProvider BuildProvider() => - new ServiceCollection() - .AddSingleton() - .BuildServiceProvider(); -} -public class MyModule : ModuleBase -{ - // Inject via public settable prop - public MyService MyService { get; set; } - - // ...or via the module's constructor - - // private readonly MyService _myService; - // public MyModule (MyService myService) => _myService = myService; - - [Command("string")] - public Task GetOrSetStringAsync(string input) - { - if (string.IsNullOrEmpty(_myService.MyCoolString)) _myService.MyCoolString = input; - return ReplyAsync(_myService.MyCoolString); - } -} \ No newline at end of file diff --git a/docs/faq/commands/samples/Remainder.cs b/docs/faq/commands/samples/Remainder.cs deleted file mode 100644 index 337fb6e45..000000000 --- a/docs/faq/commands/samples/Remainder.cs +++ /dev/null @@ -1,20 +0,0 @@ -// Input: -// !echo Coffee Cake - -// Output: -// Coffee Cake -[Command("echo")] -public Task EchoRemainderAsync([Remainder]string text) => ReplyAsync(text); - -// Output: -// CommandError.BadArgCount -[Command("echo-hassle")] -public Task EchoAsync(string text) => ReplyAsync(text); - -// The message would be seen as having multiple parameters, -// while the method only accepts one. -// Wrapping the message in quotes solves this. -// This way, the system knows the entire message is to be parsed as a -// single String. -// e.g., -// !echo "Coffee Cake" \ No newline at end of file diff --git a/docs/faq/commands/samples/missing-dep.cs b/docs/faq/commands/samples/missing-dep.cs deleted file mode 100644 index d3fb9085b..000000000 --- a/docs/faq/commands/samples/missing-dep.cs +++ /dev/null @@ -1,29 +0,0 @@ -public class MyModule : ModuleBase -{ - private readonly DatabaseService _dbService; - public MyModule(DatabaseService dbService) - => _dbService = dbService; -} -public class CommandHandler -{ - private readonly CommandService _commands; - private readonly IServiceProvider _services; - public CommandHandler(DiscordSocketClient client) - { - _services = new ServiceCollection() - .AddService() - .AddService(client) - // We are missing DatabaseService! - .BuildServiceProvider(); - } - public async Task RegisterCommandsAsync() - { - // ... - // The method fails here because DatabaseService is a required - // dependency and cannot be resolved by the dependency - // injection service at runtime since the service is not - // registered in this instance of _services. - await _commands.AddModulesAsync(Assembly.GetEntryAssembly(), _services); - // ... - } -} \ No newline at end of file diff --git a/docs/faq/commands/samples/runmode-cmdattrib.cs b/docs/faq/commands/samples/runmode-cmdattrib.cs deleted file mode 100644 index 253acc4a9..000000000 --- a/docs/faq/commands/samples/runmode-cmdattrib.cs +++ /dev/null @@ -1,7 +0,0 @@ -[Command("process", RunMode = RunMode.Async)] -public async Task ProcessAsync(string input) -{ - // Does heavy calculation here. - await Task.Delay(TimeSpan.FromMinute(1)); - await ReplyAsync(input); -} \ No newline at end of file diff --git a/docs/faq/commands/samples/runmode-cmdconfig.cs b/docs/faq/commands/samples/runmode-cmdconfig.cs deleted file mode 100644 index 11d9cc295..000000000 --- a/docs/faq/commands/samples/runmode-cmdconfig.cs +++ /dev/null @@ -1,10 +0,0 @@ -public class Setup -{ - private readonly CommandService _command; - - public Setup() - { - var config = new CommandServiceConfig{ DefaultRunMode = RunMode.Async }; - _command = new CommandService(config); - } -} \ No newline at end of file diff --git a/docs/faq/misc/glossary.md b/docs/faq/misc/glossary.md deleted file mode 100644 index 4b661f65c..000000000 --- a/docs/faq/misc/glossary.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -uid: FAQ.Glossary -title: Common Terminologies / Glossary ---- - -# Glossary - -This is an additional chapter for quick references to various common -types that you may see within Discord.Net. To see more information -regarding each type of object, click on the object to navigate -to our API documentation page where you might find more explanation -about it. - -## Common Types - -* A **Guild** ([IGuild]) is an isolated collection of users and -channels, and are often referred to as "servers". - - Example: [Discord API](https://discord.gg/jkrBmQR) -* A **Channel** ([IChannel]) represents a generic channel. - - Example: #dotnet_discord-net - - See [Channel Types](#channel-types) - -[IGuild]: xref:Discord.IGuild -[IChannel]: xref:Discord.IChannel - -## Channel Types - -### Message Channels -* A **Text Channel** ([ITextChannel]) is a message channel from a -Guild. -* A **DM Channel** ([IDMChannel]) is a message channel from a DM. -* A **Group Channel** ([IGroupChannel]) is a message channel from a -Group. - - This is rarely used due to the bot's inability to join groups. -* A **Private Channel** ([IPrivateChannel]) is a DM or a Group. -* A **Message Channel** ([IMessageChannel]) can be any of the above. - -### Misc Channels -* A **Guild Channel** ([IGuildChannel]) is a guild channel in a guild. - - This can be any channels that may exist in a guild. -* A **Voice Channel** ([IVoiceChannel]) is a voice channel in a guild. -* A **Category Channel** ([ICategoryChannel]) (2.0+) is a category that -holds one or more sub-channels. -* A **Nested Channel** ([INestedChannel]) (2.0+) is a channel that can -exist under a category. - -[INestedChannel]: xref:Discord.INestedChannel -[IGuildChannel]: xref:Discord.IGuildChannel -[IMessageChannel]: xref:Discord.IMessageChannel -[ITextChannel]: xref:Discord.ITextChannel -[IGroupChannel]: xref:Discord.IGroupChannel -[IDMChannel]: xref:Discord.IDMChannel -[IPrivateChannel]: xref:Discord.IPrivateChannel -[IVoiceChannel]: xref:Discord.IVoiceChannel -[ICategoryChannel]: xref:Discord.ICategoryChannel - -## Emoji Types - -* An **Emote** ([Emote]) is a custom emote from a guild. - - Example: `<:dotnet:232902710280716288>` -* An **Emoji** ([Emoji]) is a Unicode emoji. - - Example: `👍` - -[Emote]: xref:Discord.Emote -[Emoji]: xref:Discord.Emoji - -## Activity Types - -* A **Game** ([Game]) refers to a user's game activity. -* A **Rich Presence** ([RichGame]) refers to a user's detailed -gameplay status. - - Visit [Rich Presence Intro] on Discord docs for more info. -* A **Streaming Status** ([StreamingGame]) refers to user's activity -for streaming on services such as Twitch. -* A **Spotify Status** ([SpotifyGame]) (2.0+) refers to a user's -activity for listening to a song on Spotify. - -[Game]: xref:Discord.Game -[RichGame]: xref:Discord.RichGame -[StreamingGame]: xref:Discord.StreamingGame -[SpotifyGame]: xref:Discord.SpotifyGame -[Rich Presence Intro]: https://discord.com/developers/docs/rich-presence/best-practices diff --git a/docs/faq/misc/legacy.md b/docs/faq/misc/legacy.md deleted file mode 100644 index 5931579d3..000000000 --- a/docs/faq/misc/legacy.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -uid: FAQ.Legacy -title: Questions about Legacy Versions ---- - -# Legacy Questions - -This section refers to legacy library-related questions that do not -apply to the latest or recent version of the Discord.Net library. - -## X, Y, Z does not work! It doesn't return a valid value anymore. - -If you are currently using an older version of the stable branch, -please upgrade to the latest pre-release version to ensure maximum -compatibility. Several features may be broken in older -versions and will likely not be fixed in the version branch due to -their breaking nature. - -Visit the repo's [release tag] to see the latest public pre-release. - -[release tag]: https://github.com/RogueException/Discord.Net/releases - -## I came from an earlier version of Discord.Net 1.0, and DependencyMap doesn't seem to exist anymore in the later revision? What happened to it? - -The `DependencyMap` has been replaced with Microsoft's -[DependencyInjection] Abstractions. An example usage can be seen -[here](https://github.com/foxbot/DiscordBotBase/blob/csharp/src/DiscordBot/Program.cs#L36). - -[DependencyInjection]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection \ No newline at end of file diff --git a/docs/faq/toc.yml b/docs/faq/toc.yml deleted file mode 100644 index 393e948f6..000000000 --- a/docs/faq/toc.yml +++ /dev/null @@ -1,18 +0,0 @@ -- name: Basic Concepts - items: - - name: Getting Started - topicUid: FAQ.Basics.GetStarted - - name: Basic Operations - topicUid: FAQ.Basics.BasicOp - - name: Client Basics - topicUid: FAQ.Basics.ClientBasics -- name: Commands - items: - - name: General - topicUid: FAQ.Commands.General - - name: Dependency Injection - topicUid: FAQ.Commands.DI -- name: Glossary - topicUid: FAQ.Glossary -- name: Legacy or Upgrade - topicUid: FAQ.Legacy diff --git a/docs/index.md b/docs/index.md index 9a617344a..063ec9e16 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,9 +19,29 @@ Discord.Net Labs is an experimental fork of Discord.Net that implements the newe ## Where to begin? -If this is your first time using Discord.Net, you should refer to the -[Intro](xref:Guides.Introduction) for tutorials. +If you are new to Discord.NET in general, you should refer their +[Documentation](https://docs.stillu.cc/) for guides & examples. + +Is this your first time using Labs, but you are already familiar with Discord.NET? +Refer to our [Guides](xref:Guides.Introduction) + +### Slashcommands: + +Examples on how slashcommands are created, handled & responded to is found +[Here](xref:Guides.SlashCommands.Intro) + +### User & Message commands: + +Creating User & Message commands is found +[Here](xref:Guides.ContextCommands.Creating), +interacting with them is covered +[Here](xref:Guides.ContextCommands.Reveiving). + +### Message components + +Handling & creating message components such as buttons & dropdown menu's is found [Here](xref:Guides.MessageComponents.GettingStarted) More experienced users might want to refer to the [API Documentation](xref:API.Docs) for a breakdown of the individual objects in the library. + diff --git a/docs/marketing/logo/SVG/Combinationmark White Background.svg b/docs/marketing/logo/SVG/Combinationmark White Background.svg index 5f59df1a5..249bba54c 100644 --- a/docs/marketing/logo/SVG/Combinationmark White Background.svg +++ b/docs/marketing/logo/SVG/Combinationmark White Background.svg @@ -1,58 +1,30 @@ - - - \ No newline at end of file diff --git a/docs/marketing/logo/SVG/Combinationmark White Border.svg b/docs/marketing/logo/SVG/Combinationmark White Border.svg new file mode 100644 index 000000000..b9a259a38 --- /dev/null +++ b/docs/marketing/logo/SVG/Combinationmark White Border.svg @@ -0,0 +1,30 @@ + + + + Combinationmark White + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml index bea010c5a..a1251a728 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -2,8 +2,7 @@ href: guides/ topicUid: Guides.Introduction - name: FAQ - href: faq/ - topicUid: FAQ.Basics.GetStarted + topicHref: ../FAQ.md - name: API Documentation href: api/ topicUid: API.Docs