Skip to content

Commit 320ee41

Browse files
ez-pluginsez-plugins
committed
docs: rewrite configuration reference for server owners
Replace brief bullet-point stubs with server-owner-targeted documentation: - config.yml: full settings table, annotated example, callout note - rtp.yml: sectioned (bounds, safety, countdown, biomes, protection, on-join, named centers, debug) with tables, annotated YAML examples, and plain-English explanations - limits.yml: per-world/per-group override pattern, storage backend section - gui.yml: slot numbering diagram, full entry field table, biome and current-world examples - queue.yml: explains the queue, tick reference, busy-server example - network.yml: lobby concept explained, all entry fields in a table, proxy setup note - force-rtp.yml: full settings table, clarifies per-bypass rationale
1 parent a0da72d commit 320ee41

7 files changed

Lines changed: 695 additions & 61 deletions

File tree

‎docs/config/config.md‎

Lines changed: 41 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,45 @@
1+
---
2+
title: config.yml
3+
nav_order: 1
4+
parent: Config Reference
5+
---
6+
17
# config.yml
28

3-
Global/core plugin settings:
9+
Global plugin settings — language, message prefix, and a few defaults used by
10+
utility commands. All teleport behaviour, safety rules, and cooldowns live in
11+
their own dedicated files.
12+
13+
## Settings
14+
15+
| Key | Default | Description |
16+
|:----|:--------|:------------|
17+
| `message-prefix` | `"&7[&bEzRTP&7] &r"` | Text prepended to every chat message the plugin sends. Supports `&` color codes and MiniMessage. |
18+
| `language` | `en` | Selects which file under `messages/` is used for player-facing text. Example: `en` loads `messages/en.yml`. |
19+
| `messages.force-legacy-colors` | `false` | Set to `true` on servers running very old clients that do not understand MiniMessage formatting. Converts all output to legacy `§` color codes. |
20+
| `worldguard.region-command.enabled` | `false` | Allows `/rtp <regionId>` to teleport players randomly **inside** a named WorldGuard region. Requires WorldGuard. |
21+
| `worldguard.region-command.autocomplete` | `false` | When enabled, tab-completing `/rtp` will suggest WorldGuard region names. |
22+
| `world` | `world` | Fallback world name used by utility commands (e.g. `/rtp pregenerate`). Does not affect normal RTP — that is set in `rtp.yml`. |
23+
| `radius.min` | `500` | Fallback minimum radius used by utility commands. Does not affect normal RTP. |
24+
| `enable-bstats` | `true` | Sends anonymous usage statistics to [bStats](https://bstats.org/plugin/bukkit/EzRTP/27735). No personal data is collected. Set to `false` to opt out. |
25+
26+
## Example
27+
28+
```yml
29+
message-prefix: "&7[&bEzRTP&7] &r"
30+
language: en
31+
32+
messages:
33+
force-legacy-colors: false
34+
35+
worldguard:
36+
region-command:
37+
enabled: false
38+
autocomplete: false
439

5-
- `message-prefix`: prefix injected into plugin chat output.
6-
- `language`: selects `messages/<language>.yml`.
7-
- `messages.force-legacy-colors`: forces MiniMessage output into legacy colors.
8-
- `worldguard.region-command.*`: toggles `/rtp <region>` command behavior.
9-
- `world`, `radius.min`: defaults used by utility commands such as pregeneration helpers.
10-
- `enable-bstats`: enables anonymous bStats telemetry.
40+
enable-bstats: true
41+
```
1142
12-
Most gameplay RTP settings moved to `rtp.yml` and `limits.yml`.
43+
{: .note }
44+
Most gameplay settings (destination bounds, safety, cooldowns, biomes) are in
45+
`rtp.yml` and `limits.yml`, **not** here.

‎docs/config/force-rtp.md‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,41 @@
1+
---
2+
title: force-rtp.yml
3+
nav_order: 7
4+
parent: Config Reference
5+
---
6+
17
# force-rtp.yml
28

3-
Administrative `/forcertp` behavior.
9+
Controls the `/forcertp <player>` command that lets admins and moderators teleport
10+
another player to a random location. This file lets you set the default world and
11+
choose which normal restrictions are bypassed when the command is used.
12+
13+
---
14+
15+
## Settings
16+
17+
| Key | Default | Description |
18+
|:----|:--------|:------------|
19+
| `default-world` | `world` | World used when the command is run without specifying a world. Set to `auto` to send the target player to a random location in their current world. |
20+
| `bypass.cooldown` | `true` | When `true`, `/forcertp` ignores the target player’s cooldown. Recommended — admins should never be blocked by a cooldown on a moderation tool. |
21+
| `bypass.permission` | `true` | When `true`, `/forcertp` ignores any per-destination permission checks on the target player. |
22+
| `bypass.safety` | `false` | When `true`, the destination does **not** have to pass safety checks — players can be placed on lava, inside water, etc. Leave this `false` unless you have a specific reason. |
23+
24+
---
25+
26+
## Example
27+
28+
```yml
29+
default-world: world
30+
31+
bypass:
32+
cooldown: true # don't wait for the player's cooldown
33+
permission: true # ignore per-destination permissions on the target
34+
safety: false # still enforce safe landing
35+
```
36+
37+
---
438
5-
Use this file to control command restrictions and defaults for forced teleports. Keep this file aligned with your moderation workflow and permission setup.
39+
{: .note }
40+
The `/forcertp` command itself still requires the `ezrtp.admin.forcertp` permission.
41+
The bypass settings only control what restrictions are waived for the **target** player.

‎docs/config/gui.md‎

Lines changed: 137 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,140 @@
1+
---
2+
title: gui.yml
3+
nav_order: 4
4+
parent: Config Reference
5+
---
6+
17
# gui.yml
28

3-
Inventory GUI for selecting RTP destinations.
9+
Configures the optional inventory GUI that lets players pick an RTP destination
10+
by clicking an item. Each "world" entry becomes a clickable icon in the chest
11+
inventory.
12+
13+
---
14+
15+
## Top-level settings
16+
17+
| Key | Default | Description |
18+
|:----|:--------|:------------|
19+
| `enabled` | `true` | Set to `false` to disable the GUI entirely. Players use `/rtp` only as a plain command. |
20+
| `title` | `<dark_aqua><bold>Random Teleport</bold></dark_aqua>` | Title shown at the top of the inventory. Supports MiniMessage formatting. |
21+
| `rows` | `5` | Number of rows in the chest GUI (1–6). Each row has 9 slots, so 5 rows = 45 slots total (0–44). |
22+
| `no-permission-message` | `<red>You do not have permission...</red>` | Message shown when a player clicks a destination they don’t have permission for. |
23+
| `no-destinations` | *(see default)* | Message shown when no destinations are available to the player. |
24+
| `filler.enabled` | `true` | Fill empty slots with a decorative item. |
25+
| `filler.material` | `GLASS_PANE` | Material used for filler items. |
26+
| `filler.name` | `<dark_gray> </dark_gray>` | Display name for filler items (a space makes it invisible in most themes). |
27+
28+
---
29+
30+
## Slot numbering
31+
32+
Slots are numbered left-to-right, top-to-bottom, starting at `0`:
33+
34+
```
35+
Row 1: 0 1 2 3 4 5 6 7 8
36+
Row 2: 9 10 11 12 13 14 15 16 17
37+
Row 3: 18 19 20 21 22 23 24 25 26
38+
Row 4: 27 28 29 30 31 32 33 34 35
39+
Row 5: 36 37 38 39 40 41 42 43 44
40+
```
41+
42+
For a 5-row GUI the centre slot of row 3 is **slot 22** (the default Overworld position).
43+
44+
---
45+
46+
## Adding a destination entry
47+
48+
Each entry under `worlds` becomes one clickable icon. The key name (e.g.
49+
`overworld`) is just an internal identifier — it is never shown to players.
50+
51+
```yml
52+
worlds:
53+
overworld:
54+
slot: 22 # which slot to put this icon in
55+
permission: "" # leave blank = everyone can click it
56+
icon:
57+
material: GRASS_BLOCK
58+
name: "<green><bold>Overworld</bold></green>"
59+
lore:
60+
- "<gray>Explore the surface world.</gray>"
61+
- "<dark_gray>Click to teleport.</dark_gray>"
62+
settings:
63+
world: world # must match the world folder name
64+
```
65+
66+
### Entry fields
67+
68+
| Field | Description |
69+
|:------|:------------|
70+
| `slot` | Inventory slot (0–53). Omit to place entries in order. |
71+
| `permission` | Permission node required to click. Leave blank for no restriction. |
72+
| `icon.material` | Any valid Bukkit/Minecraft item ID (e.g. `GRASS_BLOCK`, `NETHERRACK`). |
73+
| `icon.name` | Display name. Supports MiniMessage. Supports PlaceholderAPI if installed. |
74+
| `icon.lore` | List of lore lines. Supports MiniMessage and PlaceholderAPI. |
75+
| `settings.world` | World to teleport into. Use `auto` to teleport within the player’s current world. |
76+
| `settings.*` | Any `rtp.yml` setting can be overridden here (radius, biomes, cost, etc.). |
77+
78+
---
79+
80+
## Biome-restricted entry example
81+
82+
To add a button that only sends players to forest biomes:
83+
84+
```yml
85+
worlds:
86+
forest:
87+
slot: 11
88+
permission: "ezrtp.gui.forest"
89+
icon:
90+
material: OAK_SAPLING
91+
name: "<dark_green><bold>Forest</bold></dark_green>"
92+
lore:
93+
- "<gray>Land in a forest biome.</gray>"
94+
settings:
95+
world: world
96+
biomes:
97+
include:
98+
- FOREST
99+
- BIRCH_FOREST
100+
- DARK_FOREST
101+
pre-cache:
102+
enabled: true
103+
max-per-biome: 30
104+
```
105+
106+
---
107+
108+
## “Current world” entry
109+
110+
A special entry that teleports the player within whichever world they are already
111+
in. Useful on multi-world servers.
112+
113+
```yml
114+
worlds:
115+
current-world:
116+
slot: 13
117+
permission: ""
118+
icon:
119+
material: COMPASS
120+
name: "<aqua><bold>Current World</bold></aqua>"
121+
lore:
122+
- "<gray>Teleport within your current world.</gray>"
123+
settings:
124+
world: auto
125+
```
126+
127+
---
128+
129+
## Cache filtering
130+
131+
When biome pre-caching is enabled, EzRTP can hide destinations that have no
132+
pre-cached locations ready, so players are never shown an option that would make
133+
them wait.
4134

5-
- `enabled`, `title`, `rows`: top-level GUI toggles/layout.
6-
- `no-permission-message`, `cache-filter-info`, `no-destinations`: GUI messages.
7-
- `disable-cache-filtering`, `admin-only-cache-info`: cache visibility behavior.
8-
- `rare_biomes.*`: cache requirements for rare biome destinations.
9-
- `filler.*`: decorative slot filler item.
10-
- `worlds.<id>.*`: clickable entries (slot, permission, icon, RTP settings overrides).
135+
| Key | Default | Description |
136+
|:----|:--------|:------------|
137+
| `disable-cache-filtering` | `false` | Set to `true` to always show all destinations regardless of cache state. |
138+
| `admin-only-cache-info` | `false` | When `true`, the “only showing cached options” notice is only shown to players with admin permissions. |
139+
| `rare_biomes.enabled` | `true` | Apply stricter cache requirements to rare biomes listed in `rtp.yml`. |
140+
| `rare_biomes.require-cache.minimum-cached` | `1` | Minimum pre-cached locations needed before a rare-biome destination is shown. |

‎docs/config/limits.md‎

Lines changed: 96 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,99 @@
1+
---
2+
title: limits.yml
3+
nav_order: 3
4+
parent: Config Reference
5+
---
6+
17
# limits.yml
28

3-
Cooldown, usage limits, and storage backend settings.
9+
Controls how often players can use `/rtp`, how many times per day/week, and what
10+
it costs. You can set different rules per world and per permission group (e.g. VIP
11+
gets a shorter cooldown than regular players).
12+
13+
## Default limits
14+
15+
The `rtp-limits.default` block applies to all players and worlds unless a more
16+
specific override exists.
17+
18+
| Key | Default | Description |
19+
|:----|:--------|:------------|
20+
| `cooldown-seconds` | `300` | Seconds a player must wait between teleports. `0` = no cooldown. |
21+
| `daily-limit` | `10` | Maximum number of RTP uses per calendar day. `-1` = unlimited. |
22+
| `weekly-limit` | `50` | Maximum number of RTP uses per calendar week. `-1` = unlimited. |
23+
| `cost` | `0.0` | Economy cost per teleport (requires Vault). `0.0` = free. |
24+
25+
## Per-world and per-group overrides
26+
27+
Under `rtp-limits.worlds` you can override any of the four keys above for a
28+
specific world, and optionally narrow it further to a permission group.
29+
30+
Group keys start with `group.` followed by the group name as reported by your
31+
permissions plugin (e.g. `group.vip`, `group.staff`).
32+
33+
```yml
34+
rtp-limits:
35+
default:
36+
cooldown-seconds: 300
37+
daily-limit: 10
38+
weekly-limit: 50
39+
cost: 0.0
40+
worlds:
41+
world: # overworld rules
42+
default: # applies to everyone
43+
cooldown-seconds: 300
44+
daily-limit: 10
45+
weekly-limit: 50
46+
cost: 0.0
47+
group.vip: # VIP players get less cooldown and more uses
48+
cooldown-seconds: 60
49+
daily-limit: 50
50+
weekly-limit: 200
51+
cost: 0.0
52+
world_nether: # stricter limits in the Nether
53+
default:
54+
cooldown-seconds: 600
55+
daily-limit: 5
56+
weekly-limit: 20
57+
cost: 0.0
58+
group.staff: # staff have no restrictions
59+
cooldown-seconds: 0
60+
daily-limit: -1
61+
weekly-limit: -1
62+
cost: 0.0
63+
```
64+
65+
## Bypass permissions
66+
67+
Players with any of the listed permissions skip cooldowns and usage limits
68+
entirely, regardless of world or group configuration.
69+
70+
```yml
71+
rtp-limits:
72+
bypass-permissions:
73+
- ezrtp.bypass.cooldown
74+
- ezrtp.bypass.limit
75+
```
76+
77+
## Other settings
78+
79+
| Key | Default | Description |
80+
|:----|:--------|:------------|
81+
| `allow-gui-during-cooldown` | `true` | When `true`, players on cooldown can still open the destination GUI — they just cannot confirm a teleport until the cooldown expires. Set to `false` to hide the GUI entirely. |
82+
83+
## Storage backend
84+
85+
Cooldown and usage data can be stored in flat files or MySQL.
86+
87+
```yml
88+
rtp-limits:
89+
storage: yaml # options: yaml | mysql
90+
mysql:
91+
host: localhost
92+
port: 3306
93+
database: ezrtp
94+
username: ""
95+
password: ""
96+
```
497

5-
- `rtp-limits.storage`: `yaml` or `mysql`.
6-
- `rtp-limits.mysql.*`: JDBC connection values for MySQL storage.
7-
- `rtp-limits.default.*`: baseline cooldown/limits/cost.
8-
- `rtp-limits.worlds.<world>.<group>.*`: per-world and permission-group overrides.
9-
- `rtp-limits.bypass-permissions`: permissions that bypass cooldown/limits.
10-
- `rtp-limits.allow-gui-during-cooldown`: whether GUI open is allowed while on cooldown.
98+
Use `mysql` on networks where multiple servers share player data (e.g. a survival
99+
server and a resource world that both enforce the same weekly limit).

0 commit comments

Comments
 (0)