Skip to content

Commit 0d74ebf

Browse files
QuozulQuozul
committed
chore(docs): Update README and improve docs
1 parent 02b005d commit 0d74ebf

File tree

5 files changed

+270
-57
lines changed

5 files changed

+270
-57
lines changed

‎README.md‎

Lines changed: 42 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,72 @@
11
# PterodactylPowerAction
22

3-
A Velocity plugin to start and stop servers using the [Pterodactyl](https://pterodactyl.io/) client API.
3+
[![GitHub CI](https://img.shields.io/github/actions/workflow/status/Pickaria/PterodactylPowerAction/.github%2Fworkflows%2Fpush.yml?branch=master)](https://github.com/Pickaria/PterodactylPowerAction/actions)
4+
[![Latest Release](https://img.shields.io/github/v/release/Pickaria/PterodactylPowerAction)](https://github.com/Pickaria/PterodactylPowerAction/releases)
5+
[![License](https://img.shields.io/github/license/Pickaria/PterodactylPowerAction)](LICENSE)
46

5-
## How it works
7+
A resource-saving Velocity plugin that automatically manages your Minecraft servers by starting them on demand and
8+
shutting them down when idle, using either the [Pterodactyl](https://pterodactyl.io/) API or shell commands.
69

7-
This plugin will stop a server after a given delay (1 hour by default) if it is empty after a player left or changed
8-
server.
10+
---
911

10-
When a player tries to connect to a stopped server, they will be redirected to a waiting server such
11-
as [Limbo](https://www.spigotmc.org/resources/82468/) and will be automatically redirected to the requested server once
12-
it is started.
12+
## ✨ Key Features
1313

14-
If the player is already connected on the network, they will simply be informed by a message that they will be
15-
automatically redirected once the server is ready.
14+
- 🔌 **Energy & Resource Saving** - Automatically shuts down empty servers after a configurable idle period (default: 1
15+
hour)
1616

17-
If the server fails to start, the player will be informed to try again.
17+
- 🚀 **On-Demand Server Startup** - Starts servers only when players need them, optimizing resource usage
1818

19-
This plugin is also able to redirect your player that has been kicked from a backend server to the waiting server, this
20-
is toggleable in the configuration file.
19+
- 🔄 **Seamless Player Experience**:
20+
- Redirects players to a lightweight waiting server during startup
21+
- Automatically transfers players when their destination server is ready
22+
- Keeps players informed with status messages throughout the process
2123

22-
## Configuration
24+
- 🛡️ **Kick Protection** - Optionally redirects kicked players to your waiting server instead of disconnecting them
2325

24-
The [configuration guide](https://github.com/Pickaria/PterodactylPowerAction/wiki/Configuration-Guide) is available on
25-
the wiki.
26+
- 🧰 **Flexible Implementation**:
27+
- Works with Pterodactyl Panel API for managed hosting
28+
- Supports direct shell commands for self-hosted environments
2629

27-
## In-game Commands
30+
- ⚙️ **Highly Configurable**:
31+
- Customizable shutdown delay
32+
- Multiple server status checking methods
33+
- Configurable shutdown behavior on proxy restart
2834

29-
The plugin's command require the player to have the `pterodactylpoweraction.use` permission.
35+
- 🌐 **Multilingual Support** - Automatically translates messages based on the client's language (English, German,
36+
French)
3037

31-
### Reload Plugin Configuration
38+
- 🔍 **Diagnostic Tools** - Built-in doctor command to validate your configuration and troubleshoot issues
3239

33-
To reload the plugin's configuration, use the following command:
40+
## How it Works
3441

35-
```plaintext
36-
/pterodactylpoweraction reload
37-
```
42+
When a player tries to connect to a stopped server, they're temporarily sent to your waiting server while
43+
PterodactylPowerAction starts their requested destination. Once the server is ready, they're automatically transferred.
44+
The plugin monitors player activity and intelligently shuts down empty servers to save resources.
3845

39-
> [!NOTE]
40-
> If you have added a new server to `velocity.toml`, you will need to reload this configuration as well.
41-
> Currently, PterodactylPowerAction does not automatically reload Velocity's configuration, so you may require an
42-
> additional plugin for this functionality.
46+
![server-is-starting.png](docs/assets/server-is-starting.png)
47+
_Shader is Photon._
4348

44-
### Shutdown Empty Servers
49+
---
4550

46-
To manually shut down empty servers, use the following command:
51+
## Documentation
4752

48-
```plaintext
49-
/pterodactylpoweraction clear [delay=0]
50-
```
53+
### Configuration
5154

52-
This will check the player count on all servers and send stop signals to all the empty servers after the given delay. If
53-
not specified, the delay is 0 seconds by default.
55+
The [configuration guide](docs/configuration.md) is available in this document.
5456

55-
### Run Checks and Validate Configuration
57+
### In-game Commands
5658

57-
To run checks and validate the configuration, use the following command:
59+
The [commands guide](docs/commands.md) is available in this document.
5860

59-
```plaintext
60-
/pterodactylpoweraction doctor
61-
```
62-
63-
The `doctor` command is a tool for troubleshooting issues with your PterodactylPowerAction setup. It performs a
64-
series of diagnostic checks to ensure that your configuration files are correctly set up and that all necessary
65-
components are functioning properly. Running this command can help you identify and resolve potential problems.
66-
67-
## Localization
68-
69-
The plugin's messages are automatically translated based on the client's language. Currently, the following languages
70-
are supported:
71-
72-
- German
73-
- English
74-
- French
61+
---
7562

7663
## Waiting/Limbo servers
7764

7865
Here is a small list of recommended lightweights servers software to use as waiting server:
7966

80-
- [Limbo](https://www.spigotmc.org/resources/82468/)
67+
- [PicoLimbo](https://github.com/Pickaria/PterodactylPowerAction)
8168
- [NanoLimbo](https://www.spigotmc.org/resources/86198/)
82-
83-
I am also developing my own experimental [PicoLimbo](https://github.com/Quozul/PicoLimbo) server from scratch in Rust.
84-
It has 0% CPU usage on idle and uses less than 10 MB of memory with minimal network footprint by only implementing the
85-
required packets.
69+
- [Limbo](https://www.spigotmc.org/resources/82468/)
8670

8771
Note that the waiting server does not have to be a limbo server specifically, it can be any server as long as it is
8872
always accessible. If you have a dedicated lobby server in your network, you can use that, no need for a dedicated limbo
@@ -93,6 +77,8 @@ server!
9377
I am running Minecraft servers on dedicated hardware at home, I wanted to save energy costs and memory usage by stopping
9478
empty servers. Running the waiting server on a low power ARM Single Board Computer can also further save costs.
9579

80+
---
81+
9682
## Contributing
9783

9884
Contributions are welcome! If you encounter any issues or have suggestions for improvement, please submit an issue or

‎docs/assets/server-is-starting.png‎

838 KB
Loading

‎docs/commands.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Commands Guide
2+
3+
This document outlines the available commands for the PterodactylPowerAction plugin for Velocity, which allows server
4+
administrators to manage Minecraft servers through in-game commands.
5+
6+
## Command Overview
7+
8+
All PterodactylPowerAction commands use the base command:
9+
10+
```
11+
/pterodactylpoweraction
12+
```
13+
14+
For convenience, the plugin also supports the shortened alias:
15+
16+
```
17+
/ppa
18+
```
19+
20+
## Permission Requirements
21+
22+
All commands require the following permission:
23+
24+
```
25+
pterodactylpoweraction.use
26+
```
27+
28+
## Available Commands
29+
30+
### Reload Configuration
31+
32+
Reloads the plugin's configuration from disk.
33+
34+
```
35+
/pterodactylpoweraction reload
36+
```
37+
38+
**Aliases:** `/ppa reload`
39+
40+
**Description:**
41+
This command reloads the plugin's configuration file, allowing you to apply changes without restarting the proxy server.
42+
Any modifications to the configuration file will take effect immediately after running this command.
43+
44+
**Notes:**
45+
46+
- This command only reloads the plugin's configuration, not Velocity's configuration.
47+
- If you've added new servers to `velocity.toml`, you'll need to reload Velocity's configuration separately.
48+
49+
---
50+
51+
### Shutdown Empty Servers
52+
53+
Manually shuts down servers with no players.
54+
55+
```
56+
/pterodactylpoweraction clear [delay=0]
57+
```
58+
59+
**Aliases:** `/ppa clear [delay=0]`
60+
61+
**Parameters:**
62+
63+
- `delay` (optional): Time in seconds to wait before shutting down servers. Defaults to 0 if not specified.
64+
65+
**Description:**
66+
This command checks the player count on all configured servers and sends stop signals to any empty servers after the
67+
specified delay. This is useful for manually freeing up resources when servers are not in use.
68+
69+
**Examples:**
70+
71+
- `/ppa clear` - Immediately shut down all empty servers
72+
- `/ppa clear 30` - Shut down all servers after a 30-second delay if they're still empty
73+
74+
---
75+
76+
### Run Diagnostic Checks
77+
78+
Validates the plugin's configuration and performs diagnostic checks.
79+
80+
```
81+
/pterodactylpoweraction doctor
82+
```
83+
84+
**Aliases:** `/ppa doctor`
85+
86+
**Description:**
87+
The `doctor` command is a troubleshooting tool that performs a series of diagnostic checks on your
88+
PterodactylPowerAction setup.
89+
Running this command can help identify and resolve potential issues with your configuration.

‎docs/configuration.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Configuration Guide
2+
3+
This document explains how to configure the PterodactylPowerAction plugin for Velocity, which allows you to
4+
automatically start and stop Minecraft servers using either the Pterodactyl API or shell commands.
5+
6+
## Configuration File Overview
7+
8+
The configuration file uses YAML format and supports two main modes of operation:
9+
10+
- Pterodactyl API integration
11+
- Shell command execution
12+
13+
## Basic Configuration Structure
14+
15+
```yaml
16+
type: "pterodactyl" # or "shell"
17+
waiting_server_name: "limbo"
18+
ping_method: "ping" # or "pterodactyl"
19+
maximum_ping_duration: 60
20+
shutdown_after_duration: 3600
21+
redirect_to_waiting_server_on_kick: true
22+
shutdown_behaviour: "shutdown_all"
23+
```
24+
25+
## Configuration Options
26+
27+
### Common Settings
28+
29+
| Option | Description | Default Value | Possible Values |
30+
|--------------------------------------|----------------------------------------------------------------------------------------|------------------|---------------------------------------------------|
31+
| `type` | The method used to control servers | Required | `"pterodactyl"`, `"shell"` |
32+
| `waiting_server_name` | The server players will be sent to while waiting for their destination server to start | Required | Any server defined in `velocity.toml` |
33+
| `ping_method` | Method used to check if a server is running | `"ping"` | `"ping"`, `"pterodactyl"` |
34+
| `maximum_ping_duration` | Maximum time (in seconds) to wait for a server to respond | `60` | Any positive integer |
35+
| `shutdown_after_duration` | Time (in seconds) after which an empty server will be shut down | `3600` | Any positive integer |
36+
| `redirect_to_waiting_server_on_kick` | Whether to redirect players to the waiting server when kicked from a backend server | `false` | `true`, `false` |
37+
| `shutdown_behaviour` | What to do with servers when the proxy shuts down | `"shutdown_all"` | `"shutdown_all"`, `"shutdown_empty"`, `"nothing"` |
38+
39+
### Pterodactyl-Specific Settings
40+
41+
When `type` is set to `"pterodactyl"`, the following settings are required:
42+
43+
```yaml
44+
pterodactyl_api_key: "ptlc_xxx"
45+
pterodactyl_client_api_base_url: "https://example.com/api/client"
46+
servers:
47+
server_name: "server_id"
48+
```
49+
50+
| Option | Description |
51+
|-----------------------------------|------------------------------------------------------------|
52+
| `pterodactyl_api_key` | Client API key from Pterodactyl panel |
53+
| `pterodactyl_client_api_base_url` | Base URL for the Pterodactyl client API |
54+
| `servers` | Mapping of Velocity server names to Pterodactyl server IDs |
55+
56+
### Shell-Specific Settings
57+
58+
When `type` is set to `"shell"`, the following structure is required:
59+
60+
```yaml
61+
servers:
62+
server_name:
63+
working_directory: "/path/to/directory" # Optional
64+
start: "command to start server"
65+
stop: "command to stop server"
66+
```
67+
68+
| Option | Description |
69+
|---------------------|-------------------------------------------|
70+
| `working_directory` | Directory to run commands from (optional) |
71+
| `start` | Command to start the server |
72+
| `stop` | Command to stop the server |
73+
74+
## Shutdown Behavior Options
75+
76+
The `shutdown_behaviour` setting determines what happens to servers when the proxy shuts down:
77+
78+
| Value | Description |
79+
|--------------------|-------------------------------------------------|
80+
| `"nothing"` | Keeps all servers running |
81+
| `"shutdown_empty"` | Shuts down only servers with no players |
82+
| `"shutdown_all"` | Shuts down all servers, even those with players |
83+
84+
## Ping Methods
85+
86+
The `ping_method` setting determines how server availability is checked:
87+
88+
| Value | Description |
89+
|-----------------|--------------------------------------------------------------------------------|
90+
| `"ping"` | Uses Velocity's built-in ping mechanism (lighter and usually faster) |
91+
| `"pterodactyl"` | Uses the Pterodactyl API (may be more accurate but requires API configuration) |
92+
93+
## Example Configurations
94+
95+
### Pterodactyl Example
96+
97+
```yaml
98+
type: "pterodactyl"
99+
pterodactyl_api_key: "ptlc_xxx"
100+
pterodactyl_client_api_base_url: "https://panel.example.com/api/client"
101+
servers:
102+
survival: "abc123"
103+
creative: "def456"
104+
waiting_server_name: "limbo"
105+
ping_method: "ping"
106+
maximum_ping_duration: 60
107+
shutdown_after_duration: 3600
108+
redirect_to_waiting_server_on_kick: true
109+
shutdown_behaviour: "shutdown_empty"
110+
```
111+
112+
### Shell Example
113+
114+
```yaml
115+
type: "shell"
116+
servers:
117+
survival:
118+
working_directory: "/home/minecraft/servers"
119+
start: "docker compose start survival"
120+
stop: "docker compose stop survival"
121+
creative:
122+
working_directory: "/home/minecraft/servers"
123+
start: "docker compose start creative"
124+
stop: "docker compose stop creative"
125+
waiting_server_name: "limbo"
126+
ping_method: "ping"
127+
maximum_ping_duration: 60
128+
shutdown_after_duration: 3600
129+
redirect_to_waiting_server_on_kick: true
130+
shutdown_behaviour: "shutdown_all"
131+
```
132+
133+
## Notes and Warnings
134+
135+
- When using Pterodactyl behind a proxy (like CloudFlare DNS proxy), you may encounter connection issues.
136+
- The `cd` command will not work in shell commands. Use the `working_directory` setting instead.
137+
- Shell command mode has not been extensively tested on Windows.
138+
- If you add a new server to `velocity.toml`, you'll need to reload Velocity's configuration separately.

‎src/main/java/fr/pickaria/pterodactylpoweraction/ConnectionListener.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ public void onServerPreConnect(ServerPreConnectEvent event) {
7070
} else {
7171
// Server is not running, inform the player and redirect somewhere else
7272
RegisteredServer waitingServer = getWaitingServer();
73+
// TODO: If the waiting server is not reachable, we should kick instead
7374
event.setResult(ServerPreConnectEvent.ServerResult.allowed(waitingServer));
7475
}
7576

@@ -116,7 +117,6 @@ private void redirectPlayerToWaitingServerOnKick(KickedFromServerEvent event) {
116117
if (isConnectedToWaitingServer) {
117118
event.setResult(KickedFromServerEvent.Notify.create(getKickDisconnectMessage(event)));
118119
} else {
119-
// TODO: If the waiting server is not reachable, we should kick instead
120120
event.setResult(KickedFromServerEvent.RedirectPlayer.create(waitingServer, getKickRedirectMessage(event)));
121121
}
122122
scheduleServerShutdown(event.getServer());

0 commit comments

Comments
 (0)