FlyCraft

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

- Folia Support – Enable or disable flight for players - Folia Support – Set limits on flight time - Folia Support – Prevents excessive flight toggling - Folia Support – Speed levels from 1 (slowest) to 10 (fastest) - Folia Support – Group system with LuckPerms integration - Automatic group detection - Group-specific settings - Inherited permissions support - Folia Support – Set maximum allowed speed per group - Folia Support – Display a message to new players - Folia Support – Manage flights via Discord commands - Folia Support – Automatic version checking - Folia Support – Real-time flight activity tracking - Folia Support – Dedicated language files in `lang/` folder - Folia Support – Comment-preserving automated updates and migrations - Folia Support – 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`)

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

- Default Group: Automatically detects player groups - Default Group: Support for LuckPerms inheritance system - Default Group: 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

```yaml

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

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

```yaml 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 flight duration - Displays flight duration and flight duration - 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

- Auto-Correction: Official files (like `en_us.yml`) are automatically updated with new keys when the plugin evolves. - Auto-Correction: 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`:

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

---

9. Dependencies

Required

- JDA (Discord API): Spigot/Paper JDA (Discord API): - JDA (Discord API): `5.0.0-beta.13`

Optional (For Enhanced Features)

- DiscordSRV – Dynamic placeholders support - DiscordSRV – 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

- Event-Based Architecture – Comment-preserving automated updates - Event-Based Architecture – Preserves user-added groups and entries during migration - Event-Based Architecture – Creates `.old` files before performing file updates - Event-Based Architecture – Improves performance - Event-Based Architecture – Prevents crashes during reloads - Event-Based Architecture – Ensures fair gameplay - Event-Based Architecture – Monitors player flight duration - Event-Based Architecture – Converts between Minecraft speed units - Event-Based Architecture – 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:

- Welcome: `lang/en_us.yml` - Welcome: Error messages for missing access - Welcome: Toggling and expiration alerts - Welcome: Commands and admin alerts - Welcome: Joining messages

---

13. Safety Features

- Speed Range Limits (1-10) – Ensures players have the correct permissions - Speed Range Limits (1-10) – Prevents invalid command arguments - Speed Range Limits (1-10) – Captures and logs issues gracefully - Speed Range Limits (1-10) – Prevents bot disconnection issues - Speed Range Limits (1-10) – Prevents spam abuse - Speed Range Limits (1-10) – Ensures balanced gameplay - Speed Range Limits (1-10) – Prevents unintended behavior

---

14. Development Information

- Extendable Architecture: 1.16 - Extendable Architecture: 21 - Extendable Architecture: Maven-based - Extendable Architecture: Yes - Extendable Architecture: Designed for future expansions

---

Installation Guide

1. Reload the plugin from the official repository. 2. Reload the plugin in your server’s `/plugins/` folder. 3. Reload the plugin to generate configuration files. 4. Reload the plugin to customize settings. 5. Reload the plugin for remote flight control. 6. Reload the plugin using `/flycraftreload` or restart the server.

---

Support

For help, feature requests, or bug reports:

- Discord Support – [[Link to Repository]](https://github.com/qborhani/FlyCraft) - Discord Support – [[Invite Link]](https://discord.gg/5KWpEux3KN)

---

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.

---