J-Cord

A Discord API Wrapper for Java

Features

• 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.

Download

• 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.

Support

Ask questions in the Discord Support Server or open an issue.

How to Use

Bot & Selfbot

Identity

• Build an Identity

Identity bot = new IdentityBuilder()
    .setIdentityType(IdentityType.BOT)
    .useToken(Token.TOP_SECRET)
    .setEventManager(
        new EventManager().registerDispatchers(
            new ExampleDispatcher())
        )
    .build(true);

Event

• Ways to subscribe to events:
  

1. 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())
    )

2. 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()

Command System

1. Create classes that implements CommandResponder (Empty interface)
2. 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!";
    }
}

3. Register CommandResponders in a CommandFramework
4. Register the CommandFramework in EventManager

new EventManager().registerCommandFrameworks(
    new CommandFramework()
        .setPrefixes("=").registerCommandResponder(
            new ExampleResponder()
        )
)

PostAgent

• Setting Up the Agent
  1. DiscordBots

  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

  2. Discord Bot List

  PostAgent agent = PostAgent.DISCORD_BOT_LIST
      .setIdentity(identity)
      .setAPIToken(YOUR_TOKEN_HERE) // The token for Discord Bot List API
      .post(); // Post the status

  3. Discord List

  PostAgent agent = PostAgent.DISCORD_LIST
      .setIdentity(identity)
      .addPostField("token", YOUR_TOKEN_HERE) // The token for Discord List API
      .post(); // Post the status

  4. 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 on GuildCreateEvent, GuildUnavailableEvent, and GuildDeleteEvent.
  You can cancel the auto post by calling:

  agent.setAutoPost(false); // To enable this again, invoke agent.setAutoPost(true);

OAuth

• 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

Emoji

• 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 "😂"

Examples

See this GitGub repository.

Contributing

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.

Dependencies

• 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

More

• Javadocs Generated by JitPack
• Todo List: Todo.md
• Project structure:
  • Object Hierarchy.md
  • Event Hierarchy.md
• Don't forget to check out the Wiki