diff --git a/docs/bun.md b/docs/bun.md
index 1570e0f1..a217f5ea 100644
--- a/docs/bun.md
+++ b/docs/bun.md
@@ -1,20 +1,26 @@
# Bun Support
+
[Bun](https://bun.sh) is a JavaScript and TypeScript runtime that aims to be performant while retaining compatibility with Node.js applications and modules. This page exists to document details about esmBot when running on Bun.
!!! warning
Bun support is still very experimental and prone to bugs. If you find any issues while running the bot on Bun, please test if the same issue occurs on Node; if it doesn't, then specify that it's a Bun-specific issue and provide the version you used (you can find this by running `bun --version`).
## Setup
+
To set up the bot for usage with Bun, follow the [setup guide](https://docs.esmbot.net/setup) as usual, but use the `pnpm start:bun` command to start the bot instead. Additionally, you can replace `pnpm build` with `pnpm build:natives`; since Bun is capable of executing TypeScript directly, transpiling it to JavaScript is not needed.
## Differences
+
esmBot uses some of Bun's exclusive features when detected to add extra capabilities or improve performance in certain cases. Here's the current list of Bun-specific behavior:
+
- The stats command shows Bun's version number instead of Node's
- The SQLite database driver uses `bun:sqlite` instead of `better-sqlite3`
- Commands and event handlers written in TypeScript (using the .ts extension) can be loaded natively
## Known Issues
+
- Discord and image server connections do not handle disconnects properly (see [oven-sh/bun#7896](https://github.com/oven-sh/bun/issues/7896)) **Fixed in Bun 1.1!**
## Image Natives
-Previously, the image natives used with Node did not work when using Bun; however, as of Bun 1.1.4, they appear to work with no issue. It should be possible to build and use them with Bun as if you were working with Node.
\ No newline at end of file
+
+Previously, the image natives used with Node did not work when using Bun; however, as of Bun 1.1.4, they appear to work with no issue. It should be possible to build and use them with Bun as if you were working with Node.
diff --git a/docs/config.md b/docs/config.md
index a0408d3d..20732a26 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -1,10 +1,13 @@
# Config
+
esmBot uses a mix of environment variables and JSON for configuration.
## Environment Variables (.env)
+
To make managing environment variables easier, an example `.env` file is included with the bot at `.env.example` and can be used to load the variables on startup.
### Required
+
- `NODE_ENV`: Used for tuning the bot to different environments. If you don't know what to set it to, leave it as is.
- `TOKEN`: Your bot's token. You can find this [here](https://discord.com/developers/applications) under your application's Bot tab.
- `DB`: The database connection string. By default the `sqlite` and `postgresql` protocols are available, but this can be expanded by putting proper DB driver scripts into `utils/database/`.
@@ -13,6 +16,7 @@ To make managing environment variables easier, an example `.env` file is include
- `LOCALE`: The default language/locale for messages sent by the bot. A corresponding locale JSON must be present in the `locales` directory, and if the command is an interaction, it will be overridden by the user's set client language.
### Optional
+
These variables that are not necessarily required for the bot to run, but can greatly enhance its functionality:
- `STAYVC`: Set this to true if you want the bot to stay in voice chat after playing music/a sound effect. You can make it leave by using the stop command.
@@ -28,9 +32,11 @@ These variables that are not necessarily required for the bot to run, but can gr
- `ADMIN_SERVER`: A Discord server/guild ID to limit owner-only commands such as eval to.
## JSON
+
The JSON-based configuration files are located in `config/`.
### commands.json
+
```js
{
"types": {
@@ -44,6 +50,7 @@ The JSON-based configuration files are located in `config/`.
```
### messages.json
+
```js
{
"emotes": [
@@ -56,6 +63,7 @@ The JSON-based configuration files are located in `config/`.
```
### servers.json
+
```js
{
"lava": [ // Objects containing info for connecting to Lavalink audio server(s)
diff --git a/docs/containers.md b/docs/containers.md
index 577cf308..31094602 100644
--- a/docs/containers.md
+++ b/docs/containers.md
@@ -1,19 +1,25 @@
# Containers
+
You can run the bot as well as its dependencies as a series of containers using Docker or Podman. This can allow for a slightly easier setup if you're able to run one of those two container runtimes; however, the manual setup is still recommended if you want more control over the bot.
To start, install [Docker](https://docs.docker.com/engine/install/#server) or [Podman](https://podman.io/docs/installation) on your system via the linked instructions. If using Podman, you'll also need to install [podman-compose](https://github.com/containers/podman-compose/blob/main/README.md#installation).
Once you've installed one of those, you should clone the esmBot repo:
+
```sh
cd ~
git clone --recurse-submodules https://github.com/esmBot/esmBot
cd esmBot
```
+
Modify the `.env` file as described in step 6 of the manual setup. Make sure to change the `DB` option to this, however:
+
```
DB=postgresql://esmbot:verycoolpass100@postgres:5432/esmbot
```
+
You should then modify the `config/servers.json` file to change the IP addresses of the servers to match the containers. Example:
+
```json
{
"lava": [
@@ -24,7 +30,9 @@ You should then modify the `config/servers.json` file to change the IP addresses
]
}
```
+
Finally, start the bot by running the following command (click to select your container runtime):
+
=== "Podman"
```sh
podman-compose up -d
@@ -32,4 +40,4 @@ Finally, start the bot by running the following command (click to select your co
=== "Docker"
```sh
docker compose up -d
- ```
\ No newline at end of file
+ ```
diff --git a/docs/custom-commands.md b/docs/custom-commands.md
index 180d1c73..22b706f2 100644
--- a/docs/custom-commands.md
+++ b/docs/custom-commands.md
@@ -1,8 +1,11 @@
# Custom Commands
+
esmBot has a powerful and flexible command handler, allowing you to create new commands and categories simply by creating new files. This page will provide a reference for creating new commands.
## Directory Structure
+
The bot loads commands from subdirectories inside of the `commands` directory, which looks something like this by default:
+
```
commands/
- fun
@@ -17,13 +20,16 @@ commands/
> speed.js
> ...
```
+
As you can see, each command is grouped into categories, which are represented by subdirectories. To create a new category, you can simply create a new directory inside of the `commands` directory, and to create a new command, you can create a new JS file under one of those subdirectories.
!!! tip
The `message` and `user` categories are special; instead of being registered as classic or slash commands, commands in these categories are registered as right-click context menu commands. Commands in the `message` category show when selecting messages, while commands in the `user` category show when selecting users.
## Command Structure
+
It's recommended to use the `Command` class located at `#cmd-classes/command.js` to create a new command in most cases. This class provides various parameters and fields that will likely be useful when creating a command. Here is a simple example of a working command file:
+
```js
import Command from "#cmd-classes/command.js";
@@ -38,6 +44,7 @@ class HelloCommand extends Command {
export default HelloCommand;
```
+
As you can see, the first thing we do is import the Command class. We then create a new class for the command that extends that class to provide the needed parameters. We then define the command function, which is named `run`. Some static parameters, including the command description and an alias for the command, `helloworld`, are also defined. Finally, once everything in the command class is defined, we export the new class to be loaded as a module by the command handler.
The default command name is the same as the filename that you save it as, excluding the `.js` file extension. If you ever want to change the name of the command, just rename the file.
@@ -76,6 +83,7 @@ Some static fields are also available and can be set depending on your command.
- `description`: Your command's description, which is shown in the help command.
- `aliases`: An array of command aliases. People will be able to run the command using these as well as the normal command name.
- `flags`: An array of objects specifying command flags, or special arguments, that will be shown when running `help ` or a slash command. Example:
+
```js
static flags = [{
name: "argument",
@@ -84,6 +92,7 @@ static flags = [{
...
}];
```
+
- `ephemeral`: Specifies whether or not the command output should be ephemeral.
- `slashAllowed`: Specifies whether or not the command is available via slash commands.
- `directAllowed`: Specifies whether or not a command is available in direct messages.
@@ -91,6 +100,7 @@ static flags = [{
- `adminOnly`: Specifies whether or not a command should be limited to the bot owner(s).
In addition, a few helper functions are available inside the `Command` class:
+
- `this.acknowledge()`: Sends a typing indicator in the current channel. Only works with classic commands.
- `this.getString(key, returnNull)`: Gets a localized string for the input locale. If `returnNull` is set to false (the default) and the string does not exist on the input or default locales, the `key` string will be returned; otherwise, `null` will be returned.
- `this.getOptionString(key)`: Gets a command flag/option by name as a string.
@@ -100,4 +110,5 @@ In addition, a few helper functions are available inside the `Command` class:
- `this.clean(text)`: Strips and normalizes user, role, and channel mentions found in `text`
## The `run` Function
-The main JS code of your command is specified in the `run` function. This function should return a [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise) of your command output, which is why the `run` function [is an async function by default](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/async_function). The return value inside the `Promise` should be either a string or an object; you should return a string whenever you intend to reply with plain text, or an object if you intend to reply with something else, such as an embed or attachment.
\ No newline at end of file
+
+The main JS code of your command is specified in the `run` function. This function should return a [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise) of your command output, which is why the `run` function [is an async function by default](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/async_function). The return value inside the `Promise` should be either a string or an object; you should return a string whenever you intend to reply with plain text, or an object if you intend to reply with something else, such as an embed or attachment.
diff --git a/docs/index.md b/docs/index.md
index f11566a8..755735d6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,3 +1,3 @@
Welcome to the documentation site for the esmBot project! This site is intended to document more technical information about the esmBot software itself.
-If you want to run your own instance of esmBot, you might be looking for the [Setup](setup.md) page. If you're just looking to add the bot to your server, head over to [https://esmbot.net/invite](https://esmbot.net/invite).
\ No newline at end of file
+If you want to run your own instance of esmBot, you might be looking for the [Setup](setup.md) page. If you're just looking to add the bot to your server, head over to [https://esmbot.net/invite](https://esmbot.net/invite).
diff --git a/docs/postgresql.md b/docs/postgresql.md
index 7868d7fc..4249afc8 100644
--- a/docs/postgresql.md
+++ b/docs/postgresql.md
@@ -1,4 +1,5 @@
# PostgreSQL
+
Here are some instructions for setting up PostgreSQL for use with esmBot.
### 1. Install PostgreSQL.
@@ -33,19 +34,26 @@ Here are some instructions for setting up PostgreSQL for use with esmBot.
When you install PostgreSQL, it'll create a new user on your system that acts as the "superuser" of the database. You'll need to run Postgres commands as this user; however, you can run a command as that user without switching to it by using `sudo`.
First, you'll need to create a user that the bot can interact with as well as the database itself:
+
```sh
sudo su - postgres -c "createuser esmbot"
sudo su - postgres -c "createdb esmbot"
```
+
Then, launch the PostgreSQL shell for the next few commands:
+
```sh
sudo -u postgres psql
```
+
If you want to give the user a password, you can do so like this:
+
```sql
ALTER USER esmbot WITH PASSWORD 'new_password';
```
+
Once you're inside the shell, you'll need to make sure the bot owns the database and has permissions:
+
```sql
ALTER DATABASE esmbot OWNER TO esmbot;
```
@@ -55,7 +63,9 @@ You're done!
***
### Troubleshooting
+
If you get an error like `error: permission denied for table counts` when attempting to run the bot, try running these commands in the PostgreSQL shell:
+
```sql
\c esmbot
GRANT ALL PRIVILEGES ON guilds TO esmbot;
diff --git a/docs/setup.md b/docs/setup.md
index 6ce9d64f..250cb30e 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -1,4 +1,5 @@
# Setup
+
Here are some instructions to get esmBot up and running from source.
??? check "Recommended system requirements"
@@ -16,7 +17,9 @@ If you have any further questions regarding setup, feel free to ask in the #supp
You can run the bot using Docker or Podman for a somewhat simpler setup experience. [Click here to go to the container setup guide.](https://docs.esmbot.net/containers)
### 1. Install the required native dependencies.
+
Choose the OS you're using below for insallation instructions.
+
=== "Debian/Ubuntu"
These instructions apply to Debian version 12 (bookworm) or Ubuntu version 24.04 (noble) or later.
```sh
@@ -59,17 +62,20 @@ Choose the OS you're using below for insallation instructions.
Node.js is the runtime that esmBot is built on top of. The bot requires version 20.12.0 or above to run.
We suggest using nvm to manage your Node.js install. Run the following command to install it:
+
```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
```
Then run the following to install Node.js:
+
```sh
nvm install 20
nvm use 20
```
esmBot uses the pnpm package manager to manage dependencies and run build scripts. You can use Corepack (a tool included with Node.js) to enable it, and once you attempt to run it for the first time it will ask you to install it:
+
```sh
corepack enable
```
@@ -90,6 +96,7 @@ If you would like to use the PostgreSQL database, view the setup instructions [h
***
### 4. Clone the repo and install the required Node modules.
+
```sh
cd ~
git clone --recursive https://github.com/esmBot/esmBot
@@ -114,11 +121,13 @@ Lavalink is the audio server used by esmBot for music playback. If you do not pl
There are websites out there providing lists of public Lavalink instances that can be used with the bot. However, these are not recommended due to performance/security concerns and missing features, and it is highly recommended to set one up yourself instead using the steps below.
esmBot requires Lavalink version v4 or later, which requires a Java (17 or later) installation. You can use [SDKMAN](https://sdkman.io) to install Eclipse Temurin, a popular Java distribution:
+
```sh
sdk install java 17.0.11-tem
```
Initial setup is like this:
+
```sh
cd ~
mkdir Lavalink
@@ -126,7 +135,9 @@ cd Lavalink
curl -OL https://github.com/lavalink-devs/Lavalink/releases/latest/download/Lavalink.jar
ln -s ~/esmBot/application.yml .
```
+
To run Lavalink, you can use this command:
+
```sh
java -jar Lavalink.jar
```
@@ -139,6 +150,7 @@ java -jar Lavalink.jar
### 6. Configure the bot.
Configuration is done via environment variables which can be specified through a `.env` file. Copy `.env.example` to get a starter config file:
+
```sh
cp .env.example .env
```
@@ -147,9 +159,11 @@ cp .env.example .env
If you can't see either of these files, don't worry - Linux treats files whose names start with a . as hidden files.
To edit this file in the terminal, run this command:
+
```sh
nano .env
```
+
This will launch a text editor with the file ready to go. Create a Discord application [here](https://discord.com/developers/applications) and select the Bot tab on the left, then create a bot user. Once you've done this, copy the token it gives you and put it in the `TOKEN` variable.
When you're finished editing the file, press Ctrl + X, then Y and Enter.
@@ -161,9 +175,11 @@ An overview of each of the variables in the `.env` file can be found [here](http
### 7. Run the bot.
Once everything else is set up, you can start the bot like so:
+
```sh
pnpm start
```
+
If the bot starts successfully, you're done! You can invite the bot to your server by generating an invite link under OAuth -> URL Generator in the Discord application dashboard.
!!! note
@@ -176,11 +192,13 @@ If the bot starts successfully, you're done! You can invite the bot to your serv
If you want the bot to run 24/7, you can use the [PM2](https://pm2.keymetrics.io) process manager. Install it using the following command:
+
```sh
pnpm add -g pm2
```
Once you've done that, you can start the bot using the following command:
+
```sh
pm2 start ecosystem.config.cjs
```
@@ -196,6 +214,7 @@ pm2 start ecosystem.config.cjs
***
## Troubleshooting
+
??? faq "Error: Cannot find module './build/Release/image.node'"
The native image functions haven't been built. Run `pnpm build` to build them.