# BlockEntityLimiter<\/p>\n
A Folia-compatible Minecraft plugin that limits the number of block entities per chunk for Minecraft 1.21.x.<\/p>\n
## Features<\/p>\n
– **Folia Compatible**: Fully compatible with Folia’s multi-threaded regions
\n– **High Performance**: Smart caching system reduces lag significantly
\n– **Chunk-based Limiting**: Limits block entities on a per-chunk basis
\n– **Master Limit**: Optional master limit that controls total block entities across all types
\n– **Individual Limits**: Each block entity type has its own configurable limit
\n– **Toggle System**: Enable\/disable limiting for each block entity type
\n– **No Deletion**: Plugin only prevents placement, never removes existing block entities
\n– **Hot Reload**: Reload configuration without restarting the server
\n– **Shulker Box Support**: Single config entry covers all shulker box colors
\n– **Thread-Safe**: Designed for Folia’s concurrent region system
\n– **Auto-Forceload**: Automatically forceloads chunks with high block entity counts<\/p>\n
## Tracked Block Entities<\/p>\n
– Decorated Pot
\n– Ender Chest
\n– Blast Furnace
\n– Smoker
\n– Furnace
\n– Barrel
\n– Dropper
\n– Dispenser
\n– Chest
\n– Trapped Chest
\n– Hopper
\n– Shulker Box (all colors)<\/p>\n
## Installation<\/p>\n
1. Download the latest release JAR file
\n2. Place it in your server’s `plugins` folder
\n3. Restart your server or load the plugin
\n4. Configure `plugins\/BlockEntityLimiter\/config.yml` to your needs<\/p>\n
## Configuration<\/p>\n
### Master Limit
\nThe master limit controls the total number of block entities across ALL types:<\/p>\n
“`yaml
\nmaster-limit:
\n enabled: true # Enable\/disable master limit
\n amount: 1000 # Maximum total block entities per chunk
\n“`<\/p>\n
**Example Scenarios** (with master limit of 1000):
\n– 500 chests + 500 ender chests = **Allowed**
\n– 100 chests + 900 ender chests = **Allowed**
\n– 600 chests + 500 ender chests = **Blocked** (exceeds master limit)<\/p>\n
### Individual Block Entity Limits<\/p>\n
Each block entity type has two settings:<\/p>\n
“`yaml
\nblock-entities:
\n chest:
\n enabled: true # Enable limiting for this type
\n limit: 100 # Maximum of this type per chunk
\n“`<\/p>\n
– `enabled: true` – This block entity type will be limited
\n– `enabled: false` – This block entity type can be placed without restriction
\n– `limit` – Maximum number of this specific type per chunk<\/p>\n
### How Limits Work Together<\/p>\n
When placing a block entity, the plugin checks:
\n1. Is limiting enabled for this block entity type?
\n2. Has the individual limit been reached?
\n3. (If master limit is enabled) Has the master limit been reached?<\/p>\n
Placement is **blocked** if any limit is reached.<\/p>\n
### Forceload Feature<\/p>\n
The plugin can automatically forceload chunks with many block entities:<\/p>\n
“`yaml
\nforceload:
\n enabled: false # Enable\/disable auto-forceload
\n threshold: 50 # Minimum block entities to trigger forceload
\n notify-player: true # Notify player when chunk is forceloaded<\/p>\n
periodic-check:
\n enabled: true # Enable periodic validation of forceloaded chunks
\n interval: 30 # Check every X minutes
\n delay-per-chunk: 20 # Ticks between checking each chunk (20 = 1 second)
\n verbose: false # Log detailed info for each chunk check
\n“`<\/p>\n
**How it works:**
\n– When a chunk reaches the threshold, it’s automatically forceloaded
\n– Forceloaded chunks stay loaded even when no players are nearby
\n– Useful for farms, storage systems, and automated setups
\n– **Persistent across restarts**: Forceloaded chunks are saved to `forceloaded-chunks.yml`
\n– When block entities drop below threshold (by breaking blocks), forceload is removed
\n– Players are notified when their chunk is forceloaded (optional)<\/p>\n
**Periodic Validation:**
\n– Every X minutes, the plugin checks all forceloaded chunks
\n– Validates each chunk still has enough block entities
\n– If below threshold, removes forceload automatically
\n– Checks chunks one at a time with configurable delay to prevent lag
\n– Example: With 100 forceloaded chunks and 20 tick delay, full check takes ~33 seconds
\n– **Verbose mode**: When enabled, logs detailed information about each chunk check to console<\/p>\n
**Example:** Set threshold to 50. When a chunk has 50+ hoppers\/chests\/furnaces, it stays loaded.<\/p>\n
## Commands<\/p>\n
| Command | Permission | Description |
\n|———|———–|————-|
\n| `\/belimiter reload` | `blockentitylimiter.reload` | Reload the configuration |
\n| `\/belimiter forceloaded [page]` | `blockentitylimiter.admin` | List all forceloaded chunks (paginated) |
\n| `\/belimiter` | `blockentitylimiter.use` | Show help message |<\/p>\n
**Aliases**: `\/bel`, `\/blocklimiter`<\/p>\n
**Forceloaded Command Pages:**
\n– Page 1: Shows summary with total count
\n– Page 2+: Shows list of chunks (10 per page)<\/p>\n
## Permissions<\/p>\n
| Permission | Default | Description |
\n|———–|———|————-|
\n| `blockentitylimiter.use` | true | Access to main command |
\n| `blockentitylimiter.reload` | op | Reload configuration |
\n| `blockentitylimiter.admin` | op | Access admin commands |<\/p>\n
## Performance<\/p>\n
The plugin uses an intelligent caching system to minimize lag:
\n– **Cache Duration**: 500ms (configurable in code)
\n– **Automatic Invalidation**: Cache updates when blocks are placed\/broken
\n– **Memory Management**: Automatic cleanup of old cache entries
\n– **Thread-Safe**: ConcurrentHashMap for Folia compatibility<\/p>\n
In testing scenarios with high block placement rates, the cache reduces chunk scanning by over 95%, preventing lag spikes.<\/p>\n
### Forceload Safety<\/p>\n
The forceload feature is designed to be safe and reversible:
\n– \u2705 **Non-destructive**: Only sets chunks to forceloaded, never modifies blocks
\n– \u2705 **Automatic cleanup**: Removes forceload when block entities drop below threshold
\n– \u2705 **Persistent storage**: Saves to `forceloaded-chunks.yml` and restores on restart
\n– \u2705 **Periodic validation**: Automatically checks and removes invalid forceloads
\n– \u2705 **Manual override**: Admins can manually remove forceload with `\/forceload remove`
\n– \u2705 **Graceful shutdown**: Saves all data before server stops
\n– \u26a0\ufe0f **Memory usage**: Forceloaded chunks consume server memory – use reasonable thresholds
\n– \u26a0\ufe0f **Performance**: Too many forceloaded chunks can impact performance – monitor with `\/belimiter forceloaded`<\/p>\n","protected":false},"excerpt":{"rendered":"
Limits the number of block entities per chunk<\/p>\n","protected":false},"featured_media":32289,"template":"","meta":{"_minecraft_slug":"blockentitylimiter","_minecraft_project_id":"qQDeaCRo","_minecraft_author":"MistaSoup","_minecraft_license":"MIT","_minecraft_downloads":33,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"blockentitylimiter.zip","_minecraft_size_bytes":82022,"_minecraft_version_count":4,"_minecraft_updated_at":"2026-05-15T21:54:58.679080Z","_minecraft_date_created":"2026-01-25T04:55:44.884940Z","_minecraft_date_modified":"2026-01-31T00:24:38.011436Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/blockentitylimiter","_minecraft_icon_attachment_id":32289,"_minecraft_imported_at":"2026-06-01T14:40:07+00:00","_minecraft_import_hash":"b397a9e1bbf9e7248cb3c7067f6c4eef","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[43,125,89,90,127,128,129,92],"mod_loader":[131,132,133,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-32288","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-cursed","mod_category-folia","mod_category-game-mechanics","mod_category-optimization","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-utility","mod_loader-folia","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n