A Spigot/Paper library for creating and managing client-side (packet-based) blocks.
PacketBlocks lets you display blocks to players without modifying the real world, while still providing APIs for interaction, metadata, block breaking, and per-player visibility.

• Spawn blocks visible only to specific players
• Fully per-player block states (BlockData, suppliers, metadata)
• Break simulation (PacketBlockBreakEvent) with configurable item drops
• Per-viewer visibility conditions (filters)
• Utilities for bounding boxes, collision handling, and animations
• Automatic viewer management

• Server: Paper 1.21+ (or a compatible fork)
• Java: 21+
• Dependency: PacketEvents 2.9.5+

This project is not published to a repository host. You must clone it and install it manually:

git clone https://github.com/BitByLogics/PacketBlocks.git cd PacketBlocks mvn clean install

This installs the library into your local Maven repository (~/.m2/repository).

Add it as a dependency in your plugin project:

<dependency> <groupId>net.bitbylogic</groupId> <artifactId>packetblocks</artifactId> <version>1.0.0</version> <scope>provided</scope> </dependency>

Replace 1.0.0 with the actual project version.

Location loc = player.getLocation().add(0, 0, 1); BlockData blockData = Bukkit.createBlockData(Material.DIAMOND_BLOCK); // Get the block manager PacketBlockManager blockManager = PacketBlocks.getInstance().getBlockManager(); // Create the packet block PacketBlock packetBlock = blockManager.createBlock(loc, blockData); // Add permission view requirement packetBlock.addViewCondition(player -> player.hasPermission("packetblocks.view")); // Make it visible to a player packetBlock.addAndUpdateViewer(player); // Update for all viewers packetBlock.setBlockDataForAll(Material.GOLD_BLOCK.createBlockData()); // Simulate break (fires PacketBlockBreakEvent and drops items by default) packetBlock.simulateBreak(player);

Full API documentation for PacketBlocks is available online:
View Javadocs

simulateBreak(...) triggers PacketBlockBreakEvent. This event:

• Is cancellable
• By default, will drop items based on the BlockState and tool used
• If you do not want items to drop, call event.setDropItems(false) in your event listener

The PacketBlockManager is the main API for managing PacketBlocks on the server. You can get the manager using:

PacketBlockManager blockManager = PacketBlocks.getInstance().getBlockManager();

Some important methods:

• createBlock(Location location, BlockData blockData) – Creates a new PacketBlock at the specified location
• removeBlock(PacketBlock packetBlock) – Removes a block and resets the world block for all viewers
• removeIf(Predicate<PacketBlock> removePredicate) – Removes blocks that match a given condition
• getBlock(Location location) – Gets the PacketBlock at a specific location, if it exists
• getBlocks(World world) – Gets all PacketBlocks in a world
• getBlocks(World world, int chunkX, int chunkZ) – Gets all PacketBlocks in a specific chunk
• getBlocksByViewer(Player player) – Gets all PacketBlocks currently visible to a player
• getBlocksByViewerWithMeta(Player player, String metaKey) – Gets all PacketBlocks visible to a player that contain a specific metadata key

Build the project:

mvn clean install

Contributions are welcome:

1. Fork the repository
2. Create a branch for your feature/fix
3. Open a Pull Request with a clear description and tests/examples when appropriate

MIT License — see LICENSE.

BitByLogic
Discord: @BitByLogic