Added some Documentation for Mobot: Introduction, Installation, Getting Started on Custom modules, Lifecycle Methods and SlashCommands
This commit is contained in:
sieadev
@@ -25,7 +25,7 @@ features:
|
||||
details: A Library made to ease server-side Fabric mod development.
|
||||
link: /serverlibraries
|
||||
- title: MoBot
|
||||
details: A Modular Discord Bot with a simple but efficent API.
|
||||
details: A modular Discord bot written in Java, with a feature-rich API.
|
||||
link: /mobot
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
banner_title: "MoBot - Command Arguments"
|
||||
banner_description: "Learn how to use command arguments in MoBot"
|
||||
---
|
||||
|
||||
# 🛠️ Command Arguments
|
||||
Command arguments allow you to pass additional information to your commands when they are invoked. This is useful for creating dynamic commands that can perform different actions based on user input.
|
||||
|
||||
## 📜 `@SlashCommandArgument` Annotation
|
||||
The `@SlashCommandArgument` annotation is used to define an argument for a slash command. You can specify the name, description, type, and whether the argument is required or optional.
|
||||
You can add it to the method that handles the command, and it will automatically parse the argument from the command invocation.
|
||||
`SlashCommandArgument`'s can also be stacked, so you can have multiple arguments for a single command.
|
||||
|
||||
Optionally you can add a `Map<String, Object>` to the method signature to get all arguments as a Map. If you prefer to retrieve the arguments from the event, you can use `#event.getOptions()`.
|
||||
|
||||
| Option | Description |
|
||||
|-----------------|-----------------------------------------------------------------------------|
|
||||
| `name` | The name of the argument. This is what users will type to provide the value. |
|
||||
| `description` | A short description of what the argument does. |
|
||||
| `type` | The type of the argument. This can be a string, integer, etc. |
|
||||
| `required` | Whether the argument is required or optional. |
|
||||
| `autoComplete` | Whether the argument should be auto-completed. |
|
||||
|
||||
Here’s an example of a command with an argument using the `@SlashCommandArgument` annotation:
|
||||
|
||||
```java
|
||||
public class MyCommand implements SlashCommandHandler {
|
||||
@SlashCommand(
|
||||
name = "greet",
|
||||
description = "Greet a user"
|
||||
)
|
||||
@SlashCommandArgument(
|
||||
name = "user",
|
||||
description = "The user to greet",
|
||||
type = OptionType.USER,
|
||||
required = true
|
||||
)
|
||||
public void onGreetCommand(SlashCommandInteractionEvent event, Map<String, Object> args) {
|
||||
// Get the user argument
|
||||
User user = (User) args.get("user");
|
||||
|
||||
// Reply to the command
|
||||
event.reply("Hello, " + user.getName() + "!").queue();
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
banner_title: "MoBot - Creating a Command"
|
||||
banner_description: "Learn how to create custom commands for MoBot"
|
||||
---
|
||||
|
||||
# 🛠️ Creating a Command
|
||||
|
||||
Commands are a core feature of Discord Bots. They allow users to interact with the bot and perform various actions. In MoBot, creating a command is straightforward and flexible, allowing you to define custom behavior for your bot.
|
||||
|
||||
## 🚀 Commands in the MoBot API
|
||||
To make commands easy to use, MoBot provides a extensive API for creating and managing commands.
|
||||
Apart from the `SlashCommandHandler` interface, the SlashCommand System is build entirely from annotations.
|
||||
|
||||
::: warning NOTE
|
||||
You will have to implement the `SlashCommandHandler` interface if you want to use `@SlashCommand` and other annotations.
|
||||
:::
|
||||
|
||||
## 📜 `@SlashCommand` Annotation
|
||||
The `@SlashCommand` annotation is used to define a slash command. Apart from the name and description, you can also specify aliases and required permissions.
|
||||
This annotation is placed on a method that will handle the command when it is invoked.
|
||||
The method should accept a `SlashCommandInteractionEvent` parameter, which contains information about the command invocation and allows you to respond to the user.
|
||||
|
||||
| Option | Description |
|
||||
|-----------------|------------------------------------------------------------------------------|
|
||||
| `name` | The name of the command. This is what users will type to invoke the command. |
|
||||
| `description` | A short description of what the command does. |
|
||||
| `aliases` | An array of alternative names for the command. |
|
||||
| `permissions` | The permission required to use the command. |
|
||||
|
||||
Here’s an example of a simple `PingCommand` using the `@SlashCommand` annotation:
|
||||
|
||||
```java
|
||||
public class PingCommand implements SlashCommandHandler {
|
||||
@SlashCommand(
|
||||
name = "ping",
|
||||
description = "Ping the bot to check if it's alive"
|
||||
)
|
||||
public void onPingCommand(SlashCommandInteractionEvent event) {
|
||||
event.reply("Pong!").queue();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🛠️ Registering the Command
|
||||
|
||||
To register the command, you need to create an instance of your command class and register it using the `#registerSlashCommandHandler` method in your module's main class.
|
||||
|
||||
Here's an example of how to register the `PingCommand` in your module:
|
||||
|
||||
```java
|
||||
public class MyModule extends MbModule {
|
||||
@Override
|
||||
public void onEnable() {
|
||||
registerSlashCommandHandler(new PingCommand());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,9 +1,42 @@
|
||||
{
|
||||
"/mobot/": [
|
||||
{
|
||||
"text": "MoBot Documentation",
|
||||
"text": "Introduction",
|
||||
"items": [
|
||||
{ "text": "Getting Started", "link": "/mobot" }
|
||||
{ "text": "Installation", "link": "/mobot/introduction/installation" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"text": "Creating a Module",
|
||||
"collapsed": false,
|
||||
"items": [
|
||||
{ "text": "Getting Started", "link": "/mobot/creating-a-module/modules-introduction" },
|
||||
{ "text": "Module Lifecycle", "link": "/mobot/creating-a-module/module-lifecycle" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"text": "Commands",
|
||||
"collapsed": false,
|
||||
"items": [
|
||||
{ "text": "Creating a Command", "link": "/mobot/commands/creating-a-command" },
|
||||
{ "text": "Command Arguments", "link": "/mobot/commands/command-arguments" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"text": "Events",
|
||||
"collapsed": false,
|
||||
"items": [
|
||||
{ "text": "What are Events?", "link": "/mobot/events/events-introduction" },
|
||||
{ "text": "Creating a Listener", "link": "/mobot/events/creating-a-listener" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"text": "Configs",
|
||||
"collapsed": false,
|
||||
"items": [
|
||||
{ "text": "Default Config", "link": "/mobot/configuration/default-config" },
|
||||
{ "text": "Custom Configs", "link": "/mobot/configuration/custom-configs" },
|
||||
{ "text": "Non Yaml Configs", "link": "/mobot/configuration/non-yaml-configs" }
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
banner_title: "MoBot - Module Lifecycle"
|
||||
banner_description: "Learn about the lifecycle of a MoBot module"
|
||||
---
|
||||
|
||||
# 📦 Module Lifecycle
|
||||
MoBot modules follow a specific lifecycle to ensure proper initialization, operation, and cleanup. Understanding this lifecycle is crucial for creating reliable and efficient modules.
|
||||
|
||||
## 🔄 Lifecycle Phases
|
||||
The lifecycle of a MoBot module consists of several phases, each with its own purpose and responsibilities. Here’s a breakdown of each phase:
|
||||
### 1. Initialization
|
||||
When MoBot starts, it scans the modules directory for JAR files. Each module is loaded, and its MbModule class is instantiated. During this phase, the module's dependencies are resolved, and its configuration is loaded.
|
||||
### 2. Pre-Enable
|
||||
Before the Discord Bot is fully initialized, the `preEnable()` method of the module's main class is called. This is where you can perform actions that involve the `BotBuilder`. This includes stuff like setting the bots status or other tasks that can not be performed after the bot is fully initialized.
|
||||
### 3. Enable
|
||||
After initialization, the `onEnable()` method of the module's main class is called. This is where you should set up your module's main functionality, such as registering commands, listeners, or tasks.
|
||||
### 4. Disable
|
||||
When MoBot shuts down or the module is unloaded, the `onDisable()` method is called. Use this phase to clean up resources, save data, and gracefully stop any ongoing tasks.
|
||||
### 5. Post-Disable
|
||||
After the Discord Bot is fully disabled, the `postDisable()` method of the module's main class is called. You can use this phase to perform any final cleanup tasks that require the bot to be fully disabled.
|
||||
|
||||
::: warning NOTE
|
||||
All of these methods are optional, and you can choose to implement only the ones you need.
|
||||
:::
|
||||
|
||||
## Usage Example
|
||||
```java
|
||||
public class MyModule extends MbModule {
|
||||
@Override
|
||||
public void preEnable() {
|
||||
// Perform actions before the bot is fully initialized
|
||||
}
|
||||
|
||||
@Override
|
||||
public void onEnable() {
|
||||
// Register commands, listeners, etc.
|
||||
}
|
||||
|
||||
@Override
|
||||
public void onDisable() {
|
||||
// Save data, stop tasks, etc.
|
||||
}
|
||||
|
||||
@Override
|
||||
public void postDisable() {
|
||||
// Final cleanup tasks
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🛠️ Cheat Sheet
|
||||
| Method | Description |
|
||||
|-----------------|------------------------------------------------------------------------------------|
|
||||
| `preEnable()` | Called before the bot is fully initialized. Use this to set up the bot. |
|
||||
| `onEnable()` | Called when the module is enabled. Use this to register commands, listeners, etc. |
|
||||
| `onDisable()` | Called when the module is disabled. Use this to save data, clean up resources etc. |
|
||||
| `postDisable()` | Called after the bot is fully disabled. Use this for final cleanup tasks. |
|
||||
@@ -0,0 +1,126 @@
|
||||
---
|
||||
banner_title: "MoBot - Creating a Module"
|
||||
banner_description: "Learn how to create a module for MoBot"
|
||||
---
|
||||
|
||||
# 🧩 Creating a Module
|
||||
MoBot is designed to be modular, allowing you to create your own modules to extend its functionality.
|
||||
This guide will walk you through the process of creating a module for MoBot.
|
||||
|
||||
|
||||
## 🧠 Prerequisites
|
||||
|
||||
Before we begin, make sure you’re comfortable with:
|
||||
|
||||
- Basic **Java** programming
|
||||
- Using **Maven** (or any preferred Java build tool)
|
||||
- Understanding the basics of how MoBot operates
|
||||
|
||||
If you're new to Java or Maven, we recommend checking out a few beginner tutorials first.
|
||||
|
||||
Also, make sure you've reviewed the [MoBot Installation Guide](/mobot/introduction/installation) to understand how the bot is structured and how modules fit into it.
|
||||
|
||||
## 🧩 What Makes a Module?
|
||||
|
||||
For a module to be recognized and loaded by MoBot, it needs **two essential parts**:
|
||||
|
||||
1. A **Main class** that extends `MbModule`
|
||||
2. A **`module.yml`** configuration file that defines metadata about the module
|
||||
|
||||
Additionally, you’ll need to include the **MoBot API** as a dependency in your project.
|
||||
|
||||
## 🛠 Step 1: Set Up Your Maven Project
|
||||
To create a module, you need to set up a Maven project. You can do this using your favorite IDE or by using the command line.
|
||||
If you're using the command line, you can create a new Maven project with the following command:
|
||||
|
||||
```bash
|
||||
mvn archetype:generate -DgroupId=com.example -DartifactId=MyModule -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
|
||||
```
|
||||
This will create a new Maven project looking something like this:
|
||||
|
||||
```bash
|
||||
MyModule/
|
||||
├── pom.xml
|
||||
└── src/
|
||||
└── main/
|
||||
└── java/
|
||||
└── com/
|
||||
└── example/
|
||||
└── MyModule/
|
||||
└── App.java
|
||||
```
|
||||
|
||||
### Add MoBot API Dependency
|
||||
To use the MoBot API in your module, you need to add it as a dependency in your `pom.xml` file. Open the `pom.xml` file and add the following lines inside the `<repositories>` and `<dependencies>` sections:
|
||||
|
||||
```xml
|
||||
<repository>
|
||||
<id>pixel-services-releases</id>
|
||||
<name>Pixel Services</name>
|
||||
<url>https://maven.pixel-services.com/releases</url>
|
||||
</repository>
|
||||
|
||||
<dependency>
|
||||
<groupId>com.pixelservices.mobot</groupId>
|
||||
<artifactId>mobot-api</artifactId>
|
||||
<version>VERSION</version> <!-- Replace VERSION -->
|
||||
</dependency>
|
||||
```
|
||||
|
||||
Make sure to replace `VERSION` with the latest version of the MoBot API.
|
||||
|
||||
[](https://maven.pixel-services.com/#/releases/com/pixelservices/mobot/mobot-api)
|
||||
|
||||
## 🧱 Step 2: Create Your Main Class
|
||||
Either locate your existing main class or create a new one. This class will be the entry point for your module and should extend `MbModule`.
|
||||
```java
|
||||
public class MyModule extends MbModule {
|
||||
@Override
|
||||
public void onEnable() {
|
||||
//Do something
|
||||
}
|
||||
|
||||
@Override
|
||||
public void onDisable() {
|
||||
//Do something
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📜 Step 3: Create the `module.yml` File
|
||||
The `module.yml` file contains metadata about your module, such as its name, version, and description. Create a new file named `module.yml` in the `src/main/resources` directory of your project.
|
||||
```yaml
|
||||
name: MyModule
|
||||
version: 1.0.0
|
||||
description: This is a sample module for MoBot.
|
||||
main: com.example.MyModule
|
||||
authors: [Your Name]
|
||||
license: MIT
|
||||
depedencies: []
|
||||
```
|
||||
|
||||
### Explanation of the Fields
|
||||
- **name**: The name of your module.
|
||||
- **version**: The version of your module.
|
||||
- **description**: A brief description of your module.
|
||||
- **main**: The fully qualified name of your main class.
|
||||
- **authors**: A list of authors for your module.
|
||||
- **license**: The license under which your module is distributed.
|
||||
- **dependencies**: A list of other modules that your module depends on. This is optional and can be left empty if your module has no dependencies.
|
||||
|
||||
## 🚀 Step 4: Build Your Module
|
||||
Once you have created your main class and `module.yml` file, you can build your module using Maven. Open a terminal in the root directory of your project and run the following command:
|
||||
|
||||
```bash
|
||||
mvn clean package
|
||||
```
|
||||
|
||||
This will create a JAR file for your module in the `target` directory. The JAR file will be named `MyModule-1.0.0.jar` (or whatever version you specified in the `module.yml` file).
|
||||
|
||||
Congratulations! You have successfully created a module for MoBot. Now you can load it into your MoBot instance and start using it.
|
||||
|
||||
## 🔌 Step 5: Load Your Module into MoBot
|
||||
To load your module into MoBot, simply place the JAR file you just created into the `modules` directory of your MoBot instance.
|
||||
When you start MoBot, it will automatically detect and load your module.
|
||||
|
||||
Need help? Join our [Discord server](https://discord.gg/KTF3Wsk85G) for support and to connect with other MoBot users.
|
||||
+12
-1
@@ -1,4 +1,15 @@
|
||||
---
|
||||
banner_title: "MoBot - A Modular Discord Bot"
|
||||
banner_description: "MoBot is a modular Discord bot written in Java, featuring a beginner-friendly api and extensive documentation."
|
||||
banner_description: "MoBot is a modular Discord bot written in Java, with a feature rich API."
|
||||
---
|
||||
|
||||
# MoBot
|
||||
|
||||
MoBot is a modular, extensible Discord bot framework built in Java. It's designed to give developers full control over bot behavior through a clean and powerful API, while keeping setup and module development approachable—even for beginners.
|
||||
|
||||
At its core, MoBot supports a plugin-like architecture that allows you to build and manage independent modules, each with its own logic, commands, event listeners, and dependencies. Whether you're creating small utilities or full-featured systems, MoBot provides the structure and flexibility to support your ideas.
|
||||
|
||||
Modules are easy to configure and hot-load, and the framework handles startup order, logging, and lifecycle management out of the box. With a strong focus on developer experience, MoBot includes detailed documentation and examples to help you get started quickly.
|
||||
|
||||
Ready to get started? Follow the [Installation guide](/mobot/introduction/installation).
|
||||
Interested in building your own modules? Head over to [Creating a Module](/mobot/creating-a-module/modules-introduction) to learn more.
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
banner_title: "MoBot - Installation"
|
||||
banner_description: "How to install MoBot and set up MoBot"
|
||||
---
|
||||
|
||||
# 📦 Installation
|
||||
|
||||
Follow these steps to install and set up MoBot on your machine. MoBot is designed to be easy to install and configure, so you can get started quickly.
|
||||
## 🔧 Requirements
|
||||
- Java 17 or higher
|
||||
- A Discord Bot Token (You can create one by following the instructions below)
|
||||
|
||||
## 🤖 Create a Discord Bot
|
||||
|
||||
If you already have a Discord bot, you can skip this step. If you don't have a bot yet, follow these steps to create one:
|
||||
|
||||
::: details Click to expand
|
||||
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications).
|
||||
2. Click on the "New Application" button.
|
||||
3. Enter a name for your application and click "Create".
|
||||
4. In the left sidebar, click on "Bot".
|
||||
5. Click on the "Add Bot" button.
|
||||
6. Under the "Token" section, click on "Copy" to copy your bot token. **Keep this token secret!** It is used to authenticate your bot with Discord.
|
||||
7. Under the "Privileged Gateway Intents" section, enable the intents you need for your bot. For example, if your bot needs to read messages in channels, enable the "Message Content Intent".
|
||||
8. Under the "OAuth2" section, select the "bot" scope and the permissions your bot needs. This will generate a URL that you can use to invite your bot to your server.
|
||||
9. Copy the generated URL and paste it into your browser. Select the server you want to invite your bot to and click "Authorize".
|
||||
10. Your bot is now created and invited to your server!
|
||||
:::
|
||||
|
||||
## 📥 Download MoBot
|
||||
Grab the latest release from the [Releases Page](https://github.com/Pixel-Services/MoBot/releases).
|
||||
1. Go to the [Releases Page](https://github.com/Pixel-Services/MoBot/releases)
|
||||
2. Download the latest `MoBot.jar` file.
|
||||
|
||||
## 🚀 Run MoBot for the First Time
|
||||
In your terminal, navigate to the directory where you downloaded `MoBot.jar` and run the following command:
|
||||
```bash
|
||||
java -jar MoBot.jar
|
||||
```
|
||||
|
||||
When you run MoBot for the first time, MoBot will ask you for a **Discord bot token**.
|
||||
You can get your token from the [Discord Developer Portal](https://discord.com/developers/applications).
|
||||
|
||||
Once you enter your token, MoBot will create a `bot.yml` file in the same directory. This file contains your bot's configuration settings.
|
||||
Additionally, MoBot will create a `modules` directory where you can place your custom modules.
|
||||
|
||||
It should look something like this:
|
||||
```bash
|
||||
mobot/
|
||||
├── MoBot.jar
|
||||
├── bot.yml
|
||||
└── modules/
|
||||
```
|
||||
|
||||
## ⚙️ Configure MoBot
|
||||
Open the `bot.yml` file in a text editor. This file contains the configuration settings for your bot. You can customize various settings, such as:
|
||||
- **Token**: Your Discord bot token.
|
||||
- **Gateway Intents**: The intents your bot will use. You can add or remove intents as needed.
|
||||
- **Check Updates**: Whether to check for updates on startup.
|
||||
|
||||
Depending on what modules you have installed, you may need to enable specific intents. For example, if you have a module that requires the `GUILD_MEMBERS` intent, you need to add it in the `bot.yml` file.
|
||||
```yaml
|
||||
intents:
|
||||
- GUILD_MEMBERS
|
||||
```
|
||||
|
||||
## 🔌 Install Modules
|
||||
As of today, there is no official MoBot module repository. However, you can find some community modules on our Discord.
|
||||
To install a module, simply place the module's `.jar` file in the `modules` directory. MoBot will automatically load the module on startup.
|
||||
|
||||
You can also create your own modules! Check out the [Creating a Module](/mobot/creating-a-module/modules-introduction) section for more information on how to create and manage your own modules.
|
||||
|
||||
## ✅ Start the Bot
|
||||
Once you have configured your bot and installed any necessary modules, you can start the bot by running the following command in your terminal:
|
||||
```bash
|
||||
java -jar MoBot.jar
|
||||
```
|
||||
You should see logs indicating that the bot and any modules have been loaded successfully.
|
||||
|
||||
Need help? Join our [Discord server](https://discord.gg/KTF3Wsk85G) for support and to connect with other MoBot users.
|
||||
Reference in New Issue
Block a user