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 + an economy plugin to enable `/flyvoucher buy`.
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

Languages & messages:

- Supported language codes: `en`, `nl`, `es`, `fr`, `ru`, `tr`, `zh`.
- Message files are packaged under `resources/messages/messages_{code}.yml` and are copied to `plugins/EzFlyTime/messages/` on first run.

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

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

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

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`).
- 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.

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/messages_*.yml`: translation files for messages; edit safely and run `/flytime reload`.

Flight per-session limit:

Contact & support

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