FlameStack - Optimize Performance v0.0.1

Overview

FlameStack is a professional Minecraft item stacker plugin built to reduce the number of dropped item entities on SMP, survival, economy, farming, and high-player-count servers.

Instead of repeatedly scanning every entity in every loaded world, FlameStack maintains an optimized spatial index organized by world, chunk, and vertical chunk section. Newly dropped items are registered through lifecycle events, placed into the correct indexed section, and processed through bounded lookup budgets.

The result is a lightweight ground item stacking plugin that can combine hundreds or thousands of identical dropped items into one logical item entity without constantly performing expensive world-wide entity searches.

FlameStack also includes a vanilla-aware minimum stacking requirement. Normal item stacks remain untouched until their combined amount exceeds the material's normal Minecraft stack limit. This prevents the plugin from renaming or modifying ordinary dropped items when extended stacking is not yet necessary.

If you are searching for a Minecraft item stacker, Paper item stacking plugin, Folia item stacker, dropped item optimizer, or a configurable alternative to basic item merge plugins, FlameStack is designed for that role.

Why FlameStack

Most item stacking plugins use one of two approaches.

They either rely entirely on Minecraft's normal merge limit, which cannot represent large item piles, or they repeatedly scan nearby entities and worlds with little control over lookup cost.

FlameStack uses a maintained spatial index instead.

Each tracked item is associated with:

• Its world
• Its chunk X and Z
• Its 16-block vertical chunk section
• Its material
• Its current logical amount
• Its item similarity fingerprint
• Its exact position

When FlameStack searches for a merge target, it checks only the indexed sections intersecting the configured merge radius. It does not search unrelated chunks, unrelated worlds, or every loaded entity.

Lookup work is also bounded through configurable scan and candidate limits, allowing server owners to control how much item processing may occur during each coordinator cycle.

Vanilla-Aware Minimum Stack Requirement

FlameStack is configured by default to preserve normal Minecraft item behavior until extended stacking is required.

Default configuration:


With this enabled, two item entities only become eligible for FlameStack merging when their combined amount exceeds the material's vanilla maximum stack size.

Examples:


This creates a more natural system.

Players can drop and interact with ordinary item stacks normally. FlameStack only begins extended stacking when Minecraft's normal stack capacity is no longer enough.

Smart Stack Displays

FlameStack can display the item name and logical amount directly above qualifying stacked items.

Default format:


Example:


The floating display is not applied to every dropped item.

With the default vanilla-aware trigger enabled:

• A normal stack of 64 stone has no FlameStack floating name.
• A logical stack of 65 stone displays its name and amount.
• A logical stack of 320 stone displays its complete amount.
• A non-stackable item begins displaying at an amount of 2.

This avoids unnecessary visual clutter and prevents FlameStack from interacting with item displays before the configured stacking threshold has been achieved.

Items with their own custom display name use that name in the FlameStack label instead of replacing their item metadata.

Display formatting supports Adventure MiniMessage syntax and can be changed directly from configuration.

Large Logical Item Stacks

Minecraft normally limits most item stacks to 64. FlameStack can represent much larger quantities inside one dropped item entity.

The default maximum is:


That is equivalent to 36 full stacks of 64 items represented by one ground entity.

The maximum is configurable, allowing each server to select a limit appropriate for its gameplay and performance requirements.

When the target reaches its configured maximum, any remaining quantity stays on the donor item instead of being deleted.

Material Blacklist and Whitelist

FlameStack includes one configurable material filter supporting both blacklist and whitelist operation.

Default:


Available modes:

Blacklist

Every valid material may stack except the materials listed in contents.

Whitelist

Only materials listed in contents may stack.

Material input is normalized and resolved safely. Namespaced material values, spaces, hyphens, and standard Bukkit material names are supported.

Examples:


Invalid material names are logged and ignored instead of crashing or preventing the plugin from enabling.

High-Performance Spatial Index

FlameStack is designed around incremental item tracking instead of repeated full-world searches.

Its lookup architecture uses:

• Concurrent world and chunk-section indexes
• Event-driven item registration
• One-tick deferred spawn registration for reliable entity lifecycle state
• Bounded item scan budgets
• Bounded candidate checks per item
• Exact squared-distance filtering
• Material and metadata similarity filtering
• Stale index cleanup
• Deduplicated work queues
• Deterministic merge reservations

The plugin does not perform a global entity sweep during every scan cycle.

Only tracked items and indexed sections relevant to the configured radius are considered.

Safe Merge Transactions

Merging two live entities can conflict with other server actions such as:

• Player pickup
• Hopper pickup
• Vanilla item merging
• Chunk unloading
• Item despawning
• Concurrent FlameStack scans

FlameStack uses temporary merge reservations to prevent the same item from participating in multiple transfers at once.

During a reserved transfer:

• The donor and target are protected from duplicate merge attempts.
• Player and inventory pickup events are blocked only for the reserved entities.
• Both live item stacks are validated again before mutation.
• Material, metadata, distance, trigger, and capacity are checked again.
• The target is updated before the donor is finalized.
• Failed donor finalization causes the target quantity to be rolled back.
• Timed-out reservations are released automatically.

This keeps the item index and represented quantity consistent during concurrent gameplay activity.

Real Folia Support

FlameStack declares and implements Folia support.


Folia support is not limited to adding the descriptor flag.

The plugin detects scheduler capabilities at runtime and routes item entity reads and mutations through the owning entity scheduler on Folia.

On Bukkit, Spigot, and standard Paper servers, entity work falls back to the normal Bukkit scheduler.

The asynchronous coordinator only handles thread-safe structures such as:

• UUIDs
• Immutable item snapshots
• Concurrent maps
• Concurrent sets
• Bounded queues
• Primitive coordinates

Live Bukkit entity mutation remains on the correct scheduler context.

Adventure and MiniMessage

FlameStack uses Adventure and MiniMessage for configurable messages and formatting.

Supported formatting includes:

• Named colors
• Hex colors
• Gradients
• Bold, italic, underline, and other decorations
• Safe unparsed placeholders
• Configurable prefixes
• Configurable help and statistics output
• Configurable floating stack labels

Adventure dependencies are shaded and relocated into FlameStack, so no separate Adventure plugin dependency is required.

Runtime Debugging

FlameStack includes bounded internal diagnostics for server owners who need to understand why an item was not registered, located, reserved, or merged.

Debugging is disabled by default:


When enabled, FlameStack reports structured stages and reasons such as:


Repeated lookup messages are throttled per item to avoid uncontrolled console spam.

Debug output can be enabled, reloaded, used for diagnosis, and disabled again without restarting the server.

Runtime Statistics

The statistics command exposes current internal state:

• Detected platform
• Number of tracked item entities
• Number of indexed chunk sections
• Number of active merge reservations

This allows administrators to confirm that item registration and indexed lookup are working without exposing implementation internals to players.

Commands


/flamestack help

Shows the configured FlameStack command help.

/flamestack reload

Reloads configuration, material filters, trigger behavior, display formatting, debug state, and scan settings.

/flamestack stats

Shows the detected platform, tracked item count, indexed section count, and active reservation count.

Permissions


flamestack.admin

Master administrative permission. Includes reload and statistics access.

flamestack.reload

Allows /flamestack reload.

flamestack.stats

Allows /flamestack stats.

All administrative permissions default to server operators.

Installation

1. Download FlameStack.
2. Place the jar inside your server's plugins folder.
3. Start the server once to generate config.yml.
4. Edit the stacking, material, trigger, display, and message settings.
5. Use /flamestack reload to apply configuration changes.

FlameStack has no required plugin dependencies.

Compatibility


FlameStack uses capability detection for Folia scheduling rather than relying on server version strings.

Default Configuration



Frequently Asked Questions

Does FlameStack rename every dropped item?

No. With the default trigger settings, the floating display only appears after the logical amount becomes greater than that material's normal Minecraft stack limit.

Will two half-stacks always be merged?

Not when vanilla-aware triggering is enabled. Stone 32 + 32 remains at the vanilla limit of 64. Stone 32 + 33 exceeds the limit and becomes eligible.

Can I prevent specific materials from stacking?

Yes. Use blacklist mode and add those materials to allow_list.contents.

Can I allow only selected materials?

Yes. Change allow_list.mode to whitelist.

What happens if I enter an invalid material?

The material is logged and ignored. It does not crash the plugin.

Can I change the maximum logical stack size?

Yes. Change stacking.max-stack-size. The default is 2304.

Can I change the merge distance?

Yes. Change stacking.merge-radius. The default is 8 blocks.

Does FlameStack support custom item names?

Yes. When the item has its own display name, FlameStack uses its plain item name in the floating amount label without replacing the item's metadata.

Does FlameStack support Folia?

Yes. FlameStack declares Folia support and uses capability-detected entity scheduler execution for item entity operations.

Does it require PlaceholderAPI, ProtocolLib, PacketEvents, or another plugin?

No. FlameStack has no required plugin dependencies.

How can I diagnose an item that does not merge?

Set debug: true, run /flamestack reload, reproduce the issue, and review the structured TRACK, LOOKUP, RESERVATION, TRANSFER, and MERGE messages.

What Makes FlameStack Valuable

FlameStack is not a cosmetic rename utility and not a simple repeating nearby-entity loop.

It is a focused Minecraft ground item stacking system with:

• Vanilla-aware minimum stacking thresholds
• Large configurable logical stacks
• Chunk-section spatial indexing
• Bounded lookup work
• Blacklist and whitelist material control
• MiniMessage displays and messages
• Structured debugging
• Live runtime statistics
• Concurrent merge reservations
• Bukkit, Spigot, Paper, and Folia support

For SMP servers, survival networks, economy servers, farms, grinders, and other environments where large quantities of dropped items can create unnecessary entity load, FlameStack provides a controlled and configurable way to consolidate those items without abandoning normal Minecraft behavior.