EzFlyTime

EzFlyTime - Flight Vouchers & Bossbar for Spigot/Paper servers

EzFlyTime provides a production-ready flight-time system, a customizable voucher shop GUI, and optional bossbar/fuel displays. Built for Vault and PlaceholderAPI compatibility with robust voucher protection (PDC + legacy fallback).

Why use EzFlyTime?

• Lightweight and configurable (YAML or MySQL storage)
• Voucher shop with Vault integration for purchases
• Persistent, secure voucher metadata with legacy fallback
• Bossbar & particle integrations for a polished player experience

Quick Install

1. Place the EzFlyTime jar into your plugins/ folder and start the server.
2. Review plugins/EzFlyTime/config.yml and adjust vouchers: and bossbar:.
3. (Optional) Install Vault plus an economy plugin (e.g., EzEconomy to enable /flyvoucher buy and economy features.
4. Run /flytime reload after edits or restart the server.

Commands

• /fly — Toggle flight (players).
• /flytime — Show remaining time; run with no args to open the voucher shop GUI (players with ezflytime.buy).
• /flytime reload — Reload configuration and recreate managers.
• /flyvoucher gui — Open the voucher shop GUI.
• /flyvoucher give <player> <voucherId> [amount] — Give vouchers.
• /flyvoucher buy <voucherId> [amount] — Buy vouchers via economy.

Permissions

• ezflytime.fly — Toggle flight (default: true)
• ezflytime.flytime — View remaining time (default: true)
• ezflytime.buy — Access purchases & GUI (default: true)
• ezflytime.give — Admin: give vouchers (default: OP)
• ezflytime.reload — Admin: reload config (default: OP)

Configuration Highlights

Vouchers live under the vouchers: section in config.yml.

Example voucher:

vouchers:
  basic:
    material: PAPER
    name: '&aBasic Fly Voucher'
    lore:
      - '&7Redeem for 5 minutes of flight.'
    duration-seconds: 300
    price: 1000

voucher-gui.yml controls the shop layout and materials. EzFlyTime uses a resolver to support both legacy and modern Material names, but verify after major server updates.

Bossbar example:

bossbar:
  enabled: true
  title: '&aFlight Time: {time}'
  color: GREEN
  style: SEGMENTED_10

PlaceholderAPI

• %ezflytime_time_remaining% / %ezflytime_formatted% — formatted time
• %ezflytime_time_remaining_raw% / %ezflytime_seconds% — raw seconds
• %ezflytime_minutes% — whole minutes

Integrations

EzFlyTime integrates with several common server plugins to provide economy, placeholders and optional compatibility features:

• Vault — economy & permissions abstraction. Install Vault to enable economy-based voucher purchases and broad compatibility with economy plugins.
• EzEconomy — lightweight economy plugin tested with EzFlyTime: EzEconomy on Modrinth
• PlaceholderAPI — register placeholders to expose flight time and formatted values to chat, scoreboards and GUIs. PlaceholderAPI on Modrinth
• mcMMO — supported as a soft-dependency for servers using mcMMO mechanics.

Tips:

• Install Vault and an economy plugin (EzEconomy or another supported provider) to enable purchase flows and price/cost features.
• PlaceholderAPI placeholders require the PAPI plugin and the EzFlyTime expansion (if available) to be registered.
• Integrations are optional; EzFlyTime runs in a degraded mode if external plugins are absent.

Troubleshooting & Best Practices

• Enable debug in config.yml to log voucher item meta and PDC reads if vouchers fail to redeem.
• Test vouchers on a clean server when using anti-dupe or serialization plugins — some external plugins strip metadata; EzFlyTime falls back to legacy lore.
• After editing voucher-gui.yml or particles.yml, run /flytime reload to apply changes. The reload flow disposes previous managers and clears bossbars to avoid duplicates.
• If bossbar duplicates after reload, update to the latest jar — recent versions include cleanup logic on reload.

Particles configuration

EzFlyTime supports built-in particle effects for flight visuals. There is a companion EzFlyTimeAnimations module mentioned historically, however that module is not released and will not be released. Use the built-in particle configuration below or request example templates. Particle effects are configured in particles.yml (in the plugin resources or plugins/EzFlyTime/ after first run). Below are the supported keys and a complete example.

Configuration reference (keys and descriptions):

• enabled (boolean): globally enable/disable all plugin particle effects.
• mode (string): where particles appear; common values: trail, wing, ambient, on-toggle.
• particle (string): the Particle enum name used by the server (e.g., REDSTONE, CLOUD, SPELL, FLAME, TOTEM, SMOKE_NORMAL). Use names available for your Minecraft server version.
• count (int): number of particles spawned per spawn event. Lower values are cheaper.
• speed (float): particle speed parameter passed to the server API.
• offset (map): { x: 0.1, y: 0.2, z: 0.1 } — positional random offset.
• color (map or single value): for colored particles (e.g., REDSTONE/DUST) provide { r: 1.0, g: 0.2, b: 0.2 } or an integer RGB in 0-255 depending on server mappings.
• frequency (int): ticks between each particle spawn (20 ticks = 1 second). Increase this value to lower CPU usage.
• radius (double): distance from player center to spawn particles (for ring/wing modes).
• perPlayer (boolean): whether particles are spawned per-player (true) or globally (false). Per-player is more private but more CPU intensive.
• onlyWhenFlying (boolean): spawn effects only while the player is flying.
• distanceLimit (double): do not spawn for players farther than this value from viewers (saves performance on large servers).
• sound (map): optional sound to play with particle; keys: name (Sound enum), volume, pitch.

Example particles.yml:

enabled: true
default:
  mode: trail
  particle: REDSTONE
  count: 6
  speed: 0.02
  offset:
    x: 0.05
    y: 0.1
    z: 0.05
  color:
    r: 0.1
    g: 0.8
    b: 1.0
  frequency: 4            # spawn every 4 ticks (5 times per second)
  perPlayer: true
  onlyWhenFlying: true
  distanceLimit: 48.0
  sound:
    name: ENTITY_PLAYER_LEVELUP
    volume: 0.5
    pitch: 1.0

wing-effect:
  mode: wing
  particle: CLOUD
  count: 3
  speed: 0.01
  radius: 0.7
  frequency: 6
  perPlayer: true
  onlyWhenFlying: true

ambient:
  enabled: false
  mode: ambient
  particle: SPELL_WITCH
  count: 1
  frequency: 40

Notes & best practices:

• Particle names and parameters are server-version dependent. If the configured particle is invalid on your server version the plugin will log a warning and skip that effect. Use the built-in resolver or consult your server's org.bukkit.Particle for valid names.
• For large servers prefer perPlayer: false, higher frequency and lower count values. Example low-cost settings: count: 1, frequency: 20.
• Use distanceLimit to reduce client-side spam for viewers far away. -- Colored REDSTONE particles require the server to accept dust/colour parameters; if color is ignored on your server, switch to simpler particle types (e.g., SPELL, FLAME). The previously referenced EzFlyTimeAnimations module is not released and will not be released.
• If you rely on advanced animations (wing shapes, lerped trails), test on a staging server first and enable debug to log spawn-frequency and any color-mapping fallbacks.

Troubleshooting particles:

• No particles visible: check enabled, onlyWhenFlying, and the player's client settings (particles reduced/ambient settings). Also confirm server and client versions are compatible with the particle type.
• High CPU or lag: reduce count, increase frequency, disable perPlayer or lower distanceLimit.
• Color not applied for REDSTONE: your server version may require a different dust/color format; try using normalized 0–1 floats or integer RGB depending on server logs.

For advanced custom effects, request an example wing/trail pattern and I'll add ready-to-copy templates for particles.yml.

Full configuration checklist

• config.yml: vouchers, bossbar, storage, debug and dupe-detection toggles.
• voucher-gui.yml: GUI layout, materials, slots, close/confirm buttons.
• particles.yml: particle effects for flights and cosmetics (see above).
• messages_*.yml: translation files for messages; edit safely and run /flytime reload.

Contact & support

For support and feature requests join the official Discord: https://discord.gg/yWP95XfmBS