FlyCraft - Official Documentation

Overview

FlyCraft is a lightweight and powerful flight management plugin for Minecraft servers. It allows players to toggle flight mode, adjust flight speed, and integrate with Discord for remote management. With built-in metrics, update checking, and LuckPerms integration, it provides a complete flight control solution for your server.

1. Core Features

Toggle Flight Mode – Enable or disable flight for players
Configurable Flight Duration – Set limits on flight time
Customizable Cooldown System – Prevents excessive flight toggling
Adjustable Fly Speed – Speed levels from 1 (slowest) to 10 (fastest)
Group-Based Permissions – Group system with LuckPerms integration
- Automatic group detection
- Group-specific settings
- Inherited permissions support
Speed Restrictions – Set maximum allowed speed per group
Welcome Messages – Display a message to new players
Full Discord Integration – Manage flights via Discord commands
Update Checker – Automatic version checking
Discord Notifications – Real-time flight activity tracking
Multi-Language Support – Dedicated language files in lang/ folder
Next-Gen Config Engine – Comment-preserving automated updates and migrations
LuckPerms Integration – Seamless group-based permission management
Folia Support – Full support for Folia and modern server architectures

2. Commands

2.1 In-Game Commands

Command	Description	Permission	Aliases
`/fly [player]`	Toggle flying mode	`flycraft.use`	`flymode`
`/flyspeed <1-10>`	Adjust flying speed	`flycraft.flyspeed`	N/A
`/flycraftreload`	Reload the plugin configuration	`flycraft.reload`	`fcr`, `flyreload`

Notes:

Using /fly [player] requires additional flycraft.others permission
/flyspeed requires both flycraft.flyspeed and appropriate flycraft.maxflyspeed.<1-10> permission
Fly speed is adjustable from 1 (slowest) to 10 (fastest)
Players can only set speeds up to their maximum allowed speed permission

2.2 Discord Commands

Command	Description	Requirements
`!startfly <player>`	Enables flight for the specified player	Requires configured Discord role
`!stopfly <player>`	Disables flight for the specified player	Requires configured Discord role
`!flyspeed <player> <1-10>`	Sets the player’s flight speed	Requires configured Discord role

3. Permissions

3.1 Basic Permissions

Permission	Description	Default
`flycraft.use`	Allows toggling flight mode	`op`
`flycraft.flyspeed`	Allows changing flight speed	`op`
`flycraft.flytime`	Allows using flight time commands	`op`
`flycraft.reload`	Allows reloading the configuration	`op`
`flycraft.others`	Allows managing flight for other players	`op`

3.2 Speed Control Permissions

Permission	Description	Default
`flycraft.maxflyspeed.1`	Allows setting fly speed up to 1	`op`
`flycraft.maxflyspeed.2`	Allows setting fly speed up to 2	`op`
`flycraft.maxflyspeed.3`	Allows setting fly speed up to 3	`op`
`flycraft.maxflyspeed.4`	Allows setting fly speed up to 4	`op`
`flycraft.maxflyspeed.5`	Allows setting fly speed up to 5	`op`
`flycraft.maxflyspeed.6`	Allows setting fly speed up to 6	`op`
`flycraft.maxflyspeed.7`	Allows setting fly speed up to 7	`op`
`flycraft.maxflyspeed.8`	Allows setting fly speed up to 8	`op`
`flycraft.maxflyspeed.9`	Allows setting fly speed up to 9	`op`
`flycraft.maxflyspeed.10`	Allows setting fly speed up to 10	`op`

3.3 Permission Groups

Permission	Description	Includes
`flycraft.*`	Grants all FlyCraft permissions	All permissions listed above

4. Permission Systems

4.1 Basic Permissions (All Permission Plugins)

If you're using any permission plugin other than LuckPerms (like PermissionsEx, GroupManager, etc.), use these basic permissions to control access:

flycraft.use - Allow flight
flycraft.flyspeed - Allow speed changes
flycraft.maxflyspeed.<1-10> - Set maximum allowed speed
flycraft.others - Manage other players
flycraft.reload - Reload configuration

4.2 Group System (LuckPerms Only)

FlyCraft includes a powerful group-based permission system that works exclusively with LuckPerms. When LuckPerms is installed, the plugin will automatically use group settings from groups.yml based on the player's LuckPerms groups. If LuckPerms is not installed, the plugin will fall back to using the basic permission system.

4.1 Group Configuration (`groups.yml`)

groups:
  default:
    can-fly: false
    max-fly-speed: 1
    flight-duration: 300
    flight-cooldown: 60

  vip:
    can-fly: true
    max-fly-speed: 3
    flight-duration: 600
    flight-cooldown: 30

  mvp:
    can-fly: true
    max-fly-speed: 5
    flight-duration: 1200
    flight-cooldown: 15

  admin:
    can-fly: true
    max-fly-speed: 10
    flight-duration: -1
    flight-cooldown: 0

4.2 Group Settings

Setting	Description	Default
`can-fly`	Whether the group can use flight	`false`
`max-fly-speed`	Maximum flight speed (1-10)	`1`
`flight-duration`	Flight duration in seconds (-1 for unlimited)	`300`
`flight-cooldown`	Cooldown between flights in seconds	`60`

4.3 Group System Features (LuckPerms Only)

LuckPerms Integration: Automatically detects player groups
Inherited Permissions: Support for LuckPerms inheritance system
Group Priorities: Uses primary group with fallback to inherited groups
Default Group: Fallback settings for players without a specific group

Important Note: The group system requires LuckPerms to be installed and enabled on your server. If you're using a different permission plugin, please use the basic permissions system described in section 4.1.

5. Configuration (`config.yml`)

4.1 General Settings

# Update Checker Settings
update-checker:
  enabled: true
  notify-ops: true
  debug: false

# Language Settings
# The file name in the lang/ folder (e.g., en_us for en_us.yml)
language: "en_us"

# Flight Settings
flight-duration: 300 # Duration of flight in seconds (default: 300)
flight-cooldown: 60 # Cooldown time between flights (default: 60)
welcome-message-enabled: true # Enable welcome messages

4.2 Discord Integration

discord:
  enabled: true
  channel-id: "YOUR_CHANNEL_ID"
  bot-token: "YOUR_BOT_TOKEN"
  bot-settings:
    status: "ONLINE" # ONLINE, IDLE, DO_NOT_DISTURB, INVISIBLE
    activity:
      type: "PLAYING" # PLAYING, WATCHING, LISTENING, COMPETING
      message: "with %online_players% players"
  commands:
    enabled: true
    prefix: "!"
    allowed-roles:
      - "ROLE_ID_1"
      - "ROLE_ID_2"
  embed:
    enabled: true
    color:
      start: "#3498db"
      end: "#e74c3c"
      speed: "#f1c40f"
    thumbnail:
      enabled: true
      url: "https://minotar.net/avatar/%player%/64"
    footer:
      text: "FlyCraft • %server_name%"

4.3 Bot Activity Settings

bot-activity:
  type: PLAYING # Options: PLAYING, WATCHING, LISTENING, COMPETING
  message: "Flying on %server_name% with %online_players%/%max_players% online!"

8. Discord Features

5.1 Notifications

Flight start/stop alerts
Speed change updates
Total flight time tracking
Player avatars included in embeds

5.2 Message Formatting

Supports custom emojis
Displays player names and server info
Tracks flight duration

6. Time Formatting

FlyCraft automatically formats time periods for maximum clarity:

25 seconds
1 minute 30 seconds
2 hours 15 minutes 45 seconds

7. Multi-Language System

FlyCraft now supports a robust multi-language system. All user-facing strings are handled via dedicated files in the plugins/FlyCraft/lang/ directory.

7.1 Key Features

Official Languages: Official files (like en_us.yml) are automatically updated with new keys when the plugin evolves.
Custom Languages: You can create your own language files (e.g., fr_fr.yml). These files are protected and will never be overwritten or modified by the plugin's auto-updater.
Auto-Correction: If a required key is missing from a custom file, the plugin will fall back to the default English value to prevent errors.

7.2 Changing Language

To change the plugin's language, edit the language option in config.yml:

language: "es_es" # This will look for lang/es_es.yml

9. Dependencies

Required

Minecraft Server: Spigot/Paper 1.16+
JDA (Discord API): 5.0.0-beta.13

Optional (For Enhanced Features)

PlaceholderAPI – Dynamic placeholders support
Vault – Economy and permissions support
DiscordSRV – Alternative Discord integration

10. PlaceholderAPI Support

FlyCraft fully supports PlaceholderAPI, allowing you to display flight information in scoreboards, chat, tab lists, and menus.

8.1 Global Placeholders

Placeholder	Description
`%flycraft_flying_count%`	Number of players currently flying

8.2 Player Placeholders

Placeholder	Description
`%flycraft_is_flying%`	Returns `true` or `false`
`%flycraft_status%`	Returns "Flying" or "Not Flying"
`%flycraft_time_left%`	Remaining flight time (e.g., "5m 30s") or "Unlimited"
`%flycraft_can_fly%`	Returns `true` if player has permission to fly
`%flycraft_speed%`	Current flight speed (e.g., "1", "2")
`%flycraft_max_speed%`	Player's maximum allowed flight speed
`%flycraft_cooldown%`	Remaining cooldown time (e.g., "30s") or "Ready"
`%flycraft_group%`	Returns "Authorized" or "Unauthorized" based on group access

8.3 Specific Player Placeholders

Replace <playername> with the name of the target player.

Placeholder	Description
`%flycraft_status_<playername>%`	Fly status of specific player
`%flycraft_cooldown_<playername>%`	Cooldown status of specific player
`%flycraft_max_speed_<playername>%`	Max speed of specific player

11. Technical Features

Next-Gen Migration Engine – Comment-preserving automated updates
Custom Data Protection – Preserves user-added groups and entries during migration
Automated Backups – Creates .old files before performing file updates
Async Discord Messaging – Improves performance
Safe Reload Handling – Prevents crashes during reloads
Automatic Cooldown Management – Ensures fair gameplay
Flight Time Tracking – Monitors player flight duration
Speed Conversion Handling – Converts between Minecraft speed units
Error Logging & Handling – Logs issues for troubleshooting
Event-Based Architecture – Efficient and modular

12. Messages

All messages are customizable in the relevant language file within the lang/ folder:

Default file: lang/en_us.yml
Permissions: Error messages for missing access
Flight Status: Toggling and expiration alerts
Discord: Commands and admin alerts
Welcome: Joining messages

13. Safety Features

Permission Checks – Ensures players have the correct permissions
Input Validation – Prevents invalid command arguments
Error Handling – Captures and logs issues gracefully
Safe Discord Reconnection – Prevents bot disconnection issues
Cooldown Enforcement – Prevents spam abuse
Flight Duration Limits – Ensures balanced gameplay
Speed Range Limits (1-10) – Prevents unintended behavior

14. Development Information

API Version: 1.16
Java Version: 21
Build System: Maven-based
Open Source: Yes
Extendable Architecture: Designed for future expansions

Installation Guide

Download FlyCraft v1.4 from the official repository.
Place the .jar file in your server’s /plugins/ folder.
Restart your server to generate configuration files.
Edit config.yml to customize settings.
(Optional) Configure Discord Bot for remote flight control.
Reload the plugin using /flycraftreload or restart the server.

Support

For help, feature requests, or bug reports:

GitHub Issues – [Link to Repository]
Discord Support – [Invite Link]

License

License FlyCraft is an open-source project licensed under the GNU General Public License v3.0 (GPL-3.0). You are free to use, modify, and distribute it, provided that:

Proper credit is given to the original author (Borhani).
Any modifications or redistributed versions are also licensed under GPL-3.0.
The original license is included in all copies or substantial portions of the project.

For full license details, see: GNU GPL v3.

Credits

Developed by Aevorin Studios.

FlyCraft