ojaj.docs|Docs|License

Gameplay & mechanics

This page documents exactly what the plugin does on every jump: no hand-waving. Everything below is the real behavior of the current alpha.

The trigger

The plugin listens to PlayerJumpEvent, a Paper API event that fires when a player actually jumps (not when they sprint, step or fall). That single event is the only trigger in the whole plugin; there are no commands, redstone or timers involved.

The checks, in order

Before the server launches, the jumping player runs through a guard chain. The first failing check stops everything silently:

  1. Master toggle: enabled: false disables the plugin entirely.
  2. Re-entry lock: if you were launched within the last 5 ticks, your own jump can't start a new chain. This is what stops the chaos from feeding on itself.
  3. Bypass permission: players with onejump.bypass never trigger global jumps (they still get launched by everyone else).
  4. World filter: in whitelist mode jumps only count inside the listed worlds; in blacklist mode they count everywhere except the listed worlds.
  5. Cooldown: the jumping player must have waited cooldown.seconds (default 2s) since their last attempt. The cooldown starts even if the next check fails.
  6. Trigger chance: when enabled, a roll of 1–100 must be <= trigger-chance.chance. Failed rolls still consume the cooldown, so a streak of bad luck is possible by design.

The launch

Once a trigger passes, every online player, including the jumper, gets their vertical velocity replaced in the same tick:

  • Fixed mode: velocity.y for everyone (the vanilla jump is ≈ 0.42).
  • Random mode (default): each player rolls an independent value in [velocity.random.min, velocity.random.max). Note the upper bound is exclusive; with the defaults 0.35–1.10, some players hop and some nearly leave atmosphere.
  • Horizontal momentum is preserved; only the Y component changes.

The spectacle

Each launched player also gets, per jump:

  • Particles: a burst of particles.amount particles roughly one block above their feet.
  • Sound: sound.type played at their location with the configured volume and pitch.
  • Action bar: actionbar.message with %player% replaced by the trigger's name.
  • Title + subtitle: with the same placeholder and configured fade timings.
  • Trail: a repeating task spawns trail.amount particles per tick for trail.duration-ticks ticks, and stops early if the player logs off.

Finally one chat broadcast goes out to everyone announcing who started it.

Built-in safeguards

  • No infinite cascade: the 5-tick re-entry lock means plugin-launched players can't immediately re-trigger.
  • Opt-out: onejump.bypass removes a player from the trigger pool entirely.
  • Scope: world whitelist/blacklist keeps the chaos out of lobbies, events or minigames.
  • Soft landings: with fall-damage.cancel: true (the default) the plugin cancels fall damage events server-wide: for every entity, not only damage from its own launches. Set it to false if you want vanilla fall damage back.

Stats & persistence

Every successful trigger credits +1 to the jumping player's counter (launched players don't earn stats for being yeeted). Counters live in memory only; they reset when the server restarts. /onejump reload does not clear them.

Colors & placeholders

Messages (actionbar.message, titles.title, titles.subtitle, broadcast.message) support legacy & color codes and the %player% placeholder. Invalid particles.type / sound.type IDs fall back silently to end_rod and entity_firework_rocket_launch.