Skip to content

Latest commit

 

History

History
196 lines (163 loc) · 10.5 KB

README_en.md

File metadata and controls

196 lines (163 loc) · 10.5 KB

WorldUtils

A plugin for modern Paper and Folia Minecraft servers, providing many world-related utility functions and settings

Language: English | [切换到简体中文](./README.md)

✨ Features

  • 🔧 Flexible: Hierarchical configuration system with configuration inheritance for simple and clear feature setup
  • 🔒 World Protection: Provides 9 types of world protection
  • 🌍 Independent World Properties: Adjust independent settings for each world
  • 💬 Messages: Supports next-generation MiniMessage format, ActionBar provides more elegant player notifications with frequent trigger optimization
  • ⚡ High Performance: Extremely lightweight with no redundant code, plugin size only 65KB
  • 🎯 Permission System: Fine-grained permission control, supports using permissions to bypass specific protections

🚀 Quick Start

1. Using Pre-compiled Binaries

Visit Releases to get the latest pre-compiled version

2. Compile Yourself

  • Java 21 or higher
  • Maven 3.6+ (only needed for compilation)
  1. Clone the repository:
git clone https://github.com/StarCodeClub/WorldUtils.git
cd WorldUtils
  1. Compile the plugin:
mvn clean package
  1. After compilation, find WorldUtils-1.3.0-SNAPSHOT.jar in the target/ directory

📖 Usage

Configuration File Structure

# Plugin prefix (MiniMessage format)
plugin-prefix: "<gradient:#00eec0:#00c5ff><b>[WU]</b></gradient>"

# World configuration files
configs:
  # default is the default configuration and also a [configuration template], please do not delete!!!
  default:
    # Prevent players from modifying the world (placing blocks, filling water/lava, placing paintings, modifying item frames and flower pots...)
    anti-world-edit: false
    # Prevent players from PVP in this world (players hurting each other)
    anti-pvp: false
    # Prevent players from entering this world (cannot be intercepted immediately on Folia, but will be teleported to Fallback World within 2s)
    anti-player-enter: false
    # If a player is found in a forbidden world, they will be teleported to that world's spawn point
    world-enter-fallback: "world"
    # Make explosions not destroy blocks in this world (still causes damage)
    anti-explosion: false
    # Prevent players from interacting with blocks in this world (opening containers, using workbenches, etc.)
    anti-block-interaction: false
    # Prevent players from using items in this world (throwing snowballs, eggs, shooting arrows, using spawn eggs, flint and steel, etc.)
    anti-use-item: false
    # Prevent players from damaging entities in this world (does not include player vs player damage)
    anti-attack-entity: false
    # Prevent players from interacting with entities in this world (riding mounts, using leads, trading with villagers, etc.)
    anti-entity-interaction: false
    # Prevent players from picking up or dropping items in this world
    anti-pickup-drop-items: false
    # Set independent game mode for the world (set to empty to use default game mode)
    world-gamemode: ""
    # Whether to force prohibit players from changing game mode in this world
    force-world-gamemode: false
    # Cancel player collision (prohibit players from pushing entities in this world to change their position), players themselves can still be pushed by other entities (calculated by client)
    cancel-player-collision: false

    # Send notification to player when entering this world, set to empty to not send
    enter-message:
      chat-message: ""
      action-bar: ""

      title: "" # Use \n to separate title and subtitle
      duration: 2 # Display duration, only effective for Title

    # ActionBar notification when player lacks permission (MiniMessage format)
    # Optimized for frequent triggers, only sends once within 1s, fill with empty string "" to not send to player
    messages:
      anti-world-edit: "{plugin-prefix} <red>You don't have permission to modify this world.</red>"
      anti-pvp: "{plugin-prefix} <red>PVP is prohibited in this world.</red>"
      anti-player-enter: "{plugin-prefix} <red>You don't have permission to enter this world.</red>"
      anti-block-interaction: "{plugin-prefix} <red>You don't have permission to interact with blocks in this world.</red>"
      anti-attack-entity: "{plugin-prefix} <red>Attacking entities in this world is prohibited.</red>"
      anti-entity-interaction: "{plugin-prefix} <red>Interacting with entities in this world is prohibited.</red>"
      anti-pickup-drop-items: "{plugin-prefix} <red>Picking up or dropping items in this world is prohibited.</red>"
      anti-use-item: "{plugin-prefix} <red>Using items in this world is prohibited.</red>"
      player-gamemode-change: "{plugin-prefix} <red>Game mode has been unified with this world</red>"

  common:
    # Only need to add settings you want to adjust, other settings inherit from default by default
    # You can also manually specify parent to inherit other configurations
    # parent: default
    anti-explosion: true

  hub:
    parent: common
    # Only need to add settings you want to adjust based on common
    anti-world-edit: true
    anti-block-interaction: true
    anti-attack-entity: true

    messages:
      anti-world-edit: "{plugin-prefix} <red>You cannot modify any blocks in the hub.</red>"

    enter-message:
      title: "<b>Welcome to the Hub</b>\n<yellow>Have fun playing on this server!</yellow>"
      duration: 3



# Specify which world uses which configuration
# Unspecified worlds use default configuration by default
# Specified as disable will disable WorldUtils in that world
world-config:
  "world": common
  "hub": hub # Make world use hub configuration
  "world_the_end": disable

Feature Description

Protection Type Description Covered Events Folia Support
anti-world-edit Prohibit world modification Prohibit block placement/destruction, bucket operations, painting/item frame interaction Full support✅
anti-pvp Prohibit player combat Cancel player vs player damage Full support✅
anti-player-enter Prohibit player world entry Intercept world change teleportation Cannot intercept immediately, but can teleport to fallback world within 2s
anti-explosion Prohibit explosion block destruction Prevent TNT, creeper, fireball explosions (non-entity destruction) Full support✅
anti-block-interaction Prohibit block interaction Intercept opening containers, using workbenches, etc. Full support✅
anti-attack-entity Prohibit attacking entities Prohibit attacking or killing non-player entities Full support✅
anti-entity-interaction Prohibit entity interaction Intercept riding mounts, using leads, trading with villagers, etc. Full support✅
anti-pickup-drop-items Prohibit dropping/picking up items Prohibit players from picking up or dropping items in this world Full support✅
anti-use-item Prohibit using items Intercept throwing snowballs, eggs, shooting arrows, using spawn eggs, etc. Full support✅
world-gamemode Independent world game mode Change game mode when switching worlds Full support✅
cancel-player-collision Cancel player collision Prohibit players from pushing entities in this world to change their position Full support✅

🎮 Commands & Permissions

Command List

Command Description Permission
/wu help Show help information wu.admin
/wu status View protection settings overview wu.admin
/wu status <world> View protection settings for specified world wu.admin
/wu set-config <world> <protect_config/disable> Switch protection configuration for a world wu.admin
/wu reload Reload configuration file wu.admin
/wu version Show plugin version wu.admin

Permission System

This plugin has no default permissions

Admin Permissions

  • wu.admin - Use all /wu commands (default: OP)

Bypass Permissions

  • wu.bypass.* - Bypass all world protections (default: OP)
  • wu.bypass.<world>.anti-world-edit - Bypass world edit protection for specified world
  • wu.bypass.<world>.anti-pvp - Bypass PVP protection for specified world
  • wu.bypass.<world>.anti-player-enter - Bypass entry protection for specified world
  • wu.bypass.<world>.anti-block-interaction - Bypass block interaction protection for specified world
  • wu.bypass.<world>.anti-attack-entity - Bypass entity attack protection for specified world
  • wu.bypass.<world>.anti-entity-interaction - Bypass entity interaction protection for specified world
  • wu.bypass.<world>.anti-pickup-drop-items - Bypass pickup/drop items protection for specified world
  • wu.bypass.<world>.anti-use-item - Bypass item use protection for specified world
  • wu.bypass.change-gamemode - With this permission, WU will not modify your game mode
  • wu.bypass.cancel-player-collision - With this permission, WU will not adjust your collision effects

If you encounter problems or have feature suggestions, please submit them to GitHub Issues.
This project is licensed under the MIT License, see the LICENSE file for details.