|
|
|
@@ -1,128 +1,67 @@ |
|
|
|
# Discord.Net Labs |
|
|
|
[](https://www.nuget.org/packages/Discord.Net.Labs) |
|
|
|
[](https://discord.gg/dvSfUTet3K) |
|
|
|
|
|
|
|
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 |
|
|
|
|
|
|
|
## 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. |
|
|
|
|
|
|
|
## 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! |
|
|
|
|
|
|
|
## Branches |
|
|
|
### Dev |
|
|
|
This branch is kept up to date with dnets dev branch. we pull of it to ensure that labs will work with pre existing dnet code. |
|
|
|
|
|
|
|
### release/2.x |
|
|
|
This branch is what will be pushed to nuget, sometimes its not up to date as we wait for other features to be finished. |
|
|
|
|
|
|
|
### old/SlashCommandService |
|
|
|
This branch is on pause and does not work currently, There is a pull request open to implement a working version of a slash command service. It can be found [here](https://github.com/Discord-Net-Labs/Discord.Net-Labs/pull/52) |
|
|
|
|
|
|
|
### 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 |
|
|
|
```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 |
|
|
|
Slash command example how to's can be found [here](https://github.com/Discord-Net-Labs/Discord.Net-Labs/tree/Interactions/docs/guides/slash-commands). |
|
|
|
# Discord.Net |
|
|
|
|
|
|
|
[](https://www.nuget.org/packages/Discord.Net) |
|
|
|
[](https://www.myget.org/feed/Packages/discord-net) |
|
|
|
[](https://dev.azure.com/discord-net/Discord.Net/_build/latest?definitionId=1&branchName=dev) |
|
|
|
[](https://discord.gg/jkrBmQR) |
|
|
|
|
|
|
|
An unofficial .NET API Wrapper for the Discord client (https://discord.com). |
|
|
|
|
|
|
|
## Documentation |
|
|
|
|
|
|
|
- [Nightly](https://docs.stillu.cc/) |
|
|
|
- [Latest CI repo](https://github.com/discord-net/docs-static) |
|
|
|
|
|
|
|
## Installation |
|
|
|
|
|
|
|
### Stable (NuGet) |
|
|
|
|
|
|
|
Our stable builds available from NuGet through the Discord.Net metapackage: |
|
|
|
|
|
|
|
- [Discord.Net](https://www.nuget.org/packages/Discord.Net/) |
|
|
|
|
|
|
|
The individual components may also be installed from NuGet: |
|
|
|
|
|
|
|
- [Discord.Net.Commands](https://www.nuget.org/packages/Discord.Net.Commands/) |
|
|
|
- [Discord.Net.Rest](https://www.nuget.org/packages/Discord.Net.Rest/) |
|
|
|
- [Discord.Net.WebSocket](https://www.nuget.org/packages/Discord.Net.WebSocket/) |
|
|
|
- [Discord.Net.Webhook](https://www.nuget.org/packages/Discord.Net.Webhook/) |
|
|
|
|
|
|
|
### Unstable (MyGet) |
|
|
|
|
|
|
|
Nightly builds are available through our MyGet feed (`https://www.myget.org/F/discord-net/api/v3/index.json`). |
|
|
|
|
|
|
|
## Compiling |
|
|
|
|
|
|
|
In order to compile Discord.Net, you require the following: |
|
|
|
|
|
|
|
### Using Visual Studio |
|
|
|
|
|
|
|
- [Visual Studio 2017](https://www.microsoft.com/net/core#windowsvs2017) |
|
|
|
- [.NET Core SDK](https://www.microsoft.com/net/download/core) |
|
|
|
|
|
|
|
The .NET Core workload must be selected during Visual Studio installation. |
|
|
|
|
|
|
|
### Using Command Line |
|
|
|
|
|
|
|
- [.NET Core SDK](https://www.microsoft.com/net/download/core) |
|
|
|
|
|
|
|
## Known Issues |
|
|
|
|
|
|
|
### WebSockets (Win7 and earlier) |
|
|
|
|
|
|
|
.NET Core 1.1 does not support WebSockets on Win7 and earlier. This issue has been fixed since the release of .NET Core 2.1. It is recommended to target .NET Core 2.1 or above for your project if you wish to run your bot on legacy platforms; alternatively, you may choose to install the [Discord.Net.Providers.WS4Net](https://www.nuget.org/packages/Discord.Net.Providers.WS4Net/) package. |
|
|
|
|
|
|
|
## Versioning Guarantees |
|
|
|
|
|
|
|
This library generally abides by [Semantic Versioning](https://semver.org). Packages are published in MAJOR.MINOR.PATCH version format. |
|
|
|
|
|
|
|
An increment of the PATCH component always indicates that an internal-only change was made, generally a bugfix. These changes will not affect the public-facing API in any way, and are always guaranteed to be forward- and backwards-compatible with your codebase, any pre-compiled dependencies of your codebase. |
|
|
|
|
|
|
|
An increment of the MINOR component indicates that some addition was made to the library, and this addition is not backwards-compatible with prior versions. However, Discord.Net **does not guarantee forward-compatibility** on minor additions. In other words, we permit a limited set of breaking changes on a minor version bump. |
|
|
|
|
|
|
|
Due to the nature of the Discord API, we will oftentimes need to add a property to an entity to support the latest API changes. Discord.Net provides interfaces as a method of consuming entities; and as such, introducing a new field to an entity is technically a breaking change. Major version bumps generally indicate some major change to the library, and as such we are hesitant to bump the major version for every minor addition to the library. To compromise, we have decided that interfaces should be treated as **consumable only**, and your applications should typically not be implementing interfaces. (For applications where interfaces are implemented, such as in test mocks, we apologize for this inconsistency with SemVer). |
|
|
|
|
|
|
|
Furthermore, while we will never break the API (outside of interface changes) on minor builds, we will occasionally need to break the ABI, by introducing parameters to a method to match changes upstream with Discord. As such, a minor version increment may require you to recompile your code, and dependencies, such as addons, may also need to be recompiled and republished on the newer version. When a binary breaking change is made, the change will be noted in the release notes. |
|
|
|
|
|
|
|
An increment of the MAJOR component indicates that breaking changes have been made to the library; consumers should check the release notes to determine what changes need to be made. |
quin lynch