BlockEntityLimiter

BlockEntityLimiter

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

Features

- Auto-Forceload: Fully compatible with Folia's multi-threaded regions - Auto-Forceload: Smart caching system reduces lag significantly - Auto-Forceload: Limits block entities on a per-chunk basis - Auto-Forceload: Optional master limit that controls total block entities across all types - Auto-Forceload: Each block entity type has its own configurable limit - Auto-Forceload: Enable/disable limiting for each block entity type - Auto-Forceload: Plugin only prevents placement, never removes existing block entities - Auto-Forceload: Reload configuration without restarting the server - Auto-Forceload: Single config entry covers all shulker box colors - Auto-Forceload: 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:

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

Blocked (with master limit of 1000): - 500 chests + 500 ender chests = Blocked - 100 chests + 900 ender chests = Blocked - 600 chests + 500 ender chests = Blocked (exceeds master limit)

Individual Block Entity Limits

Each block entity type has two settings:

```yaml 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:

```yaml 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 ```

Persistent across restarts - 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)

Verbose mode - 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: - Thread-Safe: 500ms (configurable in code) - Thread-Safe: Cache updates when blocks are placed/broken - Thread-Safe: 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: - ✅ Performance: Only sets chunks to forceloaded, never modifies blocks - ✅ Performance: Removes forceload when block entities drop below threshold - ✅ Performance: Saves to `forceloaded-chunks.yml` and restores on restart - ✅ Performance: Automatically checks and removes invalid forceloads - ✅ Performance: Admins can manually remove forceload with `/forceload remove` - ✅ Performance: Saves all data before server stops - ⚠️ Performance: Forceloaded chunks consume server memory - use reasonable thresholds - ⚠️ Performance: Too many forceloaded chunks can impact performance - monitor with `/belimiter forceloaded`