Java interface for the official Discord API, written in Java 8. The API is also available in a few other languages.
For the latest dev builds, use the short commit hash or dev-SNAPSHOT
as your version.
Adding Discord4J as a dependency for a project
Given that @VERSION@
= the a version of Discord4J (this can either be a release version, the short commit hash or dev-SNAPSHOT
).
With Maven
In your pom.xml
add:
...
<repositories>
...
<repository> <!-- This repo fixes issues with transitive dependencies -->
<id>jcenter</id>
<url>http://jcenter.bintray.com</url>
</repository>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
...
<dependencies>
...
<dependency>
<groupId>com.github.austinv11</groupId>
<artifactId>Discord4j</artifactId>
<version>@VERSION@</version>
<!-- <classifier>shaded</classifier> <!-- Include this line if you want a shaded jar (all the Discord4J dependencies bundled into one jar)-->
</dependency>
</dependencies>
...
With Gradle
In your build.gradle
add:
...
repositories {
...
jcenter() //This prevents issues with transitive dependencies
maven {
url "https://jitpack.io"
}
}
...
dependencies {
...
compile "com.github.austinv11:Discord4j:@VERSION@"
//compile "com.github.austinv11:Discord4j:@VERSION@:shaded" //Use this line instead of the one above it if you want a shaded jar (all the Discord4J dependencies bundled into one jar)
}
...
So, how do I use this?
Tutorials/Resources
- The Discord4J Tutorial Series maintained by @Panda
- A quick overview of the AudioPlayer by @oopsjpeg
- A Discord Bot quick start example maintined by @quantic
- A simple Discord4J module example by @Martacus
Starting with the API
The very first thing you need to do is obtain a "DiscordClient" object. This can be done by using the ClientBuilder
.
Example:
public class Example {
public static IDiscordClient getClient(String token, boolean login) { // Returns an instance of the Discord client
ClientBuilder clientBuilder = new ClientBuilder(); // Creates the ClientBuilder instance
clientBuilder.withToken(token); // Adds the login info to the builder
if (login) {
return clientBuilder.login(); // Creates the client instance and logs the client in
} else {
return clientBuilder.build(); // Creates the client instance but it doesn't log the client in yet, you would have to call client.login() yourself
}
}
}
Events
The Discord4J library is very event driven. Your bot can detect these events through the use of an event listener. There are two ways of creating an event listener:
- Using
IListener
:
public class InterfaceListener implements IListener<ReadyEvent> { // The event type in IListener<> can be any class which extends Event
@Override
public void handle(ReadyEvent event) { // This is called when the ReadyEvent is dispatched
doCoolStuff();
}
}
- Using the
@EventSubscriber
annotation:
public class AnnotationListener {
@EventSubscriber
public void onReadyEvent(ReadyEvent event) { // This method is called when the ReadyEvent is dispatched
foo();
}
public void onMessageReceivedEvent(MessageReceivedEvent event) { // This method is NOT called because it doesn't have the @EventSubscriber annotation
bar();
}
}
Registering your listener:
public class Main {
public static void main(String[] args) {
IDiscordClient client = Example.getClient(args[0], args[1], true); // Gets the client object (from the first example)
EventDispatcher dispatcher = client.getDispatcher(); // Gets the EventDispatcher instance for this client instance
dispatcher.registerListener(new InterfaceListener()); // Registers the IListener example class from above
dispatcher.registerListener(new AnnotationListener()); // Registers the @EventSubscriber example class from above
}
}
Modules
Discord4J has an API for creating modular Discord Bots! See [Martacus's sample repo](https://github .com/Martacus/Simplecommands/tree/master) for an example as to how it works.
More examples
See the examples directory.
Projects using Discord4J
- Official Discord4J Addons: A collection of official addons and modules for Discord4J (https://github.com/Discord4J-Addons)
- D4J/JDA Player by @DV8FromTheWorld: A full-featured audio player for Discord4J and JDA (https://github.com/DV8FromTheWorld/JDA-Player)
- Discordinator by @alpha;helix: A modularized command API (https://github.com/alphahelix00/Discordinator)
- Instructability by @Kaioru: A simple command API (https://github.com/Kaioru/Instructability)
Deprecation policy
Due to the nature of the Discord API, any deprecations found in the API should not be expected to last past the current version. Meaning that if a method is deprecated on version 2.1.0, do not assume the method will be available in version 2.2.0.
Development
The Discord API is still in development. Functions may break at any time.
In such an event, please contact me or submit a pull request.
Pull requests
No one is perfect at programming and I am no exception. If you see something that can be improved, please read the contributing guildelines and feel free to submit a pull request!
Other info
More information can be found in the javadocs.
You can contact me on the Official Discord4J Server (recommended) or the Discord API server in the #java_discord4j channel.