docs(pterodactyl): flushed out the docs more
This commit is contained in:
parent
12862ccea7
commit
45797361a6
GPG key ID:
B8953EC01E5C4063
4 changed files with 248 additions and 142 deletions
165
.docs/pterodactyl/configuration.md
Normal file
165
.docs/pterodactyl/configuration.md
Normal file
|
|
@ -0,0 +1,165 @@
|
||||||
|
# Configuration
|
||||||
|
|
||||||
|
This page will go over all of the configuration options for the Pterodactyl cog.
|
||||||
|
All of the commands below can be accessed through `[p]pterodactyl config`.
|
||||||
|
|
||||||
|
## `api`
|
||||||
|
|
||||||
|
This option determines which [PlayerDB](https://playerdb.co/) endpoint the cog will use to retrieve player avatars.
|
||||||
|
This is only used for webhook avatars in the chat integration system. You should probably leave this as default.
|
||||||
|
|
||||||
|
Default value: `minecraft`
|
||||||
|
|
||||||
|
## `chat`
|
||||||
|
|
||||||
|
### `channel`
|
||||||
|
|
||||||
|
This option determines what channel chat messages will be sent to. If this is unset, the chat integration won't work.
|
||||||
|
**Make sure the bot has permissions to speak in this channel!**
|
||||||
|
|
||||||
|
Default value: `None`
|
||||||
|
|
||||||
|
### `command`
|
||||||
|
|
||||||
|
This option determines what command will be sent to the server whenever a message is sent in the configured chat channel. 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).
|
||||||
|
|
||||||
|
Available placeholders:
|
||||||
|
|
||||||
|
- `.$C` - replaced with hex color of the author's top colored role
|
||||||
|
- `.$D` - replaced with the author's discriminator (will usually be 0, you shouldn't use this)
|
||||||
|
- `.$I` - replaced with the author's ID
|
||||||
|
- `.$M` - replaced with message content
|
||||||
|
- `.$N` - replaced with author's display name (or guild nickname, if set)
|
||||||
|
- `.$U` - replaced with the author's username (NOT display name, you should usually use `.$N`)
|
||||||
|
|
||||||
|
Default value:
|
||||||
|
|
||||||
|
```json
|
||||||
|
tellraw @a ["",{"text":".$D ","color":".$C"},{"text":" (DISCORD): ","color":"blue"},{"text":".$M","color":"white"}]
|
||||||
|
```
|
||||||
|
|
||||||
|
## `consolechannel`
|
||||||
|
|
||||||
|
/// 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 some power actions.
|
||||||
|
They will also be able to see potentially sensitive information, such as player IPs, if [IP Masking](configuration.md#ip) is disabled.
|
||||||
|
///
|
||||||
|
|
||||||
|
This option determines what channel console logs will be sent to. If this is unset, the console integration won't work.
|
||||||
|
**Make sure the bot has permissions to speak in this channel!**
|
||||||
|
Server status changes, Discord --> Minecraft chat messages, and command executions will all be logged here.
|
||||||
|
|
||||||
|
/// admonition
|
||||||
|
type: info
|
||||||
|
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`
|
||||||
|
|
||||||
|
This is to prevent the console channel from flooding and getting backed up by Discord's message ratelimits.
|
||||||
|
///
|
||||||
|
|
||||||
|
Default value: `None`
|
||||||
|
|
||||||
|
## `ip`
|
||||||
|
|
||||||
|
This option determines whether or not IP's will be redacted when posted in chat or to the console channel.
|
||||||
|
|
||||||
|
Default value: `True`
|
||||||
|
|
||||||
|
## `messages`
|
||||||
|
|
||||||
|
### `join`
|
||||||
|
|
||||||
|
This option determines what the description in embeds will be when a user joins the server. Has no effect if embeds aren't used.
|
||||||
|
|
||||||
|
Default value: `Welcome to the server! 👋`
|
||||||
|
|
||||||
|
### `leave`
|
||||||
|
|
||||||
|
This option determines what the description in embeds will be when a user leaves the server. Has no effect if embeds aren't used.
|
||||||
|
|
||||||
|
Default value: `Goodbye! 👋`
|
||||||
|
|
||||||
|
### `shutdown`
|
||||||
|
|
||||||
|
This option determines what the bot will send in the chat channel when the server stops.
|
||||||
|
|
||||||
|
Default value: `Server stopped!`
|
||||||
|
|
||||||
|
### `startup`
|
||||||
|
|
||||||
|
This option determines what the bot will send in the chat channel when the server is started.
|
||||||
|
|
||||||
|
Default value: `Server started!`
|
||||||
|
|
||||||
|
## `regex`
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
### `achievement`
|
||||||
|
|
||||||
|
This regex pattern is used to detect advacnements/challenges. The default should work for most Minecraft servers.
|
||||||
|
|
||||||
|
Default value:
|
||||||
|
|
||||||
|
```re
|
||||||
|
^\[\d{2}:\d{2}:\d{2} INFO\]: (.*) has (made the advancement|completed the challenge) \[(.*)\]$
|
||||||
|
```
|
||||||
|
|
||||||
|
### `chat`
|
||||||
|
|
||||||
|
This regex pattern is used to detect chat messages. You will probably have to change this if you're using any plugins or mods that use custom chat formatting, like EssentialsX Chat or Styled Chat.
|
||||||
|
|
||||||
|
Default value:
|
||||||
|
|
||||||
|
```re
|
||||||
|
\[(\d{2}:\d{2}:\d{2})\sINFO\]:\s<(\w+)>\s(.*)
|
||||||
|
```
|
||||||
|
|
||||||
|
### `join`
|
||||||
|
|
||||||
|
This regex pattern is used to detect whenever a user joins the server. You shouldn't usually need to change this.
|
||||||
|
|
||||||
|
Default value:
|
||||||
|
|
||||||
|
```re
|
||||||
|
^\[\d{2}:\d{2}:\d{2} INFO\]: ([^<\n]+) joined the game$
|
||||||
|
```
|
||||||
|
|
||||||
|
### `leave`
|
||||||
|
|
||||||
|
This regex pattern is used to detect whenever a user leaves the server. You shouldn't usually need to change this.
|
||||||
|
|
||||||
|
Default value:
|
||||||
|
|
||||||
|
```re
|
||||||
|
^\[\d{2}:\d{2}:\d{2} INFO\]: ([^<\n]+) left the game$
|
||||||
|
```
|
||||||
|
|
||||||
|
### `server`
|
||||||
|
|
||||||
|
This regex pattern is used to detect whenever a server message is sent. You will have to change this if you aren't running on Paper, most likely.
|
||||||
|
|
||||||
|
Default value:
|
||||||
|
|
||||||
|
```re
|
||||||
|
^\[\d{2}:\d{2}:\d{2} INFO\]:( \[Not Secure\])? \[.*\] (.*)
|
||||||
|
```
|
||||||
|
|
||||||
|
## `serverid`
|
||||||
|
|
||||||
|
This option determines which server's websocket to connect to. See [Getting Started](getting-started.md#getting-server-information) for more information on this.
|
||||||
|
|
||||||
|
Default value: `None`
|
||||||
|
|
||||||
|
## `url`
|
||||||
|
|
||||||
|
This option determines what panel the cog will send requests to. See [Getting Started](getting-started.md#getting-server-information) for more information on this.
|
||||||
|
|
||||||
|
Default value: `None`
|
||||||
|
|
||||||
|
## `view`
|
||||||
|
|
||||||
|
Lists all of the configuration options offered by the cog.
|
||||||
81
.docs/pterodactyl/getting-started.md
Normal file
81
.docs/pterodactyl/getting-started.md
Normal file
|
|
@ -0,0 +1,81 @@
|
||||||
|
# Getting Started
|
||||||
|
|
||||||
|
This page will go over the steps required to get started with 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.
|
||||||
|
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.*
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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"]
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Create a new API key.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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_...
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 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/`.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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/`.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Now, we need to get the id of your server. Navigate to the `Settings` page in your panel.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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`.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
See the [Configuration](configuration.md) page for more information.
|
||||||
|
|
@ -1,141 +0,0 @@
|
||||||
# Setup
|
|
||||||
|
|
||||||
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.
|
|
||||||
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.*
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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"]
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Create a new API key.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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_...
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## 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/`.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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/`.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Now, we need to get the id of your server. Navigate to the `Settings` page in your panel.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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`.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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`
|
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
Available placeholders:
|
|
||||||
|
|
||||||
- `.$C` - replaced with hex color of the author's top colored role
|
|
||||||
- `.$D` - replaced with the author's discriminator (will usually be 0, you shouldn't use this)
|
|
||||||
- `.$I` - replaced with the author's ID
|
|
||||||
- `.$M` - replaced with message content
|
|
||||||
- `.$N` - replaced with author's display name (or guild nickname, if set)
|
|
||||||
- `.$U` - replaced with the author's username (NOT display name, you should usually use `.$N`)
|
|
||||||
|
|
||||||
Default:
|
|
||||||
```json
|
|
||||||
tellraw @a ["",{"text":".$D ","color":".$C"},{"text":" (DISCORD): ","color":"blue"},{"text":".$M","color":"white"}]
|
|
||||||
```
|
|
||||||
|
|
@ -21,7 +21,8 @@ nav:
|
||||||
- Nerdify: nerdify.md
|
- Nerdify: nerdify.md
|
||||||
- Pterodactyl:
|
- Pterodactyl:
|
||||||
- pterodactyl/index.md
|
- pterodactyl/index.md
|
||||||
- Setup: pterodactyl/setup.md
|
- Getting Started: pterodactyl/getting-started.md
|
||||||
|
- Configuration: pterodactyl/configuration.md
|
||||||
|
|
||||||
plugins:
|
plugins:
|
||||||
- git-authors
|
- git-authors
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue