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!"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🖼️ 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:
  spawn:
    location:
      ==: org.bukkit.Location
      world: world
      x: 0.0
      y: 64.0
      z: 0.0
      pitch: 0.0
      yaw: 0.0
    display-name: "&a&lSpawn"
    display-item: "GRASS_BLOCK"
    lore:
      - "&7The main spawn point"
      - "&7&oFree to use"
    permission: "warps.spawn"
    cost: 0.0
    slot: 10

- 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)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ❓ FAQ
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Q: How do I set a warp icon?
  A: Use /editwarp , click "Edit Display Item", then either type a material name or hold the item and type "hand". After typing, the editor will reopen with the new icon.
• Q: Can I have different costs for different warps?
  A: Yes. Each warp has its own cost field. If set to 0 (or omitted), it uses the global cost from warp-config.yml.
• Q: How do I make a warp require a permission?
  A: Set the permission field for that warp (e.g., warps.spawn). Players without that permission will see a locked icon in the GUI and cannot use the warp.
• Q: The teleport gets cancelled when I move – how do I disable that?
  A: Set teleport-delay: 0 in warp-config.yml. Teleports will then be instant.
• Q: Can I change the GUI layout?
  A: Yes. Edit gui.yml – you can change the size, define your own slot list, and customise the navigation buttons. The warp list will paginate over the defined slots.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🔗 Links
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• GateWayMC‑Core
• Vault
• PlaceholderAPI