Piston Crusher Plugin

Automate block crushing using piston mechanics.
Configurable whitelist, multiplier, crusher block type, and live admin commands.

            

Piston Crusher is an open-source Minecraft automation plugin that turns piston interactions into configurable block-crushing mechanics. When a piston extends and a whitelisted block is pushed into the configured crusher block, the target block is removed and item drops are generated using the configured multiplier. The plugin stores persistent runtime settings in data files (whitelist.yml, crusherblock.yml) and exposes all management operations through /pistoncrusher commands.

Core Features

• Whitelist-Driven Crushing: Only materials on the plugin whitelist are eligible for crushing
• Multiplier Control: Set a global drop multiplier (minimum 1.0) via command
• Custom Crusher Block: Choose the block that acts as the crusher target in the piston line
• Runtime Administration: Manage whitelist, multiplier, and crusher block without restart
• Persistent Settings: Whitelist and crusher block are saved in plugin data files
• Tab Completion: Subcommands and material names are suggested automatically

Supported Platforms

• Server Software: Spigot, Paper, Purpur, CraftBukkit
• Minecraft Versions: 1.20 and higher
• Java Requirements: Java 17+
• Dependencies: None - fully self-contained, no external plugins required

Table of Contents

1. Getting Started
   • Prerequisites
   • Installation Steps
   • First Launch
   • Verifying Installation
2. Configuration
   • Data Files
3. How It Works
4. Setup Example
5. Administrative Commands
6. Permissions
7. Building from Source
8. License
9. Screenshots

Getting Started

Prerequisites

Before installing Piston Crusher, confirm the following requirements are met:

• A Minecraft server running Spigot, Paper, Purpur, or any compatible fork
• Server version 1.20 or higher (api-version: 1.20 is the minimum)
• Java 17 or newer installed on the machine running the server
• Operator or console access to install plugin files

No additional plugins or libraries are needed. Piston Crusher has zero external dependencies.

Installation Steps

1. Download the latest .jar from the Releases page
2. Stop your server completely before placing any files
3. Copy the .jar into your server's plugins/ directory
4. Start the server - Piston Crusher generates its configuration folder automatically on first boot

First Launch

On the first server start after installation, Piston Crusher creates the following structure:

plugins/
└── PistonCrusher/
    ├── whitelist.yml      - Materials eligible for crushing (default: COBBLESTONE)
    └── crusherblock.yml   - The block material used as crusher target (default: WAXED_CHISELED_COPPER)

The plugin is ready to use immediately after installation. To build a working crusher, arrange blocks according to the Setup Example section.

Verifying Installation

• Run /plugins in-game - PistonCrusher should appear green in the list
• Run /pistoncrusher whitelist list to confirm the default whitelist is loaded
• Place a cobblestone block between a piston and a waxed chiseled copper block and fire the piston - the cobblestone should be crushed and drop items
• If the plugin fails to load, check the server console for PistonCrusher error messages (common causes: wrong Java version, corrupt JAR, or unsupported API version)

Configuration

Data Files

Piston Crusher does not use a standard config.yml; instead it persists state in dedicated files:

File	Key	Default	Description
plugins/PistonCrusher/whitelist.yml	whitelist	[COBBLESTONE]	Materials eligible for crushing
plugins/PistonCrusher/crusherblock.yml	crusherblock	WAXED_CHISELED_COPPER	Block material that acts as crusher target

Note: Material values must be valid Bukkit material names (for example cobblestone, stone, gold_block). Only movable blocks are accepted.

How It Works

When a piston is fired, Piston Crusher intercepts the BlockPistonExtendEvent. It checks every block that the piston is about to push in order. If the piston encounters a block that is on the whitelist and the block directly ahead of it matches the configured crusher block material, the following happens:

1. The candidate block (the whitelisted one) is removed from the world
2. Item drops are spawned at that location
3. The drop quantity is multiplied by the configured multiplier (minimum 1.0)

The piston itself does not physically move the block - the event is cancelled for the target block so Minecraft's built-in pushing behavior does not apply. All other blocks in the push line that are not whitelisted are pushed normally.

Setup Example

To build a working piston crusher, arrange blocks in a straight line:

[Piston] --> [Block to Crush] --> [Crusher Block]

• The piston must face directly toward the candidate block
• The candidate block must be on the whitelist
• The block directly in front of the candidate must match the configured crusher block material
• On success, the candidate block is removed and its drops are spawned with the configured multiplier applied

Administrative Commands

Command	Description
/pistoncrusher	Show command usage
/pistoncrusher whitelist add <material>	Add a material to the crush whitelist
/pistoncrusher whitelist remove <material>	Remove a material from the crush whitelist
/pistoncrusher whitelist list	Display all currently whitelisted materials
/pistoncrusher multiplier <value>	Set the drop multiplier (values below 1 are clamped to 1)
/pistoncrusher multiplier	Display the current output multiplier
/pistoncrusher crusherblock <material>	Set the designated crusher block type
/pistoncrusher crusherblock	Display the current crusher block material

Permissions

Permission	Description	Default
pistoncrusher.admin	Access to all /pistoncrusher commands	op

Building from Source

Piston Crusher uses Apache Maven as its build system. The plugin is packaged as a standard JAR with no external runtime dependencies.

Requirements:

• Java 17 or newer
• Apache Maven 3.6 or newer

Steps:

# Clone the repository
git clone https://github.com/Cobbleworks/Piston-Crusher-Plugin.git
cd Piston-Crusher-Plugin

# Compile and package
mvn clean package

The output JAR is written to target/PistonCrusher-x.x.x.jar. Copy it into your server's plugins/ folder as described in the Installation Steps section.

Project Structure:

src/main/
├── java/org/example/
│   ├── PistonCrusherPlugin.java   - Plugin entry point (onEnable / onDisable)
│   ├── PistonCrusherListener.java - Piston extend event handling and crush logic
│   └── PistonCrusherCommand.java  - All /pistoncrusher subcommands + tab completion
└── resources/
    └── plugin.yml                 - Plugin metadata, commands, permissions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Screenshots

The screenshots below demonstrate Piston Crusher in action, including emerald block crushing, multiple crusher alignment, and automated cobblestone farm setups.

Piston Crusher - Emerald Crushing	Piston Crusher - Multiple Crushers
Piston Crusher - Cobblestone Farm	Piston Crusher - Gold Crush
Piston Crusher - Auto Generator	Piston Crusher - Block Arrangement