A Discord API Wrapper for Java
- Builders and managers to makes creating and managing discord objects easier.
- Multiple choices for receiving events.
- Easy to use command system via reflection.
- Post bot status to bot listing websites automatically.
- Built in support for Webhook and OAuth 2
- Get emojis by aliases use in Discord. No more external emoji dependencies.
- All Jars
- Gradle (In your
build.gradle
file)
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compile 'com.github.AlienIdeology:J-Cord:-SNAPSHOT'
}
- Maven (In your
pom.xml
file)
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependency>
<groupId>com.github.AlienIdeology</groupId>
<artifactId>J-Cord</artifactId>
<version>-SNAPSHOT</version>
</dependency>
Note: Using -SNAPSHOT
as the version will automatically be the latest commit from
branch master
. To use the latest commit of other branches, use BranchName-SNAPSHOT
.
You may also use a release tag
or commit hash
to specify the version you intend to use.
Ask questions in the Discord Support Server or open an issue.
- Build an Identity
Identity bot = new IdentityBuilder()
.setIdentityType(IdentityType.BOT)
.useToken(Token.TOP_SECRET)
.setEventManager(
new EventManager().registerDispatchers(
new ExampleDispatcher())
)
.build(true);
- Ways to subscribe to events:
- Use
DispatcherAdaptor
Objects registered as adaptors must extends DispatcherAdaptor.
DispatcherAdaptor example:
public class ExampleDispatcher extends DispatcherAdaptor {
@Override
public void onMessageCreate (MessageCreateEvent event) {
if (event.getMessage().getContent().startsWith("?") { // Prefix
// Do stuff
}
}
}
When building identity:
new EventManager().registerDispatchers(
new ExampleDispatcher())
)
- Use
EventSubscriber
annotation Register objects that have methods annotates as EventSubscriber.
EventSubscriber example:
public class ExampleSubscriber {
@EventSubscriber
public void onMessageCreateEvent(MessageCreateEvent event) {
System.out.println(event.getChannel());
}
}
When building identity:
new EventManager().registerEventSubscriber(
new ExampleSubscriber()
)
- Wait for an Event
- Asynchronously (Perform the consumer action when a specified event is dispatched before the timeout)
// Get the Event Manager eventManager.<MessageCreateEvent>onNext( event -> event.getUser().isSelf(), // Only get message create events that are from the identity event -> System.out.println("I just said: " + event.getMessage().getContent(), // Perform actions 3000, // Timeouts in millisecond () -> System.out.println("Still no response after 30 seconds!") // Actions to perform if timeout exceeds );
- Synchronously (Blocking the thread until event dispatched or timeout exceeds)
// Get the Event Manager MessageCreateEvent event = eventManager.waitForNext( event -> event.getUser().isSelf(), // Only get message create events that are from the identity 3000, // Timeouts in millisecond () -> System.out.println("Still no response after 30 seconds!") // Actions to perform if timeout exceeds ); System.out.println("I just said: " + event.getMessage().getContent()
- Create classes that implements CommandResponder (Empty interface)
- Annotate methods as @Command
public class ExampleResponder implements CommandResponder {
@Command (aliases = {"ping", "pong", "thump"})
public String onPingCommand (String[] args, MessageCreateEvent event) {
return event.getUser().mention()+" pong!";
}
}
- Register CommandResponders in a CommandFramework
- Register the CommandFramework in EventManager
new EventManager().registerCommandFrameworks(
new CommandFramework()
.setPrefixes("=").registerCommandResponder(
new ExampleResponder()
)
)
- Setting Up the Agent
PostAgent agent = PostAgent.DISCORD_BOTS .setIdentity(identity) // Set the Identity object, which is used to post shard and guild count .setAPIToken(YOUR_TOKEN_HERE) // The token for Discord Bots API .post(); // Post the status
PostAgent agent = PostAgent.DISCORD_BOT_LIST .setIdentity(identity) .setAPIToken(YOUR_TOKEN_HERE) // The token for Discord Bot List API .post(); // Post the status
PostAgent agent = PostAgent.DISCORD_LIST .setIdentity(identity) .addPostField("token", YOUR_TOKEN_HERE) // The token for Discord List API .post(); // Post the status
- Custom website
PostAgent agent = new PostAgent(identity) .setAPIName("Discord Bla Bla Bla Bots Bla Bla Bla List") // Isn't the name typically like that? .setPostUrl("same_api_endpoint") // An API EndPoint URL .setJsonShardIDKey("shard_id") // The json field for shard ID (0 based) .setJsonShardKey("shard_count") // The json field for shard count .setJsonServerKey("server_count") // The server count .addPostField("some_json_key", "some_value") // Add whatever is required .post(); // Or you can use .post(Consumer<MultipartBody>) to add custom fields or headers, too
- Post Automatically
Every post agent will automatically post status onGuildCreateEvent
,GuildUnavailableEvent
, andGuildDeleteEvent
.
You can cancel the auto post by calling:agent.setAutoPost(false); // To enable this again, invoke agent.setAutoPost(true);
- Using the
OAuthBuilder
OAuthBuilder builder = new OAuthBuilder()
.setClientId(ID) // Application's ID
.setClientSecret(SECRET) // Application's secret
.setRedirectUrl(URL) // Used to redirect an user agent and provide authorization code for the oauth
.setScopes(Scope.BOT, Scope.IDENTIFY);
- Get the Authorization URL for the application
String authorizationUrl = builder.buildUrl();
- Build an
OAuth
instance
OAuth application = builder
.buildOAuth()
.autoAuthorize(); // Automatically get the authorization code
- Get Emojis:
List<Emoji> emojis;
emojis = Emojis.EMOJIS; // A collection of all emojis in Discord
emojis = Emojis.getByCategory(EmojiCategory.PEOPLE); // Returns a list of emojis that belongs to the "people" category
- Get an Emoji by an attribute:
Emoji emoji;
emoji = Emojis.getByName("face with tears of joy");
emoji = Emojis.getByKeyword("laugh");
emoji = Emojis.getByAlias(":joy:");
emoji = Emojis.getByUnicode("\uD83D\uDE02");
// All the methods above returns the emoji "😂"
See this GitGub repository.
Please fork this project, and read Contributing.md. Use Issue Template.md for creating issues, and use Pull Request Template.md for creating pull requests.
- NV Websocket Client
v2.2
- NanoHTTPD
v2.2.0
- Unirest for Java
v1.4.9
- JSON-java
v20160212
- Apache Commons Lang 3
v3.4
- Apache Commons IO
2.5
- JetBrains Annotations
v15.0
- TypeTools
v0.5.0