From b42d864ee8a3a5aeef8a7cf00f010a2abaf58fdc Mon Sep 17 00:00:00 2001
From: twme-ai <299940106+twme-ai@users.noreply.github.com>
Date: Wed, 19 Aug 2026 04:40:36 +0000
Subject: [PATCH] docs: rewrite README for players and administrators [skip ci]
---
README.md | 387 +++++++++++++++++++++++++++++++++++-------------------
1 file changed, 253 insertions(+), 134 deletions(-)
diff --git a/README.md b/README.md
index 4dbc360..de6068a 100644
--- a/README.md
+++ b/README.md
@@ -1,135 +1,254 @@
-
-
# DebugStickPro
-> ### A powerful debugstick plugin
----
-> **Warning**: This plugin is still in development and may have bugs. Please report any bugs you find to the [issue page](https://github.com/TWME-TW/DebugStickPro/issues)
-
-> **โ ๏ธ v0.5.0+ Requirement**: This plugin now requires [PacketEvents](https://github.com/retrooper/packetevents) to function properly. Please install PacketEvents before using v0.5.0+.
-
-> Supports Spigot, Paper, and Folia from Minecraft 1.19.4 through 26.2. Paper is the primary platform.
-
-The compatibility matrix starts every stable Paper and Folia release available
-between 1.19.4 and 26.2. Mineflayer additionally verifies commands, MiniMessage
-item output, and VirtualEntities display spawn/removal at the 1.19, 1.20, and
-1.21 protocol generations. The 26.x releases receive startup and plugin-enable
-tests because Mineflayer does not yet support those protocols.
----
-## Features:
-### Dynamically display block data:
- - Display the data of the block you are looking at in the action bar.
-#### Classic Mode
-
-
-#### Copy Mode
-
-
-#### Freeze Mode
-
-
-### Three Modes:
- - Classic Mode: The same as the original debug stick.
- - Copy Mode: Copy the data of a block and paste it onto other blocks.
- - Freeze Mode: Freeze the status of a block.
-
-## ๐ What's New in v0.5.0
-
-### **Revolutionary Freeze Mode Enhancement**
-- **๐ง Packet-Based Block Freezing**: Complete rewrite using PacketEvents for client-side visual effects
-- **๐ป Ghost-Free Experience**: No more server-side `BARRIER` blocks - smoother and cleaner freeze operations
-- **โก Enhanced Performance**: Improved freeze/unfreeze logic with better cleanup and tracking
-- **๐งน Simplified Architecture**: Modernized codebase with PacketEvents and VirtualEntities integration
-
-### **Technical Improvements**
-- **New Dependencies**: PacketEvents 2.13.0 and VirtualEntities integration
-- **API Modernization**: Updated to use standard Bukkit enums for better compatibility
-- **Better Physics Handling**: Enhanced BlockPhysicsEventListener for improved freeze functionality
-- **Advanced Tracking**: Sophisticated duplicate prevention and state management
-
-### Custom Item Support:
- - You can customize the item used as the debug stick in the config file.
-
-### CoreProtect Log Support:
- - Support for CoreProtect, which can record the operation of the debug stick.
-
-### Auto Region Protection Support:
- - Support for region protection plugins, such as WorldGuard, GriefPrevention, etc.
-
-### Addon:
- - [Nether-No-Water](https://www.spigotmc.org/resources/dsp-add-on-nether-no-water.118723/): An add-on that prevents players from changing Waterlogged data in the Nether.
-### Support filtering specific BlockData:
- - You can filter specific BlockData in the config file.
-
-### Support for multiple languages.
- - Automatically select translation files based on the player's language.
-> Translation files for each language need to be translated manually beforehand.
-## Configuration:
-### Configuration File:
-[config.yml](https://github.com/TWME-TW/DebugStickPro/blob/main/src/main/resources/config.yml)
-
-Missing settings in an existing `config.yml` and missing entries in language files
-are filled automatically from the bundled defaults when the plugin loads. Existing
-values and translations are preserved.
-
-`BlockDataFilter.AllowUnsafeBisectedData` is disabled by default to prevent invalid
-double-block structures and duplicate drops. Enable it only when multi-block
-`Bisected` properties are intentionally needed.
-
-### Language File:
-[lang](https://github.com/TWME-TW/DebugStickPro/tree/main/src/main/resources/lang)
-### Permissions:
-[plugin.yml](https://github.com/TWME-TW/DebugStickPro/blob/main/src/main/resources/plugin.yml)
-- Blacklist bypass:
- - `debugstickpro.bypassblacklist` (bypass all blacklisted BlockData)
- - `debugstickpro.bypassblacklist.` (example: `debugstickpro.bypassblacklist.waterloggeddata`)
-
-### Commands:
- > `/debugstickpro` = `/dsp` โ `/dsp help`
- - `/dsp help` Show help message.
- - `/dsp give [player]` Give a debug stick to a player.
- - `/dsp mode ` Change the mode.
- - `/dsp reload` Reload the configuration file.
-
----
-
-### Usage:
- - Use `/dsp give` to get a debug stick.
-#### Classic Mode:
-Same as regular debugging stick operation:
- - Left-click to select the desired data type to modify.
- - Right-click to change the value of that data.
-
-#### Copy Mode:
- - Left-click to select the data of a block to be copied.
- - Right-click to paste that block's data onto other blocks.
-
-#### Freeze Mode:
- > The status of frozen blocks will not be updated.
- - Right-click to freeze/unfreeze a block.
- - Left-click to unfreeze all frozen blocks.
-### How to change mode:
- - Press the `Swap Hand` key to switch mode. (Default: F)
-
-## How to install:
-
-### Requirements
-- **Java 17-20** for legacy 1.19.4 servers, or the Java version required by your server release
-- **JDK 25** to build DebugStickPro (the published JAR targets Java 17 for the full server range)
-- **Spigot, Paper, or Folia 1.19.4-26.2** (Paper is recommended)
-- **[PacketEvents](https://github.com/retrooper/packetevents) 2.13.0+** (Required for v0.5.0+)
-
-Spigot protocol checkpoints are tested locally with the official BuildTools.
-The complete stable Paper and Folia version matrix runs for every pull request.
-
-### Installation Steps
-1. Install [PacketEvents](https://github.com/retrooper/packetevents) if not already installed
-2. Download the latest version of DebugStickPro from the [release page](https://github.com/TWME-TW/DebugStickPro/releases)
-3. Put the plugin into the `plugins` folder of your server
-4. Restart your server
-5. Enjoy!
-
-## Latest Dev Version:
- - https://repo.twme.dev/#/snapshots/dev/twme/DebugStickPro
-
-### Known Issues:
- - You have to sneak in order to change the Lit value of the candle.
+
+
+
+DebugStickPro gives trusted builders a practical way to inspect, edit, copy, and
+temporarily freeze Minecraft block states. It provides the familiar debug-stick
+workflow without requiring a vanilla debug stick and adds an action-bar preview,
+copy mode, freeze mode, permissions, filters, localization, and protection-plugin
+integration.
+
+[Download the latest release](https://github.com/TWME-TW/DebugStickPro/releases) |
+[Report a problem](https://github.com/TWME-TW/DebugStickPro/issues) |
+[View the default configuration](src/main/resources/config.yml)
+
+[Player Guide](#player-guide) | [Administrator Guide](#administrator-guide)
+
+> DebugStickPro requires
+> [PacketEvents](https://github.com/retrooper/packetevents) 2.13.0 or later.
+>
+> The plugin is under active development. Test updates on a non-production server
+> and report reproducible problems on the issue tracker.
+
+## What you can do
+
+- See the block-state properties of the block you are looking at in the action bar.
+- Select and change one property at a time in Classic mode.
+- Copy compatible properties from one block and apply them to other blocks.
+- Temporarily freeze blocks so physics and neighboring updates do not change them.
+- Use the plugin in English or Traditional Chinese, selected from each player's
+ client locale.
+- Let existing region-protection plugins decide where a player may make changes.
+- Record Classic and Copy mode changes through CoreProtect when it is installed.
+
+## Player Guide
+
+### Get started
+
+1. Ask an administrator for a Debug Stick, or run `/dsp give` if you have permission.
+2. Hold the Debug Stick in your main hand.
+3. Look at a block within five blocks. Its editable properties appear in the action
+ bar.
+4. Press your **Swap Item With Offhand** key (`F` by default) to move to the next
+ mode. Sneak while pressing it to move to the previous mode.
+
+You can also hold the stick and run `/dsp mode ` to select a
+mode directly. Modes that you do not have permission to use are skipped.
+
+### Controls
+
+| Mode | Left click | Right click |
+| --- | --- | --- |
+| **Classic** | Select the next editable property. | Cycle the selected property's value. |
+| **Copy** | Copy all supported block-state properties from the targeted block. | Apply matching copied properties to the targeted block. |
+| **Freeze** | Unfreeze every block that you froze. | Freeze or unfreeze the targeted block. |
+
+Copy mode only applies properties shared by the source and destination. It does not
+replace the destination block's material or copy container contents.
+
+Freeze mode is temporary. Frozen blocks are restored when their owner disconnects,
+when the plugin is disabled, or when an administrator reloads DebugStickPro. It is
+not a persistent block-lock system.
+
+### Mode previews
+
+#### Classic mode
+
+
+
+#### Copy mode
+
+
+
+#### Freeze mode
+
+
+
+### Player commands
+
+`/debugstickpro` and `/dsp` are aliases. Square brackets indicate an optional
+argument; angle brackets indicate a required argument.
+
+| Command | What it does |
+| --- | --- |
+| `/dsp` or `/dsp help` | Show the command list. |
+| `/dsp give` | Give yourself a Debug Stick. |
+| `/dsp give ` | Give an online player a Debug Stick. |
+| `/dsp mode ` | Change the held stick to Classic, Copy, or Freeze mode. |
+
+The server owner decides which commands and modes players may use.
+
+## Administrator Guide
+
+### Requirements and supported servers
+
+| Component | Requirement |
+| --- | --- |
+| Server software | Spigot, Paper, or Folia from Minecraft 1.19.4 through 26.2. Paper is the primary and recommended platform. |
+| Java runtime | The plugin targets Java 17. Run the Java version required by your chosen Minecraft server release. |
+| Required plugin | [PacketEvents](https://github.com/retrooper/packetevents) 2.13.0 or later. |
+| Optional plugins | CoreProtect and PlaceholderAPI. |
+
+VirtualEntities is bundled inside DebugStickPro and does not need to be installed
+separately.
+
+### Installation
+
+1. Stop the server.
+2. Download PacketEvents and place its JAR in the server's `plugins` directory.
+3. Download DebugStickPro from the
+ [GitHub Releases page](https://github.com/TWME-TW/DebugStickPro/releases) and
+ place its JAR in the same directory.
+4. Start the server and confirm that PacketEvents and DebugStickPro both enable
+ without errors.
+5. Grant the required permissions, then use `/dsp give ` to issue a stick.
+
+Use a full server restart when installing or updating either plugin. Bukkit's global
+`/reload` is not supported and may leave packet or display state inconsistent.
+
+When upgrading DebugStickPro, back up `plugins/DebugStickPro/config.yml` and the
+`lang` directory before replacing the JAR. On startup, missing settings and missing
+language entries are added from the bundled defaults while existing values are
+preserved.
+
+### Administrator commands
+
+| Command | Sender | Permission | What it does |
+| --- | --- | --- | --- |
+| `/dsp help` | Player or console | `debugstickpro.help` | Show the command list. |
+| `/dsp give` | Player | `debugstickpro.give` | Give the sender a Debug Stick. |
+| `/dsp give ` | Player or console | `debugstickpro.give` | Give an online player a Debug Stick. |
+| `/dsp mode ` | Player | `debugstickpro.mode` plus the mode permission | Change the held stick to Classic, Copy, or Freeze mode. |
+| `/dsp reload` | Player or console | `debugstickpro.reload` | Reload DebugStickPro's configuration and languages and release frozen blocks. |
+
+### Permissions
+
+`debugstickpro.help` is granted to everyone by default. Every other declared
+permission defaults to server operators.
+
+| Permission | Purpose |
+| --- | --- |
+| `debugstickpro.basic` | Recommended parent node for normal trusted users; includes use, give, mode, Copy, Freeze, and help permissions. |
+| `debugstickpro.admin` | Full access; includes `debugstickpro.basic`, reload, and all bypass permissions. |
+| `debugstickpro.help` | View command help. |
+| `debugstickpro.use` | Hold and interact with a Debug Stick and see its action-bar display. |
+| `debugstickpro.give` | Use the give command for yourself or an online player. |
+| `debugstickpro.give.other` | Parent node that includes `debugstickpro.give`, provided for permission-group organization. |
+| `debugstickpro.mode` | Use the `/dsp mode` command. |
+| `debugstickpro.mode.copy` | Enter and use Copy mode. |
+| `debugstickpro.mode.freeze` | Enter and use Freeze mode. |
+| `debugstickpro.bypassregion` | Ignore automatic region-protection checks. |
+| `debugstickpro.bypassblockfilter` | Ignore both block material allowlists and denylists. |
+| `debugstickpro.bypassblacklist` | Ignore the entire block-data property blacklist. |
+| `debugstickpro.bypassblacklist.` | Ignore one block-data property blacklist entry, for example `debugstickpro.bypassblacklist.waterloggeddata`. |
+
+Grant `debugstickpro.basic` only to players who are allowed to modify block states.
+These changes can create normally unobtainable or unsafe block combinations.
+
+### Configuration
+
+The generated configuration is `plugins/DebugStickPro/config.yml`. The
+[default config](src/main/resources/config.yml) contains comments and all available
+keys. Do not edit `ConfigVersion`; DebugStickPro uses it when upgrading the file.
+
+| Section | What it controls |
+| --- | --- |
+| `Language` | Default locale and the locale files eligible for automatic per-player selection. |
+| `ActionBarDisplay` | Property centering and the action-bar refresh interval in ticks. |
+| `DebugStickItem` | Material, MiniMessage display name and lore, and per-mode custom model data. |
+| `WhitelistWorlds` | Worlds where the stick may be used when the allowlist is enabled. `*` allows every world. |
+| `BlacklistWorlds` | Worlds where the stick cannot be used. This list takes precedence over `WhitelistWorlds`. |
+| `AutoRegionProtection` | Whether DebugStickPro asks other plugins if the player may build at the target. |
+| `BlockDataFilter` | Which block-state property types are visible and editable. The blacklist takes precedence over the whitelist. |
+| `BlockFilter` | Which block materials may be targeted. The blacklist takes precedence over the whitelist. |
+| `ModeSetting` | Whether selected, copied, or frozen state is cleared when a player leaves a mode. |
+
+Material names must match Bukkit's
+[Material enum](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html).
+Block-data filter names come from DebugStickPro's
+[supported property types](src/main/java/dev/twme/debugstickpro/blockdatautil/subdata).
+
+`BlockDataFilter.AllowUnsafeBisectedData` is disabled by default. Enabling it exposes
+the `half` property of doors, double plants, and other multi-block structures; this
+can create invalid pairs or duplicate drops.
+
+After changing the configuration, run `/dsp reload`. If you change
+`DebugStickItem.Material` or its custom model data, issue new sticks so players do
+not keep items created under the old settings.
+
+### Languages
+
+English (`en_US`) and Traditional Chinese (`zh_TW`) are bundled. For each player,
+DebugStickPro normalizes the client locale and uses the matching entry from
+`Language.LangFiles`; otherwise it falls back to `Language.DefaultLanguage`.
+
+To add a translation:
+
+1. Copy `plugins/DebugStickPro/lang/en_US.yml` to a locale-named file such as
+ `de_DE.yml`.
+2. Translate the values without changing the YAML keys or MiniMessage tags.
+3. Add `de_DE` to `Language.LangFiles` in `config.yml`.
+4. Run `/dsp reload`.
+
+Missing entries in existing language files are filled from the bundled locale or,
+for custom locales, from English. Existing translations are preserved.
+
+### Integrations and protection
+
+- **PacketEvents** is required for Freeze mode's packet and display behavior.
+- **CoreProtect** is optional. When a compatible CoreProtect API is available,
+ Classic and Copy mode changes are recorded as block changes.
+- **PlaceholderAPI** is optional. Installed placeholders are expanded in localized
+ messages before they are sent to players.
+- **Automatic region protection** asks the server's event system whether a player
+ can place at the target location. Protection plugins that cancel that placement
+ check can therefore deny DebugStickPro changes. Disable this behavior with
+ `AutoRegionProtection.Enabled` only when another access-control strategy is in
+ place.
+- [Nether-No-Water](https://www.spigotmc.org/resources/dsp-add-on-nether-no-water.118723/)
+ is an optional add-on that prevents players from changing the `waterlogged`
+ property in the Nether.
+
+### Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| DebugStickPro does not enable | Confirm PacketEvents 2.13.0 or later is installed and enabled first. Check that the server and Java versions match the support table. |
+| The stick does nothing | Hold a plugin-issued stick in the main hand; verify `debugstickpro.use`, world lists, block filters, and region protection. |
+| Copy or Freeze mode is skipped | Grant `debugstickpro.mode.copy` or `debugstickpro.mode.freeze`. Grant `debugstickpro.mode` as well when the player uses the mode command. |
+| A property is missing | Check `BlockDataFilter`, its per-type bypass permission, and `AllowUnsafeBisectedData`. Some properties are intentionally unavailable for safety. |
+| A player's language is not selected | Confirm the normalized locale file exists, is listed in `Language.LangFiles`, and contains valid YAML. |
+| Existing sticks stop working after an item config change | Reissue them with `/dsp give`; recognition uses the currently configured material. |
+| Frozen blocks need to be released | The player can left-click in Freeze mode, or an administrator can run `/dsp reload`. |
+
+Known limitation: players must sneak to change a candle's `lit` value.
+
+### Compatibility testing
+
+Continuous integration builds the plugin and starts every stable Paper and Folia
+release covered by the support range. Representative 1.19, 1.20, and 1.21 protocol
+versions also run in-game command, item, display, locale, and mode tests. Spigot
+protocol checkpoints are tested separately with the official BuildTools. Paper
+remains the primary platform.
+
+## Building from source
+
+Building requires JDK 25; the produced plugin JAR targets Java 17.
+
+```bash
+mvn -B package
+```
+
+The shaded plugin is written to `target/DebugStickPro-.jar`. Development
+artifacts are also available from the
+[TWME snapshot repository](https://repo.twme.dev/#/snapshots/dev/twme/DebugStickPro).