TPHandler

TPHandler

Version 1.0.0 · Paper/Purpur 1.21.x · Java 21

A teleport management plugin for survival and PvP servers. TPHandler bundles a single per-player home, a full TPA request system with two-phase warm-up and BossBars, and an optional paid one-time teleport back to your death chest. Economy, combat and death-chest behaviour are all optional integrations, so the plugin works standalone and grows with the plugins you already run.

Features

• Homes — one home per player with /sethome, /home and /delhome. The first few /sethome uses are free; after that each re-set can cost money (configurable).
• TPA requests — /tpa, /tpaccept, /tpdeny, /tpcancel with a clean two-phase flow: an accept countdown, then a warm-up during which the requester must stand still.
• Warm-up you can trust — teleports can cancel on move, on damage or on entering combat. Feedback is shown via action bar or a configurable BossBar.
• Death-chest teleport — when a player dies and a death chest is created, they can be offered a paid one-time teleport back to it, with an expiry window and post-death delay.
• Dual economy, optional — MultiBank (primary, async) or Vault (fallback). If no economy is installed, costs simply do not apply.
• Combat aware — with CombatLog installed, teleports respect combat tags so players cannot escape a fight by teleporting.
• Per-player language — English, Portuguese and French, with PlayerSettings picking the player's chosen locale when present.
• Bypass permissions — fine-grained nodes to bypass warm-up, cost, combat and cooldown, plus a global switch to disable all bypasses (so operators share the normal experience).
• SQLite storage — homes are persisted locally; all database access is serialized on a dedicated thread for reliability.

Commands

Aliases: /tph for /tphandler.

Permissions

Configuration

The full config.yml is generated on first run. Key sections:

# Language: en_US, pt_PT or fr_FR (ships as pt_PT; per-player via PlayerSettings)
locale: "pt_PT"

# Dual economy: MultiBank (primary) and Vault (fallback).
# AUTO picks the first available provider from the priority list.
economy:
  mode: AUTO
  priority: ["MULTIBANK", "VAULT"]

teleport:
  warmup-seconds: 5
  cancel-on-move: true
  cancel-on-damage: true
  cancel-on-combat: true
  feedback:
    mode: "ACTIONBAR"   # CHAT, ACTIONBAR, BOSSBAR, NONE

# Set to false to disable ALL bypass permissions even for OPs.
bypass:
  enabled: true

home:
  enabled: true
  sethome:
    free-sets: 5
    cost-after-free: 250.0

tpa:
  enabled: true
  cost: 400.0
  request-timeout-seconds: 60
  cooldown-seconds: 10
  charge-on-request: false   # otherwise charges on /tpaccept
  refund-on-deny: true
  accept-countdown-seconds: 3
  warmup-seconds: 5

# Requires the DeathChest plugin.
deathchestTeleport:
  enabled: true
  cost: 2000.0
  offerExpiryMinutes: 20
  postDeathWaitSeconds: 60
  restrictions:
    # Kept true by default so a tagged player cannot escape combat with one click.
    requireNotInCombat: true
    warmupSeconds: 0

storage:
  database: "tphandler.db"

Notable keys:

• economy.mode — AUTO, MULTIBANK or VAULT. AUTO uses priority order.
• home.sethome.free-sets / cost-after-free — how many free /sethome uses each player gets before re-setting a home starts costing money.
• tpa.charge-on-request — charge (and refund on deny/timeout) when the request is sent, or charge only when it is accepted.
• deathchestTeleport.restrictions.requireNotInCombat — leave true; the death-chest teleport is instant, so allowing it in combat would let tagged players escape a fight.

Installation

1. Requires Paper or Purpur 1.21.x and Java 21.
2. Drop TPHandler-1.0.0.jar into your server's plugins/ folder.
3. (Optional) Install any of the integrations below for the extra features.
4. Start the server, then edit plugins/TPHandler/config.yml and run /tph reload.

Dependencies

All integrations are optional (soft dependencies) — TPHandler runs without any of them:

• MultiBank or Vault — economy for home / TPA / death-chest costs. Without an economy provider, those costs are skipped.
• CombatLog — combat tagging so teleports respect combat state.
• DeathChest — enables the paid one-time death-chest teleport.
• PlayerSettings — per-player language selection.

Support / Source

Source code: https://github.com/henriquescrrrr/carrageis-tphandler