🟧 LF-Pistons

🔵 Smart and optimized piston-based crop harvesting

Java 21 • Paper/Purpur 1.21.x

🔥 About

LF-Pistons is a lightweight and highly configurable plugin that creates an optimized automatic harvesting system using pistons.

When a supported plant reaches its harvest stage, the plugin checks whether a valid piston is pointing toward it. If a piston is detected, LF-Pistons automatically harvests the plant, generates its drops and safely resets the crop when necessary.

The system is event-driven and includes performance limits, cache optimization, drop grouping and automatic TPS/MSPT protection, making it suitable for servers with large farms and many active players.

LF-Pistons is ideal for:

• Creating balanced automatic farms
• Reducing excessive redstone usage
• Preventing uncontrolled farm automation
• Replacing heavy piston and block update systems
• Creating custom farming mechanics
• Controlling farms differently in each world

⚙️ Main Features

🌱 Farming system

• Automatic harvesting when a valid piston points toward a mature plant
• Support for normal pistons, sticky pistons or both
• Optional powered-only mode
• Configurable piston detection radius
• Automatic crop resetting
• Mature plant recovery
• Custom drops with amount ranges and chances
• Individual behavior for each plant
• Configurable bone meal behavior
• All built-in supported plants enabled by default

🌍 Per-world configuration

Each world can have its own:

• Enabled state
• Registered plant list
• Piston mode
• Powered-only setting
• Detection radius
• Farm profile
• Processing behavior

🗂️ Reusable farm profiles

Create reusable profiles for different farm types and apply them to multiple worlds.

Example profiles can be created for:

• Sugar cane
• Bamboo
• Cactus
• Kelp
• Traditional crops
• Custom plant setups

🖥️ Management interface

• Built-in plant management menu
• Plant search
• Plant categories
• Pagination
• Plant status display
• Piston mode selection
• Confirmation before removing plants
• Automatic backup before menu changes
• Chat-based input where required

📊 Harvest statistics

Persistent statistics are recorded:

• Globally
• Per world
• Per plant
• By total harvest operations
• By total harvested plant units

Statistics can be accessed through commands and PlaceholderAPI.

🌐 Languages

Included languages:

• English
• Portuguese
• French
• Spanish

English is used by default and can be changed in config.yml.

🌿 Supported Plants

• Pumpkin
• Melon
• Bamboo
• Sugar Cane
• Glow Berries / Cave Vines
• Amethyst Clusters
• Cactus
• Kelp
• Wheat
• Carrots
• Potatoes
• Beetroots
• Nether Wart
• Cocoa
• Sweet Berries
• Torchflower
• Pitcher Plant

Additional custom plants can be configured using the optional ItemsAdder and CustomCrops bridges.

🔄 How It Works

1. A registered plant grows or becomes ready to harvest.
2. LF-Pistons checks for a valid piston pointing toward the plant.
3. The configured piston type and detection radius are verified.
4. If powered-only mode is enabled, the piston must also be powered.
5. Protection hooks and performance limits are checked.
6. The plant is harvested and its configured drops are generated.
7. Crops that can regrow are safely reset to their initial stage.
8. The harvest is recorded in the statistics system.

By default, the piston only needs to point toward the plant. Enable powered-only if a redstone signal should also be required.

🧱 Piston Modes

• NORMAL — Only normal pistons are accepted
• STICKY — Only sticky pistons are accepted
• BOTH — Normal and sticky pistons are accepted

The piston mode can be configured globally, through farm profiles or separately for each world.

🌾 Individual Plant Settings

Each plant can override the global configuration.

Available options include:

• Custom piston detection radius
• Custom drops
• Minimum and maximum drop amounts
• Individual drop chances
• Bone meal behavior
• World-specific overrides

Custom drop format

MATERIAL:min-max:chance

Example:

WHEAT:1-2:1.0

This example generates between one and two wheat with a 100% chance.

Bone meal modes

• VANILLA — Keeps the normal Minecraft behavior
• HARVEST — Allows bone meal growth to trigger harvesting
• DENY — Prevents bone meal from affecting the configured plant

♻️ Mature Plant Recovery

Plants may become fully grown while LF-Pistons is disabled, while the server is starting or while their chunks are unloaded.

LF-Pistons can recover these plants automatically:

• During server startup
• When a chunk is loaded
• When a piston is activated
• When using /lfpistons recover

Loaded chunks are processed gradually to prevent lag spikes.

🚀 Performance Protection

LF-Pistons includes multiple systems to safely handle large farms:

• Event-driven plant processing
• Per-world plant cache
• Safe piston detection cache
• Global harvest limit per tick
• Automatic TPS protection
• Automatic MSPT protection
• Reduced processing during server overload
• Incremental mature plant recovery
• Asynchronous chunk snapshot scanning
• Grouped drops by chunk
• Configurable item entity limit per tick
• Automatic cache cleanup when worlds unload
• No uncontrolled full-world scans

When server performance falls below the configured TPS or exceeds the configured MSPT, LF-Pistons temporarily reduces its processing limit.

🔍 Inspection and Diagnostics

Having trouble with a farm? LF-Pistons includes built-in troubleshooting tools.

Use /lfpistons inspect and click a plant to view:

• Detected piston
• Piston direction
• Distance from the plant
• Current operating mode
• Powered-only state
• Reason why the plant is not being harvested

Temporary diagnostics can be enabled for a limited number of minutes. The diagnostic system automatically disables itself to prevent unnecessary logging.

Example:

/lfpistons diagnose 5

This enables detailed diagnostics for five minutes.

✅ Configuration Validator

Use /lfpistons validate to detect configuration problems.

The validator checks:

• Invalid Minecraft materials
• Unsupported plants
• Invalid custom drops
• Dangerous processing limits
• Missing farm profiles
• Conflicting settings
• Invalid world configurations

The validator only runs when requested and has practically no impact on normal server performance.

⌨️ Commands

Command alias: /lfp

🔑 Permissions

🧩 PlaceholderAPI

PlaceholderAPI is optional.

Available placeholders:

• %lfpistons_harvests_total% — Total harvest operations
• %lfpistons_plant_units_total% — Total harvested plant units
• %lfpistons_harvests_world% — Harvests in the player's current world
• %lfpistons_harvests_world_WORLD_NAME% — Harvests in a selected world
• %lfpistons_harvests_plant_MATERIAL% — Harvests for a selected plant
• %lfpistons_state% — Current system state
• %lfpistons_mode% — Current piston mode
• %lfpistons_cache_size% — Current cache size
• %lfpistons_pending_drop_groups% — Pending drop groups
• %lfpistons_diagnostics% — Diagnostic system state
• %lfpistons_plants_world% — Registered plants in the current world

Replace WORLD_NAME and MATERIAL with the required world or Minecraft material name.

🔌 Optional Integrations

PlaceholderAPI

Provides harvest statistics and system state placeholders.

WorldGuard

Optionally blocks automatic harvesting inside protected regions.

GriefPrevention

Optionally blocks automatic harvesting inside claims.

ItemsAdder

Provides support for custom plant identifiers and display items.

CustomCrops

Provides support for custom crops, mature stages and custom drops.

All integrations are optional soft dependencies. LF-Pistons can start and operate without them.

WorldGuard and GriefPrevention restrictions are disabled by default. Automatic growth does not have a responsible player identity, so enabling these restrictions will block LF-Pistons harvesting inside protected locations.

🛠️ Developer API

LF-Pistons provides a public API through Bukkit's ServicesManager.

Other plugins can:

• Access registered plants
• Read harvest statistics
• Inspect piston detection results
• Register custom protection hooks
• Cancel or modify harvests
• Receive information after a successful harvest

Available events:

• HarvestPreEvent — Cancellable and allows drop modification
• HarvestPostEvent — Called after a successful harvest

💾 Configuration Safety

• Automatic configuration migration
• Automatic backup before menu changes
• Configurable backup retention
• Administrative change history
• Detailed reload report
• Invalid configuration detection
• Safe cache invalidation
• Automatic world cache cleanup

Existing configurations from previous versions are migrated automatically.

We still recommend creating a backup before every major update.

📥 Installation

1. Download the latest LF-Pistons JAR.
2. Stop your Minecraft server.
3. Place the JAR inside the /plugins/ folder.
4. Start the server.
5. Configure the generated plugins/LF-Pistons/config.yml file.
6. Run /lfpistons validate.
7. Run /lfpistons status to confirm that the system is active.

🔄 Updating from an Older Version

1. Stop the server.
2. Back up the existing plugins/LF-Pistons/ folder.
3. Replace the old JAR with the new version.
4. Start the server normally.
5. Existing configuration values will be migrated automatically.
6. Run /lfpistons validate after startup.
7. Review the console for migration or validation warnings.

Do not delete your existing configuration unless you want to reset the plugin completely.

❓ Troubleshooting

If a plant is not being harvested:

1. Run /lfpistons status.
2. Run /lfpistons validate.
3. Use /lfpistons inspect and click the plant.
4. Check whether the piston is pointing toward the plant.
5. Check the configured piston mode.
6. Check whether powered-only mode is enabled.
7. Check WorldGuard and GriefPrevention restrictions.
8. Use /lfpistons recover if the plant was already mature.
9. Enable temporary diagnostics if the problem continues.

📌 Important Notes

• Designed for performance and stability
• Recommended for survival and economy servers
• Supports large automatic farms
• Does not require redstone unless powered-only mode is enabled
• Existing configurations are migrated automatically
• Optional integrations are not required for startup
• Always stop the server before replacing the plugin JAR

💬 Support

Need help or want to report a problem?

👉 Join the LF Studios Discord

❤️ Made by LF Studios