Reference

Custom Events

Technical reference for PulseEvents 1.0.0 custom event configuration, action execution, validation, and runtime behavior.

PulseEvents 1.0.0 Config-Driven Developer Docs
Back to PulseEvents Download Plugin

Overview

Runtime Integration

  • Custom events live under custom-events in config.yml.
  • They are registered on startup and on /pe reload.
  • GUI chance editing, queueing, bossbar, announcements, and placeholders all support custom events as first-class entries.

Example

Minimal YAML

custom-events:
  meteor-shower:
    enabled: true
    name: "Meteor Shower"
    chance: 100
    duration: 45
    icon: MAGMA_BLOCK
    min-players: 2
    allowed-worlds: []
    start-message: "&c%event% has started."
    end-message: "&7%event% has ended."
    bossbar-title: "&6%event%"
    actions:
      opening-title:
        type: title
        target: all-players
        title: "&6%event%"
        subtitle: "&7Take cover."
      impact-wave:
        type: spawn-tnt
        target: random-players
        target-count: 2
        chance: 70
        delay-seconds: 4
        amount: 2
        fuse-ticks: 50
        explosion-power: 3.0

Reference

Top-Level Event Fields

Field Type / Default Behavior
enabled boolean / true false skips the event on load.
name string Used in GUI, queue, broadcasts, and placeholders.
chance integer / 100 Selection weight. 0 makes the event manual or queue only.
duration integer / required Must be greater than 0. Controls bossbar timer and auto-stop.
icon Material Bukkit material such as NETHER_STAR, MAGMA_BLOCK, or EMERALD.
min-players integer / 1 Counts only eligible players.
allowed-worlds list / [] Empty list allows any world permitted by global multiworld rules.
start-message string / optional Overrides the default start broadcast. Supports %event%.
end-message string / optional Overrides the default end broadcast. Supports %event%.
bossbar-title string / optional Overrides the default bossbar title. Supports %event%.
actions config section / required Contains named action entries.

Reference

Common Action Fields

Field Type / Default Behavior
type required Action type selector.
target all-players Options: all-players, all, random-player, random-players.
target-count integer / 1 Used with random-players. Clamped to online player count.
chance integer / 100 Per-action chance gate from 0 to 100. Rolled on each execution.
delay-seconds integer / 0 Delays the first run.
repeat-every-seconds integer / 0 0 means no repeat.
repeat-times integer / 1 Total executions when repeating.

Action Types

Supported Actions

1. message

Sends chat text.

Fields: message. Supports %event%.

2. sound

Plays a Bukkit sound.

Fields: sound, volume (default 1.0), pitch (default 1.0).

3. potion

Applies a potion effect.

Fields: effect, effect-duration-seconds (default 5), amplifier (default 0).

4. teleport

Applies a random offset teleport.

Fields: random-offset.x.min/max, random-offset.y.min/max, random-offset.z.min/max.

5. spawn-mob

Spawns entities.

Fields: entity (default ZOMBIE), amount (default 1), offset.x, offset.y, offset.z.

6. strike-lightning

Triggers lightning.

Fields: effect-only (default false), offset.x, offset.y, offset.z.

7. spawn-tnt

Spawns primed TNT.

Fields: amount, fuse-ticks (default 40), explosion-power (default 4.0), offset.x, offset.y, offset.z.

8. velocity

Sets player velocity.

Fields: velocity.x, velocity.y, velocity.z.

9. ignite

Sets the target on fire.

Fields: fire-ticks (default 60).

10. economy-reward

Runs a Vault payout.

Fields: money.min, money.max. Requires Vault.

11. title

Shows title and subtitle.

Fields: title, subtitle, fade-in-ticks (10), stay-ticks (40), fade-out-ticks (10). Supports %event%.

12. console-command

Runs a command as console per target.

Fields: command. Supports %event%, %player%, %world%.

13. player-command

Runs a command as player.

Fields: command. Supports %event%, %player%, %world%.

Validation

Events Are Skipped If

  • duration <= 0
  • icon is not a valid Material
  • No actions section exists
  • An action has no type
  • sound uses an invalid Sound value
  • potion uses an invalid PotionEffectType
  • spawn-mob uses an invalid EntityType
  • console-command or player-command has an empty command
  • economy-reward has no Vault provider
  • An action uses an unsupported type

Runtime

Operational Notes

  • GUI queue input supports middle click, Q, and Ctrl+Q.
  • min-players counts players eligible under both global and event-specific world rules.
  • random-players picks unique players up to target-count.

Shipped Presets

meteor-shower gravity-well hot-potato jackpot-rush blink-surge