### Gradle Dependency Setup for RoseStacker

Source: https://github.com/rosewood-development/rosestacker/wiki/API-Getting-Started

This snippet shows how to add the RoseStacker dependency to your project using Gradle. Ensure you replace `$VERSION$` with the correct plugin version. This setup is crucial for accessing the RoseStacker API.

```groovy
repositories {
    maven {
        url = 'https://repo.rosewooddev.io/repository/public/'
    }
}

dependencies {
    compile 'dev.rosewood:rosestacker:$VERSION$'
}
```

--------------------------------

### Getting RoseStacker API Instance in Java

Source: https://github.com/rosewood-development/rosestacker/wiki/API-Getting-Started

This Java code snippet shows how to obtain an instance of the RoseStackerAPI within your Bukkit/Spigot plugin. It checks if the RoseStacker plugin is enabled before attempting to get the instance. This is the primary method for interacting with the RoseStacker plugin's functionalities.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;

public class Example extends JavaPlugin {
    private RoseStackerAPI rsAPI;

    @Override
    public void onEnable() {
        if (Bukkit.getPluginManager().isPluginEnabled("RoseStacker")) {
            this.rsAPI = RoseStackerAPI.getInstance();
        }

        // When you want to access the API, check if the instance is null
        if (this.rsAPI != null) {
            // Do stuff with the API here
        }
    }
}
```

--------------------------------

### RoseStackerAPI Singleton Access

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Get the main API instance to interact with all stacking functionality. This is the entry point for using the RoseStacker API.

```APIDOC
## RoseStackerAPI Singleton Access

### Description
Get the main API instance to interact with all stacking functionality.

### Method
`RoseStackerAPI.getInstance()`

### Endpoint
N/A (Java API Method)

### Parameters
None

### Request Example
```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;

RoseStackerAPI api = RoseStackerAPI.getInstance();
```

### Response
#### Success Response (200)
- **RoseStackerAPI** - The singleton instance of the RoseStackerAPI.

#### Response Example
```java
// Java code example demonstrating usage
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.Zombie;

public class ExamplePlugin {
    public void checkEntityStack(LivingEntity entity) {
        RoseStackerAPI api = RoseStackerAPI.getInstance();

        // Check if entity is stacked
        if (api.isEntityStacked(entity)) {
            // StackedEntity stack = api.getStackedEntity(entity);
            System.out.println("Entity is stacked");
        } else {
            System.out.println("Entity is not stacked");
        }
    }
}
```
```

--------------------------------

### Maven Dependency Setup for RoseStacker

Source: https://github.com/rosewood-development/rosestacker/wiki/API-Getting-Started

This snippet demonstrates how to include the RoseStacker dependency in your project using Maven. Replace `$VERSION$` with the applicable plugin version. This configuration enables your project to utilize the RoseStacker API.

```xml
<repositories>
    <repository>
        <id>rosewood-repo</id>
        <url>https://repo.rosewooddev.io/repository/public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>dev.rosewood</groupId>
        <artifactId>rosestacker</artifactId>
        <version>$VERSION$</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

--------------------------------

### Get Item Stack Settings (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves and displays the stacking configuration settings for a specific item type, like diamonds. It uses the RoseStackerAPI to get the ItemStackSettings and prints information regarding stacking enablement, maximum stack size, display name, and merge radius.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.settings.ItemStackSettings;
import org.bukkit.Material;

public void getItemSettings() {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    ItemStackSettings diamondSettings = api.getItemStackSettings(Material.DIAMOND);

    System.out.println("Diamond stacking enabled: " + diamondSettings.isStackingEnabled());
    System.out.println("Max stack size: " + diamondSettings.getMaxStackSize());
    System.out.println("Display name: " + diamondSettings.getDisplayName());
    System.out.println("Merge radius: " + diamondSettings.getMergeRadius());
}
```

--------------------------------

### Get Stacking Thread for World - Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves the StackingThread instance responsible for managing stacks within a specific Minecraft world. This method uses the RoseStackerAPI to get the thread and then prints information about the number of stacked entities, items, blocks, and spawners managed by that thread. Dependencies include dev.rosewood.rosestacker.api.RoseStackerAPI, dev.rosewood.rosestacker.stack.StackingThread, and Bukkit's World class.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackingThread;
import org.bukkit.World;

public void getWorldStackingThread(World world) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    StackingThread thread = api.getStackingThread(world);

    if (thread != null) {
        System.out.println("World " + world.getName() + " has stacking thread");
        System.out.println("Entity stacks: " + thread.getStackedEntities().size());
        System.out.println("Item stacks: " + thread.getStackedItems().size());
        System.out.println("Block stacks: " + thread.getStackedBlocks().size());
        System.out.println("Spawner stacks: " + thread.getStackedSpawners().size());
    }
}
```

--------------------------------

### Get Spawner Stack Settings in Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves configuration settings for a specific spawner type using the RoseStackerAPI. It takes an EntityType as input and returns SpawnerStackSettings, which include details like stacking status, max stack size, display name, and spawn count multiplier. Requires the RoseStackerAPI and Bukkit API.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.settings.SpawnerStackSettings;
import org.bukkit.entity.EntityType;

public void getSpawnerSettings() {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    SpawnerStackSettings settings = api.getSpawnerStackSettings(EntityType.ZOMBIE);

    if (settings != null) {
        System.out.println("Zombie spawner stacking enabled: " + settings.isStackingEnabled());
        System.out.println("Max stack size: " + settings.getMaxStackSize());
        System.out.println("Display name: " + settings.getDisplayName());
        System.out.println("Spawn count multiplier: " + settings.getSpawnCountStackSizeMultiplier());
    }
}
```

--------------------------------

### Get All Stacked Entities

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieve all currently loaded entity stacks across all worlds. This can be useful for monitoring or mass operations.

```APIDOC
## Get All Stacked Entities

### Description
Retrieve all currently loaded entity stacks across all worlds.

### Method
`RoseStackerAPI.getStackedEntities()`

### Endpoint
N/A (Java API Method)

### Parameters
None

### Request Example
```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import java.util.Map;

RoseStackerAPI api = RoseStackerAPI.getInstance();
Map<?, ?> allStacks = api.getStackedEntities();
```

### Response
#### Success Response (200)
- **Map&lt;UUID, StackedEntity&gt;** - A map where keys are the UUIDs of the representative entity in the stack, and values are the `StackedEntity` objects.

#### Response Example
```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedEntity;
import java.util.Map;
import java.util.UUID;

public void getAllEntityStacks() {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    Map<UUID, StackedEntity> allStacks = api.getStackedEntities();

    for (Map.Entry<UUID, StackedEntity> entry : allStacks.entrySet()) {
        StackedEntity stack = entry.getValue();
        System.out.println("Entity: " + stack.getEntity().getType() +
                         " at " + stack.getLocation() +
                         " - Size: " + stack.getStackSize());
    }

    System.out.println("Total entity stacks: " + allStacks.size());
}
```
```

--------------------------------

### Get Block Stack Settings (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves and displays the stacking configuration settings for a specific block type, such as sponges. It fetches the BlockStackSettings using the RoseStackerAPI and checks if stacking is enabled, the maximum stack size, and the display name. It also handles cases where the block type is not stackable.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.settings.BlockStackSettings;
import org.bukkit.Material;

public void getBlockSettings() {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    BlockStackSettings spongeSettings = api.getBlockStackSettings(Material.SPONGE);

    if (spongeSettings != null) {
        System.out.println("Sponge stacking enabled: " + spongeSettings.isStackingEnabled());
        System.out.println("Max stack size: " + spongeSettings.getMaxStackSize());
        System.out.println("Display name: " + spongeSettings.getDisplayName());
    } else {
        System.out.println("Sponge blocks are not stackable");
    }
}
```

--------------------------------

### Get Entity Stack Settings (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves and displays the stacking configuration settings for a specific entity type, such as zombies. It accesses the EntityStackSettings object via the RoseStackerAPI and prints properties like stacking enablement, maximum stack size, display name, and whether the entire stack is killed on death.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.settings.EntityStackSettings;
import org.bukkit.entity.EntityType;

public void getEntitySettings() {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    EntityStackSettings zombieSettings = api.getEntityStackSettings(EntityType.ZOMBIE);

    System.out.println("Zombie stacking enabled: " + zombieSettings.isStackingEnabled());
    System.out.println("Max stack size: " + zombieSettings.getMaxStackSize());
    System.out.println("Display name: " + zombieSettings.getDisplayName());
    System.out.println("Kill entire stack on death: " + zombieSettings.shouldKillEntireStackOnDeath());
}
```

--------------------------------

### Get All Stacked Items

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves a map of all currently loaded item stacks. The keys are UUIDs and the values are StackedItem objects. This function iterates through the stacks and prints their type, size, and location.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedItem;
import java.util.Map;
import java.util.UUID;

public void listAllItemStacks() {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    Map<UUID, StackedItem> allItems = api.getStackedItems();

    for (Map.Entry<UUID, StackedItem> entry : allItems.entrySet()) {
        StackedItem stack = entry.getValue();
        System.out.println("Item: " + stack.getItem().getItemStack().getType() +
                         " - Size: " + stack.getStackSize() +
                         " at " + stack.getLocation());
    }
}
```

--------------------------------

### Listen to Block Stack Event - Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Handles the BlockStackEvent triggered when blocks are stacked together. This listener allows access to the stacked block's details, including its type and new size, as well as the amount by which it was increased. It also provides an example of how to cancel the event. Dependencies include dev.rosewood.rosestacker.event.BlockStackEvent and Bukkit's event handling classes.

```java
import dev.rosewood.rosestacker.event.BlockStackEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class BlockStackListener implements Listener {

    @EventHandler
    public void onBlockStack(BlockStackEvent event) {
        System.out.println("Block stacked!");
        System.out.println("Block: " + event.getStack().getBlock().getType());
        System.out.println("New size: " + event.getStack().getStackSize());
        System.out.println("Increase amount: " + event.getIncreaseAmount());

        // Cancel if needed
        // event.setCancelled(true);
    }
}
```

--------------------------------

### Get Stacked Entity from Living Entity

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Check if a specific living entity is part of a stack and retrieve its stack data. Returns null if the entity is not stacked.

```APIDOC
## Get Stacked Entity from Living Entity

### Description
Check if a specific living entity is part of a stack and retrieve its stack data. Returns null if the entity is not stacked.

### Method
`RoseStackerAPI.getStackedEntity(LivingEntity)`

### Endpoint
N/A (Java API Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **entity** (LivingEntity) - Required - The entity to check.

### Request Example
```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.Player;

RoseStackerAPI api = RoseStackerAPI.getInstance();
StackedEntity stack = api.getStackedEntity(someLivingEntity);
```

### Response
#### Success Response (200)
- **StackedEntity** - The `StackedEntity` object if the entity is part of a stack, otherwise null.

#### Response Example
```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedEntity;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.Player;

public void handleEntityInteraction(Player player, LivingEntity entity) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    StackedEntity stack = api.getStackedEntity(entity);

    if (stack != null) {
        player.sendMessage("This is a stack of " + stack.getStackSize() + " entities!");
        player.sendMessage("Entity type: " + stack.getEntity().getType());
        player.sendMessage("Stack location: " + stack.getLocation());
    } else {
        player.sendMessage("This entity is not stacked");
    }
}
```
```

--------------------------------

### Check and Get Stacked Block (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Checks if a given block is part of a stack and retrieves its StackedBlock information. If stacked, it sends messages to the player indicating the stack size and block type. This function depends on the RoseStackerAPI and takes a Player and Block as input.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedBlock;
import org.bukkit.block.Block;
import org.bukkit.entity.Player;

public void checkBlockStack(Player player, Block block) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    if (api.isBlockStacked(block)) {
        StackedBlock stackedBlock = api.getStackedBlock(block);
        player.sendMessage("This block has a stack of " + stackedBlock.getStackSize());
        player.sendMessage("Block type: " + stackedBlock.getBlock().getType());
    } else {
        player.sendMessage("This block is not stacked");
    }
}
```

--------------------------------

### Check and Get Stacked Spawner (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Checks if a given block is a spawner and if it's part of a stack, then retrieves its StackedSpawner information. If stacked, it sends messages to the player detailing the stack size and spawn type. This function depends on the RoseStackerAPI and takes a Player and Block as input.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedSpawner;
import org.bukkit.Material;
import org.bukkit.block.Block;
import org.bukkit.entity.Player;

public void checkSpawnerStack(Player player, Block block) {
    if (block.getType() != Material.SPAWNER) {
        player.sendMessage("This is not a spawner");
        return;
    }

    RoseStackerAPI api = RoseStackerAPI.getInstance();

    if (api.isSpawnerStacked(block)) {
        StackedSpawner spawner = api.getStackedSpawner(block);
        player.sendMessage("Spawner stack size: " + spawner.getStackSize());
        player.sendMessage("Spawns: " + spawner.getSpawner().getSpawnedType());
    } else {
        player.sendMessage("This spawner is not stacked");
    }
}
```

--------------------------------

### Get Stacks in Specific Chunks (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves all stacked entities and items within a specified collection of chunks. This function is useful for analyzing the contents of specific areas of the world. It iterates through the retrieved stacks and prints their types and sizes.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedEntity;
import dev.rosewood.rosestacker.stack.StackedItem;
import org.bukkit.Chunk;
import java.util.Collection;
import java.util.Collections;
import java.util.List;

public void getStacksInChunk(Chunk chunk) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    Collection<Chunk> chunks = Collections.singleton(chunk);

    List<StackedEntity> entities = api.getStackedEntities(chunks);
    List<StackedItem> items = api.getStackedItems(chunks);

    System.out.println("Chunk contains " + entities.size() + " entity stacks");
    System.out.println("Chunk contains " + items.size() + " item stacks");

    for (StackedEntity entity : entities) {
        System.out.println("  - " + entity.getEntity().getType() +
                         " x" + entity.getStackSize());
    }
}
```

--------------------------------

### Get Stacked Entity Data from Living Entity

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Checks if a specific LivingEntity is part of a stack and retrieves its StackedEntity data. If the entity is not stacked, it returns null. This method is crucial for interacting with individual entities that are part of a stack.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedEntity;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.Player;

public void handleEntityInteraction(Player player, LivingEntity entity) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    StackedEntity stack = api.getStackedEntity(entity);

    if (stack != null) {
        player.sendMessage("This is a stack of " + stack.getStackSize() + " entities!");
        player.sendMessage("Entity type: " + stack.getEntity().getType());
        player.sendMessage("Stack location: " + stack.getLocation());
    } else {
        player.sendMessage("This entity is not stacked");
    }
}
```

--------------------------------

### Get Stacked Item

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Checks if a given dropped item entity is part of a stack. It takes a Bukkit Item entity as input and returns a StackedItem object if it's part of a stack, otherwise null. The output includes stack size, item type, and age.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedItem;
import org.bukkit.entity.Item;

public void checkItemStack(Item item) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    StackedItem stackedItem = api.getStackedItem(item);

    if (stackedItem != null) {
        System.out.println("Item stack size: " + stackedItem.getStackSize());
        System.out.println("Item type: " + stackedItem.getItem().getItemStack().getType());
        System.out.println("Age: " + stackedItem.getAge() + " ticks");
    }
}
```

--------------------------------

### Compile RoseStacker Plugin using Gradle

Source: https://github.com/rosewood-development/rosestacker/wiki/Home

This snippet shows the command to compile the RoseStacker plugin from its source code using Gradle. It requires the Gradle wrapper to be present in the project's root directory. The output is a JAR file located in the build directory.

```bash
./gradlew build
```

--------------------------------

### Pre-Stack Entities for Efficient Spawning

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Spawn multiple entities as a pre-stacked group for optimal performance. This method handles the creation and stacking internally.

```APIDOC
## Pre-Stack Entities for Efficient Spawning

### Description
Spawn multiple entities as a pre-stacked group for optimal performance. This method handles the creation and stacking internally.

### Method
`RoseStackerAPI.preStackEntities(EntityType, int, Location, SpawnReason)` or `RoseStackerAPI.preStackEntities(EntityType, int, Location)`

### Endpoint
N/A (Java API Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **entityType** (EntityType) - Required - The type of entity to spawn.
- **amount** (int) - Required - The number of entities to spawn in the stack.
- **location** (Location) - Required - The location where the entities will be spawned.
- **spawnReason** (SpawnReason) - Optional - The reason for spawning the entity (e.g., CUSTOM, NATURAL).

### Request Example
```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import org.bukkit.Location;
import org.bukkit.entity.EntityType;
import org.bukkit.event.entity.CreatureSpawnEvent.SpawnReason;

RoseStackerAPI api = RoseStackerAPI.getInstance();
Location loc = new Location(world, x, y, z);
api.preStackEntities(EntityType.ZOMBIE, 50, loc, SpawnReason.CUSTOM);
```

### Response
#### Success Response (200)
This method does not return a value, but it spawns the stacked entities.

#### Response Example
```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import org.bukkit.Location;
import org.bukkit.entity.EntityType;
import org.bukkit.event.entity.CreatureSpawnEvent.SpawnReason;

public void spawnStackedMobs(Location location) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    // Spawn 50 zombies as a single stacked entity
    api.preStackEntities(EntityType.ZOMBIE, 50, location, SpawnReason.CUSTOM);

    // Spawn 100 cows at location
    api.preStackEntities(EntityType.COW, 100, location);

    System.out.println("Spawned stacked entities at " + location);
}
```
```

--------------------------------

### Access RoseStackerAPI Singleton Instance

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves the main RoseStackerAPI instance to interact with all stacking functionalities. This is the primary entry point for programmatic access to the plugin's features. It does not require any specific inputs and returns the API instance.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.Zombie;

public class ExamplePlugin {
    public void checkEntityStack(LivingEntity entity) {
        RoseStackerAPI api = RoseStackerAPI.getInstance();

        // Check if entity is stacked
        if (api.isEntityStacked(entity)) {
            StackedEntity stack = api.getStackedEntity(entity);
            System.out.println("Entity stack size: " + stack.getStackSize());
        } else {
            System.out.println("Entity is not stacked");
        }
    }
}
```

--------------------------------

### Pre-Stack Entities for Efficient Spawning

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Spawns multiple entities as a pre-stacked group for optimal performance. This method allows specifying the entity type, quantity, location, and optionally the spawn reason. It's an efficient way to populate worlds with stacked entities.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import org.bukkit.Location;
import org.bukkit.entity.EntityType;
import org.bukkit.event.entity.CreatureSpawnEvent.SpawnReason;

public void spawnStackedMobs(Location location) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    // Spawn 50 zombies as a single stacked entity
    api.preStackEntities(EntityType.ZOMBIE, 50, location, SpawnReason.CUSTOM);

    // Spawn 100 cows at location
    api.preStackEntities(EntityType.COW, 100, location);

    System.out.println("Spawned stacked entities at " + location);
}
```

--------------------------------

### Create Entity Stack

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Programmatically create an entity stack from a living entity. The `tryStack` parameter determines if it should attempt to merge with nearby stacks.

```APIDOC
## Create Entity Stack

### Description
Programmatically create an entity stack from a living entity. The `tryStack` parameter determines if it should attempt to merge with nearby stacks.

### Method
`RoseStackerAPI.createEntityStack(LivingEntity, boolean)`

### Endpoint
N/A (Java API Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **entity** (LivingEntity) - Required - The entity to stack.
- **tryStack** (boolean) - Required - If true, attempts to merge with nearby stacks.

### Request Example
```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import org.bukkit.World;
import org.bukkit.Location;
import org.bukkit.entity.Zombie;

RoseStackerAPI api = RoseStackerAPI.getInstance();
StackedEntity stack = api.createEntityStack(someZombieEntity, true);
```

### Response
#### Success Response (200)
- **StackedEntity** - The created or merged `StackedEntity` object, or null if stacking failed.

#### Response Example
```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedEntity;
import org.bukkit.Location;
import org.bukkit.World;
import org.bukkit.entity.EntityType;
import org.bukkit.entity.Zombie;

public void createZombieStack(World world, Location location) {
    // Spawn a zombie
    Zombie zombie = (Zombie) world.spawnEntity(location, EntityType.ZOMBIE);

    RoseStackerAPI api = RoseStackerAPI.getInstance();

    // Create a stack from the entity (tryStack=true will attempt to merge with nearby stacks)
    StackedEntity stack = api.createEntityStack(zombie, true);

    if (stack != null) {
        System.out.println("Created entity stack with size: " + stack.getStackSize());
    } else {
        System.out.println("Failed to create entity stack - stacking may be disabled");
    }
}
```
```

--------------------------------

### List All Spawner Stacks (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves and lists all currently loaded spawner stacks using the RoseStackerAPI. It iterates through a map of blocks to StackedSpawner objects, printing details like location, stack size, and the type of mob being spawned. This requires the RoseStackerAPI instance.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedSpawner;
import org.bukkit.block.Block;
import java.util.Map;

public void listAllSpawnerStacks() {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    Map<Block, StackedSpawner> allSpawners = api.getStackedSpawners();

    for (Map.Entry<Block, StackedSpawner> entry : allSpawners.entrySet()) {
        StackedSpawner stack = entry.getValue();
        System.out.println("Spawner at " + stack.getLocation() +
                         " - Size: " + stack.getStackSize() +
                         " - Type: " + stack.getSpawner().getSpawnedType());
    }
}
```

--------------------------------

### Pre-Stack and Drop Items

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Drops multiple items at a specified location as a pre-stacked collection. It accepts a Collection of ItemStacks and a Location. The API function `preStackItems` handles the consolidation of these items into stacks upon dropping.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import org.bukkit.Location;
import org.bukkit.Material;
import org.bukkit.inventory.ItemStack;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;

public void dropStackedItems(Location location) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    Collection<ItemStack> items = new ArrayList<>();
    items.add(new ItemStack(Material.DIAMOND, 64));
    items.add(new ItemStack(Material.DIAMOND, 64));
    items.add(new ItemStack(Material.GOLD_INGOT, 32));

    // Drop items as stacks
    api.preStackItems(items, location);

    System.out.println("Dropped pre-stacked items at " + location);
}
```

--------------------------------

### Create Item Stack

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Programmatically creates a stacked item in the world. It takes a World and Location as input. The function first drops a base item and then uses the API to create a stacked item, optionally merging with nearby items.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedItem;
import org.bukkit.Location;
import org.bukkit.Material;
import org.bukkit.World;
import org.bukkit.entity.Item;
import org.bukkit.inventory.ItemStack;

public void createItemStack(World world, Location location) {
    // Drop an item
    ItemStack itemStack = new ItemStack(Material.DIAMOND, 1);
    Item item = world.dropItem(location, itemStack);

    RoseStackerAPI api = RoseStackerAPI.getInstance();

    // Create a stacked item (tryStack=true will merge with nearby items)
    StackedItem stackedItem = api.createItemStack(item, true);

    if (stackedItem != null) {
        System.out.println("Created item stack with size: " + stackedItem.getStackSize());
    }
}
```

--------------------------------

### Create Block Stack (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Programmatically creates a block stack for a given block if it's of a stackable type (e.g., SPONGE). It attempts to create a stack of a specified size and reports success or failure. This method requires the RoseStackerAPI and a Block object.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedBlock;
import org.bukkit.Material;
import org.bukkit.block.Block;

public void createBlockStack(Block block) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    // Ensure block is the correct type
    if (block.getType() == Material.SPONGE) {
        int stackSize = 100;
        StackedBlock stackedBlock = api.createBlockStack(block, stackSize);

        if (stackedBlock != null) {
            System.out.println("Created block stack of size " + stackedBlock.getStackSize());
        } else {
            System.out.println("Failed to create block stack - may not be stackable");
        }
    }
}
```

--------------------------------

### List All Block Stacks (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Retrieves and lists all currently loaded block stacks using the RoseStackerAPI. It iterates through a map of blocks to StackedBlock objects, printing details like block type, location, and stack size. This method requires the RoseStackerAPI instance and provides a count of total stacks.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedBlock;
import org.bukkit.block.Block;
import java.util.Map;

public void listAllBlockStacks() {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    Map<Block, StackedBlock> allBlocks = api.getStackedBlocks();

    for (Map.Entry<Block, StackedBlock> entry : allBlocks.entrySet()) {
        StackedBlock stack = entry.getValue();
        System.out.println("Block: " + stack.getBlock().getType() +
                         " at " + stack.getLocation() +
                         " - Size: " + stack.getStackSize());
    }

    System.out.println("Total block stacks: " + allBlocks.size());
}
```

--------------------------------

### Listen to Spawner Stack Event - Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Handles the SpawnerStackEvent which occurs when spawners are stacked. This listener allows inspection of the target and added spawner stack sizes, the entity type being spawned, and optionally, the player who performed the stacking. Dependencies include dev.rosewood.rosestacker.event.SpawnerStackEvent and Bukkit's event handling classes.

```java
import dev.rosewood.rosestacker.event.SpawnerStackEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class SpawnerStackListener implements Listener {

    @EventHandler
    public void onSpawnerStack(SpawnerStackEvent event) {
        System.out.println("Spawner stacked!");
        System.out.println("Target spawner size: " + event.getTarget().getStackSize());
        System.out.println("Added spawner size: " + event.getStack().getStackSize());
        System.out.println("Entity type: " + event.getTarget().getSpawner().getSpawnedType());

        if (event.getPlayer() != null) {
            System.out.println("Stacked by player: " + event.getPlayer().getName());
        }
    }
}
```

--------------------------------

### Create Entity Stack Programmatically

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Creates a new entity stack from a given LivingEntity. The `tryStack` parameter determines if the new stack should attempt to merge with nearby existing stacks. This method returns the created StackedEntity or null if stacking fails.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedEntity;
import org.bukkit.Location;
import org.bukkit.World;
import org.bukkit.entity.EntityType;
import org.bukkit.entity.Zombie;

public void createZombieStack(World world, Location location) {
    // Spawn a zombie
    Zombie zombie = (Zombie) world.spawnEntity(location, EntityType.ZOMBIE);

    RoseStackerAPI api = RoseStackerAPI.getInstance();

    // Create a stack from the entity (tryStack=true will attempt to merge with nearby stacks)
    StackedEntity stack = api.createEntityStack(zombie, true);

    if (stack != null) {
        System.out.println("Created entity stack with size: " + stack.getStackSize());
    } else {
        System.out.println("Failed to create entity stack - stacking may be disabled");
    }
}
```

--------------------------------

### Create Spawner Stack (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Programmatically creates a stacked spawner at a given block location. It checks if the block is a spawner and utilizes the RoseStackerAPI to establish the stack. The function returns the created StackedSpawner object or null if creation fails.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedSpawner;
import org.bukkit.Material;
import org.bukkit.block.Block;

public void createSpawnerStack(Block block) {
    if (block.getType() != Material.SPAWNER) {
        return;
    }

    RoseStackerAPI api = RoseStackerAPI.getInstance();

    int stackSize = 5;
    boolean placedByPlayer = true;

    StackedSpawner spawner = api.createSpawnerStack(block, stackSize, placedByPlayer);

    if (spawner != null) {
        System.out.println("Created spawner stack of size " + spawner.getStackSize());
    } else {
        System.out.println("Failed to create spawner stack");
    }
}
```

--------------------------------

### Listen to Item Stack Event - Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Handles the ItemStackEvent which is triggered when two item stacks merge. This listener demonstrates how to access information about the target and merging stacks, their sizes, and item types. It also shows how to cancel the stacking event if a condition, like exceeding a maximum stack size, is met. Dependencies include dev.rosewood.rosestacker.event.ItemStackEvent and Bukkit's event handling classes.

```java
import dev.rosewood.rosestacker.event.ItemStackEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class ItemStackListener implements Listener {

    @EventHandler
    public void onItemStack(ItemStackEvent event) {
        System.out.println("Items stacked!");
        System.out.println("Target stack: " + event.getTarget().getStackSize());
        System.out.println("Merging stack: " + event.getStack().getStackSize());
        System.out.println("Item type: " + event.getTarget().getItem().getItemStack().getType());

        // Cancel stacking if total would exceed a threshold
        int total = event.getTarget().getStackSize() + event.getStack().getStackSize();
        if (total > 1000) {
            event.setCancelled(true);
        }
    }
}
```

--------------------------------

### Retrieve All Stacked Entities

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Fetches all currently loaded entity stacks across all worlds managed by RoseStacker. It returns a map where keys are UUIDs and values are StackedEntity objects. This is useful for iterating through and inspecting all stacked entities on the server.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedEntity;
import java.util.Map;
import java.util.UUID;

public void getAllEntityStacks() {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    Map<UUID, StackedEntity> allStacks = api.getStackedEntities();

    for (Map.Entry<UUID, StackedEntity> entry : allStacks.entrySet()) {
        StackedEntity stack = entry.getValue();
        System.out.println("Entity: " + stack.getEntity().getType() +
                         " at " + stack.getLocation() +
                         " - Size: " + stack.getStackSize());
    }

    System.out.println("Total entity stacks: " + allStacks.size());
}
```

--------------------------------

### Listen to Entity Multiple Death Event in Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Handles the event when multiple entities within a stack die simultaneously. This Java code provides access to the original stack size, the number of entities killed, and the killer's information. It also allows you to retrieve and process the loot drops from the mass death. Requires Bukkit API.

```java
import dev.rosewood.rosestacker.event.EntityStackMultipleDeathEvent;
import dev.rosewood.rosestacker.event.EntityStackMultipleDeathEvent.EntityDrops;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.inventory.ItemStack;

public class DeathListener implements Listener {

    @EventHandler
    public void onMultipleDeath(EntityStackMultipleDeathEvent event) {
        System.out.println("Multiple entities died!");
        System.out.println("Original stack size: " + event.getOriginalStackSize());
        System.out.println("Entities killed: " + event.getEntityKillCount());
        System.out.println("Stack: " + event.getStack().getEntity().getType());

        if (event.getKiller() != null) {
            System.out.println("Killed by: " + event.getKiller().getName());
        }

        // Access the drops
        EntityDrops drops = event.getDrops();
        System.out.println("Experience: " + drops.getExperience());

        for (ItemStack item : drops.getDrops()) {
            System.out.println("Drop: " + item.getType() + " x" + item.getAmount());
        }
    }
}
```

--------------------------------

### Listen to Entity Stack Event in Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Handles the event that is triggered when two entity stacks merge together. This Java listener class allows you to react to stacking events, inspect the stacks involved, and optionally cancel the stacking process based on custom conditions. It requires Bukkit API.

```java
import dev.rosewood.rosestacker.event.EntityStackEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class StackListener implements Listener {

    @EventHandler
    public void onEntityStack(EntityStackEvent event) {
        System.out.println("Entity stacked!");
        System.out.println("Target stack size: " + event.getTarget().getStackSize());
        System.out.println("Stack being merged size: " + event.getStack().getStackSize());

        // Cancel stacking if needed
        if (event.getTarget().getStackSize() > 100) {
            event.setCancelled(true);
        }
    }
}
```

--------------------------------

### Manipulate Stack Size Directly - Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Demonstrates how to directly modify the stack sizes of existing stacked entities, items, and blocks. This includes methods to increase stack size by a specified amount (optionally updating the display) and decrease the stack size by one. It also shows how to set an item stack's size to a specific value. Dependencies include dev.rosewood.rosestacker.stack.StackedEntity, dev.rosewood.rosestacker.stack.StackedItem, and dev.rosewood.rosestacker.stack.StackedBlock.

```java
import dev.rosewood.rosestacker.stack.StackedEntity;
import dev.rosewood.rosestacker.stack.StackedItem;
import dev.rosewood.rosestacker.stack.StackedBlock;

public void modifyStackSizes(StackedEntity entity, StackedItem item, StackedBlock block) {
    // Increase entity stack
    entity.increaseStackSize(10, true); // Add 10 entities, update display
    System.out.println("Entity stack now: " + entity.getStackSize());

    // Decrease entity stack (removes one entity)
    StackedEntity removed = entity.decreaseStackSize();
    System.out.println("Removed entity stack of size: " + removed.getStackSize());

    // Set item stack size directly
    item.setStackSize(500);
    System.out.println("Item stack now: " + item.getStackSize());

    // Increase block stack
    block.increaseStackSize(25);
    System.out.println("Block stack now: " + block.getStackSize());
}
```

--------------------------------

### Calculate Entity Loot Drops in Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Calculates loot and experience for a stacked entity's death. This Java code uses the RoseStackerAPI to determine drops for an entire stack or a partial count, considering if the drops should be randomized. It requires StackedEntity and Bukkit API.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.event.EntityStackMultipleDeathEvent.EntityDrops;
import dev.rosewood.rosestacker.stack.StackedEntity;
import org.bukkit.inventory.ItemStack;

public void calculateLoot(StackedEntity stackedEntity) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    // Get loot for entire stack
    EntityDrops drops = api.getStackedEntityLoot(stackedEntity);

    System.out.println("Total experience: " + drops.getExperience());
    System.out.println("Drops:");
    for (ItemStack item : drops.getDrops()) {
        System.out.println("  - " + item.getType() + " x" + item.getAmount());
    }

    // Get loot for specific count
    EntityDrops partialDrops = api.getStackedEntityLoot(stackedEntity, 10, true);
    System.out.println("Drops for 10 entities: " + partialDrops.getDrops().size() + " items");
}
```

--------------------------------

### Listen to Entity Unstack Event in Java

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Handles the event triggered when an entity is removed from a stack. This Java code allows you to monitor unstacking actions, access information about the original stack and the unstacked entity, and even cancel the unstacking operation if necessary. It requires Bukkit API.

```java
import dev.rosewood.rosestacker.event.EntityUnstackEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class UnstackListener implements Listener {

    @EventHandler
    public void onEntityUnstack(EntityUnstackEvent event) {
        System.out.println("Entity unstacked!");
        System.out.println("Original stack size: " + event.getStack().getStackSize());
        System.out.println("Unstacked entity: " + event.getUnstackedEntity().getType());

        // You can cancel the unstack
        // event.setCancelled(true);
    }
}
```

--------------------------------

### Drop Single Item Stack

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Drops a specified quantity of an item type as a single stacked item at a given location. This function takes an ItemStack, the desired amount, a Location, and a boolean `dropNaturally` to control spawning behavior. It returns the created StackedItem.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedItem;
import org.bukkit.Location;
import org.bukkit.Material;
import org.bukkit.inventory.ItemStack;

public void dropCustomStackedItem(Location location) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();

    ItemStack itemStack = new ItemStack(Material.EMERALD);
    int amount = 500; // Drop 500 emeralds as a single stack
    boolean dropNaturally = false;

    StackedItem stackedItem = api.dropItemStack(itemStack, amount, location, dropNaturally);

    if (stackedItem != null) {
        System.out.println("Dropped " + amount + " items as a stack");
    }
}
```

--------------------------------

### Remove Spawner Stack (Java)

Source: https://context7.com/rosewood-development/rosestacker/llms.txt

Removes a spawner stack from the world using the RoseStackerAPI. It first retrieves the StackedSpawner object associated with the given block and then proceeds to remove it. The method logs the size of the removed stack.

```java
import dev.rosewood.rosestacker.api.RoseStackerAPI;
import dev.rosewood.rosestacker.stack.StackedSpawner;
import org.bukkit.block.Block;

public void removeSpawnerStack(Block block) {
    RoseStackerAPI api = RoseStackerAPI.getInstance();
    StackedSpawner spawner = api.getStackedSpawner(block);

    if (spawner != null) {
        int size = spawner.getStackSize();
        api.removeSpawnerStack(spawner);
        System.out.println("Removed spawner stack of size " + size);
    }
}
```