BlockEntityLimiter

A Folia-compatible Minecraft plugin that limits the number of block entities per chunk for Minecraft 1.21.x.

Features

• Folia Compatible: Fully compatible with Folia's multi-threaded regions
• High Performance: Smart caching system reduces lag significantly
• Chunk-based Limiting: Limits block entities on a per-chunk basis
• Master Limit: Optional master limit that controls total block entities across all types
• Individual Limits: Each block entity type has its own configurable limit
• Toggle System: Enable/disable limiting for each block entity type
• No Deletion: Plugin only prevents placement, never removes existing block entities
• Hot Reload: Reload configuration without restarting the server
• Shulker Box Support: Single config entry covers all shulker box colors
• Thread-Safe: Designed for Folia's concurrent region system
• Auto-Forceload: Automatically forceloads chunks with high block entity counts

Tracked Block Entities

• Decorated Pot
• Ender Chest
• Blast Furnace
• Smoker
• Furnace
• Barrel
• Dropper
• Dispenser
• Chest
• Trapped Chest
• Hopper
• Shulker Box (all colors)

Installation

1. Download the latest release JAR file
2. Place it in your server's plugins folder
3. Restart your server or load the plugin
4. Configure plugins/BlockEntityLimiter/config.yml to your needs

Configuration

Master Limit

The master limit controls the total number of block entities across ALL types:

master-limit:
  enabled: true    # Enable/disable master limit
  amount: 1000     # Maximum total block entities per chunk

Example Scenarios (with master limit of 1000):

• 500 chests + 500 ender chests = Allowed
• 100 chests + 900 ender chests = Allowed
• 600 chests + 500 ender chests = Blocked (exceeds master limit)

Individual Block Entity Limits

Each block entity type has two settings:

block-entities:
  chest:
    enabled: true   # Enable limiting for this type
    limit: 100      # Maximum of this type per chunk

• enabled: true - This block entity type will be limited
• enabled: false - This block entity type can be placed without restriction
• limit - Maximum number of this specific type per chunk

How Limits Work Together

When placing a block entity, the plugin checks:

1. Is limiting enabled for this block entity type?
2. Has the individual limit been reached?
3. (If master limit is enabled) Has the master limit been reached?

Placement is blocked if any limit is reached.

Forceload Feature

The plugin can automatically forceload chunks with many block entities:

forceload:
  enabled: false          # Enable/disable auto-forceload
  threshold: 50           # Minimum block entities to trigger forceload
  notify-player: true     # Notify player when chunk is forceloaded
  
  periodic-check:
    enabled: true         # Enable periodic validation of forceloaded chunks
    interval: 30          # Check every X minutes
    delay-per-chunk: 20   # Ticks between checking each chunk (20 = 1 second)
    verbose: false        # Log detailed info for each chunk check

How it works:

• When a chunk reaches the threshold, it's automatically forceloaded
• Forceloaded chunks stay loaded even when no players are nearby
• Useful for farms, storage systems, and automated setups
• Persistent across restarts: Forceloaded chunks are saved to forceloaded-chunks.yml
• When block entities drop below threshold (by breaking blocks), forceload is removed
• Players are notified when their chunk is forceloaded (optional)

Periodic Validation:

• Every X minutes, the plugin checks all forceloaded chunks
• Validates each chunk still has enough block entities
• If below threshold, removes forceload automatically
• Checks chunks one at a time with configurable delay to prevent lag
• Example: With 100 forceloaded chunks and 20 tick delay, full check takes ~33 seconds
• Verbose mode: When enabled, logs detailed information about each chunk check to console

Example: Set threshold to 50. When a chunk has 50+ hoppers/chests/furnaces, it stays loaded.

Commands

Command	Permission	Description
/belimiter reload	blockentitylimiter.reload	Reload the configuration
/belimiter forceloaded [page]	blockentitylimiter.admin	List all forceloaded chunks (paginated)
/belimiter	blockentitylimiter.use	Show help message

Aliases: /bel, /blocklimiter

Forceloaded Command Pages:

• Page 1: Shows summary with total count
• Page 2+: Shows list of chunks (10 per page)

Permissions

Permission	Default	Description
blockentitylimiter.use	true	Access to main command
blockentitylimiter.reload	op	Reload configuration
blockentitylimiter.admin	op	Access admin commands

Performance

The plugin uses an intelligent caching system to minimize lag:

• Cache Duration: 500ms (configurable in code)
• Automatic Invalidation: Cache updates when blocks are placed/broken
• Memory Management: Automatic cleanup of old cache entries
• Thread-Safe: ConcurrentHashMap for Folia compatibility

In testing scenarios with high block placement rates, the cache reduces chunk scanning by over 95%, preventing lag spikes.

Forceload Safety

The forceload feature is designed to be safe and reversible:

• ✅ Non-destructive: Only sets chunks to forceloaded, never modifies blocks
• ✅ Automatic cleanup: Removes forceload when block entities drop below threshold
• ✅ Persistent storage: Saves to forceloaded-chunks.yml and restores on restart
• ✅ Periodic validation: Automatically checks and removes invalid forceloads
• ✅ Manual override: Admins can manually remove forceload with /forceload remove
• ✅ Graceful shutdown: Saves all data before server stops
• ⚠️ Memory usage: Forceloaded chunks consume server memory - use reasonable thresholds
• ⚠️ Performance: Too many forceloaded chunks can impact performance - monitor with /belimiter forceloaded