ultimategdbot-api

High-level API to conveniently build Discord bots in Java, on top of Discord4J

License

License

Categories

Categories

Discord API Business Logic Libraries
GroupId

GroupId

com.github.alex1304
ArtifactId

ArtifactId

ultimategdbot-api
Last Version

Last Version

6.0.2
Release Date

Release Date

Type

Type

jar
Description

Description

ultimategdbot-api
High-level API to conveniently build Discord bots in Java, on top of Discord4J
Project URL

Project URL

http://maven.apache.org
Source Code Management

Source Code Management

https://github.com/ultimategdbot/ultimategdbot/tree/master

Download ultimategdbot-api

How to add to project

<!-- https://jarcasting.com/artifacts/com.github.alex1304/ultimategdbot-api/ -->
<dependency>
    <groupId>com.github.alex1304</groupId>
    <artifactId>ultimategdbot-api</artifactId>
    <version>6.0.2</version>
</dependency>
// https://jarcasting.com/artifacts/com.github.alex1304/ultimategdbot-api/
implementation 'com.github.alex1304:ultimategdbot-api:6.0.2'
// https://jarcasting.com/artifacts/com.github.alex1304/ultimategdbot-api/
implementation ("com.github.alex1304:ultimategdbot-api:6.0.2")
'com.github.alex1304:ultimategdbot-api:jar:6.0.2'
<dependency org="com.github.alex1304" name="ultimategdbot-api" rev="6.0.2">
  <artifact name="ultimategdbot-api" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.github.alex1304', module='ultimategdbot-api', version='6.0.2')
)
libraryDependencies += "com.github.alex1304" % "ultimategdbot-api" % "6.0.2"
[com.github.alex1304/ultimategdbot-api "6.0.2"]

Dependencies

compile (6)

Group / Artifact Type Version
io.projectreactor : reactor-core jar 3.3.8.RELEASE
com.discord4j : discord4j-core jar 3.1.0
com.discord4j : stores-caffeine jar 3.1.3
com.github.alex1304 : rdi jar 1.0.1
org.jdbi : jdbi3-core jar
org.jdbi : jdbi3-sqlobject jar

provided (1)

Group / Artifact Type Version
com.google.code.findbugs : jsr305 jar 3.0.1

test (3)

Group / Artifact Type Version
com.h2database : h2 jar 1.4.200
ch.qos.logback : logback-classic jar 1.2.3
org.junit.jupiter : junit-jupiter jar 5.4.2

Project Modules

There are no modules declared in this project.

UltimateGDBot

GitHub release (latest SemVer including pre-releases) Maven Central License javadoc Official Server Crowdin

High-level API to conveniently build Discord bots in Java, on top of Discord4J.

Notice

This library is not yet fully documented. The quick start instructions given in this README are of course insufficient to master the library and make full-fledged bots, full documentation will be available as soon as possible in a later update. In the meantime, you can take a look at the source code of the UlitmateGDBot Core Plugin which is a common plugin that provides essential commands for a Discord bot (such as !help, !ping, etc).

What is UltimateGDBot?

UltimateGDBot allows to make plugin-oriented bots. A plugin is what will allow you to add features to your bot. The goal is that you write only the features you want to see in your bot with the least amount of boilerplate code possible, the library does (almost) all the boring stuff for you.

Getting started

This library requires the JDK 11 or newer. You can download the OpenJDK here.

Maven

<dependencies>
	<dependency>
		<groupId>com.github.alex1304</groupId>
		<artifactId>ultimategdbot-api</artifactId>
		<version>[VERSION]</version>
	</dependency>
</dependencies>

Where [VERSION] is the latest as per Maven Central

Gradle

repositories {
	mavenCentral()
}

dependencies {
	implementation 'com.github.alex1304:ultimategdbot-api:[VERSION]'
}

How it works

Most of the boilerplate code that you will write when working with this library will be at the start, when setting up your plugin. Each plugin can declare one or more services, which will do specific actions such as loading commands, processing data from database, and anything you want your Discord bot to do.

Services are initialized using the principle of dependency injection, using the RDI library. Each service may depend on other services, either made by yourself, provided by the library (e.g BotService), or even from external parties. You define the service hierarchy of your plugin through RDI's ServiceDescriptors that you expose via an implementation of ServiceDeclarator. If you didn't understand anything don't worry, maybe a concrete example will make everything clear.

Note: the API makes use of the Reactor types (Flux and Mono) to give async capabilities to the bot, you can read more about Reactor here.

Example of a basic plugin

The first step is to declare a service for your plugin, that will serve as root. In this example, this service will only be in charge of loading commands.

public class MyService {

	private final BotService bot;

	private MyService(BotService bot) {
		this.bot = bot;
	}

	public static Mono<MyService> create(BotService bot) {
		return RootServiceSetupHelper.create(() -> new MyService(bot))
				.addCommandProvider(bot.command(), new CommandProvider("MyCommands"))
				.setup();
	}
}

The class RootServiceSetupHelper is what will allow you to autoload your commands from the module path.

Before adding a command, you need to declare the service you just created, so that it can be loaded on startup by the bot launcher. To achieve this, create a subclass of ServiceDeclarator like so:

public class MyServices implements ServiceDeclarator {

	public static final ServiceReference<MyService> ROOT = ServiceReference.ofType(MyService.class);

	@Override
	public Set<ServiceDescriptor> declareServices(BotConfig botConfig) {
		return Set.of(
			ServiceDescriptor.builder(ROOT)
						.setFactoryMethod(FactoryMethod.staticFactory("create", Mono.class, Injectable.ref(CommonServices.BOT)))
						.build()
		);
	}
}

ROOT is just a reference that will uniquely identify your service. The setFactoryMethod line allows to specify the method that creates your service. In this case, it's a static method called "create" which returns a Mono and takes BotService as parameter. CommonServices.BOT is what allows to inject BotService into your service.

Next step is to create the plugin. For that, just create a subclass of Plugin:

public class MyPlugin implements Plugin {

	@Override
	public ServiceReference<?> rootService() {
		return MyServices.ROOT;
	}
	
	@Override
	public Mono<PluginMetadata> metadata() {
		return Mono.just(PluginMetadata.builder("MyPlugin").build());
	}
}

It simply specifies which service should be used as root, and meta information on the plugin (like the name of the plugin, the version, who created it, etc). Here we only provided the name of the plugin, which is the only information mandatory.

In order to make all of this work, since UltimateGDBot uses the Java module system to load the plugins and the services, you need to declare a module-info.java with the following minimal contents:

open module example.plugin {

	requires ultimategdbot.api;

	provides ServiceDeclarator with MyServices;
	provides Plugin with MyPlugin;
}

The module must be open so that the launcher can initialize your plugin, and must expose your ServiceDeclarator and your Plugin via provides instructions.

Example command

Writing commands with the UltimateGDBot command API is very easy:

@CommandDescriptor(
	aliases = "hello",
	shortDescription = "Responds to the user with \"hello\"."
)
class HelloCommand {

	@CommandAction
	public Mono<Void> run(Context ctx) {
		return ctx.reply("hello").then();
	}
}

Use annotations to provide all the meta-information you would give to any bot command (aliases, help message, permission level, etc). You can access information such as who ran the command, what are the arguments, etc via the Context object. Your command will automatically be added thanks to the RootServiceSetupHelper of your root service, so no need to worry about doing new HelloCommand() anywhere in your code!

How to run the bot?

See the UlitmateGDBot launcher project to run your plugins created with this library.

Useful Links

Contributing

You may use snapshot and alpha/beta versions if you want to report bugs and give feedback on this project. Issues and pull requests on the master branch are welcome, just follow the instructions on the issue creation menu.

License

This project is released under the MIT license.

Contact

E-mail: [email protected]

Discord: Alex1304#9704 (Server https://discord.gg/VpVdKvg)

Twitter: @gd_alex1304

com.github.alex1304

UltimateGDBot

A collection of repositories for the UltimateGDBot project.

Versions

Version
6.0.2
6.0.1
6.0.0
6.0.0-alpha3
6.0.0-alpha1
5.0.1
5.0.0
5.0.0-RC3.HOTFIX-1
5.0.0-RC3
5.0.0-RC2
5.0.0-RC1
4.0.6
4.0.5
4.0.4
4.0.3
4.0.2
4.0.1
4.0.0
4.0.0-alpha8
4.0.0-alpha7
4.0.0-alpha6
4.0.0-alpha5
4.0.0-alpha4
4.0.0-alpha3
4.0.0-alpha2