P_WorldFly

P_WorldFly is a Paper/Spigot plugin for Minecraft 1.21.3 that controls where players are allowed to use fly on the server. It lets the server owner allow flight only inside configured areas, with multiple local regions, per-region permissions, a selection wand, temporary border visualization, fall protection, customizable messages, and optional WorldGuard and PlaceholderAPI support.

What the plugin does

• Allows or blocks fly based on the player's location.
• Supports multiple local fly regions created by the plugin.
• Supports a custom permission for each region.
• Can automatically enable fly when a player enters an allowed area.
• Can only block fly outside allowed areas without enabling fly by itself.
• Can remove fly when the player leaves the allowed area, depending on the selected mode.
• Protects the player from fall damage after fly is removed.
• Warns the player when they are close to a region border.
• Provides a configurable selection wand.
• Shows temporary visual borders for regions, visible only to the admin using the command.
• Can use WorldGuard regions as allowed fly areas.
• Registers PlaceholderAPI placeholders automatically when PlaceholderAPI is installed.

Requirements

• Paper or Spigot server compatible with API 1.21.
• Java 21.
• WorldGuard is optional and only needed if you want to allow fly inside WorldGuard regions.
• PlaceholderAPI is optional and only needed if you want to use the plugin placeholders.

Server installation

1. Get the P_WorldFly-1.0.0.jar file.
2. Place the file inside the server plugins folder.
3. Restart the server so the plugin folder and configuration files are generated.
4. Edit plugins/P_WorldFly/config.yml as needed.
5. Use /pworldfly reload after changing the configuration, or restart the server.

Important files

File	Purpose
P_WorldFly-1.0.0.jar	Main plugin file that must be placed inside the plugins folder.
plugins/P_WorldFly/config.yml	Main plugin configuration.
plugins/P_WorldFly/lang/pt_br.yml	Portuguese messages.
plugins/P_WorldFly/lang/en_us.yml	English messages.

Permissions

Permission	Who should have it	Purpose
pworldfly.use	Players allowed to use fly in allowed areas	Lets the player be considered valid for the fly system.
pworldfly.admin	Administrators	Allows access to plugin setup and management commands.
pworldfly.bypass	Administrators or special ranks	Ignores fly blocking outside allowed areas.

If settings.require-permission-to-fly is enabled, players must have pworldfly.use to use fly inside allowed areas.

Main command

The main command is /pworldfly.

Available aliases: /worldfly and /pwfly.

Admin commands

Command	What it does
/pworldfly help	Shows the plugin help.
/pworldfly create	Creates a new local region.
/pworldfly setpos1	Sets the first region position using the admin's current location.
/pworldfly setpos2	Sets the second region position using the admin's current location.
/pworldfly pos1	Shortcut for /pworldfly setpos1 .
/pworldfly pos2	Shortcut for /pworldfly setpos2 .
/pworldfly wand [region]	Gives the selection wand and selects the active region for editing.
/pworldfly show [seconds]	Shows the region border for a limited time.
/pworldfly list	Lists all configured local regions.
/pworldfly status	Shows the overall plugin status and all regions.
/pworldfly status	Shows the status of one specific region.
/pworldfly enable	Enables a region.
/pworldfly disable	Disables a region.
/pworldfly clear	Clears the region selection by removing world, pos1, and pos2.
/pworldfly delete	Removes the region from the configuration.
/pworldfly expand vertical	Expands the region from the minimum world height to the maximum world height.
/pworldfly expand worldheight	Same as vertical.
/pworldfly expand up	Expands the region upward by the given amount.
/pworldfly expand down	Expands the region downward by the given amount.
/pworldfly reload	Reloads the configuration and reapplies the rules to online players.

Region names can contain letters, numbers, underscores, and hyphens. The maximum length is 32 characters.

The plugin also accepts the original Portuguese command names: criar, mostrar, listar, ativar, desativar, limpar, deletar, varinha, expandir, recarregar, and ajuda.

How to create a region

1. Use /pworldfly create .
2. Use /pworldfly wand to receive the selection wand.
3. Left-click a block with the wand to set pos1.
4. Right-click a block with the wand to set pos2.
5. Use /pworldfly show to check the region border.
6. Use /pworldfly status to confirm the region is complete.
7. Give pworldfly.use to the players or ranks that should be able to fly in the area.

pos1 and pos2 must be in the same world.

Operating modes

Mode	Behavior
AUTO_ENABLE	When a player enters a valid area, the plugin automatically enables allowFlight. When the player leaves, it removes fly and blocks flight outside the area.
ONLY_BLOCK	The plugin does not enable fly by itself. It only cancels flight attempts outside allowed areas.
PERMISSION_ONLY	The plugin does not enable fly by itself, but it allows another plugin to grant fly inside the area. When the player leaves, it removes fly.

Recommended mode for simple setups: AUTO_ENABLE.

Recommended mode when another plugin already manages fly: PERMISSION_ONLY or ONLY_BLOCK, depending on the behavior you want.

Essential configuration

Option	Purpose
language	Sets the message language. Use pt_br or en_us.
settings.mode	Sets the plugin mode: AUTO_ENABLE, ONLY_BLOCK, or PERMISSION_ONLY.
settings.require-permission-to-fly	Defines whether the player needs pworldfly.use.
settings.keep-creative-and-spectator-fly	Prevents the plugin from removing fly from Creative or Spectator players.
settings.notify-on-fly-enabled	Sends a message when fly is allowed.
settings.notify-on-fly-disabled	Sends a message when fly is removed.
settings.enabled-message-cooldown-seconds	Cooldown between repeated fly-enabled messages.
settings.warning-cooldown-seconds	Cooldown between block or border warnings.
settings.disable-plugin-fly-on-shutdown	Removes fly granted by the plugin when the server shuts down.
settings.fall-protection.enabled	Enables fall protection when leaving an allowed area.
settings.fall-protection.seconds	Duration of the fall protection.
settings.fall-protection.slow-falling	Applies slow falling during fall protection.
settings.fall-protection.reset-fall-distance	Resets fall distance when fall protection is applied.
settings.audit.enabled	Enables periodic checks for online players.
settings.audit.interval-ticks	Interval between periodic checks. 20 ticks is about 1 second.
settings.audit.only-check-flying-players	Limits periodic checks to players currently flying.
selection.wand-material	Material used as the selection wand.
selection.default-use-y-axis	Defines whether new regions include height by default.
selection.default-warning-distance	Default distance for border warnings.
visualization.line-material	Temporary visual block used for border lines.
visualization.corner-material	Temporary visual block used for region corners.
visualization.spacing	Spacing between temporary visual border blocks.
visualization.max-blocks	Maximum amount of temporary visual blocks sent to the player.
visualization.duration-seconds	Default duration of the border visualization.
visualization.auto-show-after-pos-set	Automatically shows the region after positions are set.
visualization.batch-send	Sends visual blocks in batches to reduce impact.
messages.use-actionbar	Sends status messages through the actionbar.

Region configuration

Each local region is stored inside the regions section of config.yml.

Field	Purpose
enabled	Defines whether the region is active.
world	World where the region exists.
permission	Optional permission required for this specific region.
use-y-axis	Defines whether the Y height is checked.
warning-distance	Distance from the border used to warn the player.
pos1	First region position.
pos2	Second region position.

If use-y-axis is enabled, the player must be inside the X, Y, and Z limits of the region.

If use-y-axis is disabled, the plugin only checks X and Z and ignores height.

If permission is empty, any player with pworldfly.use can use fly in that region.

If permission is filled, the player must have both pworldfly.use and the specific region permission.

WorldGuard support

WorldGuard is optional. To use WorldGuard regions as allowed fly areas, install WorldGuard on the server and enable the hook in the configuration.

Option	Purpose
hooks.worldguard.enabled	Enables or disables the WorldGuard integration.
hooks.worldguard.allowed-regions	List of WorldGuard region IDs where fly is allowed.

The plugin only allows fly in WorldGuard regions listed in hooks.worldguard.allowed-regions.

Local P_WorldFly regions and allowed WorldGuard regions can work together.

PlaceholderAPI support

If PlaceholderAPI is installed, P_WorldFly automatically registers placeholders using the pworldfly identifier.

General placeholders

Placeholder	Returns
%pworldfly_in_area%	true if the player is inside an allowed area.
%pworldfly_region%	Current region ID, or none if the player is not inside an allowed area.
%pworldfly_region_source%	Current region source: local, worldguard, or none.
%pworldfly_fly_allowed%	true if fly is currently allowed.
%pworldfly_near_border%	true if the player is near a local region border.
%pworldfly_border_distance%	Distance to the local region border. Returns -1 when not applicable.
%pworldfly_fly_mode%	Current plugin mode.
%pworldfly_worldguard_hook%	true if the WorldGuard hook is active.
%pworldfly_region_count%	Number of configured local regions.
%pworldfly_selected_region%	Region currently selected by the player for editing.
%pworldfly_bypass%	true if the player has pworldfly.bypass.
%pworldfly_global_permission%	true if the player has the global permission to use the fly system.
%pworldfly_current_world%	Current player world.
%pworldfly_region_permission%	Permission of the current local region, or none.
%pworldfly_region_warning_distance%	Warning distance of the current local region.
%pworldfly_region_use_y%	true if the current local region checks the Y axis.
%pworldfly_region_complete%	true if the current local region is complete.

Region placeholders

Replace with the region ID.

Placeholder	Returns
%pworldfly_region_exists_%	true if the region exists.
%pworldfly_region_enabled_%	true if the region is enabled.
%pworldfly_region_world_%	Configured world of the region.
%pworldfly_region_permission_%	Specific region permission, or none.
%pworldfly_region_warning_distance_%	Region warning distance.
%pworldfly_region_use_y_%	true if the region checks the Y axis.
%pworldfly_region_complete_%	true if the region has world, pos1, and pos2 set.
%pworldfly_region_pos1_%	Region pos1 coordinates.
%pworldfly_region_pos2_%	Region pos2 coordinates.

When a region does not exist, some placeholders return unknown.

Important admin notes

• Players with pworldfly.bypass are not blocked by the plugin.
• Creative and Spectator players are ignored if settings.keep-creative-and-spectator-fly is enabled.
• The selection wand only works for players with pworldfly.admin.
• Region visualization uses fake temporary blocks sent only to the player who used the command.
• When a player leaves an allowed area, the plugin may remove fly and apply fall protection.
• Incomplete regions are not used to allow fly.
• If the configured region world is not loaded, the region will not work until the world is loaded.
• Always use /pworldfly status after configuring a region to confirm everything is correct.

Recommended setup flow

1. Install the plugin in the plugins folder.
2. Restart the server.
3. Create a region with /pworldfly create .
4. Select pos1 and pos2 with the wand.
5. Check the area with /pworldfly show .
6. Configure rank permissions in the server permission plugin.
7. Adjust settings.mode if needed.
8. Use /pworldfly reload.
9. Test entering and leaving the region with an account that does not have bypass.