Skip to content

Commit 2a370ff

Browse files
NonSwagNonSwag
authored
Merge pull request #144 from TheNextLvl-net/docs/portals
Add portals documentation
2 parents 78536d6 + a4eca57 commit 2a370ff

File tree

8 files changed

+634
-12
lines changed

8 files changed

+634
-12
lines changed

‎content/docs/portals/access-control.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Access Control
3+
description: Manage portal permissions, costs, and cooldowns
4+
---
5+
6+
# Access Control
7+
8+
Access control allows you to restrict portal usage with permissions, entry fees, and cooldowns.
9+
Create VIP portals, premium teleports, or prevent portal spam.
10+
11+
## Commands
12+
13+
### Set Entry Permission
14+
15+
Sets a permission requirement for using the portal.
16+
Usage: `/portal permission <portal> <permission>`
17+
18+
**Examples:**
19+
```
20+
<gray># Require VIP permission</gray>
21+
/portal permission <aqua>vip-portal</aqua> <yellow>server.vip</yellow>
22+
23+
<gray># Require admin permission</gray>
24+
/portal permission <aqua>admin-portal</aqua> <yellow>server.admin</yellow>
25+
26+
<gray># Require custom permission</gray>
27+
/portal permission <aqua>premium-portal</aqua> <yellow>portals.premium</yellow>
28+
29+
<gray># Require donor permission</gray>
30+
/portal permission <aqua>donor-portal</aqua> <yellow>server.donor</yellow>
31+
```
32+
33+
<Callout type="info">
34+
Players without the required permission will be denied entry.
35+
</Callout>
36+
37+
### Set Entry Cost
38+
39+
Sets an entry fee that players must pay to use the portal.
40+
Usage: `/portal cost <portal> <amount>`
41+
42+
**Examples:**
43+
```
44+
<gray># Set cost of 100</gray>
45+
/portal cost <aqua>spawn-portal</aqua> <yellow>100</yellow>
46+
47+
<gray># Set cost of 500</gray>
48+
/portal cost <aqua>vip-portal</aqua> <yellow>500</yellow>
49+
50+
<gray># Set cost of 1000</gray>
51+
/portal cost <aqua>premium-portal</aqua> <yellow>1000</yellow>
52+
53+
<gray># Remove cost</gray>
54+
/portal cost <aqua>free-portal</aqua> <yellow>0</yellow>
55+
```
56+
57+
<Callout type="warning">
58+
Entry costs require Vault and an economy plugin to be installed.
59+
Economy must be enabled in the configuration file.
60+
</Callout>
61+
62+
### Set Cooldown
63+
64+
Sets a cooldown period between portal uses for each player.
65+
Usage: `/portal cooldown <portal> <cooldown>`
66+
67+
**Examples:**
68+
```
69+
<gray># Set 30 second cooldown</gray>
70+
/portal cooldown <aqua>spawn-portal</aqua> <yellow>30s</yellow>
71+
72+
<gray># Set 60 second cooldown</gray>
73+
/portal cooldown <aqua>random-portal</aqua> <yellow>60s</yellow>
74+
75+
<gray># Set 5 minute cooldown</gray>
76+
/portal cooldown <aqua>premium-portal</aqua> <yellow>300s</yellow>
77+
78+
<gray># Remove cooldown</gray>
79+
/portal cooldown <aqua>instant-portal</aqua> <yellow>0</yellow>
80+
```
81+
82+
<Callout type="info">
83+
Cooldowns are per-player and prevent portal spam.
84+
</Callout>
85+
86+
## Entry Denial
87+
88+
When a player is denied entry to a portal, they will:
89+
90+
1. Be pushed back from the portal (if knockback is enabled)
91+
2. Not be charged or put on cooldown
92+
93+
Players can be denied for:
94+
- Missing required permission
95+
- Portal still on cooldown from previous use
96+
- Insufficient funds for entry fee
97+
98+
<Callout type="info">
99+
Knockback speed and whether knockback is enabled can be configured in the config file.
100+
</Callout>

‎content/docs/portals/creating-portals.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Creating Portals
3+
description: Create and define portal regions
4+
---
5+
6+
# Creating Portals
7+
8+
Creating portals is the first step in building your portal network.
9+
You can create portals using WorldEdit selections or by manually specifying coordinates.
10+
11+
## Commands
12+
13+
### Create a Portal
14+
15+
Usage: `/portal create <name> [<from>] <to> [<world>]`
16+
Creates a new portal with the specified name and region.
17+
18+
**With WorldEdit Selection:**
19+
```
20+
<gray># Get WorldEdit wand</gray>
21+
//wand
22+
23+
<gray># Select two corners of the portal region</gray>
24+
<gray># Left-click first corner, right-click second corner</gray>
25+
26+
<gray># Create the portal</gray>
27+
/portal create <aqua>my-portal</aqua>
28+
```
29+
30+
**With Manual Coordinates:**
31+
```
32+
<gray># Create portal with specific bounds</gray>
33+
/portal create <aqua>spawn-portal</aqua> <yellow>0 64 0</yellow> <green>10 74 10</green> <light_purple>minecraft:overworld</light_purple>
34+
35+
<gray># Create large portal area</gray>
36+
/portal create <aqua>hub-portal</aqua> <yellow>-5 60 -5</yellow> <green>5 70 5</green> <light_purple>farmworld:overworld</light_purple>
37+
38+
<gray># Create vertical portal</gray>
39+
/portal create <aqua>wall-portal</aqua> <yellow>100 64 100</yellow> <green>105 74 100</green>
40+
```
41+
42+
<Callout type="info">
43+
If you have a WorldEdit selection active, you don't need to specify coordinates.
44+
If you don't have a selection, coordinates are required.
45+
</Callout>
46+
47+
### Redefine Portal Bounds
48+
49+
Usage: `/portal redefine <portal> [<from>] <to> [<world>]`
50+
Changes the physical region of an existing portal.
51+
52+
**With WorldEdit Selection:**
53+
```
54+
<gray># Select new portal region with WorldEdit</gray>
55+
//wand
56+
57+
<gray># Redefine the portal</gray>
58+
/portal redefine <aqua>my-portal</aqua>
59+
```
60+
61+
**With Manual Coordinates:**
62+
```
63+
<gray># Redefine portal with new bounds</gray>
64+
/portal redefine <aqua>spawn-portal</aqua> <yellow>0 64 0</yellow> <green>15 74 15</green> <light_purple>minecraft:overworld</light_purple>
65+
66+
<gray># Make portal larger</gray>
67+
/portal redefine <aqua>hub-portal</aqua> <yellow>-10 60 -10</yellow> <green>10 70 10</green> <light_purple>farmworld:overworld</light_purple>
68+
69+
<gray># Adjust portal position</gray>
70+
/portal redefine <aqua>wall-portal</aqua> <yellow>200 64 200</yellow> <green>205 74 200</green>
71+
```
72+
73+
<Callout type="tip">
74+
WorldEdit is optional but recommended for easier portal creation.
75+
You can always use manual coordinates if WorldEdit is not available.
76+
</Callout>

‎content/docs/portals/index.mdx‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: Overview
3+
description: Create and manage custom portals
4+
icon: BookMarked
5+
---
6+
7+
# Portals
8+
9+
Portals is a powerful Minecraft server plugin for **Folia** and **Paper**
10+
that allows you to create custom portals with advanced functionality.
11+
Create portals that teleport players across worlds,
12+
link to other portals, transfer players to different servers, or execute commands.
13+
14+
## Features
15+
16+
### Portal Actions
17+
18+
- **Linked Portals**: Create bidirectional or one-way portals that connect to each other
19+
- **Coordinate Teleports**: Teleport players to specific coordinates across worlds
20+
- **Random Teleports**: Teleport players randomly within defined bounds or radius
21+
- **Server Transfers**: Transfer players to external servers (hostname + port)
22+
- **Network Connects**: Connect to servers within your BungeeCord/Velocity network
23+
- **Command Execution**: Run commands as the player or console when entering a portal
24+
25+
### Access Control
26+
27+
- **Entry Permissions**: Restrict portal access with custom permissions
28+
- **Entry Fees**: Charge players using **ServiceIO** or **Vault** economy integration
29+
- **Cooldowns**: Set cooldown periods between portal uses
30+
31+
### Portal Creation
32+
33+
- **WorldEdit Integration**: Use WorldEdit selections for easy portal creation
34+
- **Manual Bounds**: Define portal regions with coordinate arguments
35+
- **Flexible Regions**: Create portals of any shape and size
36+
37+
## Quick Start
38+
39+
### Basic Usage
40+
41+
The main command of Portals is `/portal`,
42+
and requires the permission `portals.command.<subcommand>`:
43+
44+
```
45+
<gray># Create a portal using WorldEdit selection</gray>
46+
/portal create <aqua>spawn-portal</aqua>
47+
48+
<gray># Set the portal to teleport to spawn</gray>
49+
/portal action <aqua>spawn-portal</aqua> teleport <yellow>minecraft:overworld</yellow> <green>0 64 0</green> <light_purple>0 0</light_purple>
50+
51+
<gray># Add a cooldown of 30 seconds</gray>
52+
/portal cooldown <aqua>spawn-portal</aqua> <yellow>30s</yellow>
53+
54+
<gray># Set an entry fee of 100</gray>
55+
/portal cost <aqua>spawn-portal</aqua> <yellow>100</yellow>
56+
57+
<gray># List all portals</gray>
58+
/portal list
59+
```
60+
61+
### Common Scenarios
62+
63+
#### Linked Portals
64+
65+
Create two portals that link to each other:
66+
```
67+
<gray># Create first portal</gray>
68+
/portal create <aqua>portal-a</aqua>
69+
70+
<gray># Create second portal</gray>
71+
/portal create <aqua>portal-b</aqua>
72+
73+
<gray># Link portal-a to portal-b</gray>
74+
/portal action <aqua>portal-a</aqua> teleport-portal <yellow>portal-b</yellow>
75+
76+
<gray># Link portal-b to portal-a (for bidirectional)</gray>
77+
/portal action <aqua>portal-b</aqua> teleport-portal <yellow>portal-a</yellow>
78+
```
79+
80+
#### Random Teleport Portal
81+
82+
Create a portal that teleports players randomly:
83+
```
84+
<gray># Create the portal</gray>
85+
/portal create <aqua>random-portal</aqua>
86+
87+
<gray># Set random teleport with radius of 1000 blocks around 0, 64, 0 with a 100 block height limit</gray>
88+
/portal action <aqua>random-portal</aqua> teleport-random <yellow>minecraft:overworld</yellow> <green>0 64 0</green> <light_purple>1000</light_purple> <gold>100</gold>
89+
```
90+
91+
#### Server Transfer Portal
92+
93+
Connect players to another server in your network:
94+
```
95+
<gray># Create the portal</gray>
96+
/portal create <aqua>lobby-portal</aqua>
97+
98+
<gray># Connect to lobby server (BungeeCord/Velocity)</gray>
99+
/portal action <aqua>lobby-portal</aqua> connect <yellow>lobby</yellow>
100+
```
101+
102+
#### Premium Portal with Fee
103+
104+
Create a portal with entry requirements:
105+
```
106+
<gray># Create the portal</gray>
107+
/portal create <aqua>vip-portal</aqua>
108+
109+
<gray># Set entry fee</gray>
110+
/portal cost <aqua>vip-portal</aqua> <yellow>500</yellow>
111+
112+
<gray># Set entry permission</gray>
113+
/portal permission <aqua>vip-portal</aqua> <yellow>server.vip</yellow>
114+
115+
<gray># Set cooldown (60 seconds)</gray>
116+
/portal cooldown <aqua>vip-portal</aqua> <yellow>60s</yellow>
117+
```
118+
119+
## Permission System
120+
121+
### Command Permissions
122+
123+
Portals uses fine-grained permissions following the pattern:
124+
- `portals.command.create` - Create portals
125+
- `portals.command.delete` - Delete portals
126+
- `portals.command.list` - List portals
127+
- `portals.command.action` - Set portal actions
128+
- `portals.command.redefine` - Redefine portal bounds
129+
- `portals.command.cost` - Set entry fees
130+
- `portals.command.cooldown` - Set cooldowns
131+
- `portals.command.teleport` - Teleport to portals
132+
- `portals.command.permission` - Set entry permissions
133+
134+
### Entry Permissions
135+
136+
Portal entry permissions are custom and set per-portal using `/portal permission`.
137+
138+
## WorldEdit Integration
139+
140+
Portals optionally integrates with WorldEdit for easier portal creation:
141+
142+
1. Use `//wand` to get the WorldEdit selection tool
143+
2. Select the portal region by clicking two corners
144+
3. Run `/portal create <name>` to create the portal with your selection
145+
146+
Alternatively, you can specify bounds manually:
147+
```
148+
/portal create <aqua>my-portal</aqua> <yellow>x1 y1 z1</yellow> <green>x2 y2 z2</green> <light_purple>world</light_purple>
149+
```

‎content/docs/portals/managing-portals.mdx‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Managing Portals
3+
description: List, delete, and teleport to portals
4+
---
5+
6+
# Managing Portals
7+
8+
Portal management commands allow you to view, delete, and navigate between your portals.
9+
These commands help you maintain and organize your portal network.
10+
11+
## Commands
12+
13+
### List Portals
14+
15+
Displays a list of all portals on the server.
16+
Usage: `/portal list`
17+
18+
<Callout type="tip">
19+
You can click on the portal names in the output to teleport to them.
20+
</Callout>
21+
22+
### Delete Portal
23+
24+
Permanently removes a portal from the server.
25+
Usage: `/portal delete <portal>`
26+
27+
**Examples:**
28+
```
29+
<gray># Delete a specific portal</gray>
30+
/portal delete <aqua>old-portal</aqua>
31+
32+
<gray># Remove unused portal</gray>
33+
/portal delete <aqua>test-portal</aqua>
34+
35+
<gray># Clean up temporary portal</gray>
36+
/portal delete <aqua>event-portal</aqua>
37+
```
38+
39+
<Callout type="warning">
40+
Deleting a portal is permanent and cannot be undone.
41+
All portal settings (action, cost, cooldown, permission) will be lost.
42+
</Callout>
43+
44+
### Teleport to Portal
45+
46+
Teleports you to the specified portal's location.
47+
Usage: `/portal teleport <portal>`
48+
49+
**Examples:**
50+
```
51+
<gray># Teleport to a portal</gray>
52+
/portal teleport <aqua>spawn-portal</aqua>
53+
54+
<gray># Quick navigation to portal</gray>
55+
/portal teleport <aqua>hub</aqua>
56+
57+
<gray># Check portal location</gray>
58+
/portal teleport <aqua>zone-1</aqua>
59+
```
60+
61+
<Callout type="info">
62+
This command is for administrators to quickly navigate to portals.
63+
It does not trigger the portal's action.
64+
</Callout>

0 commit comments

Comments
 (0)