Skip to content

Commit

Permalink
[Gradle Release Plugin] - pre tag commit: 'v3.0.6'.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Javacord-CI
Javacord-CI committed May 10, 2020
1 parent d502d7f commit 66e6b04
Show file tree
Hide file tree
Showing 3 changed files with 165 additions and 80 deletions.
2 changes: 1 addition & 1 deletion .github/README.md.sha256
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
87828c8747d7ddab7f5617287553c11a296487e8c7df4881d6bf2210faae96c9
7b7fd89b960a597a68ba5ae3def6618e5f5da9002c0fe695cbd50eadedf78e4c
241 changes: 163 additions & 78 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,46 +1,75 @@
![](https://javacord.org/img/javacord3_banner.png)
# Javacord [![Latest version](https://shields.javacord.org/github/release/Javacord/Javacord.svg?label=Version&colorB=brightgreen&style=flat-square)](https://github.com/Javacord/Javacord/releases/latest) [![Latest JavaDocs](https://shields.javacord.org/badge/JavaDoc-Latest-yellow.svg?style=flat-square)](https://docs.javacord.org/api/v/latest/) [![Javacord Wiki](https://shields.javacord.org/badge/Wiki-Home-red.svg?style=flat-square)](https://javacord.org/wiki/) [![Javacord Discord server](https://shields.javacord.org/discord/151037561152733184.svg?colorB=%237289DA&label=Discord&style=flat-square)](https://discord.gg/0qJ2jjyneLEgG7y3)

An easy to use multithreaded library for creating Discord bots in Java.

## Feature Coverage
Javacord is a modern library that focuses on simplicity and speed ????.
By reducing itself to standard Java classes and features like [`Optional`](https://javacord.org/wiki/essential-knowledge/working-with-optionals/)s and [`CompletableFuture`](https://javacord.org/wiki/essential-knowledge/working-with-futures/)s, it is extremely easy to use for every Java developer, as it does not require you to learn any new frameworks or complex abstractions.
It has rich [documentation](#-documentation) and an [awesome community on Discord](#-support) that loves to help with any specific problems and questions.

## ???? Basic Usage

The following example logs the bot in and replies to every "!ping" message with "Pong!".

```java
public class MyFirstBot {

public static void main(String[] args) {
// Insert your bot's token here
String token = "your token";

DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();

// Add a listener which answers with "Pong!" if someone writes "!ping"
api.addMessageCreateListener(event -> {
if (event.getMessageContent().equalsIgnoreCase("!ping")) {
event.getChannel().sendMessage("Pong!");
}
});

// Print the invite url of your bot
System.out.println("You can invite the bot by using the following url: " + api.createBotInvite());
}

Javacord supports every action a Discord bot is able to perform.
Some of these features include, but are not limited to:
}
```

- sending messages
- attaching files
- event listening
- user management
- server administration
- *... **and many others***
<img src="https://javacord.org/img/javacord-readme/ping-pong-white.gif">

**Sending voice will be added in an upcoming release**.
New features introduced by Discord are typically added in less than one week, depending on scale.
More sophisticated examples can be found at the [end of the README](#-more-examples).
You can also check out the [example bot](https://github.com/Javacord/Example-Bot) for a fully functional bot.

## Download / Installation
## ???? Download / Installation

The recommended way to get Javacord is to use a build manager, like Gradle or Maven.
If you are not familiar with build managers, you can follow this [Setup Guide](#ide-setup)
or download Javacord directly from [GitHub](https://github.com/Javacord/Javacord/releases/latest).
If you are not familiar with build managers, you can follow this [setup guide](#-ide-setup) or download Javacord directly from [GitHub](https://github.com/Javacord/Javacord/releases/latest).

### Javacord Dependency

#### Gradle

```groovy
repositories { mavenCentral() }
dependencies { implementation 'org.javacord:javacord:3.0.5' }
dependencies { implementation 'org.javacord:javacord:3.0.6' }
```

#### Maven

```xml
<dependency>
<groupId>org.javacord</groupId>
<artifactId>javacord</artifactId>
<version>3.0.5</version>
<version>3.0.6</version>
<type>pom</type>
</dependency>
```

#### Sbt

```scala
libraryDependencies ++= Seq("org.javacord" % "javacord" % "3.0.6")
```

### Optional Logger Dependency

Any Log4j-2-compatible logging framework can be used to provide a more sophisticated logging experience
Expand All @@ -51,100 +80,156 @@ For example, Log4j Core in Gradle
```groovy
dependencies { runtimeOnly 'org.apache.logging.log4j:log4j-core:2.11.0' }
```
Take a look at the [Logger Configuration](https://javacord.org/wiki/basic-tutorials/logger-configuration/) wiki article for further information.
Take a look at the [logger configuration](https://javacord.org/wiki/basic-tutorials/logger-configuration/) wiki article for further information.

## IDE Setup
## ???? IDE Setup

If you have never used Gradle or Maven before, you should take a look at one of the setup tutorials:
* **[IntelliJ & Gradle](https://javacord.org/wiki/getting-started/intellij-gradle/)** _(recommended)_
* **[IntelliJ & Maven](https://javacord.org/wiki/getting-started/intellij-maven/)**
* **[Eclipse & Maven](https://javacord.org/wiki/getting-started/eclipse-maven/)**

## Support
## ???? Support

Javacord's Discord community is an excellent resource if you have questions about the library.
* **[The Javacord Server](https://discord.gg/0qJ2jjyneLEgG7y3)**
* **[The Javacord server](https://discord.gg/0qJ2jjyneLEgG7y3)**

## Documentation
## ???? Documentation

* The [Javacord Wiki](https://javacord.org/wiki/) is a great place to get started
* Additional documentation can be found in the [JavaDoc](https://docs.javacord.org/api/v/latest/)
* The [Javacord wiki](https://javacord.org/wiki/) is a great place to get started.
* Additional documentation can be found in the [JavaDoc](https://docs.javacord.org/api/v/latest/).

## Logging in
## ???? How to Create a Bot User and Get Its Token

Logging in is very simple
```java
public class MyFirstBot {
* **[Creating a Bot User Account](https://javacord.org/wiki/essential-knowledge/creating-a-bot-account/)**

public static void main(String[] args) {
// Insert your bot's token here
String token = "your token";
## ???? Version Numbers

DiscordApi api = new DiscordApiBuilder().setToken(token).login().join();
The version number has a 3-digit format: `major.minor.trivial`
* `major`: Increased extremely rarely to mark a major release (usually a rewrite affecting very huge parts of the library).
* `minor`: Any backward incompatible change to the api.
* `trivial`: A backward compatible change to the **api**. This is usually an important bugfix (or a bunch of smaller ones)
or a backwards compatible feature addition.

## ???? Deprecation Policy

// Add a listener which answers with "Pong!" if someone writes "!ping"
api.addMessageCreateListener(event -> {
if (event.getMessageContent().equalsIgnoreCase("!ping")) {
event.getChannel().sendMessage("Pong!");
}
});
A method or class that is marked as deprecated can be removed with the next minor release (but it will usually stay for
several minor releases). A minor release might remove a class or method without having it deprecated, but we will do our
best to deprecate it before removing it. We are unable to guarantee this though, because we might have to remove / replace
something due to changes made by Discord, which we are unable to control. Usually you can expect a deprecated method or
class to stay for at least 6 months before it finally gets removed, but this is not guaranteed.

// Print the invite url of your bot
System.out.println("You can invite the bot by using the following url: " + api.createBotInvite());
## ???? Large Bots Using Javacord

Javacord is used by many large bots. Here are just a few of them:
* [**Yunite**](https://yunite.xyz/): A bot for Fortnite which runs on over 30,000 servers with over five million users.
* [**Beemo**](https://beemo.gg/): A bot that prevents raids of many large servers such as [discord.gg/LeagueOfLegends](https://discord.gg/LeagueOfLegends), [discord.gg/VALORANT](https://discord.gg/VALORANT), and many more.

If you own a large bot that uses Javacord, feel free to add it to the list in a pull request!

## ???? More Examples

### Using the MessageBuilder ????

<img align="right" src="https://javacord.org/img/javacord-readme/message-builder.png" width="34%">

The following example uses the built-in `MessageBuilder`. It is very useful to construct complex messages with images, code-blocks, embeds, or attachments.

```java
new MessageBuilder()
.append("Look at these ")
.append("awesome", MessageDecoration.BOLD, MessageDecoration.UNDERLINE)
.append(" animal pictures! ????")
.appendCode("java", "System.out.println(\"Sweet!\");")
.addAttachment(new File("C:/Users/JohnDoe/Pictures/kitten.jpg"))
.addAttachment(new File("C:/Users/JohnDoe/Pictures/puppy.jpg"))
.setEmbed(new EmbedBuilder()
.setTitle("WOW")
.setDescription("Really cool pictures!")
.setColor(Color.ORANGE))
.send(channel);
```

### Listeners in Their Own Class ????

All the examples use inline listeners for simplicity. For better readability it is also possible to have listeners in their own class:

```java
public class MyListener implements MessageCreateListener {

@Override
public void onMessageCreate(MessageCreateEvent event) {
Message message = event.getMessage();
if (message.getContent().equalsIgnoreCase("!ping")) {
event.getChannel().sendMessage("Pong!");
}
}

}
```

You can also login non-blocking asynchronously
```java
public class MyFirstBot {
api.addListener(new MyListener());
```

public static void main(String[] args) {
// Insert your bot's token here
String token = "your token";
For commands, you have the option of using one of the many existing command frameworks such as
* [**Command Framework**](https://github.com/Vampire/command-framework) by [@Vampire](https://github.com/Vampire)
* [**Sdcf4j**](https://github.com/Bastian/sdcf4j) by [@Bastian](https://github.com/Bastian)

new DiscordApiBuilder().setToken(token).login().thenAccept(api -> {
// Add a listener which answers with "Pong!" if someone writes "!ping"
api.addMessageCreateListener(event -> {
if (event.getMessageContent().equalsIgnoreCase("!ping")) {
event.getChannel().sendMessage("Pong!");
}
});

// Print the invite url of your bot
System.out.println("You can invite the bot by using the following url: " + api.createBotInvite());
})
// Log any exceptions that happened
.exceptionally(ExceptionLogger.get());
}
or even write your own!

### Attach Listeners to Objects ????

You can even attach listeners to objects.
Let's say you have a very sensitive bot.
As soon as someone reacts with a ???? within the first 30 minutes of message creation, it deletes its own message.

```java
api.addMessageCreateListener(event -> {
if (event.getMessageContent().equalsIgnoreCase("!ping")) {
event.getChannel().sendMessage("Pong!").thenAccept(message -> {
// Attach a listener directly to the message
message.addReactionAddListener(reactionEvent -> {
if (reactionEvent.getEmoji().equalsEmoji("????")) {
reactionEvent.deleteMessage();
}
}).removeAfter(30, TimeUnit.MINUTES);
});
}
}
```
The result then looks like this:

Check out the [Example Bot](https://github.com/Javacord/Example-Bot) to learn more.
<img src="https://javacord.org/img/javacord-readme/sensitive-bot-round.gif">

## How to create a bot user and get its token
### Creating a Temporary Voice Channel ????????

* **[Creating a Bot User Account](https://javacord.org/wiki/essential-knowledge/creating-a-bot-account/)**
This example creates a temporary voice channel that gets deleted when the last user leaves it or if nobody joins it within the first 30 seconds after creation.

## Version numbers
```java
Server server = ...;
ServerVoiceChannel channel = new ServerVoiceChannelBuilder(server)
.setName("tmp-channel")
.setUserlimit(10)
.create()
.join();

// Delete the channel if the last user leaves
channel.addServerVoiceChannelMemberLeaveListener(event -> {
if (event.getChannel().getConnectedUserIds().isEmpty()) {
event.getChannel().delete();
}
});

The version number has a 3-digit format: `major.minor.trivial`
* `major`: Increased extremely rarely to mark a major release (usually a rewrite affecting very huge parts of the library).
You can expect this digit to not change for several years.
* `minor`: Any backwards incompatible change to the api. You can expect this digit to change about 1-3 times per year.
* `trivial`: A backwards compatible change to the **api**. This is usually an important bugfix (or a bunch of smaller ones)
or a backwards compatible feature addition. You can expect this digit to change 1-2 times per month.

## Deprecation policy
// Delete the channel if no user joined in the first 30 seconds
api.getThreadPool().getScheduler().schedule(() -> {
if (channel.getConnectedUserIds().isEmpty()) {
channel.delete();
}
}, 30, TimeUnit.SECONDS);
```

A method or class that is marked as deprecated can be removed with the next minor release (but it will usually stay for
several minor releases). A minor release might remove a class or method without having it deprecated, but we will do our
best to deprecate it before removing it. We are unable to guarantee this though, because we might have to remove / replace
something due to changes made by Discord, which we are unable to control. Usually you can expect a deprecated method or
class to stay for at least 6 months before it finally gets removed, but this is not guaranteed.
> **Note**: You should also make sure to remove the channels on bot shutdown (or startup)

## Discord Server
## ???? License

Join the [Javacord Server](https://discord.gg/0qJ2jjyneLEgG7y3) for support, status updates, or just chatting with other users.
Javacord is distributed under the [Apache license version 2.0](./LICENSE).
2 changes: 1 addition & 1 deletion gradle.properties
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
org.gradle.caching = true
version = 3.0.6-SNAPSHOT
version = 3.0.6

0 comments on commit 66e6b04

Please sign in to comment.