PacketTrigger

PacketTrigger lets you intercept the messages and packets other plugins send to players and replace them with your own actions: commands, titles, sounds, particles, and more. All without touching a single line of code.

A lot of plugins (BattlePass, quest systems, job plugins, etc.) communicate by sending hidden chat messages to players. PacketTrigger catches those messages before the player ever sees them, reads any data values embedded in them, and fires whatever actions you've configured instead.

---

What can I do with this?

• Turn a silent BattlePass XP message into a proper title + sound + particle burst
• Have a quest plugin trigger console commands, give rewards, and show a custom HUD — all from one config
• Use the captured data values (like XP amounts or quest names) inside your actions
• Expose those values to any other plugin via PlaceholderAPI (%pt_triggerName_1%)
• Add conditions so actions only fire when certain criteria are met
• Set per-trigger cooldowns so nothing can be spammed
• Pick a random action from a list for mystery rewards
• Repeat actions multiple times with a configurable interval
• Lock triggers behind permissions so only certain players trigger them
• Choose whether to intercept system messages, player chat, or both

---

Requirements

• Paper 1.19+ or Purpur
• PacketEvents (required)
• PlaceholderAPI (optional but recommended)

---

Installation

1. Download and drop PacketEvents into your plugins/ folder
2. Drop PacketTrigger.jar into your plugins/ folder
3. Start the server — plugins/PacketTrigger/config.yml is generated automatically
4. Edit your triggers in config.yml
5. Run /pt reload

---

Quick example

Your BattlePass plugin sends this message to the player:

$bp 14 ! 82

You add this to config.yml:

triggers:
  battlepass-xp:
    enabled: true
    placeholder: "$bp"
    delimiter: "!"
    packet-source: SYSTEM
    cooldown: 2
    conditions:
      - "{1} > 0"
    actions:
      - type: SEND_TITLE
        title: "&6+{1} XP"
        subtitle: "&7Total: &e{2} XP"
      - type: PLAY_SOUND
        sound: "ENTITY_EXPERIENCE_ORB_PICKUP"
        pitch: 1.2
      - type: CONSOLE_COMMAND
        command: "somecommand give %player% {1}"

The original message is hidden from the player. Instead they get a title showing +14 XP with a sound, and your console command runs with the real values filled in.

---

Action Types

Type	What it does
CONSOLE_COMMAND	Run a command as console
PLAYER_COMMAND	Run a command as the player
SEND_MESSAGE	Send a chat message (&-colors supported)
SEND_ACTIONBAR	Send an action bar message
SEND_TITLE	Send a title and subtitle with configurable fade times
BROADCAST	Broadcast to all online players
PLAY_SOUND	Play a sound with volume and pitch control
PLAY_PARTICLE	Spawn particles around the player
REPEAT	Repeat a set of actions N times with an interval
RANDOM	Pick one random action from a list

All actions support an optional delay field (in ticks, 20 ticks = 1 second).

---

Placeholders

These work in any action field — commands, messages, titles, etc.

Placeholder	Value
{1}, {2} ...	Captured data values from the intercepted message
%pt_triggerName_1%	Same, but works globally via PlaceholderAPI
%player%	Player name
%player_uuid%	Player UUID
%player_world%	Current world
%player_health%	Current health
%player_level%	XP level
{math:expression}	Evaluate math inline, e.g. {math:{1}*2+10}
Any PAPI placeholder	If PlaceholderAPI is installed

PacketTrigger also registers its own PAPI expansion so other plugins like TAB and scoreboards can read trigger data:

%pt_battlepass-xp_1%   →  last value 1 fired for that player
%pt_quest-complete_2%  →  last value 2 fired for that player

---

Conditions

Conditions let you control whether a trigger should fire. All conditions must pass.

conditions:
  - "{1} > 0"
  - "%player_level% >= 10"
  - "{1} contains daily"

Supported operators: == != > < >= <= contains startswith endswith

---

Per-Trigger Options

Option	Description
enabled	Set to false to disable without deleting
placeholder	The string the message must start with
delimiter	Separator between data values (default: !)
packet-source	SYSTEM (plugin messages), PLAYER (chat), or BOTH
permission	Only fire for players with this permission
cooldown	Seconds between fires per player
conditions	List of checks that must all pass

---

Commands

Command	Description
/pt reload	Reload config.yml
/pt list	Show all loaded triggers and their status
/pt test <trigger> <player> [data...]	Fire a trigger manually for testing
/pt debug [player]	Toggle per-player packet logging
/pt stats	Show how many times each trigger has fired
/pt resetstats	Reset fire counts
/pt toggle <setting>	Toggle log-to-console or log-packet-content live
/pt clearcooldowns [player]	Clear cooldowns for a player or everyone

All commands require packettrigger.admin (op by default). See the Wiki for individual permission nodes.

---

License

MIT — do whatever you want with it.