Reference

Custom Events

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

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

Overview

Runtime Integration

  • Custom events live as separate .yml files in the plugin events/ folder.
  • They are loaded on startup and refreshed on /pe reload.
  • GUI chance editing, queueing, bossbar, announcements, and placeholders all treat custom events as first-class entries.

Example

Minimal Event File

event:
  key: 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

These fields define how an event is displayed, selected, and gated before any actions run.

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

Every action supports the same execution controls, then adds fields specific to its type.

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

Action cards below list the required inputs and the fields most often used in production configs.

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%.

Placeholders

Runtime Variables

Use these placeholders in messages, bossbars, GUIs, and other text fields that render live event state.

Placeholder Returns Notes
%pulseevents_current_event% Current event name or none Returns none when no event is running.
%pulseevents_current_event_time_remaining% Time remaining Updates while an event is active.
%pulseevents_leading_event% Leading event or none Returns none when no votes are active.
%pulseevents_leading_event_votes% Vote count Shows the current vote total for the leading event.
%pulseevents_event_active% Active state Use for conditional displays or status text.
%pulseevents_events_enabled% Enabled state Reflects whether the event system is enabled.
%pulseevents_queue_size% Queue size Returns 0 when the queue is empty.
%pulseevents_registered_events% Registered count Returns 0 when no events are registered.
%pulseevents_player_streak% Player streak Returns 0 when the player has no streak.
%pulseevents_top_streak% Top streak Returns 0 when no streak has been recorded.
%pulseevents_next_streak_milestone% Next milestone Returns 0 when no milestone is defined.

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.
  • Chance rolls apply per action, so a single event can mix guaranteed and optional effects.

Shipped Presets

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