⚡ PulseMsg

Timed broadcast & advertisement plugin — clickable links, hex colors, priority overrides, and a smart flood guard.

📖 What is PulseMsg?

PulseMsg is a lightweight but powerful broadcast plugin that lets server owners schedule timed advertisement messages with full color control, clickable links, hover tooltips, and a smart flood guard so players never get spammed.

Each message runs on its own independent timer — no more messages colliding or overflowing chat at the same time.

✨ Features

| Feature | Description |
|---|---|
| ⏱ Per-message timers | Each message has its own interval-seconds — completely independent |
| 🔗 Clickable links | Open URLs, suggest commands, run commands, or copy text to clipboard |
| 🎨 Full color support | Legacy &x codes and hex &#RRGGBB both supported on every line |
| 🚨 Priority messages | Mark a message as priority: true to always fire, even alongside others |
| 🛡 Flood guard | At most one non-priority message per scheduler tick — no chat spam |
| 🔒 Permission gating | Send specific messages only to players with a given permission node |
| 🔀 Random or sequential | Send messages in order or shuffle them with random-order: true |
| 👥 Minimum players | Skip broadcasts when fewer than N players are online |
| ♻ Hot reload | /pm reload applies all config changes with zero server restart |

📋 Commands

All commands require the pulsemsg.admin permission (default: OP).
Aliases: /pulsemsg, /pm, /pulse

| Command | Description |
|---|---|
| /pm reload | Reload config and restart the scheduler |
| /pm list | List all messages with enabled/disabled status |
| /pm send <id> | Manually fire a message immediately |
| /pm info <id> | Show details and next-fire countdown for a message |
| /pm toggle | Pause or resume all broadcasts |
| /pm help | Show the help menu |

🔑 Permissions

| Node | Default | Description |
|---|---|---|
| pulsemsg.admin | OP | Full access to all PulseMsg commands |
| pulsemsg.bypass | false | Player will never receive any broadcasts |

⚙ Configuration

PulseMsg generates a fully documented config.yml on first run. Here's a taste:

global-interval-seconds: 60
global-prefix: '&#5865f2&l[PulseMsg]&r '
random-order: false
minimum-players: 0

messages:

  discord-ad:
    enabled: true
    title: '&#7289da&l⚡ Join Our Discord ⚡'
    body:
      - '&7Stay connected with the community!'
      - '&7Get support, updates, and giveaways.'
      - ' '
      - '&#7289da&l&nJoin Now&r &7— discord.gg/example'
    interval-seconds: 300
    priority: true                  # always fires even alongside other messages
    prefix: '&#7289da[Discord]&r '  # overrides the global prefix
    click:
      action: OPEN_URL
      value: 'https://discord.gg/example'
      hover: '&9Click to join our Discord!'

  store-ad:
    enabled: true
    title: '&#f1c40f&l★ Support The Server ★'
    body:
      - '&7Ranks, cosmetics and more at our store!'
    interval-seconds: 1200
    priority: false
    click:
      action: OPEN_URL
      value: 'https://store.example.com'
      hover: '&eClick to open the store!'

Click actions

| Action | Effect |
|---|---|
| OPEN_URL | Opens a URL in the player's browser |
| SUGGEST_CMD | Puts text into the player's chat box |
| RUN_CMD | Runs a command as the player |
| COPY_TEXT | Copies text to the player's clipboard |

How scheduling works

PulseMsg ticks every global-interval-seconds. Each tick it counts down every message's own timer independently. When a message is due:

• Priority messages always fire — even if another message is also due that tick.
• Non-priority messages are flood-guarded — only one fires per tick. If multiple are due simultaneously, the others simply wait for their next natural interval.

🖥 Requirements

• Minecraft: 1.20+
• Server: Spigot or Paper
• Java: 17 or newer

Made with care by rradajbi — open an issue on GitHub for bugs or feature requests.