PacketTrigger

GitHub

Wiki

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`:

```yaml 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.

```yaml 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.