SmartSpawner

https://docs.smartspawner.site/
Admin
SmartSpawner is a high-performance GUI-based spawner plugin for Minecraft servers that generates...
Tokens:29,904
Snippets:301
Trust Score:2.2
Update:4 months ago
Show doc for...
Tokens:
Raw
### Database Configuration Example

Source: https://docs.smartspawner.site/configuration

This snippet shows a comprehensive example of database configuration, including mode, server details, migration settings, and specific configurations for SQLite and SQL (MySQL/MariaDB) with connection pooling.

```yaml
database:
  mode: YAML
  server_name: "server1"
  sync_across_servers: false
  migrate_from_local: true
  database: "smartspawner"
  sqlite:
    file: "spawners.db"
  sql:
    host: "localhost"
    port: 3306
    username: "root"
    password: ""
    pool:
      maximum-size: 10
      minimum-idle: 2
      connection-timeout: 10000
      max-lifetime: 1800000
      idle-timeout: 600000
      keepalive-time: 30000
      leak-detection-threshold: 0
```

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

### Example Drop Calculations

Source: https://docs.smartspawner.site/item_spawners_settings

Provides concrete examples of how the base amount and mob range translate to actual item drops.

```text
Base amount 1-1 → Actual drops: 1-4 items
Base amount 2-3 → Actual drops: 2-12 items
Base amount 1-2 → Actual drops: 1-8 items
```

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

### Spawner Data Management Example

Source: https://docs.smartspawner.site/developer-api/api-examples

This example demonstrates how to get spawner data by location, display its information, and modify it using SpawnerDataModifier. It includes functionality to upgrade spawners and set their delay. Requires a Player as sender and a spawner at the targeted location.

```java
import github.nighter.smartspawner.api.SmartSpawnerAPI;
import github.nighter.smartspawner.api.data.SpawnerDataDTO;
import github.nighter.smartspawner.api.data.SpawnerDataModifier;
import org.bukkit.Location;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;


public class SpawnerCommand implements CommandExecutor {


    private final SmartSpawnerAPI api;


    public SpawnerCommand(SmartSpawnerAPI api) {
        this.api = api;
    }


    @Override
    public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
        if (!(sender instanceof Player)) {
            sender.sendMessage("Player only command!");
            return true;
        }


        Player player = (Player) sender;
        Location location = player.getTargetBlock(null, 5).getLocation();


        // Get spawner data
        SpawnerDataDTO spawnerData = api.getSpawnerByLocation(location);


        if (spawnerData == null) {
            player.sendMessage("§cNo spawner found at that location!");
            return true;
        }


        // Display spawner information
        player.sendMessage("§6=== Spawner Info ===");
        player.sendMessage("§eID: §f" + spawnerData.getSpawnerId());
        player.sendMessage("§eEntity: §f" + spawnerData.getEntityType());
        player.sendMessage("§eStack Size: §f" + spawnerData.getStackSize() +
                          " §7(read-only)");
        player.sendMessage("§eMax Stack: §f" + spawnerData.getMaxStackSize());
        player.sendMessage("§eBase Delay: §f" + spawnerData.getBaseSpawnerDelay() + " ticks");
        player.sendMessage("§eBase Min Mobs: §f" + spawnerData.getBaseMinMobs());
        player.sendMessage("§eBase Max Mobs: §f" + spawnerData.getBaseMaxMobs());
        player.sendMessage("§eBase Max Exp: §f" + spawnerData.getBaseMaxStoredExp());
        player.sendMessage("§eBase Storage Pages: §f" + spawnerData.getBaseMaxStoragePages());


        // Modify spawner using SpawnerDataModifier
        if (args.length > 0 && args[0].equalsIgnoreCase("upgrade")) {
            SpawnerDataModifier modifier = api.getSpawnerModifier(spawnerData.getSpawnerId());


            if (modifier != null) {
                // Upgrade spawner with method chaining
                modifier.setBaseMaxMobs(modifier.getBaseMaxMobs() + 2)
                        .setBaseMinMobs(modifier.getBaseMinMobs() + 1)
                        .setBaseMaxStoredExp(modifier.getBaseMaxStoredExp() + 500)
                        .setBaseMaxStoragePages(modifier.getBaseMaxStoragePages() + 1)
                        .applyChanges();


                player.sendMessage("§aSpawner upgraded successfully!");
            }
        }


        // Modify delay using SpawnerDataModifier
        if (args.length > 0 && args[0].equalsIgnoreCase("setdelay")) {
            if (args.length > 1) {
                try {
                    long newDelay = Long.parseLong(args[1]);
                    SpawnerDataModifier modifier = api.getSpawnerModifier(spawnerData.getSpawnerId());


                    if (modifier != null) {
                        modifier.setBaseSpawnerDelay(newDelay)
                                .applyChanges();
                        player.sendMessage("§aSpawner delay set to " + newDelay + " ticks!");
                    }
                } catch (NumberFormatException e) {
                    player.sendMessage("§cInvalid delay value!");
                }
            }
        }


        return true;
    }
}
```

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

### Example: Giving Spawners to Players

Source: https://docs.smartspawner.site/spawners_settings

Examples demonstrating how to use the /ss give spawner command to provide specific types and amounts of spawners to players. The [amount] parameter is optional and defaults to 1.

```bash
/ss give spawner @p skeleton 1
```

```bash
/ss give spawner Player123 wither_skeleton 3
```

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

### Item Spawner Configuration Example

Source: https://docs.smartspawner.site/item_spawners_settings

This is a basic example of the item spawner configuration structure in YAML. It shows global defaults and specific item settings.

```yaml
# Global default for unknown items
default_material: "SPAWNER"


ITEM_MATERIAL:
  material: <MATERIAL>
  experience: <number>
  loot:
    ITEM_ID:
      amount: <min>-<max>
      chance: <percentage>
      # Optional properties
      potion_type: <POTION_TYPE>  # For tipped arrows only
  head_texture:
    material: <MATERIAL>
    custom_texture: <texture_hash>  # null for vanilla materials

```

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

### Complete MythicMobs Custom Boss Example with Spawner Drops

Source: https://docs.smartspawner.site/integrations/mythicmobs

Example of a custom boss configuration in MythicMobs, including probabilities for dropping different spawner types.

```yaml
CustomBoss:
  Type: ZOMBIE
  Health: 100
  Drops:
  - smartspawner BLAZE 1-2 0.5
  - smartspawner WITHER_SKELETON 1 0.25
  - gold_ingot 5-10 1.0
```

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

### Initialize SmartSpawner API in Java Plugin

Source: https://docs.smartspawner.site/developer-api/api-installation

Basic setup to retrieve and connect to the SmartSpawner API upon your plugin's enablement. Handles cases where the API might not be found.

```java
import github.nighter.smartspawner.api.SmartSpawnerAPI;
import github.nighter.smartspawner.api.SmartSpawnerProvider;


public class YourPlugin extends JavaPlugin {


    private SmartSpawnerAPI api;


    @Override
    public void onEnable() {
        // Initialize API
        api = SmartSpawnerProvider.getAPI();
        if (api == null) {
            getLogger().warning("SmartSpawner not found!");
            return;
        }


        getLogger().info("SmartSpawner API connected successfully!");
    }


    public SmartSpawnerAPI getAPI() {
        return api;
    }
}
```

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

### Example Player Head Button Configuration

Source: https://docs.smartspawner.site/gui_layout

Configure a GUI button to use a custom player head texture. This snippet shows a button with a specific texture hash, enabled for selling integration, and acting as an info button.

```yaml
slot_14:
  material: PLAYER_HEAD
  custom_texture: "df5de940bfe499c59ee8dac9f9c3919e7535eff3a9acb16f4842bf290f4c679f"
  enabled: true
  info_button: true
  if:
    sell_integration:
      left_click:
        action: "sell_and_exp"
      right_click:
        action: "open_stacker"
    no_sell_integration:
      click:
        action: "open_stacker"
```

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

### Implement Custom Spawner Layout Provider

Source: https://docs.smartspawner.site/developer-api/api-gui-layout

Sets a custom layout provider to dynamically determine GUI layouts. This example shows how to provide a 'premium' layout for specific players. Return null to use default layout resolution.

```java
import github.nighter.smartspawner.api.SmartSpawnerAPI;
import github.nighter.smartspawner.api.SmartSpawnerProvider;
import github.nighter.smartspawner.api.gui.*;
import github.nighter.smartspawner.api.data.SpawnerDataDTO;
import org.bukkit.entity.Player;


SmartSpawnerAPI api = SmartSpawnerProvider.getAPI();


api.setSpawnerLayoutProvider(new SpawnerGuiLayoutProvider() {
    private final GuiLayoutData premiumMainGui = buildPremiumMainGui(); // build once


    @Override
    public GuiLayoutData getLayout(SpawnerDataDTO spawner, Player player, GuiLayoutType type) {
        // Example: premium island members get a custom layout
        if (type == GuiLayoutType.MAIN_GUI && isPremiumIsland(player)) {
            return premiumMainGui;
        }
        return null; // Use default layout resolution
    }


    @Override
    public String getProviderName() {
        return "MyIslandPlugin";
    }
});
```

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

### Verify SmartSpawner Installation

Source: https://docs.smartspawner.site/installation

Run this command in the server console or in-game chat to check if SmartSpawner has loaded successfully. You should see SmartSpawner listed with a green status.

```minecraft-commands
/plugins
```

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

### Register Programmatic Main GUI Layout

Source: https://docs.smartspawner.site/developer-api/api-gui-layout

Build and register a custom main GUI layout using the builder API. This example demonstrates setting up buttons with various actions, materials, and sounds. The storage and sell confirm layouts can be omitted by passing null.

```java
import github.nighter.smartspawner.api.SmartSpawnerAPI;
import github.nighter.smartspawner.api.SmartSpawnerProvider;
import github.nighter.smartspawner.api.gui.*;
import org.bukkit.Material;


SmartSpawnerAPI api = SmartSpawnerProvider.getAPI();


// Build the main GUI layout
GuiLayoutData mainGui = new GuiLayoutBuilder()
    .type(GuiLayoutType.MAIN_GUI)
    .addButton("slot_11", new GuiButtonBuilder()
        .slot(11)
        .material(Material.CHEST)
        .cooldown("2s")
        .action("click", "open_storage")
        .sound("block.chest.open", 1.0f, 1.0f)
        .build())
    .addButton("slot_14", new GuiButtonBuilder()
        .slot(14)
        .material(Material.PLAYER_HEAD)
        .infoButton(true)
        .customTexture("df5de940bfe499c59ee8dac9f9c3919e7535eff3a9acb16f4842bf290f4c679f")
        .action("left_click", "sell_and_exp")
        .action("right_click", "open_stacker")
        .sound("left_click", "ui.button.click")
        .successSound("left_click", "block.note_block.bell")
        .successSound("left_click", "entity.experience_orb.pickup")
        .failSound("left_click", "block.note_block.pling")
        .sound("right_click", "ui.button.click")
        .build())
    .addButton("slot_15", new GuiButtonBuilder()
        .slot(15)
        .material(Material.EXPERIENCE_BOTTLE)
        .action("click", "collect_exp")
        .build())
    .build();


// Register the layout (storage and sell confirm can be null)
GuiLayoutRegistry registry = api.getLayoutRegistry();
registry.registerLayout("myplugin_custom", mainGui, null, null);
```

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

### Global Layout Registration Methods

Source: https://docs.smartspawner.site/developer-api/api-gui-layout

Provides methods to interact with the layout registry for managing global GUI layouts. These include getting the registry, registering/unregistering layouts programmatically or from YAML, checking registration status, and retrieving all registered layout names.

```APIDOC
## Global Layout Registration

### Methods

- **`getLayoutRegistry()`**
  - Description: Gets the layout registry.
  - Return Type: `GuiLayoutRegistry`

- **`registerLayout(String name, GuiLayoutData mainGui, GuiLayoutData storageGui, GuiLayoutData sellConfirmGui)`**
  - Description: Registers a programmatic layout.
  - Return Type: `boolean`

- **`registerLayoutFromYaml(String name, File mainGuiYaml, File storageGuiYaml, File sellConfirmGuiYaml)`**
  - Description: Registers a layout from YAML files.
  - Return Type: `boolean`

- **`unregisterLayout(String name)`**
  - Description: Unregisters a layout.
  - Return Type: `boolean`

- **`isRegistered(String name)`**
  - Description: Checks if a layout is registered.
  - Return Type: `boolean`

- **`getRegisteredLayouts()`**
  - Description: Gets all registered layout names.
  - Return Type: `Set<String>`
```

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

### Validate Spawner Item Type

Source: https://docs.smartspawner.site/developer-api/api-examples

This example demonstrates how to check if an item is a SmartSpawner, a Vanilla Spawner, or an Item Spawner, and retrieve its entity type or material. It requires the SmartSpawnerAPI and Bukkit event handling.

```java
import github.nighter.smartspawner.api.SmartSpawnerAPI;
import org.bukkit.Material;
import org.bukkit.entity.EntityType;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerInteractEvent;
import org.bukkit.inventory.ItemStack;


public class SpawnerChecker implements Listener {


    private final SmartSpawnerAPI api;


    public SpawnerChecker(SmartSpawnerAPI api) {
        this.api = api;
    }


    @EventHandler
    public void onPlayerInteract(PlayerInteractEvent event) {
        Player player = event.getPlayer();
        ItemStack item = event.getItem();


        if (item == null || item.getType() != Material.SPAWNER) {
            return;
        }


        // Check spawner type
        if (api.isSmartSpawner(item)) {
            EntityType type = api.getSpawnerEntityType(item);
            player.sendMessage("§aSmartSpawner: §e" + type);
        }
        else if (api.isVanillaSpawner(item)) {
            EntityType type = api.getSpawnerEntityType(item);
            player.sendMessage("§7Vanilla Spawner: §e" + type);
        }
        else if (api.isItemSpawner(item)) {
            Material material = api.getItemSpawnerMaterial(item);
            player.sendMessage("§6Item Spawner: §e" + material);
        }
    }
}
```

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

### Sound List Configuration

Source: https://docs.smartspawner.site/gui_layout

Demonstrates how to use a list for sound keys, allowing multiple sounds or sounds with custom volume and pitch. Includes a plain Bukkit key and an object with specific parameters.

```yaml
sound_success:
  - block.note_block.bell
  - name: entity.experience_orb.pickup
    volume: 0.8
    pitch: 1.2

```

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

### Get All Spawners

Source: https://docs.smartspawner.site/developer-api/api-data-access

Retrieves a list of all registered spawners on the server. Useful for iterating and displaying spawner information.

```java
import java.util.List;


List<SpawnerDataDTO> allSpawners = api.getAllSpawners();
player.sendMessage("Total spawners: " + allSpawners.size());


for (SpawnerDataDTO spawner : allSpawners) {
    player.sendMessage("- " + spawner.getEntityType() +
                      " at " + spawner.getLocation() +
                      " (Stack: " + spawner.getStackSize() + ")");
}
```

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

### Get Spawner Data by ID

Source: https://docs.smartspawner.site/developer-api/api-data-access

Retrieves spawner data using its unique identifier. Use SpawnerDataModifier for modifications.

```java
String spawnerId = "spawner-uuid-here";
SpawnerDataDTO spawnerData = api.getSpawnerById(spawnerId);


if (spawnerData != null) {
    // READ-ONLY: Can only read data
    Location location = spawnerData.getLocation();
    player.sendMessage("Spawner location: " + location);
    player.sendMessage("Max Stack: " + spawnerData.getMaxStackSize());


    // To modify, use SpawnerDataModifier
    SpawnerDataModifier modifier = api.getSpawnerModifier(spawnerId);
    if (modifier != null) {
        modifier.setMaxStackSize(2000)
                .applyChanges();
        player.sendMessage("Max stack size updated!");
    }
}
```

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

### Get Spawner Data by Location

Source: https://docs.smartspawner.site/developer-api/api-data-access

Retrieves spawner data using its block location. Use SpawnerDataModifier to apply changes.

```java
import github.nighter.smartspawner.api.data.SpawnerDataDTO;
import org.bukkit.Location;


Location location = block.getLocation();
SpawnerDataDTO spawnerData = api.getSpawnerByLocation(location);


if (spawnerData != null) {
    // READ-ONLY: Can only read data, cannot modify
    player.sendMessage("Spawner ID: " + spawnerData.getSpawnerId());
    player.sendMessage("Entity Type: " + spawnerData.getEntityType());
    player.sendMessage("Stack Size: " + spawnerData.getStackSize());
    player.sendMessage("Base Delay: " + spawnerData.getBaseSpawnerDelay() + " ticks");


    // To modify values, use SpawnerDataModifier
    SpawnerDataModifier modifier = api.getSpawnerModifier(spawnerData.getSpawnerId());
    if (modifier != null) {
        modifier.setBaseMaxMobs(10)
                .setBaseMinMobs(2)
                .setBaseSpawnerDelay(600L)
                .applyChanges(); // Must call to save changes
        player.sendMessage("Values updated!");
    }
}
```

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

### Calculate Approximation Threshold

Source: https://docs.smartspawner.site/configuration

This formula determines when approximation mode starts based on mob count and drop chance. It is used when `approximate_loot` is enabled.

```mathematica
mobCount > (97.5 / dropChancePercent) * approximation_threshold

```

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

### Registering a Programmatic Layout

Source: https://docs.smartspawner.site/developer-api/api-gui-layout

Demonstrates how to build and register a custom GUI layout using the SmartSpawner API's builder pattern. This allows for dynamic creation of GUI elements, actions, and sounds.

```APIDOC
## Registering a Programmatic Layout

### Example

```java
import github.nighter.smartspawner.api.SmartSpawnerAPI;
import github.nighter.smartspawner.api.SmartSpawnerProvider;
import github.nighter.smartspawner.api.gui.*;
import org.bukkit.Material;


SmartSpawnerAPI api = SmartSpawnerProvider.getAPI();


// Build the main GUI layout
GuiLayoutData mainGui = new GuiLayoutBuilder()
    .type(GuiLayoutType.MAIN_GUI)
    .addButton("slot_11", new GuiButtonBuilder()
        .slot(11)
        .material(Material.CHEST)
        .cooldown("2s")
        .action("click", "open_storage")
        .sound("block.chest.open", 1.0f, 1.0f)
        .build())
    .addButton("slot_14", new GuiButtonBuilder()
        .slot(14)
        .material(Material.PLAYER_HEAD)
        .infoButton(true)
        .customTexture("df5de940bfe499c59ee8dac9f9c3919e7535eff3a9acb16f4842bf290f4c679f")
        .action("left_click", "sell_and_exp")
        .action("right_click", "open_stacker")
        .sound("left_click", "ui.button.click")
        .successSound("left_click", "block.note_block.bell")
        .successSound("left_click", "entity.experience_orb.pickup")
        .failSound("left_click", "block.note_block.pling")
        .sound("right_click", "ui.button.click")
        .build())
    .addButton("slot_15", new GuiButtonBuilder()
        .slot(15)
        .material(Material.EXPERIENCE_BOTTLE)
        .action("click", "collect_exp")
        .build())
    .build();


// Register the layout (storage and sell confirm can be null)
GuiLayoutRegistry registry = api.getLayoutRegistry();
registry.registerLayout("myplugin_custom", mainGui, null, null);

```

After registration, server admins can select it in `config.yml`:

```yaml
gui_layout: "myplugin_custom"
```
```

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

### Spawner Data Access Methods

Source: https://docs.smartspawner.site/developer-api/api-data-access

Provides methods to retrieve spawner data. You can get a spawner by its location or unique ID, or fetch a list of all registered spawners.

```APIDOC
## Spawner Data Access Methods

### Description
Provides methods to retrieve spawner data. You can get a spawner by its location or unique ID, or fetch a list of all registered spawners.

### Methods

- **getSpawnerByLocation(Location)**: Gets spawner data by block location.
- **getSpawnerById(String)**: Gets spawner data by unique ID.
- **getAllSpawners()**: Gets all registered spawners.
- **getSpawnerModifier(String)**: Gets a modifier to change spawner properties.
- **removeSpawner(String)**: Removes a spawner by its unique ID. Completes when block/data cleanup finishes.
- **removeSpawner(Location)**: Removes a spawner by its location. Completes when block/data cleanup finishes.

### Return Types

- **getSpawnerByLocation**: `SpawnerDataDTO`
- **getSpawnerById**: `SpawnerDataDTO`
- **getAllSpawners**: `List<SpawnerDataDTO>`
- **getSpawnerModifier**: `SpawnerDataModifier`
- **removeSpawner**: `CompletableFuture<Boolean>`
```

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

### Storage Selling Integration

Source: https://docs.smartspawner.site/configuration

Enable and configure the integration for selling items from spawner storage, including currency and price source modes.

```yaml
sell_integration:
  enabled: true
  currency: VAULT
  excellenteconomy_currency: coins
  price_source_mode: SHOP_PRIORITY
  shop_integration:
    enabled: true
    preferred_plugin: auto
  custom_prices:
    enabled: true
    default_price: 1.0

```

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

### Registering a Layout from YAML

Source: https://docs.smartspawner.site/developer-api/api-gui-layout

Shows how to register a GUI layout by providing YAML files. This is useful for plugins that ship their layout configurations as resources.

```APIDOC
## Registering a Layout from YAML

### Example

```java
SmartSpawnerAPI api = SmartSpawnerProvider.getAPI();


File mainGui = new File(getDataFolder(), "layouts/main_gui.yml");
File storageGui = new File(getDataFolder(), "layouts/storage_gui.yml");
File sellConfirmGui = new File(getDataFolder(), "layouts/sell_confirm_gui.yml");


api.getLayoutRegistry().registerLayoutFromYaml("myplugin_custom", mainGui, storageGui, sellConfirmGui);

```

The YAML format must match the built-in SmartSpawner layout files.
```

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

### Setting Default Island Role Permissions

Source: https://docs.smartspawner.site/integrations/superiorskyblock2

Configure default permissions for island roles in SuperiorSkyblock2's config.yml. This example sets 'spawner_stack' and 'spawner_open_menu' for Owner and Admin roles.

```yaml
island-roles:
  Owner:
    permissions:
      - spawner_stack
      - spawner_open_menu
  Admin:
    permissions:
      - spawner_stack
      - spawner_open_menu
  Moderator:
    permissions:
      - spawner_open_menu
  Member:
    permissions: []
```

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

### Get the entity type from a spawner item

Source: https://docs.smartspawner.site/developer-api/api-validation

Retrieves the EntityType associated with a spawner item. Returns null if the item is not a valid spawner. This is useful for determining what entity a spawner will produce.

```java
import org.bukkit.entity.EntityType;
import org.bukkit.inventory.ItemStack;

// Assuming 'api' is an instance of your SmartSpawner API

ItemStack item = player.getItemInHand();
EntityType entityType = api.getSpawnerEntityType(item);


if (entityType != null) {
    player.sendMessage("This spawner spawns: " + entityType.name());
} else {
    player.sendMessage("This is not a valid spawner!");
}
```

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

### Use Vietnamese with Default GUI

Source: https://docs.smartspawner.site/configuration

Demonstrates setting the language to Vietnamese (`vi_VN`) while using the default GUI layout. Language and GUI layout settings are independent.

```yaml
language: vi_VN
gui_layout: default
```

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

### Give Spawner Command Syntax

Source: https://docs.smartspawner.site/spawners_settings

This is the base syntax for the /ss give spawner command. Use this to understand the parameters required.

```bash
/ss give spawner <player> <item_type> [amount]
```

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

### Get the material type from an item spawner

Source: https://docs.smartspawner.site/developer-api/api-validation

Retrieves the Material type from an item spawner. This method should be used after confirming the item is an item spawner using `isItemSpawner()`. Returns null if the material cannot be determined.

```java
import org.bukkit.Material;
import org.bukkit.inventory.ItemStack;

// Assuming 'api' is an instance of your SmartSpawner API

ItemStack item = player.getItemInHand();


if (api.isItemSpawner(item)) {
    Material material = api.getItemSpawnerMaterial(item);
    if (material != null) {
        player.sendMessage("This spawner spawns: " + material.name());
    }
}
```

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

### Configure Language and GUI Layout

Source: https://docs.smartspawner.site/configuration

Set the primary language and the graphical user interface layout for SmartSpawner. The `debug` option enables verbose console output for troubleshooting.

```yaml
language: en_US
gui_layout: default
debug: false
```

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

### Read and Modify Spawner Base Values

Source: https://docs.smartspawner.site/developer-api/api-data-access

Demonstrates how to retrieve a spawner modifier, read its current base configuration values, and then update these values before applying the changes. Ensure a valid spawner ID is used to get the modifier.

```java
SpawnerDataModifier modifier = api.getSpawnerModifier(spawnerId);


if (modifier != null) {
    // Read current values
    int maxStoragePages = modifier.getBaseMaxStoragePages();
    int minMobs = modifier.getBaseMinMobs();
    int maxMobs = modifier.getBaseMaxMobs();
    int maxStoredExp = modifier.getBaseMaxStoredExp();
    long spawnerDelay = modifier.getBaseSpawnerDelay();


    player.sendMessage("Current Config Values:");
    player.sendMessage("Storage Pages: " + maxStoragePages);
    player.sendMessage("Min Mobs: " + minMobs);
    player.sendMessage("Max Mobs: " + maxMobs);
    player.sendMessage("Max Exp: " + maxStoredExp);
    player.sendMessage("Delay: " + spawnerDelay + " ticks");


    // Modify values
    modifier.setBaseMaxStoragePages(5)
            .setBaseMinMobs(3)
            .setBaseMaxMobs(20)
            .setBaseMaxStoredExp(10000)
            .setBaseSpawnerDelay(300L)
            .applyChanges();


    player.sendMessage("All values updated successfully!");
}
```

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

### Register Layout from YAML Files

Source: https://docs.smartspawner.site/developer-api/api-gui-layout

Register a custom GUI layout by providing paths to YAML files for the main, storage, and sell confirm GUIs. The YAML format must be compatible with SmartSpawner's built-in layout files.

```java
SmartSpawnerAPI api = SmartSpawnerProvider.getAPI();


File mainGui = new File(getDataFolder(), "layouts/main_gui.yml");
File storageGui = new File(getDataFolder(), "layouts/storage_gui.yml");
File sellConfirmGui = new File(getDataFolder(), "layouts/sell_confirm_gui.yml");


api.getLayoutRegistry().registerLayoutFromYaml("myplugin_custom", mainGui, storageGui, sellConfirmGui);
```

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

### View or Change GUI Layout

Source: https://docs.smartspawner.site/commands

Use this command to view or modify the currently active GUI layout. The layout argument autocompletes from the specified directory.

```bash
/ss gui_layout
/ss gui_layout <layout>
```

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

### Enable Bedrock Player Form UI

Source: https://docs.smartspawner.site/configuration

Configuration to enable a mobile-friendly form UI for Bedrock players, replacing standard chest GUIs. Requires Floodgate.

```yaml
bedrock_support:
  enable_formui: true
```

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

### Select Custom Layout in Config

Source: https://docs.smartspawner.site/developer-api/api-gui-layout

After registering a custom GUI layout, server administrators can select it by specifying its name in the server's `config.yml` file.

```yaml
gui_layout: "myplugin_custom"
```

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

### Spawner Stacking Permission Configuration

Source: https://docs.smartspawner.site/integrations/superiorskyblock2

Configure permissions for stacking spawners. This includes settings for display, enabled/disabled states, role permissions, and audio feedback for access.

```yaml
spawner_stack:
  display-menu: true
  permission-enabled:
    type: SPAWNER
    name: '&fSpawner Stack'
    lore:
      - '&fPermission that allows the user to stack spawners.'
      - '&fStatus: &aEnabled'
  permission-disabled:
    type: SPAWNER
    name: '&fSpawner Stack'
    lore:
      - '&fPermission that allows the user to stack spawners.'
      - '&fStatus: &cDisabled'
  role-permission:
    type: SPAWNER
    name: '&fSpawner Stack'
    lore:
      - '&fPermission that allows the user to stack spawners.'
      - '&fRole: &e{}&f.'
      - ''
      - '{0}'
  has-access:
    sound:
      type: ENTITY_EXPERIENCE_ORB_PICKUP
      volume: 0.2
      pitch: 0.2
  no-access:
    sound:
      type: BLOCK_ANVIL_PLACE
      volume: 0.2
      pitch: 0.2
```

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

### GUI Layout Directory Structure

Source: https://docs.smartspawner.site/gui_layout

This shows the default directory structure for GUI layout files.

```yaml
plugins/SmartSpawner/gui_layouts/
├── default/
│   ├── main_gui.yml
│   ├── storage_gui.yml
│   └── sell_confirm_gui.yml
├── DonutSMP/
│   └── ...
└── DonutSMP_v2/
    └── ...
```

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

### Independent Left and Right Click Actions and Sounds

Source: https://docs.smartspawner.site/gui_layout

Allows independent configuration of actions and sounds for left and right clicks. Left click is set to 'sell_and_exp' with success and fail sounds, while right click is set to 'open_stacker' with a default click sound.

```yaml
left_click:
  action: "sell_and_exp"
  sound: ui.button.click
  sound_success: block.note_block.bell
  sound_fail: block.note_block.pling
right_click:
  action: "open_stacker"
  sound: ui.button.click

```

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

### Basic Diamond Spawner Configuration

Source: https://docs.smartspawner.site/item_spawners_settings

Configuration for a simple diamond spawner. Sets the material, experience, and loot properties.

```yaml
# Simple diamond spawner
DIAMOND:
  material: "DIAMOND"
  experience: 1
  loot:
    DIAMOND:
      amount: 1-1  # Will generate 1-4 diamonds per trigger (multiplied by min_mobs to max_mobs)
      chance: 100.0
  head_texture:
    material: "DIAMOND"
    custom_texture: null

```

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

### View Spawner Prices Command

Source: https://docs.smartspawner.site/commands

Opens a GUI to display sell prices for all items generated by spawners. This command requires sell integration to be active and shows current shop or custom prices.

```minecraft-commands
/ss prices
```

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

### Handle Spawner GUI Open

Source: https://docs.smartspawner.site/developer-api/api-events

Use the SpawnerOpenGUIEvent to intercept when a player opens the spawner GUI. This event allows for permission checks and cancellation of the GUI opening.

```Java
import github.nighter.smartspawner.api.events.SpawnerOpenGUIEvent;


@EventHandler
public void onSpawnerOpenGUI(SpawnerOpenGUIEvent event) {
    Player player = event.getPlayer();
    EntityType entityType = event.getEntityType();
    boolean isRefresh = event.isRefresh();


    // Handle GUI open
    if (!player.hasPermission("spawner.gui.open")) {
        event.setCancelled(true);
        player.sendMessage("No permission to open spawner GUI!");
    }
}
```

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

### Configure Hologram Visuals

Source: https://docs.smartspawner.site/configuration

Settings for displaying floating text holograms above spawners, including position, alignment, and visual enhancements like shadows and transparency.

```yaml
hologram:
  enabled: false
  offset_x: 0.5
  offset_y: 1.6
  offset_z: 0.5
  alignment: CENTER
  shadowed_text: true
  see_through: false
  transparent_background: false
```

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

### SimpleClaimSystem v1.x.x Status Settings

Source: https://docs.smartspawner.site/integrations/simpleclaimsystem

Configuration for status settings in SimpleClaimSystem v1.x.x. Ensure 'Destroy' and 'InteractBlocks' are enabled for spawner management.

```yaml
status-settings:
  Build: true
  Destroy: true
  Buttons: true
  Items: true
  InteractBlocks: true
  # ... other settings

```

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

### Spawner Statistics Command

Source: https://docs.smartspawner.site/developer-api/api-examples

Creates a command to display server-wide spawner statistics, including total spawners, total stack size, and counts by entity type. Requires the SmartSpawnerAPI instance.

```java
import github.nighter.smartspawner.api.SmartSpawnerAPI;
import github.nighter.smartspawner.api.data.SpawnerDataDTO;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.EntityType;


import java.util.HashMap;
import java.util.List;
import java.util.Map;


public class SpawnerStatsCommand implements CommandExecutor {


    private final SmartSpawnerAPI api;


    public SpawnerStatsCommand(SmartSpawnerAPI api) {
        this.api = api;
    }


    @Override
    public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
        // Get all spawners
        List<SpawnerDataDTO> allSpawners = api.getAllSpawners();


        // Count by entity type
        Map<EntityType, Integer> spawnerCounts = new HashMap<>();
        int totalStackSize = 0;


        for (SpawnerDataDTO spawner : allSpawners) {
            EntityType type = spawner.getEntityType();
            spawnerCounts.put(type, spawnerCounts.getOrDefault(type, 0) + 1);
            totalStackSize += spawner.getStackSize();
        }


        // Display statistics
        sender.sendMessage("§6=== Spawner Statistics ===");
        sender.sendMessage("§eTotal Spawners: §f" + allSpawners.size());
        sender.sendMessage("§eTotal Stack Size: §f" + totalStackSize);
        sender.sendMessage("");
        sender.sendMessage("§eSpawners by Type:");


        spawnerCounts.entrySet().stream()
                .sorted((a, b) -> b.getValue().compareTo(a.getValue()))
                .forEach(entry -> {
                    sender.sendMessage("  §7- §f" + entry.getKey() +
                                     "§7: §e" + entry.getValue());
                });


        return true;
    }
}

```

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

### Give Item Spawner Command

Source: https://docs.smartspawner.site/item_spawners_settings

Use the '/ss give item_spawner' command to provide players with item spawners. Specify the player, item type, and optional amount.

```bash
/ss give item_spawner <player> <item_type> [amount]
```

```bash
/ss give item_spawner @p diamond 1
/ss give item_spawner Player123 netherite_ingot 5
```

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

### Performance Configuration

Source: https://docs.smartspawner.site/configuration

Configure loot generation approximation for large spawner stacks. Set `approximate_loot` to true for performance gains on most servers.

```yaml
performance:
  loot_generation:
    approximate_loot: true
    approximation_threshold: 1000

```

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

### Calculate Actual Drops from Base Amount

Source: https://docs.smartspawner.site/item_spawners_settings

Illustrates the formula for calculating the actual number of items dropped by a spawner based on the configured base amount and the random range of mobs.

```text
Actual Drops = Base Amount × Random(min_mobs, max_mobs)
```

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

### Configure Spawner Action Logging

Source: https://docs.smartspawner.site/configuration

Enable or disable file logging for spawner actions. Customize log file rotation, size, and format. Specify which events to log or log all events.

```yaml
logging:
  enabled: true
  json_format: false
  console_output: false
  max_log_files: 10
  max_log_size_mb: 10
  log_all_events: false
  logged_events:
    - SPAWNER_PLACE
    - SPAWNER_BREAK
    - SPAWNER_EXPLODE
    - SPAWNER_STACK_HAND
    - SPAWNER_STACK_GUI
    - SPAWNER_DESTACK_GUI
    - SPAWNER_EXP_CLAIM
    - SPAWNER_SELL_ALL
    - SPAWNER_ITEM_TAKE_ALL
    - SPAWNER_ITEMS_SORT
    - SPAWNER_ITEM_FILTER
    - SPAWNER_DROP_PAGE_ITEMS
    - COMMAND_EXECUTE_PLAYER
    - COMMAND_EXECUTE_CONSOLE
    - COMMAND_EXECUTE_RCON

```

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

### Handle Spawner Stack Event

Source: https://docs.smartspawner.site/developer-api/api-events

Listen for when spawners are stacked by hand. Access the player and the new stack size.

```Java
import github.nighter.smartspawner.api.events.SpawnerStackEvent;


@EventHandler
public void onSpawnerStack(SpawnerStackEvent event) {
    Player player = event.getPlayer();
    int newStackSize = event.getNewStackSize();


    player.sendMessage("Spawner stacked! New size: " + newStackSize);
}
```

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

### Handle Take All Items from Spawner Storage

Source: https://docs.smartspawner.site/developer-api/api-events

Use the SpawnerTakeAllEvent to manage scenarios where a player takes all items from a spawner storage page. Permissions can be checked, and the action cancelled if required.

```Java
import github.nighter.smartspawner.api.events.SpawnerTakeAllEvent;


@EventHandler
public void onSpawnerTakeAll(SpawnerTakeAllEvent event) {
    Player player = event.getPlayer();


    // Handle take all
    if (!player.hasPermission("spawner.gui.takeall")) {
        event.setCancelled(true);
        player.sendMessage("No permission to take all items from spawner!");
    }
}
```

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

### SpawnerOpenGUIEvent

Source: https://docs.smartspawner.site/developer-api/api-events

Triggered when a spawner's GUI is opened by a player.

```APIDOC
## SpawnerOpenGUIEvent

### Description
Triggered when a spawner's GUI is opened by a player.

### Event Details
- **Event Class**: `github.nighter.smartspawner.api.events.SpawnerOpenGUIEvent`
- **Cancellable**: Yes
```

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

### Skeleton Mob Configuration with Vanilla Head

Source: https://docs.smartspawner.site/spawners_settings

Configures a skeleton mob with experience, a vanilla skeleton skull, and drops including bones, arrows, and a chance for a bow.

```yaml
# Reference: https://minecraft.wiki/w/Skeleton#Drops
SKELETON:
  experience: 5
  head_texture:
    material: "SKELETON_SKULL"
    custom_texture: null  # Use vanilla skull
  loot:
    BONE:
      amount: 0-2
      chance: 66.67
    ARROW:
      amount: 0-2
      chance: 66.67
    BOW:
      amount: 1-1
      chance: 8.5
      durability: 1-384

```

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

### Give Vanilla Spawner Command

Source: https://docs.smartspawner.site/commands

Use this command to give vanilla spawners to a player. These function like standard Minecraft spawners, spawning actual mobs and not supporting stacking or a GUI.

```minecraft-commands
/ss give vanilla_spawner <player> <type> [amount]
```

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

### Default Head Texture Configuration

Source: https://docs.smartspawner.site/item_spawners_settings

Use this configuration for default item spawners with vanilla materials. Ensure the 'item_spawners_settings.yml' file exists for auto-regeneration.

```yaml
head_texture:
  material: "DIAMOND"
  custom_texture: null
```

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

### Custom Player Head Texture Configuration

Source: https://docs.smartspawner.site/item_spawners_settings

Configure custom player head textures by specifying the material as 'PLAYER_HEAD' and providing a valid texture hash. This is useful for unique item appearances.

```yaml
head_texture:
  material: "PLAYER_HEAD"
  custom_texture: "a3b9003ba2d05562c75119b8a62185c67130e9282f7acbac4bc2824c21eb95d9"
```

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

### createVanillaSpawnerItem

Source: https://docs.smartspawner.site/developer-api/api-creation

Creates vanilla spawner items that function like standard Minecraft spawners without SmartSpawner features. You can specify the entity type and the quantity.

```APIDOC
## createVanillaSpawnerItem(EntityType)

### Description
Creates a single vanilla spawner item for the specified entity type.

### Method
`createVanillaSpawnerItem(EntityType)`

### Parameters
#### Path Parameters
- **EntityType** (EntityType) - Required - The type of entity to spawn.

### Response
#### Success Response (200)
- **ItemStack** (ItemStack) - The created vanilla spawner item.

### Request Example
```java
// Create a vanilla creeper spawner
ItemStack vanillaSpawner = api.createVanillaSpawnerItem(EntityType.CREEPER);
```
```

```APIDOC
## createVanillaSpawnerItem(EntityType, int)

### Description
Creates multiple vanilla spawner items for the specified entity type.

### Method
`createVanillaSpawnerItem(EntityType, int)`

### Parameters
#### Path Parameters
- **EntityType** (EntityType) - Required - The type of entity to spawn.
- **int** (int) - Required - The number of spawner items to create.

### Response
#### Success Response (200)
- **ItemStack** (ItemStack) - The created vanilla spawner items.

### Request Example
```java
// Create multiple vanilla spawners
ItemStack vanillaSpawners = api.createVanillaSpawnerItem(EntityType.COW, 3);
```
```

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

### Create Vanilla Spawner Item

Source: https://docs.smartspawner.site/developer-api/api-creation

Use this to create a standard Minecraft vanilla spawner. It can create a single spawner or multiple spawners of a specified type.

```java
// Create a vanilla creeper spawner
ItemStack vanillaSpawner = api.createVanillaSpawnerItem(EntityType.CREEPER);
```

```java
// Create multiple vanilla spawners
ItemStack vanillaSpawners = api.createVanillaSpawnerItem(EntityType.COW, 3);
```

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

### MythicMobs SmartSpawner Syntax

Source: https://docs.smartspawner.site/integrations/mythicmobs

Use this syntax in your MythicMobs configuration file to define spawner drops. It requires the entity type and a quantity or range.

```plaintext
smartspawner <entity> <quantity/range>
```

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

### Core Spawner Properties Configuration

Source: https://docs.smartspawner.site/configuration

Defines the default generation parameters for mobs, storage, and spawner behavior. Use this to set the base values for how spawners operate.

```yaml
spawner_properties:
  default:
    min_mobs: 1
    max_mobs: 4
    range: 16
    delay: 25s


    max_storage_pages: 1
    max_stored_exp: 1000
    max_stack_size: 10000


    allow_exp_mending: true
    protect_from_explosions: true

```

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

### Spawner Menu Access Permission Configuration

Source: https://docs.smartspawner.site/integrations/superiorskyblock2

Configure permissions for accessing the spawner management menu. This includes settings for display, enabled/disabled states, role permissions, and audio feedback for access.

```yaml
spawner_open_menu:
  display-menu: true
  permission-enabled:
    type: SPAWNER
    name: '&fSpawner Menu'
    lore:
      - '&fPermission that allows the user to open the spawner menu.'
      - '&fStatus: &aEnabled'
  permission-disabled:
    type: SPAWNER
    name: '&fSpawner Menu'
    lore:
      - '&fPermission that allows the user to open the spawner menu.'
      - '&fStatus: &cDisabled'
  role-permission:
    type: SPAWNER
    name: '&fSpawner Menu'
    lore:
      - '&fPermission that allows the user to open the spawner menu.'
      - '&fRole: &e{}&f.'
      - ''
      - '{0}'
  has-access:
    sound:
      type: ENTITY_EXPERIENCE_ORB_PICKUP
      volume: 0.2
      pitch: 0.2
  no-access:
    sound:
      type: BLOCK_ANVIL_PLACE
      volume: 0.2
      pitch: 0.2
```

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

### SimpleClaimSystem v1.x.x Default Values

Source: https://docs.smartspawner.site/integrations/simpleclaimsystem

Default permission values for members in SimpleClaimSystem v1.x.x. 'Destroy' and 'InteractBlocks' should be true for spawner functionality.

```yaml
default-values-settings:
  Members:
    Build: true
    Destroy: true
    Buttons: true
    Items: true
    InteractBlocks: true
    # ... other settings

```

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

### Multiple Drop Item Spawner Configuration

Source: https://docs.smartspawner.site/item_spawners_settings

Configuration for a gold spawner with variable drops, including primary and secondary loot items.

```yaml
# Gold spawner with variable drops
GOLD_INGOT:
  material: "GOLD_INGOT"
  experience: 1
  loot:
    GOLD_INGOT:
      amount: 1-2  # Will generate 1-8 gold ingots per trigger (1-2 multiplied by 1-4)
      chance: 100.0
    GOLD_NUGGET:
      amount: 3-5  # Additional chance for gold nuggets
      chance: 50.0
  head_texture:
    material: "GOLD_INGOT"
    custom_texture: null

```

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

### Maven Dependency for SmartSpawner

Source: https://docs.smartspawner.site/developer-api/api-installation

Add the SmartSpawner API as a Maven dependency via JitPack. Replace LATEST with the specific version for production.

```xml
<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>


<dependency>
    <groupId>com.github.OpenVdra</groupId>
    <artifactId>SmartSpawner</artifactId>
    <version>LATEST</version>
    <scope>provided</scope>
</dependency>
```

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

### Natural Spawner Settings

Source: https://docs.smartspawner.site/configuration

Configure the behavior of natural spawners, including breaking, conversion to Smart Spawners, and mob spawning.

```yaml
natural_spawner:
  breakable: false
  convert_to_smart_spawner: false
  # drop_chance:
  #   default: 50.0
  #   ZOMBIE: 75.0
  #   SKELETON: 50.0
  #   BLAZE: 25.0
  spawn_mobs: true
  protect_from_explosions: false

```

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

### Create Item Spawner

Source: https://docs.smartspawner.site/developer-api/api-creation

Use this to create a spawner that generates items instead of entities. You can create a single item spawner or multiple spawners for a given material.

```java
import org.bukkit.Material;


// Create a diamond spawner
ItemStack diamondSpawner = api.createItemSpawnerItem(Material.DIAMOND);
```

```java
// Create multiple gold ingot spawners
ItemStack goldSpawners = api.createItemSpawnerItem(Material.GOLD_INGOT, 10);
```
Tokens:
Raw