Add portals documentation

content/docs/portals/access-control.mdx

@@ -0,0 +1,100 @@
+---
+title: Access Control
+description: Manage portal permissions, costs, and cooldowns
+---
+
+# Access Control
+
+Access control allows you to restrict portal usage with permissions, entry fees, and cooldowns.  
+Create VIP portals, premium teleports, or prevent portal spam.
+
+## Commands
+
+### Set Entry Permission
+
+Sets a permission requirement for using the portal.  
+Usage: `/portal permission <portal> <permission>`
+
+**Examples:**
+```
+<gray># Require VIP permission</gray>
+/portal permission <aqua>vip-portal</aqua> <yellow>server.vip</yellow>
+
+<gray># Require admin permission</gray>
+/portal permission <aqua>admin-portal</aqua> <yellow>server.admin</yellow>
+
+<gray># Require custom permission</gray>
+/portal permission <aqua>premium-portal</aqua> <yellow>portals.premium</yellow>
+
+<gray># Require donor permission</gray>
+/portal permission <aqua>donor-portal</aqua> <yellow>server.donor</yellow>
+```
+
+<Callout type="info">
+  Players without the required permission will be denied entry.
+</Callout>
+
+### Set Entry Cost
+
+Sets an entry fee that players must pay to use the portal.  
+Usage: `/portal cost <portal> <amount>`
+
+**Examples:**
+```
+<gray># Set cost of 100</gray>
+/portal cost <aqua>spawn-portal</aqua> <yellow>100</yellow>
+
+<gray># Set cost of 500</gray>
+/portal cost <aqua>vip-portal</aqua> <yellow>500</yellow>
+
+<gray># Set cost of 1000</gray>
+/portal cost <aqua>premium-portal</aqua> <yellow>1000</yellow>
+
+<gray># Remove cost</gray>
+/portal cost <aqua>free-portal</aqua> <yellow>0</yellow>
+```
+
+<Callout type="warning">
+  Entry costs require Vault and an economy plugin to be installed.  
+  Economy must be enabled in the configuration file.
+</Callout>
+
+### Set Cooldown
+
+Sets a cooldown period between portal uses for each player.  
+Usage: `/portal cooldown <portal> <cooldown>`
+
+**Examples:**
+```
+<gray># Set 30 second cooldown</gray>
+/portal cooldown <aqua>spawn-portal</aqua> <yellow>30s</yellow>
+
+<gray># Set 60 second cooldown</gray>
+/portal cooldown <aqua>random-portal</aqua> <yellow>60s</yellow>
+
+<gray># Set 5 minute cooldown</gray>
+/portal cooldown <aqua>premium-portal</aqua> <yellow>300s</yellow>
+
+<gray># Remove cooldown</gray>
+/portal cooldown <aqua>instant-portal</aqua> <yellow>0</yellow>
+```
+
+<Callout type="info">
+  Cooldowns are per-player and prevent portal spam.
+</Callout>
+
+## Entry Denial
+
+When a player is denied entry to a portal, they will:
+
+1. Be pushed back from the portal (if knockback is enabled)
+2. Not be charged or put on cooldown
+
+Players can be denied for:
+- Missing required permission
+- Portal still on cooldown from previous use
+- Insufficient funds for entry fee
+
+<Callout type="info">
+  Knockback speed and whether knockback is enabled can be configured in the config file.
+</Callout>

content/docs/portals/creating-portals.mdx

@@ -0,0 +1,76 @@
+---
+title: Creating Portals
+description: Create and define portal regions
+---
+
+# Creating Portals
+
+Creating portals is the first step in building your portal network.
+You can create portals using WorldEdit selections or by manually specifying coordinates.
+
+## Commands
+
+### Create a Portal
+
+Usage: `/portal create <name> [<from>] <to> [<world>]`  
+Creates a new portal with the specified name and region.
+
+**With WorldEdit Selection:**
+```
+<gray># Get WorldEdit wand</gray>
+//wand
+
+<gray># Select two corners of the portal region</gray>
+<gray># Left-click first corner, right-click second corner</gray>
+
+<gray># Create the portal</gray>
+/portal create <aqua>my-portal</aqua>
+```
+
+**With Manual Coordinates:**
+```
+<gray># Create portal with specific bounds</gray>
+/portal create <aqua>spawn-portal</aqua> <yellow>0 64 0</yellow> <green>10 74 10</green> <light_purple>minecraft:overworld</light_purple>
+
+<gray># Create large portal area</gray>
+/portal create <aqua>hub-portal</aqua> <yellow>-5 60 -5</yellow> <green>5 70 5</green> <light_purple>farmworld:overworld</light_purple>
+
+<gray># Create vertical portal</gray>
+/portal create <aqua>wall-portal</aqua> <yellow>100 64 100</yellow> <green>105 74 100</green>
+```
+
+<Callout type="info">
+  If you have a WorldEdit selection active, you don't need to specify coordinates.  
+  If you don't have a selection, coordinates are required.
+</Callout>
+
+### Redefine Portal Bounds
+
+Usage: `/portal redefine <portal> [<from>] <to> [<world>]`  
+Changes the physical region of an existing portal.
+
+**With WorldEdit Selection:**
+```
+<gray># Select new portal region with WorldEdit</gray>
+//wand
+
+<gray># Redefine the portal</gray>
+/portal redefine <aqua>my-portal</aqua>
+```
+
+**With Manual Coordinates:**
+```
+<gray># Redefine portal with new bounds</gray>
+/portal redefine <aqua>spawn-portal</aqua> <yellow>0 64 0</yellow> <green>15 74 15</green> <light_purple>minecraft:overworld</light_purple>
+
+<gray># Make portal larger</gray>
+/portal redefine <aqua>hub-portal</aqua> <yellow>-10 60 -10</yellow> <green>10 70 10</green> <light_purple>farmworld:overworld</light_purple>
+
+<gray># Adjust portal position</gray>
+/portal redefine <aqua>wall-portal</aqua> <yellow>200 64 200</yellow> <green>205 74 200</green>
+```
+
+<Callout type="tip">
+  WorldEdit is optional but recommended for easier portal creation.  
+  You can always use manual coordinates if WorldEdit is not available.
+</Callout>

content/docs/portals/index.mdx

@@ -0,0 +1,149 @@
+---
+title: Overview
+description: Create and manage custom portals
+icon: BookMarked
+---
+
+# Portals
+
+Portals is a powerful Minecraft server plugin for **Folia** and **Paper**
+that allows you to create custom portals with advanced functionality.
+Create portals that teleport players across worlds,
+link to other portals, transfer players to different servers, or execute commands.
+
+## Features
+
+### Portal Actions
+
+- **Linked Portals**: Create bidirectional or one-way portals that connect to each other
+- **Coordinate Teleports**: Teleport players to specific coordinates across worlds
+- **Random Teleports**: Teleport players randomly within defined bounds or radius
+- **Server Transfers**: Transfer players to external servers (hostname + port)
+- **Network Connects**: Connect to servers within your BungeeCord/Velocity network
+- **Command Execution**: Run commands as the player or console when entering a portal
+
+### Access Control
+
+- **Entry Permissions**: Restrict portal access with custom permissions
+- **Entry Fees**: Charge players using **ServiceIO** or **Vault** economy integration
+- **Cooldowns**: Set cooldown periods between portal uses
+
+### Portal Creation
+
+- **WorldEdit Integration**: Use WorldEdit selections for easy portal creation
+- **Manual Bounds**: Define portal regions with coordinate arguments
+- **Flexible Regions**: Create portals of any shape and size
+
+## Quick Start
+
+### Basic Usage
+
+The main command of Portals is `/portal`,
+and requires the permission `portals.command.<subcommand>`:
+
+```
+<gray># Create a portal using WorldEdit selection</gray>
+/portal create <aqua>spawn-portal</aqua>
+
+<gray># Set the portal to teleport to spawn</gray>
+/portal action <aqua>spawn-portal</aqua> teleport <yellow>minecraft:overworld</yellow> <green>0 64 0</green> <light_purple>0 0</light_purple>
+
+<gray># Add a cooldown of 30 seconds</gray>
+/portal cooldown <aqua>spawn-portal</aqua> <yellow>30s</yellow>
+
+<gray># Set an entry fee of 100</gray>
+/portal cost <aqua>spawn-portal</aqua> <yellow>100</yellow>
+
+<gray># List all portals</gray>
+/portal list
+```
+
+### Common Scenarios
+
+#### Linked Portals
+
+Create two portals that link to each other:
+```
+<gray># Create first portal</gray>
+/portal create <aqua>portal-a</aqua>
+
+<gray># Create second portal</gray>
+/portal create <aqua>portal-b</aqua>
+
+<gray># Link portal-a to portal-b</gray>
+/portal action <aqua>portal-a</aqua> teleport-portal <yellow>portal-b</yellow>
+
+<gray># Link portal-b to portal-a (for bidirectional)</gray>
+/portal action <aqua>portal-b</aqua> teleport-portal <yellow>portal-a</yellow>
+```
+
+#### Random Teleport Portal
+
+Create a portal that teleports players randomly:
+```
+<gray># Create the portal</gray>
+/portal create <aqua>random-portal</aqua>
+
+<gray># Set random teleport with radius of 1000 blocks around 0, 64, 0 with a 100 block height limit</gray>
+/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>
+```
+
+#### Server Transfer Portal
+
+Connect players to another server in your network:
+```
+<gray># Create the portal</gray>
+/portal create <aqua>lobby-portal</aqua>
+
+<gray># Connect to lobby server (BungeeCord/Velocity)</gray>
+/portal action <aqua>lobby-portal</aqua> connect <yellow>lobby</yellow>
+```
+
+#### Premium Portal with Fee
+
+Create a portal with entry requirements:
+```
+<gray># Create the portal</gray>
+/portal create <aqua>vip-portal</aqua>
+
+<gray># Set entry fee</gray>
+/portal cost <aqua>vip-portal</aqua> <yellow>500</yellow>
+
+<gray># Set entry permission</gray>
+/portal permission <aqua>vip-portal</aqua> <yellow>server.vip</yellow>
+
+<gray># Set cooldown (60 seconds)</gray>
+/portal cooldown <aqua>vip-portal</aqua> <yellow>60s</yellow>
+```
+
+## Permission System
+
+### Command Permissions
+
+Portals uses fine-grained permissions following the pattern:
+- `portals.command.create` - Create portals
+- `portals.command.delete` - Delete portals
+- `portals.command.list` - List portals
+- `portals.command.action` - Set portal actions
+- `portals.command.redefine` - Redefine portal bounds
+- `portals.command.cost` - Set entry fees
+- `portals.command.cooldown` - Set cooldowns
+- `portals.command.teleport` - Teleport to portals
+- `portals.command.permission` - Set entry permissions
+
+### Entry Permissions
+
+Portal entry permissions are custom and set per-portal using `/portal permission`.
+
+## WorldEdit Integration
+
+Portals optionally integrates with WorldEdit for easier portal creation:
+
+1. Use `//wand` to get the WorldEdit selection tool
+2. Select the portal region by clicking two corners
+3. Run `/portal create <name>` to create the portal with your selection
+
+Alternatively, you can specify bounds manually:
+```
+/portal create <aqua>my-portal</aqua> <yellow>x1 y1 z1</yellow> <green>x2 y2 z2</green> <light_purple>world</light_purple>
+```

content/docs/portals/managing-portals.mdx

@@ -0,0 +1,64 @@
+---
+title: Managing Portals
+description: List, delete, and teleport to portals
+---
+
+# Managing Portals
+
+Portal management commands allow you to view, delete, and navigate between your portals.  
+These commands help you maintain and organize your portal network.
+
+## Commands
+
+### List Portals
+
+Displays a list of all portals on the server.  
+Usage: `/portal list`
+
+<Callout type="tip">
+  You can click on the portal names in the output to teleport to them.
+</Callout>
+
+### Delete Portal
+
+Permanently removes a portal from the server.  
+Usage: `/portal delete <portal>`
+
+**Examples:**
+```
+<gray># Delete a specific portal</gray>
+/portal delete <aqua>old-portal</aqua>
+
+<gray># Remove unused portal</gray>
+/portal delete <aqua>test-portal</aqua>
+
+<gray># Clean up temporary portal</gray>
+/portal delete <aqua>event-portal</aqua>
+```
+
+<Callout type="warning">
+  Deleting a portal is permanent and cannot be undone.  
+  All portal settings (action, cost, cooldown, permission) will be lost.
+</Callout>
+
+### Teleport to Portal
+
+Teleports you to the specified portal's location.  
+Usage: `/portal teleport <portal>`
+
+**Examples:**
+```
+<gray># Teleport to a portal</gray>
+/portal teleport <aqua>spawn-portal</aqua>
+
+<gray># Quick navigation to portal</gray>
+/portal teleport <aqua>hub</aqua>
+
+<gray># Check portal location</gray>
+/portal teleport <aqua>zone-1</aqua>
+```
+
+<Callout type="info">
+  This command is for administrators to quickly navigate to portals.  
+  It does not trigger the portal's action.
+</Callout>