## File: README.md [maven-central]: https://img.shields.io/maven-central/v/net.dv8tion/JDA?filter=!*-preview*&logo=apachemaven&color=blue [jitpack]: https://img.shields.io/badge/Snapshots-JitPack?logo=jitpack [installation]: #-installation [discord-invite]: https://discord.gg/0hMr4ce0tIl3SLv5 [license]: https://github.com/discord-jda/JDA/tree/master/LICENSE [faq]: https://jda.wiki/introduction/faq/ [docs]: https://docs.jda.wiki/index.html [wiki]: https://jda.wiki/introduction/jda/ [troubleshooting]: https://jda.wiki/using-jda/troubleshooting/ [discord-shield]: https://discord.com/api/guilds/125227483518861312/widget.png [faq-shield]: https://img.shields.io/badge/Wiki-FAQ-blue.svg [docs-shield]: https://img.shields.io/badge/Wiki-Docs-blue.svg [troubleshooting-shield]: https://img.shields.io/badge/Wiki-Troubleshooting-darkgreen.svg [license-shield]: https://img.shields.io/badge/License-Apache%202.0-white.svg [GatewayIntent]: https://docs.jda.wiki/net/dv8tion/jda/api/requests/GatewayIntent.html [JDABuilder]: https://docs.jda.wiki/net/dv8tion/jda/api/JDABuilder.html [DefaultShardManagerBuilder]: https://docs.jda.wiki/net/dv8tion/jda/api/sharding/DefaultShardManagerBuilder.html [![maven-central][]][installation] [ [![license-shield][]][license] [![discord-shield][]][discord-invite] [![faq-shield]][faq] [![docs-shield]][docs] [![troubleshooting-shield]][troubleshooting] # JDA (Java Discord API) This open source library is intended for implementing bots on Discord using the real-time gateway and REST API. It provides event based functionality to implement bots of any kind, allowing for effective and scalable applications. ## 📖 Overview The core concepts of JDA have been developed to make building scalable apps easy: 1. Event System Providing simplified events from the gateway API, to respond to any platform events in real-time without much hassle. 1. Rest Actions Easy to use and scalable implementation of REST API functionality, letting you choose between callbacks with combinators, futures, and blocking. The library also handles rate-limits imposed by Discord automatically, while still offering ways to replace the default implementation. 1. Customizable Cache Trading memory usage for better performance where necessary, with sane default presets to choose from and customize. You can learn more by visiting our [wiki][wiki] or referencing our [Javadocs][docs]. ## 🔬 Installation [ [ This library is available on maven central. The latest version is always shown in the [GitHub Release](https://github.com/discord-jda/JDA/releases/latest). The minimum java version supported by JDA is **Java SE 8**. JDA also uses JSR 305 to support solid interoperability with Kotlin out of the box. > [!NOTE] > To use JDA for audio connections, you must also add a dependency that implements the [DAVE Protocol](https://daveprotocol.com/). See [Making a Music Bot](https://jda.wiki/using-jda/making-a-music-bot/) for details. ### Gradle ```gradle repositories { mavenCentral() } dependencies { implementation("net.dv8tion:JDA:$version") { // replace $version with the latest version // Optionally disable audio natives to reduce jar size by excluding `opus-java` and `tink` // Gradle DSL: // exclude module: 'opus-java' // required for encoding audio into opus, not needed if audio is already provided in opus encoding // exclude module: 'tink' // required for encrypting and decrypting audio // Kotlin DSL: // exclude(module="opus-java") // required for encoding audio into opus, not needed if audio is already provided in opus encoding // exclude(module="tink") // required for encrypting and decrypting audio } } ``` ### Maven ```xml net.dv8tion JDA $version ``` ## 🤖 Creating a Bot To use this library, you have to create an Application in the [Discord Application Dashboard](https://discord.com/developers/applications) and grab your bot token. You can find a step-by-step guide for this in our wiki page [Creating a Discord Bot](https://jda.wiki/using-jda/getting-started/#creating-a-discord-bot). ## 🏃‍♂️ Getting Started We provide a number of [examples](https://github.com/discord-jda/JDA/tree/master/src/examples/java) to introduce you to JDA. You can also take a look at our official [Wiki][wiki], [Documentation][docs], and [FAQ][faq]. Every bot implemented by JDA starts out using the [JDABuilder][JDABuilder] or [DefaultShardManagerBuilder][DefaultShardManagerBuilder]. Both builders provide a set of default presets for cache usage and events it wants to receive: - `createDefault` - Enables cache for users who are active in voice channels and all cache flags - `createLight` - Disables all user cache and cache flags - `create` - Enables member chunking, caches all users, and enables all cache flags We recommend reading the guide on [caching and intents](https://jda.wiki/using-jda/gateway-intents-and-member-cache-policy/) to get a feel for configuring your bot properly. Here are some possible use-cases: ### Example: Message Logging > [!NOTE] > The following example makes use of the **privileged intent** `GatewayIntent.MESSAGE_CONTENT`, which must be explicitly enabled in your application dashboard. You can find out more about intents in our [wiki guide](https://jda.wiki/using-jda/gateway-intents-and-member-cache-policy/). Simply logging messages to the console. Making use of [JDABuilder][JDABuilder], the intended entry point for smaller bots that don't intend to grow to thousands of guilds. Starting your bot and attaching an event listener, using the right [intents][GatewayIntent]: ```java public static void main(String[] args) { JDABuilder.createLight(token, EnumSet.of(GatewayIntent.GUILD_MESSAGES, GatewayIntent.MESSAGE_CONTENT)) .addEventListeners(new MessageReceiveListener()) .build(); } ``` Your event listener could look like this: ```java public class MessageReceiveListener extends ListenerAdapter { @Override public void onMessageReceived(MessageReceivedEvent event) { System.out.printf("[%s] %#s: %s\n", event.getChannel(), event.getAuthor(), event.getMessage().getContentDisplay()); } } ``` You can find a more thorough example with the [MessageLoggerExample](https://github.com/discord-jda/JDA/blob/master/src/examples/java/MessageLoggerExample.java) class. ### Example: Slash Command Bot This is a bot that makes use of [interactions](https://jda.wiki/using-jda/interactions/) to respond to user commands. Unlike the message logging bot, this bot can work without any enabled intents, since interactions are always available. ```java public static void main(String[] args) { JDA jda = JDABuilder.createLight(token, Collections.emptyList()) .addEventListeners(new SlashCommandListener()) .build(); // Register your commands to make them visible globally on Discord: CommandListUpdateAction commands = jda.updateCommands(); // Add all your commands on this action instance commands.addCommands( Commands.slash("say", "Makes the bot say what you tell it to") .addOption(STRING, "content", "What the bot should say", true), // Accepting a user input Commands.slash("leave", "Makes the bot leave the server") .setContexts(InteractionContextType.GUILD) // this doesn't make sense in DMs .setDefaultPermissions(DefaultMemberPermissions.DISABLED) // only admins should be able to use this command. ); // Then finally send your commands to discord using the API commands.queue(); } ``` An event listener that responds to commands could look like this: ```java public class SlashCommandListener extends ListenerAdapter { @Override public void onSlashCommandInteraction(SlashCommandInteractionEvent event) { switch (event.getName()) { case "say" -> { String content = event.getOption("content", OptionMapping::getAsString); event.reply(content).queue(); } case "leave" -> { event.reply("I'm leaving the server now!") .setEphemeral(true) // this message is only visible to the command user .flatMap(m -> event.getGuild().leave()) // append a follow-up action using flatMap .queue(); // enqueue both actions to run in sequence (send message -> leave guild) } } } } ``` You can find a more thorough example with the [SlashBotExample](https://github.com/discord-jda/JDA/blob/master/src/examples/java/SlashBotExample.java) class. ## 🚀 RestAction In this library, the [RestAction](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html) interface is used as a request builder for all API endpoints. This interface represents a lazy request builder, as shown in this simple example: ```java channel.sendMessage("Hello Friend!") .addFiles(FileUpload.fromData(greetImage)) // Chain builder methods to configure the request .queue() // Send the request asynchronously ``` > [!IMPORTANT] > The final call to [`queue()`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#queue%28%29) sends the request. > You can also send the request synchronously or using futures, check out our extended guide in the [RestAction Wiki](https://jda.wiki/using-jda/using-restaction/). The RestAction interface also supports a number of operators to avoid callback hell: - [`map`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#map%28java.util.function.Function%29) Convert the result of the `RestAction` to a different value - [`flatMap`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#flatMap%28java.util.function.Function%29) Chain another `RestAction` on the result - [`delay`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#delay%28java.time.Duration%29) Delay the element of the previous step As well as combinators like: - [`and`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#and(net.dv8tion.jda.api.requests.RestAction,java.util.function.BiFunction)) Require another RestAction to complete successfully, running in parallel - [`allOf`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#allOf(java.util.Collection)) Accumulate a list of many actions into one (see also [`mapToResult`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#mapToResult())) - [`zip`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#zip(net.dv8tion.jda.api.requests.RestAction,net.dv8tion.jda.api.requests.RestAction...)) Similar to `and`, but combines the results into a list And configurators like: - [`timeout`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#timeout(long,java.util.concurrent.TimeUnit)) and [`deadline`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#deadline(long)) Configure how long the action is allowed to be in queue, cancelling if it takes too long - [`setCheck`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html#setCheck(java.util.function.BooleanSupplier)) Running some checks right before the request is sent, this can be helpful when it is in queue for a while - [`reason`](https://docs.jda.wiki/net/dv8tion/jda/api/requests/restaction/AuditableRestAction.html#reason(java.lang.String)) The [audit log reason](https://discord.com/developers/docs/resources/audit-log) for an action **Example**: ```java public RestAction selfDestruct(MessageChannel channel, String content) { return channel.sendMessage("The following message will destroy itself in 1 minute!") .addComponents(ActionRow.of(Button.danger("delete", "Delete now"))) // further amend message before sending .delay(10, SECONDS, scheduler) // after sending, wait 10 seconds .flatMap((it) -> it.editMessage(content)) // then edit the message .delay(1, MINUTES, scheduler) // wait another minute .flatMap(Message::delete); // then delete } ``` This could then be used in code: ```java selfDestruct(channel, "Hello friend, this is my secret message").queue(); ``` ## 🧩 Extensions ### [jda-ktx](https://github.com/MinnDevelopment/jda-ktx) Created and maintained by [MinnDevelopment](https://github.com/MinnDevelopment). Provides [Kotlin](https://kotlinlang.org/) extensions for **RestAction** and events that provide a more idiomatic Kotlin experience. ```kotlin fun main() { val jda = light(BOT_TOKEN) jda.onCommand("ping") { event -> val time = measureTime { event.reply("Pong!").await() // suspending }.inWholeMilliseconds event.hook.editOriginal("Pong: $time ms").queue() } } ``` There are a number of examples available in the [README](https://github.com/MinnDevelopment/jda-ktx/#jda-ktx). ### [Lavaplayer](https://github.com/lavalink-devs/lavaplayer) Created by [sedmelluq](https://github.com/sedmelluq) and now maintained by the [lavalink community](https://github.com/lavalink-devs) Lavaplayer is the most popular library used by Music Bots created in Java. It is highly compatible with JDA and Discord4J and allows playing audio from YouTube, Soundcloud, Twitch, Bandcamp and [more providers](https://github.com/lavalink-devs/lavaplayer#supported-formats). The library can easily be expanded to more services by implementing your own AudioSourceManager and registering it. We recommend to also use [udpqueue](#udpqueue-an-extension-of-jda-nas) in addition to lavaplayer, to avoid stuttering issues caused by GC pauses. It is recommended to read the [Usage](https://github.com/lavalink-devs/lavaplayer#usage) section of Lavaplayer to understand a proper implementation. Sedmelluq provided a demo in his repository which presents an example implementation for JDA: https://github.com/lavalink-devs/lavaplayer/tree/master/demo-jda ### [udpqueue](https://github.com/MinnDevelopment/udpqueue.rs) (an extension of [jda-nas](https://github.com/sedmelluq/jda-nas)) Created and maintained by [sedmelluq](https://github.com/sedmelluq) and extended by [MinnDevelopment](https://github.com/MinnDevelopment) Provides a native implementation for the JDA Audio Send-System **to avoid GC pauses potentially causing problems** with continuous audio playback. Note that this send-system creates an extra UDP-Client which causes audio receive to no longer function properly, since Discord identifies the sending UDP-Client as the receiver. ```java JDABuilder builder = JDABuilder.createDefault(BOT_TOKEN) .setAudioSendFactory(new NativeAudioSendFactory()); ``` ### [Lavalink](https://github.com/lavalink-devs/Lavalink) Created by [Freya Arbjerg](https://github.com/freyacodes) and now maintained by the [lavalink community](https://github.com/lavalink-devs). Lavalink is a popular standalone audio sending node based on Lavaplayer. Lavalink was built with scalability in mind, and allows streaming music via many servers. It supports most of Lavaplayer's features. Lavalink is used by many large bots, as well as bot developers who can not use a Java library like Lavaplayer. If you plan on serving music on a smaller scale with JDA, it is often preferable to just use Lavaplayer directly as it is easier. [Lavalink-Client](https://github.com/FredBoat/Lavalink-Client) is the official Lavalink client for JDA. ## 🛠️ Contributing to JDA If you want to contribute to JDA, make sure to base your branch off of our **master** branch (or a feature-branch) and create your PR into that **same** branch. Please follow our [Contributing Guidelines](https://github.com/discord-jda/JDA/blob/master/.github/CONTRIBUTING.md). Do not expect your pull request to get immediate attention, sometimes it will take a long time to get a response. You can join our [discord server][discord-invite] and ask in [#lib-dev](https://discord.com/channels/125227483518861312/869965829024915466) before starting to work on a new PR, to get more immediate feedback from our community members. ## 🚨 Breaking Changes Due to the nature of the Discord API, the library will regularly introduce breaking changes to allow for a quick adoption of newer features. We try to keep these breaking changes minimal, but cannot avoid them entirely. Most breaking changes will result in a **minor** version bump (`5.1.2` → `5.2.0`). --- ## File: src/main/java/net/dv8tion/jda/internal/entities/channel/mixin/README.md # Entity Mixins Entity Mixins are a system in JDA that provide the following core functionalities: - Code reuse through composition instead of purely through inheritence - A way to expose internal state setters and getters without exposing them to the library user ## Example Mixin with Usage ```java //Publicly exposed entity api interface public interface SomeEntity { String getName(); default String getNameTwice() { return getName() + "-" + getName(); } RestAction updateName(String name); } //Internal mixin for that entity for code reuse and state exposing public interface SomeEntityMixin> extends SomeEntity { //---- Default implementations of interface ---- @Override default RestAction updateName(String name) { checkCanModifyEntity(); Route.CompiledRoute route = Route.custom(Method.POST, "/someEntity/name/"); return new RestActionImpl<>(route); } //---- State Accessors ---- T setName(String name); //---- Mixin Hooks ----- void checkCanModifyEntity(); } //Internal concrete implementation of the entity public class SomeEntityImpl implements SomeEntityMixin { private String name; public SomeEntityImpl() {} @Override public String getName() { return name; } @Override public SomeEntityImpl setName(String name) { this.name = name; } @Override public void checkCanModifyEntity() { //Do some check here, throw if check is bad! } } ``` ## Mixin Anatomy Table of Contents - Default implementations of interface - Default implementation of parent mixins hooks - State Accessors - Mixin Hooks - Helpers ### `---- Default implementations of interface ----` These consist of the `default` implementation of any methods that aren't already implemented via `default` in the interface itself that can be implemented via any of the `State Accessors` or `Mixin Hooks` added. Basically everything in the interface should be able to be implemented here. The only things that will not be implemented are basic getter methods that map _directly_ to underlying state with 0 modification. Example: ```java int getBitrate(); ``` This getter will map _directly_ to the `int bitrate` field of the underlying class and there's nothing we can do to implement this in the mixin. In contrast, a _calculated_ getter (or any other methods) can and should be implemented via the exposing of a `State Accessor` or `Mixin Hook`. For example: ```java // ---- Default implementations of interface ---- default List getPermissionOverrides() { TLongObjectMap overrides = getPermissionOverrideMap(); return Arrays.asList(overrides.values(new PermissionOverride[overrides.size()])); } // ---- State Accessors ---- TLongObjectMap getPermissionOverrideMap(); ``` ### `---- Default implementation of parent mixins hooks ----` These are very similar to the `Default implementations of interface` methods, however, instead of providing `default` implementations for the selected interface they are providing `default` implementations of `Mixin Hooks` defined by any of the parent mixins that this mixin may be extending. The same rules that apply to `Default implementations of interface` apply to these, they just live in a different section to better drill home where they're coming from. ### `---- State Accessors ----` State accessors are hooks that the mixin defines that give it access to the underlying state that is implemented in the concrete object so that the mixin can implement additional `default` functionality that would rely on accessing the state in the concrete object. For example, the `IPermissionContainerMixin` implements the `IPermissionContainer#getPermissionOverrides` method via usage of a state accessor to access the underlying map. See the example in `Default implementations of interface` as it shows the expected State Accessor declaration. This is what would be expected to be implemented by the concrete channel type that uses the `IPermissionContainerMixin` ```java TLongObjectMap overrides = MiscUtil.newLongMap(); @Override public TLongObjectMap getPermissionOverrideMap() { return overrides; } ``` Additionally, state accessors provide a way to expose interface-specific setters or getters used outside the mixin. This can include setters and getters for updating fields when entities update, or underlying maps when relationships update. For example, the `AudioChannelMixin` exposes: ```java TLongObjectMap getConnectedMembersMap(); ``` It does this so that methods that handle people joining and leaving audio channels can properly update the connected user mapping without needing to know the underlying channel type. ### `---- Mixin Hooks ----` Mixin Hooks are very similar to State Accessors. The difference being that while they are methods that must be implemented by subclasses of the mixin so that the mixin can provide additional `default` functionality, they aren't intended to map directly to underlying state. They are simply hooks that need to be filled in so that the mixin has all the information it needs to do its job. ### `---- Helpers ----` This section of methods is just for defining helper methods used by this mixin or the mixin/classes that subclass it. Nothing special to mention beyond that.