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

1. Download FlyCraft v1.4 from the official repository.
2. Place the .jar file in your server’s /plugins/ folder.
3. Restart your server to generate configuration files.
4. Edit config.yml to customize settings.
5. (Optional) Configure Discord Bot for remote flight control.
6. 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.

---