GateWayMC-Core

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📍 Overview
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The Warp Module adds a flexible warp system to your server. Players can open a GUI listing all available warps, each with its own icon, display name, lore, and permission. Warps can have individual costs (if Vault is installed) and a global cooldown. Teleports have a configurable delay that cancels on movement or damage. All messages support hex colours and PlaceholderAPI placeholders. The GUI is fully customisable – you can define slots, filler items, page navigation, and a locked icon for warps the player cannot use.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✨ Features
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Warp GUI – paginated GUI with custom slots, filler items, and navigation
• Per‑warp customisation – each warp can have its own:
     
• Display name (with colours)
     
• Icon (any material)
     
• Lore lines
     
• Permission node
     
• Cost (overrides global cost)
     
• GUI slot (-1 = auto, 0‑53 = fixed)
• Teleport delay – players must stand still for a configurable time (movement/damage cancels)
• Cooldown system – global cooldown between warp uses (per player)
• Economy support – charge per warp (optional, requires Vault)
• Permission control – each command can have its own permission node (configurable)
• Visual effects – particle effects and sounds on teleport (configurable)
• Hex colour support – use RRGGBB in all messages, titles, and lore
• Update checker – notifies console when a new version is available
• Fully customisable GUI – size, filler material, slot layout, navigation items, no‑permission icon
• Editor commands – /setwarp, /delwarp, /editwarp (with chat‑based editing)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🚀 Installation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Make sure GateWayMC‑Core is installed and running on a Paper 1.18.2+ server.
2. (Optional) Install Vault for economy integration and PlaceholderAPI for placeholders.
3. Drop the WarpModule.jar into the modules folder:
   plugins/GateWayMC-Core/modules/
4. Reload the core (or restart the server):
   • In‑game: /gatewaycore reload
   • Console: gatewaycore reload
5. Configuration files warp-config.yml and gui.yml are generated automatically in plugins/GateWayMC-Core/modules/Warp/
6. Edit settings and warps, then reload the module – no restart needed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  💬 Commands
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Command	Description	Permission (configurable)
/warps	Open the warp GUI	warpmodule.warps (default empty – all players)
/setwarp	Create a warp at your location	warpmodule.admin.setwarp
/delwarp	Delete a warp	warpmodule.admin.delwarp
/editwarp	Open the warp editor GUI	warpmodule.admin.editwarp

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🔑 Permissions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All permissions are fully configurable in warp-config.yml – you can set them to any node, or leave empty to allow everyone.

Default Node	Command	Default
warpmodule.warps	/warps	none (all players)
warpmodule.admin.setwarp	/setwarp	op
warpmodule.admin.delwarp	/delwarp	op
warpmodule.admin.editwarp	/editwarp	op

Additionally, each warp can have its own permission node (set in the warp's data). Players without that permission will see a locked icon in the GUI and cannot use that warp.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ⚙ Configuration (warp-config.yml)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Warp module configuration

# Teleport delay in seconds (0 = instant)
teleport-delay: 3

# Teleport cooldown (seconds) between warp uses
teleport-cooldown: 5

update-check-enabled: true

# Visual and audio effects
particle-effect:
  enabled: true
  type: PORTAL # Particle type (e.g., PORTAL, CLOUD, END_ROD)
  amount: 20 # Number of particles per burst
  speed: 0.1 # Particle speed
sound-effect:
  enabled: true
  type: ENTITY_ENDERMAN_TELEPORT # Sound name
  volume: 1.0
  pitch: 1.0
show-countdown: true # Show remaining seconds in action bar

# Vault economy integration
vault-enabled: false
cost: 0.0 # default cost per warp (can be overridden per warp)

# Permission nodes for commands (set to empty to disable permission check)
permissions:
  warps: '' # warpmodule.warps
  setwarp: warpmodule.admin.setwarp
  delwarp: warpmodule.admin.delwarp
  editwarp: warpmodule.admin.editwarp

# Messages
messages:
  no-permission: '&cYou don''t have permission to use this command.'
  cooldown: '&cYou must wait &e{time} &cseconds before using a warp again.'
  insufficient-funds: '&cYou need &e{cost} &cto use this warp.'
  warp-not-found: '&cWarp &e{name} &cnot found.'
  warp-set: '&aWarp &e{name} &aset.'
  warp-deleted: '&aWarp &e{name} &adeleted.'
  warp-already-exists: '&cA warp named &e{name} &calready exists.'
  teleporting: '&aTeleporting to &e{name}&a...'
  teleport-cancelled-move: '&cTeleport cancelled because you moved.'
  teleport-cancelled-damage: '&cTeleport cancelled because you took damage.'
  player-only: '&cThis command can only be used by players.'
  teleport-delay: '&aTeleporting in &e{seconds} &aseconds. Don''t move!'
placeholderapi-enabled: false

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🖼️ GUI Configuration (gui.yml)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# GUI configuration for warps
title: "&6Warps"
size: 54
filler:
  material: "GRAY_STAINED_GLASS_PANE"
  name: " "
  lore: []
slots:
  - 10
  - 11
  - 12
  - 13
  - 14
  - 15
  - 16
  - 19
  - 20
  - 21
  - 22
  - 23
  - 24
  - 25
  - 28
  - 29
  - 30
  - 31
  - 32
  - 33
  - 34
  - 37
  - 38
  - 39
  - 40
  - 41
  - 42
  - 43
navigation:
  previous:
    slot: 45
    item: "ARROW"
    name: "&aPrevious Page"
  next:
    slot: 53
    item: "ARROW"
    name: "&aNext Page"
# Icon for warps the player cannot use (no permission)
no-permission-icon:
  material: "BARRIER"
  name: "&cLocked"
  lore:
    - "&7You don't have permission to use this warp."

GUI options explained

• title – title of the warp GUI (supports colours/hex)
• size – inventory size (must be a multiple of 9)
• filler – item used for empty slots
• slots – list of slots where warps can appear (paginated)
• navigation – previous/next page buttons (slot, item, name)
• no-permission-icon – icon shown for warps the player cannot use

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🗂️ Warp Data (warps.yml)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Warps are stored in warps.yml inside the module folder. Each warp can have the following properties:

warps:
  test:
    location:
      ==: org.bukkit.Location
      world: world
      x: -56.77580210260474
      y: 72.0
      z: 403.1843054027495
      pitch: 19.800236
      yaw: 163.9506
    display-name: §c§lTEST
    display-item: GRASS_BLOCK
    lore:
    - TEST
    - §c§lTESTING
    - '%btclaims_total%'
    cost: 0.0
    slot: 11

- display-name – name shown in GUI (supports colours)
- display-item – material of the icon
- lore – list of lore lines (supports colours)
- permission – optional permission node; if set, players need it to see/use the warp
- cost – cost to use this warp (overrides global cost)
- slot – fixed GUI slot (-1 for auto‑placement)

You can edit this file manually or use /editwarp to modify the properties via a GUI and chat prompts.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🎨 Colour Support
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All texts support both legacy & colour codes and hex colours with RRGGBB. Examples:

• &a&lSpawn – green bold text
• FFAA00&lWarp – orange gradient heading

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ⚙ Dependencies
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Required: GateWayMC‑Core
• Optional: Vault – for economy costs
• Optional: PlaceholderAPI – for placeholders in messages (Vault also recommended)