diff --git a/.docs/img/pterodactyl/setup/1.png b/.docs/img/pterodactyl/setup/1.png new file mode 100644 index 0000000..3de8c96 Binary files /dev/null and b/.docs/img/pterodactyl/setup/1.png differ diff --git a/.docs/img/pterodactyl/setup/10.png b/.docs/img/pterodactyl/setup/10.png new file mode 100644 index 0000000..5b69027 Binary files /dev/null and b/.docs/img/pterodactyl/setup/10.png differ diff --git a/.docs/img/pterodactyl/setup/2.png b/.docs/img/pterodactyl/setup/2.png new file mode 100644 index 0000000..e42a863 Binary files /dev/null and b/.docs/img/pterodactyl/setup/2.png differ diff --git a/.docs/img/pterodactyl/setup/3.png b/.docs/img/pterodactyl/setup/3.png new file mode 100644 index 0000000..93aa175 Binary files /dev/null and b/.docs/img/pterodactyl/setup/3.png differ diff --git a/.docs/img/pterodactyl/setup/4.png b/.docs/img/pterodactyl/setup/4.png new file mode 100644 index 0000000..18507a4 Binary files /dev/null and b/.docs/img/pterodactyl/setup/4.png differ diff --git a/.docs/img/pterodactyl/setup/5.png b/.docs/img/pterodactyl/setup/5.png new file mode 100644 index 0000000..f4997e0 Binary files /dev/null and b/.docs/img/pterodactyl/setup/5.png differ diff --git a/.docs/img/pterodactyl/setup/6.png b/.docs/img/pterodactyl/setup/6.png new file mode 100644 index 0000000..01a9d33 Binary files /dev/null and b/.docs/img/pterodactyl/setup/6.png differ diff --git a/.docs/img/pterodactyl/setup/7.png b/.docs/img/pterodactyl/setup/7.png new file mode 100644 index 0000000..a7de4f9 Binary files /dev/null and b/.docs/img/pterodactyl/setup/7.png differ diff --git a/.docs/img/pterodactyl/setup/8.png b/.docs/img/pterodactyl/setup/8.png new file mode 100644 index 0000000..cc97260 Binary files /dev/null and b/.docs/img/pterodactyl/setup/8.png differ diff --git a/.docs/img/pterodactyl/setup/9.png b/.docs/img/pterodactyl/setup/9.png new file mode 100644 index 0000000..454a69d Binary files /dev/null and b/.docs/img/pterodactyl/setup/9.png differ diff --git a/.docs/pterodactyl/setup.md b/.docs/pterodactyl/setup.md index f10882a..8811bf9 100644 --- a/.docs/pterodactyl/setup.md +++ b/.docs/pterodactyl/setup.md @@ -5,5 +5,135 @@ This page will go over the steps required to setup the Pterodactyl cog. /// admonition | Screenshots may be visually distinct type: info For the purpose of this guide, I'll be using [Bloom Host's](https://bloom.host/) [Pterodactyl fork](https://mc.bloom.host/). -The steps should be basically identical for other panels, but screenshots will look visually different. +The steps should be basically identical for other panels, but screenshots will look visually different. +If in doubt, contact your host's support. /// + +## Creating a sub-user + +This is **optional**, but highly recommended, for security reasons. + +Navigate to your `Users` page, and click the `New User` button. +Type in an email address, and press `Select all permissions`. +*The bot doesn't need all of the permissions you just gave it to function, we'll deal with that in a moment.* + +![image](/img/pterodactyl/setup/1.png) + +Now, you'll need to check the email you just entered into the subusers page, and create an account. I won't cover this, as it'll change depending on what host you're using. + +Moving on, the bot doesn't need all of the permissions you just gave it. This poses a security risk, should the bot be compromised. We can fix this by importing only the permissions the bot requires. Import the following string into your subuser's permissions. + +```json +["websocket.connect","control.read-console","control.console","control.start","control.stop","control.restart","startup.read","startup.update","settings.rename","settings.reinstall"] +``` + +![image](/img/pterodactyl/setup/2.png) + +## Getting an API Key + +**Log out of your primary account, and switch to the sub-user you just created.** + +Navigate to your sub-user account's `API Credentials` page. + +![image](/img/pterodactyl/setup/3.png) + +Create a new API key. + +![image](/img/pterodactyl/setup/4.png) + +You don't have to specify an allowed IP if you don't want to, but I recommend it. If you chose to, you'll need to retrieve your bot's IP address. You can do this through SSH or through a cog like [AAA3A's IP cog](https://github.com/AAA3A-AAA3A/AAA3A-cogs). + +![image](/img/pterodactyl/setup/5.png) + +Now, use the `[p]set api` command on your bot to add the API key. +The format is as follows: + +``` +# Service: pterodactyl +# Keys and Tokens: api_key ptlc_... +``` + +![image](/img/pterodactyl/setup/6.png) + +## Getting server information + +There's some other information that the Pterodactyl cog needs to function. + +First, get the base url for your panel. This does not include any extra information, like server ids, or whatnot. In my case, I'm using `https://mc.bloom.host/`. + +![image](/img/pterodactyl/setup/7.png) + +Use the `[p]pterodactyl config url` command to set the URL the cog will use. +In my case, I'd use `-pterodactyl config url https://mc.bloom.host/`. + +![image](/img/pterodactyl/setup/8.png) + +Now, we need to get the id of your server. Navigate to the `Settings` page in your panel. + +![image](/img/pterodactyl/setup/9.png) + +Use the `[p]pterodactyl config serverid` command to add the server id to the bot. +In my case, I'd use `-pterodactyl config serverid ad712016-df3d-47a5-b1df-6b71baf50340`. + +![image](/img/pterodactyl/setup/10.png) + +Once you've done all of this, you should see a connection message in the bot's logs. Now, we need to configure some other things. + +## Configuring the cog + +### Setting up a console channel + +Create a channel, and make sure the bot has permissions to speak in it. + +/// admonition | Only give access to the console channel to people you trust! + type: danger +If a user account has access to the console channel, they can execute ***any*** command on your server, including power actions. +They will also be able to see potentially sensitive information, such as player IPs. +/// + +Once you've created a channel, use `[p]pterodactyl config consolechannel #channel` to set the console channel. +Now, logs from your server should be posted in the channel you've configured. + +Please note that, in order to avoid Discord ratelimits, logs will not be posted when the server status is one of the following: + +- `starting` +- `stopping` +- `restarting` + +This is to prevent the console channel from flooding and getting backed up by Discord's message ratelimits. + +### Setting up a chat channel + +Create another channel, and make sure the bot has permissions to speak in it and embed links. + +Once you've created a channel, use `[p]pterodactyl config chat channel #channel` to set the console channel. +Now, chat messages, user joins, and advancements/challenges from your server should be posted in the channel you've configured. + +### My chat messages aren't detected! + +If you're not running on recent versions of Paper, which this cog was developed against, or you're otherwise changing for format of chat messages, you'll need to add custom regex through the `[p]pterodactyl config regex` command. Same thing applies if any other type of message isn't being detected. I recomend using ChatGPT or something similar for this, or if you need help, you can join my [Discord server](https://discord.gg/eMUMe77Yb8). + +The default values for all of the configurable regex in the cog is as follows: + +```re +chat messages: \[(\d{2}:\d{2}:\d{2})\sINFO\]:\s<(\w+)>\s(.*), +server messages: ^\[\d{2}:\d{2}:\d{2} INFO\]: \[Not Secure\] \[.*\] (.*), +join messages: ^\[\d{2}:\d{2}:\d{2} INFO\]: ([^<\n]+) joined the game$, +leave messages: ^\[\d{2}:\d{2}:\d{2} INFO\]: ([^<\n]+) left the game$, +achivement messages: ^\[\d{2}:\d{2}:\d{2} INFO\]: (.*) has (made the advancement|completed the challenge) \[(.*)\]$, +``` + +### Changing the tellraw command + +The cog uses a tellraw command to send messages to Minecraft from Discord. To change this, use the `[p]pterodactyl config chat command` command. The JSON format Minecraft uses for this is very janky sometimes, if you need help with changing the command, you can join my [Discord server](https://discord.gg/eMUMe77Yb8). + +Required placeholders: + +- `.%U` - replaced with display name +- `.%M` - replaced with message contents +- `.%C` - replaced with top role color (hex) + +Default: +```json +tellraw @a ["",{"text":".$U ","color":".$C"},{"text":" (DISCORD): ","color":"blue"},{"text":".$M","color":"white"}] +```