Installation

Installing the mod

1. Get the mod jar from it's Modrinth, CurseForge or the GitHub Releases page. Make sure to get the one for the Minecraft version and mod loader you intend to use.

Note

Currently AstralBot supports Forge and Fabric on 1.18.2, 1.19.2 and 1.20.1 and NeoForge and Fabric on 1.21.1 Porting to different versions and loaders is not a priority for now, but PRs are always welcome. If you want a certain version supported, make an Issue.

2. Put the jar into the mods folder on your server.
3. Download the required dependencies for the version you installed and put them into the mods folder as well.

Note

You can find out what the dependencies of your specific version is by checking the details of the file/version you downloaded on CurseForge/Modrinth. These details will list the dependencies. Make sure to also download the correct versions of the dependencies!

Starting the server now will result in a message informing you that AstralBot won't start, because no token has been provided. This is handled in the next step.

Configuring the Discord bot

1. Create a new Application on the Discord Developer Portal
2. Configure your newly created Application to the three privileged gateway intents:
   • PRESENCE
   • SERVER MEMBERS
   • MESSAGE CONTENT
3. Create and copy the bot token to save it somewhere safe, for example a password manager

Caution

Never show this token to anybody else, it would let them authenticate themselves as your Application and wreak havoc on any server it's on!

4. The token can be provided in the astralbot-server.toml config file: token

5. The token can be provided in an Environment Variable named DISCORD_TOKEN for the java process running the Minecraft server.

   This can be achieved with different steps on different operating systems. The most commonly used OS for Minecraft servers is Linux, but the following steps should also work on macOS, as it's a Unix-like system too:

   1. Modify the startup script for your Minecraft server

      The Fabric and Forge server installers provide you with default start scripts, usually called run.sh (on Forge) and start.sh (on Fabric). This file should contain a call executing java with the Minecraft server jar.

      To provide the environment variable, modify it, so it looks like this:

      export DISCORD_TOKEN=<place token here>
      # ... rest of script
      java ... # java command that starts the server

   2. Start the script with the environment variable set

      Starting the script mentioned in i with the environment variable set directly also works. To do this, run the script like this:

      Fabric:

      DISCORD_TOKEN=<place token here> ./start.sh

      Forge:

      DISCORD_TOKEN=<place token here> ./run.sh

Caution

Running the script with

export DISCORD_TOKEN=<token here> ./start.sh

will make the DISCORD_TOKEN environment variable accessible to any other commands you will execute in that shell in the future, until you close it (by pressing CTRL + D or running exit)

6. Start the server. Now, instead of the message telling you AstralBot won't start because of a missing token, you should see something like JDA Login Successful indicating that the Bot is able to communicate with Discord.
7. Use the OAuth2 URL Builder in the Discord Developer Portal to generate a URL with the bot and applications.command permissions
8. Visit the generated URL to have the bot join your Discord server.

Important

If the Bot is offline while it joins your server, the Slash Commands will not be registered. The owner of the server needs to write a chat message with !reload. Once the bot sends Reloaded commands for guild the Slash Commands should be registered.