This project is no longer maintained. I don't have time to maintain it anymore, and I don't really use Discord's API much anymore anyway. If you want to maintain this library, please see issue #729.
A Discord API wrapper in Java. Fully async / reactive, built on top of RxJava. catnip tries to map roughly 1:1 to how the Discord API works, both in terms of events and REST methods available. catnip uses Java 17+.
catnip is part of the amyware Discord server.
Licensed under the BSD 3-Clause License.
Current version:
No. Use a real build tool like Maven or Gradle.
EXTENSIONS.md
for more.MODULAR_USAGE.md
for more.CACHING.md
for more.This is the simplest possible bot you can make right now:
final Catnip catnip = Catnip.catnip("your token goes here");
catnip.observable(DiscordEvent.MESSAGE_CREATE)
.filter(msg -> msg.content().equals("!ping"))
.subscribe(msg -> {
msg.respond("pong!");
}, error -> error.printStackTrace());
catnip.connect();
catnip returns RxJava operators (Completable
/Observable
/Single
/...) from
all REST methods. For example, editing your ping message to include time it
took to create the message:
final Catnip catnip = Catnip.catnip("your token goes here");
catnip.observable(DiscordEvent.MESSAGE_CREATE)
.filter(msg -> msg.content().equals("!ping"))
.subscribe(msg -> {
long start = System.currentTimeMillis();
msg.respond("pong!")
.subscribe(ping -> {
long end = System.currentTimeMillis();
ping.edit("pong! (took " + (end - start) + "ms).");
});
}, error -> error.printStackTrace());
catnip.connect();
You can also create a catnip instance asynchronously:
Catnip.catnipAsync("your token here").subscribe(catnip -> {
catnip.observable(DiscordEvent.MESSAGE_CREATE)
.filter(msg -> msg.content().equals("!ping"))
.subscribe(msg -> {
msg.respond("pong!");
}, error -> error.printStackTrace());
catnip.connect();
});
Also check out the examples for Kotlin and Scala usage.
Observable#forEach
seems like the obvious way to use the reactive methods, but as it turns out,
it's also the wrong thing to do. Observable#forEach
is generally intended for finite streams of
data; the events that catnip emits aren't finite, and as such, Observable#forEach
isn't the
correct tool to use. In addition, Observable#forEach
will stop processing events if an uncaught
exception is thrown. Instead, you should use Observable#subscribe(eventCallback, exceptionCallback)
,
which will handle exceptions properly.
catnip supports being used in REST-only or shards-only configurations. The nice thing about catnip
is that using it like this is exactly the same as using it normally. The only difference is
that to use catnip in REST-only mode, you don't call catnip.connect()
and use
catnip.rest().whatever()
instead.
By default, RxJava's Observable#subscribe()
and related methods will not operate on any
particular scheduler by default. That is, they will run on the calling thread. catnip will
automatically subscribe RxJava objects onto a scheduler provided by catnip, that defaults
to being a ForkJoinPool-based scheduler. You can customize the scheduler used with the
corresponding option in CatnipOptions
.
catnip-voice
- Voice support for your catnip bot.
https://github.com/natanbc/catnip-voicecatnip-utilities
- Some extensions for typesafe commands, event waiters, reaction menus,
and more. https://github.com/queer/catnip-utilities discordbotlist-stats-catnip
- Wrapper aiming at combining all Discord Bot Lists AND Wrappers into one artifact.
Automatically handles pushing bot stats to bot lists. https://github.com/burdoto/discordbotlist-stats#using-with-catnip--Future
-like classes. I do get why other libs
have them, I just wanted to not.