GhostBlocks Plugin
Create ghost blocks in Minecraft—blocks that are visible but have no collision!

Build Errors? Make sure you’re using Java 17+ and Maven 3.6+

Features
Core Functionality

• Ghost Blocks: Visible blocks with no hitbox or collision
  
  
• Categorized GUI: Block selection split into four categories: Building, Nature, Redstone, Decoration
  
  
• Pagination System: Easily browse blocks through paginated menus
  
  
• Ghost Block Remover: A tool to remove ghost blocks by right-clicking while looking at them
  
  
• Auto-Save System: Ghost blocks persist through server reloads and restarts

️ Technical Features

• Utilizes FallingBlock entities with gravity and decay disabled
  
  
• Thread-safe operations using concurrent data structures
  
  
• Efficient location-based ghost block mapping
  
  
• YAML-based persistent storage
  
  
• Improved removal logic using line-of-sight detection
  
  
• Admin commands for maintenance and debugging

Installation

1. Download the plugin JAR
   
   
2. Place it in your server’s plugins/ folder
   
   
3. Restart the server
   
   
4. Configuration file ghostblocks.yml will be generated automatically

⌨️ Commands

Command Description Permission
/ghostblocks Open block selection GUI
/ghostblocks help Show help info
/ghostblocks count Show number of ghost blocks
/ghostblocks manage Manage placed ghost blocks
/ghostblocks remover Get the remover tool
/ghostblocks reload Reload config and data
/ghostblocks cleanup Remove invalid ghost blocks
Aliases: /gb, /ghost

️ Permissions

• ghostblocks.use – Access to core plugin features (default: true)
  
  
• ghostblocks.admin – Admin commands and maintenance tools (default: OP)

How to Use
1. Get Ghost Blocks

• Run /ghostblocks
  
  
• Use category buttons to browse: Building, Nature, Redstone, Decoration
  
  
• Navigate with Previous/Next buttons
  
  
• Click any block to receive it as a ghost block item
  
  
• Click the "Remover" icon to get the removal tool

2. Place Ghost Blocks

• Place ghost blocks like regular blocks
  
  
• They appear instantly but with no hitbox

3. Remove Ghost Blocks

• Hold the Remover tool (a stick)
  
  
• Look at a ghost block and right-click
  
  
• The tool detects and removes ghost blocks in your line of sight

Block Categories
️ Building

• Stone, Deepslate, Sandstone, Blackstone, Prismarine, etc.

Nature

• All wood types, stripped variants, dirt, grass, ice, calcite, dripstone, etc.

⚡ Redstone

• Redstone components, copper (oxidized), furnaces, pistons, and more

Decoration

• Colored concrete, terracotta, glazed blocks, nether/end blocks, amethyst, sculk, ancient debris, etc.

⚙️ Technical Details
Ghost Block Implementation

• Based on FallingBlock entities
  
  
• Properties: gravity=false, dropItem=false, hurtEntities=false
  
  
• Positioned precisely in block centers
  
  
• Persistent using YAML storage

Data Storage

• All data saved in plugins/GhostBlocks/ghostblocks.yml
  
  
• Auto-save on shutdown, auto-load on startup
  
  
• Includes block position, type, world, and ID

Performance

• Uses ConcurrentHashMap for high performance and thread safety
  
  
• O(1) ghost block lookups by location
  
  
• Invalid block cleanup logic included
  
  
• Designed to have minimal impact on server performance

️ Building from Source
Requirements

• Java 17+
  
  
• Maven 3.6+
  
  
• Paper 1.20.6 API or newer

Build Instructions
git clone <repository-url>
cd GhostBlocks
mvn clean package

The final .jar will be located in the target/ folder.

Configuration
A ghostblocks.yml file is generated automatically.
This file stores all ghost block data. Do not edit it manually.

❗ Troubleshooting
Common Issues

1. Blocks not saving – Ensure the plugin has write permissions
   
   
2. Blocks act like normal blocks – Make sure you're on Paper 1.20.6+
   
   
3. Cannot remove ghost blocks – Use the Remover tool and look directly at the block
   
   
4. Build fails – Confirm you have Java 17+ and Maven 3.6+
   
   
5. GUI won’t open – Check your permissions (ghostblocks.use)

Debug Tips

• /ghostblocks count – See how many blocks are placed
  
  
• /ghostblocks cleanup – Remove invalid or broken ghost blocks
  
  
• Check your server console/logs for error messages

Support

1. Review the Troubleshooting section
   
   
2. Check your console for errors
   
   
3. Submit an issue with details about your problem

License
This project is licensed under the MIT License.
See the LICENSE file for more info.

Version History
v1.0.0

• Initial release with core ghost block system
  
  
• Categorized GUI and pagination
  
  
• Remover tool with line-of-sight detection
  
  
• Persistence and admin commands
  
  
• 200+ supported block types

v2.0.0

• GUI Improvements: Menu stays open when selecting blocks
  
  
• Multi-selection support without GUI closing

v3.0.0

• Fixed block glitches and decay
  
  
• Auto-save system: saves every 10 ticks (0.5s)
  
  
• Persistence bug fixes

v3.5.0

• GUI for managing existing ghost blocks
  
  
• New commands and improved UX
  
  
• Thread-safe refactoring
  
  
• APDC: Auto Player Data Cleanup system

v4.0.0

• Major TPS optimization
  
  
• Full multi-threading support
  
  
• Expanded block list and GUI improvements