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

---

Requirements

• Paper 1.19+ (or any fork)
• ProtocolLib (required)
• PlaceholderAPI (optional but recommended)

---

Installation

1. Drop PacketTrigger.jar into your plugins/ folder
2. Make sure ProtocolLib is installed
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:
    placeholder: "$bp"
    delimiter: "!"
    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"
      - 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.

---

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 without reloading
/pt clearcooldowns [player]	Clear cooldowns for a player or everyone

All commands require packettrigger.admin (op by default). See the Permissions page for finer control.

---

Placeholders

PacketTrigger registers a PlaceholderAPI expansion so other plugins can read values from the last fired trigger:

%pt_battlepass-xp_1%   →  last data value 1 for the battlepass-xp trigger
%pt_quest-complete_2%  →  last data value 2 for the quest-complete trigger

These work in TAB, scoreboards, holograms, chat plugins — anywhere PAPI is supported.

---

Building from source

Requires Java 17+.

git clone https://github.com/Clouds/PacketTrigger
cd PacketTrigger
./gradlew build

Output: build/libs/PacketTrigger-2.0.0.jar

---

License

MIT — do whatever you want with it.